Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/system-specs/modules/security.md

Large diffs are not rendered by default.

32 changes: 30 additions & 2 deletions src/kiro_crew/connections/mint.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,10 @@
from kiro_crew.loop_lock import LoopBoundLock
from kiro_crew.mcp_grant import grant_fingerprint, grant_observed
from kiro_crew.mcp_utils import mcp_server_alias
from kiro_crew.security import oauth_url_contains_credential
from kiro_crew.security import (
oauth_url_contains_credential,
sanitized_oauth_endpoint_display,
)
from kiro_crew.sel import sel
from kiro_crew.session_pid import register_protected_pid, unregister_protected_pid

Expand Down Expand Up @@ -103,6 +106,13 @@ class MintState(TypedDict, total=False):
state: str # minting | waiting | granted | failed | expired
oauth_url: str
reason: str
# Copy-ready "host/path" of the authorization URL the credential gate
# refused; set only beside reason == "mint_url_rejected", and only when
# security.sanitized_oauth_endpoint_display could produce a string the
# oauth_endpoints.json loader would accept. It rides the card view and the
# mint-state payload ONLY: the log and audit lines stay slug-only, so no
# URL-derived text reaches a logger sink.
rejected_endpoint: str
started: float
token: str # row identity; see _new_mint_token
client: Any
Expand Down Expand Up @@ -917,14 +927,28 @@ async def start_oauth_mint(
if attempt + 1 < _MINT_URL_REJECTION_ATTEMPTS:
continue

# Named on the CARD, never in the log: without the host+path the
# user cannot know what to write into oauth_endpoints.json, so the
# failure reads as unfixable. The display helper owns the
# copy-ready contract: None for a host-borne credential, userinfo,
# a redacted or capped component, a shape the extension loader would
# refuse, or a rejection the allowlist could not clear anyway (fixed
# credential, fragment, path params, http, explicit port) -- so the
# card falls back to its unnamed message rather than show a remedy
# that cannot work. Same thread hop as the gate: the counterfactual
# re-runs it, and it can stat the operator's endpoint file.
rejected_endpoint = await asyncio.to_thread(sanitized_oauth_endpoint_display, oauth_url)
async with _mints_lock:
if _mints.get(slug, {}).get("token") == my_token:
_mints[slug] = {
failed: MintState = {
"state": "failed",
"reason": "mint_url_rejected",
"started": time.monotonic(),
"token": my_token,
}
if rejected_endpoint is not None:
failed["rejected_endpoint"] = rejected_endpoint
_mints[slug] = failed
await asyncio.to_thread(_log_mint_outcome, slug, "error", "reason=mint_url_rejected")
return

Expand Down Expand Up @@ -1139,4 +1163,8 @@ def pending_mint_for(slug: str) -> MintState | None:
view["oauth_url"] = entry["oauth_url"]
if entry.get("reason"):
view["reason"] = entry["reason"]
if entry.get("rejected_endpoint"):
# Rides only beside reason == "mint_url_rejected"; see the field's note
# on MintState for why this channel and not the logger.
view["rejected_endpoint"] = entry["rejected_endpoint"]
return view
12 changes: 10 additions & 2 deletions src/kiro_crew/connections/warm.py
Original file line number Diff line number Diff line change
Expand Up @@ -2540,7 +2540,12 @@ def _credential_bearing_slugs(urls: dict[str, str]) -> set[str]:
The gate is :func:`~kiro_crew.security.oauth_url_contains_credential` -- the same
predicate the cold mint and the chat consent banner apply -- and it is synchronous
because it can consult the operator's on-disk OAuth-endpoint extension, an unbounded
stat on a network mount. Never returns or logs the value it judged.
stat on a network mount. Never returns or logs the value it judged, and it does not
name the endpoint either: a refused slug's claim is RELEASED (see
``_absorb_warm_requests``), the card then asks for a cold mint, and that mint hits the
same URL and names the endpoint through ``mint.py``'s ``mint_url_rejected`` card view.
The warm surface stays slug-only by design -- a screened premint is not a terminal
failure, and the logger is not a channel for URL-derived text.
"""
return {slug for slug, url in urls.items() if url and oauth_url_contains_credential(url)}

Expand Down Expand Up @@ -2579,7 +2584,10 @@ async def _absorb_warm_requests(result: _WarmMintResult, claims: dict[str, str])
url = resolved.get(slug, "")
if not url or slug in tainted:
# Released either way, not failed: the card asks for a fresh mint rather
# than sitting on a claim nothing will ever fill.
# than sitting on a claim nothing will ever fill. For a tainted slug
# that fresh (cold) mint is also where the user learns WHICH endpoint
# was refused -- mint.py names it on its rejection card -- so the
# release, not a failed row, is what makes the warm refusal actionable.
unfulfilled[slug] = token
continue
entry.update(
Expand Down
7 changes: 7 additions & 0 deletions src/kiro_crew/dashboard/handlers/connections.py
Original file line number Diff line number Diff line change
Expand Up @@ -448,6 +448,13 @@ async def api_connections_mint_state(request: web.Request) -> web.Response:
payload["oauth_url"] = view["oauth_url"]
if view.get("reason"):
payload["reason"] = view["reason"]
if view.get("rejected_endpoint"):
# Rides only beside reason == "mint_url_rejected". Already reduced to a
# copy-ready host+path by security.sanitized_oauth_endpoint_display
# (query, fragment, port and userinfo never reach the view), so it is
# safe to cross the wire; the card renders it in place of the unnamed
# rejection message.
payload["rejected_endpoint"] = view["rejected_endpoint"]
return web.json_response(payload)


Expand Down
52 changes: 50 additions & 2 deletions src/kiro_crew/security/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -292,6 +292,7 @@
canonicalize_ip,
diagnose_oauth_url_credential,
exfil_query_min_len,
oauth_rejection_is_endpoint_exemptible,
oauth_url_contains_credential,
redact_exfiltration_urls,
scan_exfiltration_urls,
Expand Down Expand Up @@ -701,7 +702,8 @@ def sanitized_oauth_endpoint(url: str) -> tuple[str, str] | None:
and a credential-bearing HOSTNAME makes the whole helper return ``None``
— a host is an identity, so a redacted host would name nothing;
* both components are length-capped, so a pathological URL cannot bloat a
banner or a log line.
banner or a log line; a capped component ends in ``…`` so a reader can
tell a chopped name from a whole one.

Returns ``None`` when the URL does not parse to a hostname, so callers fall
back to their existing unnamed message. Deliberately independent of WHY the
Expand Down Expand Up @@ -752,7 +754,10 @@ def sanitized_oauth_endpoint(url: str) -> tuple[str, str] | None:
# transformed form and refuse to name it.
if _oauth_component_is_unsafe(host):
return None
host = host[:_SANITIZED_OAUTH_HOST_MAX_LEN]
if len(host) > _SANITIZED_OAUTH_HOST_MAX_LEN:
# Marked like the path below: a silently chopped host reads as a whole
# hostname that nothing on disk will ever match.
host = host[:_SANITIZED_OAUTH_HOST_MAX_LEN] + "…"
path = parsed.path or "/"
if _oauth_component_is_unsafe(path):
path = _REDACTED_CREDENTIAL_TAG
Expand All @@ -761,6 +766,49 @@ def sanitized_oauth_endpoint(url: str) -> tuple[str, str] | None:
return host, path


def sanitized_oauth_endpoint_display(url: str) -> str | None:
"""A rejected endpoint as one copy-ready ``host/path`` string, or ``None``.

:func:`sanitized_oauth_endpoint` answers a diagnostic ``(host, path)`` pair
and, by contract, may hand back a component that is NOT pasteable: the
shared redaction tag for a credential-bearing path, or a ``…``-capped host
or path. A surface whose whole point is "write THIS into
``oauth_endpoints.json``" must not join those into text that reads as
actionable and is not.

So this helper returns a string only when writing the entry would WORK:

* the host matches ``_OAUTH_EXTENSION_HOST_RE`` (lowercase DNS name with a
letter TLD — so ``localhost``, IP literals and a capped host are refused);
* the path passes ``_valid_oauth_extension_path`` (leading ``/``, no
``; ? # % \\ ..`` or whitespace) and is neither redacted nor capped;
* the rejection is one the allowlist can clear
(:func:`oauth_rejection_is_endpoint_exemptible`): the gate is re-run as
if the endpoint were approved, and only a URL that then PASSES is named.
A URL refused for a fixed credential, userinfo, a fragment, path
parameters, heavy percent-encoding, ``http`` or an explicit port would be
refused again after the entry is added, so it stays unnamed rather than
advertise a remedy that cannot work.

Callers fall back to their unnamed message on ``None``. Because the
counterfactual re-runs the gate, this can stat the operator file (memoized),
so callers treat it like the gate itself and run it off the event loop.
"""
endpoint = sanitized_oauth_endpoint(url)
if endpoint is None:
return None
host, path = endpoint
# A capped host needs no check of its own: the host rule below ends in a
# letter TLD, which a trailing "…" can never satisfy.
if path == _REDACTED_CREDENTIAL_TAG or path.endswith("…"):
return None
if not _OAUTH_EXTENSION_HOST_RE.fullmatch(host) or not _valid_oauth_extension_path(path):
return None
if not oauth_rejection_is_endpoint_exemptible(url):
return None
return f"{host}{path}"


# ── Binary File MIME Allowlist ──
# Files whose UTF-8 decode fails are accepted by file_send / outbox only when
# their guessed MIME type is in this allowlist. Deny-by-default; expand only
Expand Down
2 changes: 2 additions & 0 deletions src/kiro_crew/security/_exports.py
Original file line number Diff line number Diff line change
Expand Up @@ -533,6 +533,7 @@
"maintenance_executor",
"math",
"normalize_shell_command",
"oauth_rejection_is_endpoint_exemptible",
"oauth_url_contains_credential",
"os",
"parse_qs",
Expand All @@ -553,6 +554,7 @@
"resource_limit_spec",
"sandbox_credential_targets",
"sanitized_oauth_endpoint",
"sanitized_oauth_endpoint_display",
"scan_exfiltration_urls",
"scan_history",
"scan_memory",
Expand Down
49 changes: 45 additions & 4 deletions src/kiro_crew/security/exfil.py
Original file line number Diff line number Diff line change
Expand Up @@ -874,6 +874,7 @@ def _exfil_url_warning(
is_https: bool = True,
allow_safe_presigned: bool = True,
allow_oauth_entropy: bool = False,
assume_oauth_endpoint: bool = False,
_rule_out: list[str] | None = None,
) -> str | None:
"""Classify one matched URL — the single per-URL exfil verdict.
Expand All @@ -882,6 +883,11 @@ def _exfil_url_warning(
redact_exfiltration_urls (which redacts every URL that returns non-None), so
the two paths can never drift. Returns the warning string, or None if clean.
``_rule_out`` receives only a stable rule id, never URL-derived text.
``assume_oauth_endpoint`` answers a counterfactual, never a verdict: it
treats the endpoint as if it were on the OAuth allowlist WITHOUT consulting
the builtin set or the operator file, so a caller can ask "would this URL
pass if the operator added its endpoint?". HTTPS-only / no-explicit-port
are not assumed away, because the allowlist never relaxes them either.
"""

def trace(rule: str) -> None:
Expand Down Expand Up @@ -961,7 +967,10 @@ def trace(rule: str) -> None:
allow_oauth_entropy
and is_https
and not port
and _approved_oauth_authorization_endpoint(_dom, path_and_query.split("?", 1)[0])
and (
assume_oauth_endpoint
or _approved_oauth_authorization_endpoint(_dom, path_and_query.split("?", 1)[0])
)
)
if _oauth_endpoint:
# Names are matched literally and case-sensitively; encoded/mixed-case
Expand Down Expand Up @@ -1177,8 +1186,19 @@ def _oauth_credential_scan_target(
return url[: query_start + 1] + sanitized_query + suffix


def diagnose_oauth_url_credential(url: str) -> OAuthUrlCredentialDiagnostic | None:
"""Return a safe rejection signature, never URL/value bytes or derivatives."""
def diagnose_oauth_url_credential(
url: str, *, assume_approved_endpoint: bool = False
) -> OAuthUrlCredentialDiagnostic | None:
"""Return a safe rejection signature, never URL/value bytes or derivatives.

``assume_approved_endpoint`` runs the SAME gate as if the URL's endpoint
were on the OAuth allowlist (builtin or operator file), without reading
either. It exists so a rejection surface can tell whether the
``oauth_endpoints.json`` remedy would actually clear THIS rejection before
advertising it; every unconditional rule (fixed credentials, userinfo,
fragments, path params, heavy percent-encoding, http, explicit port) still
rejects under the assumption, exactly as it does for an approved endpoint.
"""
if not url:
return None

Expand Down Expand Up @@ -1242,7 +1262,10 @@ def diagnose_oauth_url_credential(url: str) -> OAuthUrlCredentialDiagnostic | No
approved_endpoint = (
parsed.scheme.lower() == "https"
and not port
and _approved_oauth_authorization_endpoint(parsed.hostname.lower(), parsed.path)
and (
assume_approved_endpoint
or _approved_oauth_authorization_endpoint(parsed.hostname.lower(), parsed.path)
)
)
scan_target = _oauth_credential_scan_target(
url,
Expand Down Expand Up @@ -1291,6 +1314,7 @@ def diagnose_oauth_url_credential(url: str) -> OAuthUrlCredentialDiagnostic | No
is_https=parsed.scheme.lower() == "https",
allow_safe_presigned=False,
allow_oauth_entropy=True,
assume_oauth_endpoint=assume_approved_endpoint,
_rule_out=rules,
)
if warning is None:
Expand Down Expand Up @@ -1382,6 +1406,23 @@ def oauth_url_contains_credential(url: str) -> bool:
return True


def oauth_rejection_is_endpoint_exemptible(url: str) -> bool:
"""True when *url* is rejected today AND would pass with its endpoint allowlisted.

This is the question a rejection surface must answer before it names the
endpoint and points at ``oauth_endpoints.json``: the allowlist relaxes only
the query-entropy heuristics on standard front-channel parameters, so a URL
refused for a fixed credential, userinfo, a fragment, path parameters, heavy
percent-encoding, ``http`` or an explicit port is refused again after the
entry is added, and naming it would advertise a remedy that cannot work.
Reads the operator file only through the ordinary gate (memoized stat), so
callers treat it like the gate itself: run it off the event loop.
"""
if diagnose_oauth_url_credential(url) is None:
return False
return diagnose_oauth_url_credential(url, assume_approved_endpoint=True) is None


# Data-egress / reverse-shell command shapes — the exfiltration-specific subset
# of SUSPICIOUS_BASH_PATTERNS. These are enforced at the
# tool-invocation gate (denied), unlike the full SUSPICIOUS_BASH_PATTERNS list
Expand Down
57 changes: 57 additions & 0 deletions test/test_connections_handoff.py
Original file line number Diff line number Diff line change
Expand Up @@ -716,3 +716,60 @@ async def test_the_premint_then_connect_round_trip_serves_the_warm_url(
# payload deliberately does not carry the flag: no card consumes it, and the
# authorization verdict is the status feed's job.
assert not _mints["notion"].get("shared")


# ── part 4: the rejected-endpoint wire contract ──
#
# The mint-state handler re-projects the view through an explicit key allowlist, so a
# field the in-process view carries is invisible to the card unless the handler names
# it. These assert ARRIVAL at the JSON boundary, not storage.


@pytest.mark.asyncio
async def test_a_rejected_mint_names_the_endpoint_on_the_wire():
_row(
state="failed",
url=None,
shared=False,
generation=0,
activation=0,
token="tok-1",
)
_mints["notion"]["reason"] = "mint_url_rejected"
_mints["notion"]["rejected_endpoint"] = "auth.example.com/authorize"
client = await _client()
try:
body = await (await client.get("/api/connections/mint?slug=notion")).json()
finally:
await client.close()

assert body["state"] == "failed"
assert body["reason"] == "mint_url_rejected"
assert body["rejected_endpoint"] == "auth.example.com/authorize"
# Host+path only ever crosses the wire: no scheme, no query, no fragment.
assert set(body) == {"slug", "state", "token", "reason", "rejected_endpoint"}


@pytest.mark.asyncio
async def test_a_rejection_without_a_named_endpoint_omits_the_field_on_the_wire():
"""Control: when the helper could not name the endpoint the view carries no
rejected_endpoint, so the payload must not invent one -- the card then falls
back to its unnamed message."""
_row(
state="failed",
url=None,
shared=False,
generation=0,
activation=0,
token="tok-2",
)
_mints["notion"]["reason"] = "mint_url_rejected"
client = await _client()
try:
body = await (await client.get("/api/connections/mint?slug=notion")).json()
finally:
await client.close()

assert body["state"] == "failed"
assert body["reason"] == "mint_url_rejected"
assert "rejected_endpoint" not in body
Loading
Loading