Skip to content

feat(secrets): mediate Custom-secret API calls from member chats - #23756

Closed
RohanK6 wants to merge 2 commits into
mainfrom
feat/mediated-secret-egress-v2
Closed

RohanK6 wants to merge 2 commits into
mainfrom
feat/mediated-secret-egress-v2

Conversation

@RohanK6

@RohanK6 RohanK6 commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent in a member conversation can call an owner-approved HTTPS API with a stored Custom secret, without the secret ever entering the sandbox.

Today a Custom secret can only reach a tool by being injected into an MCP server's environment at launch (secret://NAME). An agent in chat has no way to make a single authenticated call to, say, a webhook or a ticketing API with a key the owner stored, short of the owner wiring a whole MCP server for it. Issue #8628 asks for a mediated path: the agent names the secret and the request, the host injects the value and sends it.

This replaces #10383, which was built on the member-proof model that #11780 removed (member_proof_header_value, issue_member_session_proof) and could no longer merge. This PR is a rebuild on the current caller-identity model, not a port of that one.

Why it matters

Without it, owners either hand the raw key to the agent (it lands in the transcript and the sandbox) or build an MCP server per API. A host-mediated call keeps the key in the vault, keeps the destination under the owner's control, and keeps each call behind an approval.

Not a goal

  • Reading API responses. The tool is write-only (POST/PUT/PATCH/DELETE) and every call returns the same fixed result, so a reflected credential has no channel back into the sandbox. Returning bodies is a separate decision.
  • Windows support. The trust argument depends on an attested Unix socket that Windows does not have; there the tool refuses explicitly.
  • Making the tool available by default. kirocrew-secrets is opt-in like the other assignable sets.

What changed (motivation → approach → change)

End-to-end flow:

owner:  kirocrew secrets authorize NAME https://api.example.com [--header X-Api-Key]
          -> signed policy in <data home>/secret-request-policy/ (masked in every sandbox)

agent (member chat) -> call_api_with_secret(secret_name, method, url, headers, query, json_body)
  -> ACP permission prompt -> owner approves
       -> approval mints a single-use capability bound to (session, tool_call_id, exact args)
  -> kirocrew-secrets MCP stub (in sandbox)
       -> owner-only dashboard Unix socket; checks the answering peer is the gateway
          (SO_PEERCRED principal + published pid/start-token) before sending anything
       -> POST /api/mediated-secret-capability   (claim the capability for this call)
       -> POST /api/mediated-secret-request      (consume it; X-Mediated-Secret-Capability)
  -> gateway: internal secret + attested member scope (member_request_scope) required;
       Global chat (no member store) refused 403
       -> verify signed policy, exact-origin match, link_unfurl.vet_unfurl_url
          (public-address vet) + pinned_connector (connect only to vetted IPs),
          inject secret, send over aiohttp, cap redirects/timeouts
       -> fixed withheld result back to the agent

Caller identity. Main's current model is member_request_scope: the internal secret plus a transport attestation of X-Session-Key (session_key_is_attested: peer ancestry, or the signed per-session token on pooled backends). Both new routes are strict internal paths and use it, so a process that only read the loopback secret and a session key is refused. That answers the earlier GPT finding that the documented member path could not mint the proof it needed: there is no separate proof to mint now; the approval-minted capability is the per-call binding, and it is only issued when the call goes through hooks.on_tool_call, which is why the server has no autoApprove and doctor never blanket-allows it.

Policy integrity. The policy is signed with a gateway-certified key minted after bind (secrets_mediation/signing_root.py, kicked off in both gateway entrypoints so the listener never waits). The key, policy and authorize lock live in one directory that every sandbox tier masks whole and that is precreated before any spawn, so publications rename inside it and never over a mount point.

Windows. #10383 used unix_socket_urlopen unconditionally, which fails opaquely on Windows. The stub now returns an explicit unsupported-platform error there, gated on platform_compat.IS_WINDOWS (not hasattr(socket, "AF_UNIX"), which modern Windows Python passes).

Other pieces: the secrets authorize CLI (cli_commands_secrets.py, parser in cli_parser_admin.py), capability registry (mediated_request_capability.py), mint/revoke wired into both approval transports (acp/client_permissions.py, acp/session_handle_permissions.py), registry/discovery/cleanup entries for the new opt-in server, secret-request-policy added to the agent file-tool deny list, a short two-sentence Custom-secrets card copy in all 13 catalogs that labels kirocrew secrets authorize as a terminal command, and docs in docs/system-specs/modules/security.md.

SSRF and transport. Dispatch has no URL vet or transport of its own: it calls link_unfurl.vet_unfurl_url (the same vet link previews, the remote MCP probe and calendar use) and sends through pinned_connector, so the connection can only reach an address the vet approved. No new HTTP dependency.

Grant lifetime. An approved grant waits for its call to reach the shared kirocrew-secrets backend, which runs calls one at a time with each padded to its deadline. So a pending (approved, unclaimed) grant lives for the bounded queue depth times the per-call budget, and a claimed grant gets the short 30 s redemption lifetime. A call queued behind a 60 s call is no longer refused. Cancellation and single use still hold.

Backwards compatibility

Compatible: the server is opt-in and new, the CLI subcommand and routes are new, and the existing secret:// launch injection is untouched.

Removes nothing: the diff only adds a server, routes, a CLI subcommand, a masked directory and copy; no existing key, path or behavior is narrowed.

Tests

  • test/test_mediated_request_dispatch.py: method allowlist, exact-origin match, userinfo/redirect/timeout handling, vault read only after policy checks, and the withheld constant for every post-send outcome.
  • test/test_mediated_request_dispatch.py also covers the shared vet: a private/loopback target is refused through vet_unfurl_url, and the send uses pinned_connector for the vetted address.
  • test/test_mediated_request_policy.py, test/test_mediated_request_provenance.py, test/test_mediated_signing_root.py: signature verification, torn/unsigned policy refusal, post-bind key mint.
  • test/test_secrets_authorize_cli.py: add/remove/reset, refusal without the gateway-owned directory, publication only inside the hidden directory.
  • test/test_mediated_secret_request_handler.py: internal-auth, attested member scope, Global refusal, capability claim/consume/replay, bounded body read across multiple chunks, and a pending grant that outlives a queued 60 s call while a claimed grant keeps the short TTL.
  • test/test_mcp_secrets.py: stub peer verification, payload caps, Windows refusal.
  • test/test_transport_permission_floor.py: approval mints the capability and revokes it when the answer write fails.
  • test/test_cli_mcp_doctor.py::test_auto_fix_never_blanket_allows_mediated_secret: doctor never pre-approves @kirocrew-secrets.
  • Contract updates: composition lazy-import table, dashboard composition census (311 MCP routes, the signing-root kick in both boots), sandbox leaf-only counts (+1 per tier for the masked directory), security package line budget (+3 for one deny-list entry), MCP registry/shared-dispatch tests.
  • website/src/pages/settings/SecretsPanel.test.tsx: new card copy.

Local run on the head: 800 passed across the feature, CLI, doctor, link-unfurl, secrets and composition-contract suites, plus 63 in SecretsPanel.test.tsx; mypy src/kiro_crew/ clean; flake8, black, isort clean on changed files; file-line-cap, agent-SDK boundary, sync-IO-in-async, ACP fixture and lockdown gates pass; i18n check and parity pass.

Manual verification

Not run end to end against a live upstream API on this host. The dispatch, handler and stub paths are covered by the tests above with the network and vault faked.

Screenshots / video

Custom secrets card with the updated copy:

Custom secrets card, light

Dark

Custom secrets card, dark

Related Issues

Fixes #8628

Supersedes #10383.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

The owner authorizes a Custom secret for one exact https origin with
`kiro-crew secrets authorize`. An agent in a private member conversation
can then call that API through the opt-in `kirocrew-secrets` MCP tool
(`call_api_with_secret`). The gateway reads the vault, injects the value,
runs the SSRF-checked request and returns a sanitized result, so the
secret never enters the sandbox.

Caller identity uses the current model on main: the MCP stub forwards
over the loopback transport with the internal secret, and the host
routes accept only an attested member session (`member_request_scope`).
Each call also redeems a single-use capability minted by the ACP
approval for that exact tool call, so a direct member call that skipped
the approval gate cannot reach the egress route. The forwarder talks only to the owner-only
dashboard Unix socket after checking the answering peer is the gateway.
Windows has no such attested channel, so there the tool returns an
explicit unsupported-platform error instead of an opaque socket failure.

By default the result is a fixed constant that reveals nothing about
the upstream response. The owner can opt an origin into the real
response with `secrets authorize --return-body`.

Fixes #8628
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 4779ec730dcf4ef9563b77091f02b1407cc9520b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level blocker: the capability is minted only on an explicit approval, bound to the exact arguments and usable once, so every unsupported path fails closed.

Notes

  • The capability is minted only in the two ACP approve_tool transports. On a harness or grant path that skips them (a remembered "always allow", or a backend whose gate runs as a hook), every call returns 403 "no matching approved tool call". Name which backends support the tool in security.md, so this doesn't get reported as a bug.
  • The pending-grant TTL (_QUEUE_DEPTH * _QUEUED_CALL_BUDGET_SECONDS, about 44 min) is tied to the stub's queue depth and timeouts by a test only. Deriving the TTL from those same constants would stop the three numbers drifting apart.

[DESIGN-REVIEWED] 4779ec7

Description read

[DESCRIPTION-READ] ebfc6c7d816a5a1a616df876ac87df2ec5ec4c9a54582b691bb02bc165fa2aa6

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

UX-level review of 4779ec730dcf4ef9563b77091f02b1407cc9520b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

cannot evaluate: missing a screenshot of the copy this PR ships. Both committed screenshots show an older, longer Custom-secrets paragraph, not the new custom_description string.

Evidence gaps

  • New Custom-secrets description (settings…custom_description, the only user-visible change): the diff ships "Encrypted keys for MCP servers and .env settings. Reference one as secret://YOUR_KEY; the value is never shown in chat. To let the agent call one approved API with a secret, run the terminal command kirocrew secrets authorize."
    • temp-screenshots/secrets-custom-description/secrets-custom-description-dark.png and …-light.png (shot-01, shot-02) render a different, older string instead: "Encrypted secrets, never shown in chat… gateway-proxied member conversation — Kiro Crew injects the value host-side… (a default Global chat is refused)."
    • The blind read judged that stale text ("I could not follow most of it"), so nobody has read the shipped wording.
    • To close the gap, re-run website/scripts/capture-secrets-custom-description.mjs against HEAD and commit both theme captures again.

Notes

  • "run the terminal command kirocrew secrets authorize" leaves out the arguments the command needs. Write it as kirocrew secrets authorize NAME https://api.example.com, or link to the setup guide, so an owner can actually run it.
  • In the blind read, "the agent" and "Kiro Crew" seemed to be two different actors. The new string uses only "the agent", so check in the fresh capture that the confusion is gone.

[UX-REVIEWED] 4779ec7

Description read

[DESCRIPTION-READ] de3deacb844ac1476780b38d0e4db5297bed0432fe274299b3a1355dbfe6305e

That sha256 names everything this verdict read: the PR description, plus the 5 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 4779ec730dcf4ef9563b77091f02b1407cc9520b — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

No blocker. The tool is opt-in, the defect has a linked issue (#8628), and the one heavier-than-needed layer (policy signing) can be removed later.

Notes

  • Item 5 — oversized: provenance.py itself says the directory "is a sandbox HIDDEN leaf, so no agent subprocess can read or replace the key, or read or write the policy". That leaves the HMAC guarding only a policy file planted before the mask existed, and sandbox_precreate plus the CLI's "refusal without the gateway-owned directory" already cover that case. Subtraction: delete secrets_mediation/signing_root.py, the key-certification and HMAC paths in provenance.py, and _kick_mediation_signing_root_mint from both gateway entrypoints. Keep the precreated hidden directory as the integrity control. Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (10 items) — 8 justified

Intent: let an agent in a member chat make one owner-approved HTTPS write with a stored Custom secret, without the secret entering the sandbox. ADDITION.

  1. New opt-in kirocrew-secrets server with a call_api_with_secret write-only tool — justified
  2. New kirocrew secrets authorize NAME ORIGIN [--header] terminal command — justified
  3. Each approval mints a single-use capability tied to that tool call, and toolCallId is carried to the backend — justified
  4. Two internal routes that need attested member scope; Global chat is refused — justified
  5. Owner policy signed by a gateway-certified key, minted after every boot — oversized
  6. New secret-request-policy/ directory, masked in every sandbox tier and on the file-tool deny list — justified
  7. Explicit unsupported-platform refusal on Windows — justified
  8. Custom-secrets card copy shortened in 13 locales, dropping "injects the value at launch" — rides along
  9. Approved grants wait out the call queue; a claimed grant keeps a 30 s lifetime — justified
  10. Committed screenshots and capture script — justified

[FIRST-PRINCIPLES-REVIEWED] 4779ec7

Description read

[DESCRIPTION-READ] 724549cb0f45b6a5a806edf649090a531b8f08e3996373b3368f3bd84c268d16

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 4779ec730dcf4ef9563b77091f02b1407cc9520b — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4779ec7

Verdict parsed from the review's SHA-scoped output markers for commit 4779ec730dcf4ef9563b77091f02b1407cc9520b.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 4779ec730dcf4ef9563b77091f02b1407cc9520b false-positive: <reason, 20 to 500 characters>

"mediated_secret_authorize succeeded but its success audit could not be recorded"
)
if args.remove:
print(f"Removed mediated-request authorization for {name!r}.")
if args.remove:
print(f"Removed mediated-request authorization for {name!r}.")
else:
print(f"Authorized {name!r} for {authorizations[name]['origin']} (policy signed).")
ev = authz[-1]
assert ev["outcome"] == "ok"
assert "MY_KEY" in ev["resources"] and "authorize" in ev["resources"]
assert "api.example.com" in ev["resources"]
@github-actions

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/sandbox_leaves.py

  • src/kiro_crew/sandbox_precreate.py

  • src/kiro_crew/security/paths_lists.py

  • src/kiro_crew/security_posture.py

  • No reasoning template for 4d9075f yet.

How to clear this check:

  1. The PR author posts the template below as a PR comment, with
    every field filled (N/A needs a reason). Keep the
    Head commit line: it must name the current head SHA.
  2. The check turns green within a minute, with no push.
  3. A new push resets this check: post it again for the new head.

Only the author's comment counts this way. A reviewer can instead
paste the filled template into an "Approve" review on this head.
Merging still needs a reviewer's approval.

## Sensitive change review
- Head commit: 4d9075f9486b2005c134857359e11671d06e251e
- What rule changed:
- Before -> after (what was allowed/blocked, now):
- Worst case if wrong (breaks commands / leaks secret / locks user out):
- Evidence checked (which sandbox result proves it):
- No regression:
  - Tools still work (which tools/commands were run, result):
  - Backward compatible (old config / old data / old callers still work, how checked):
  - Existing tests (which suites passed on this head):
- How to undo:

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 24, 2026
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging 4779ec730dcf4ef9563b77091f02b1407cc9520b. 1 of 3 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/acp/client_permissions.py:322 -- Capability is redeemable before approval commits

capability_token = mediated_request_capability.mint_for_gate_event(
Trigger: An attested member-runtime caller claims the token while approve_tool waits for the ACP write lock; stopping the member-bound subagent withdraws approval while that wait continues.
Outcome: The caller can consume the capability and start credential-bearing egress before the withdrawal check runs. Failed-write cleanup also removes only pending grants, leaving claimed grants active. Both approval transports share this race.
Anchor: backend-security-controls
Fix: Mint under the write lock after the final approval checks, immediately before writing; revoke matching pending and active grants when delivery fails.

BLOCKING -- test/test_mediated_secret_request_handler.py:796 -- Lifetime tests replace the worker-wide monotonic clock

monkeypatch.setattr(cap.time, "monotonic", lambda: clock[0])
Trigger: Either lifetime test, at lines 796 and 812, patches cap.time, which is the shared standard-library module, then advances its fake clock by thousands of seconds.
Outcome: Unrelated timing consumers in the pytest worker observe the frozen and jumping clock rather than elapsed time, violating their deadline calculations during the patch.
Anchor: tests-are-deterministic
Fix: Replace the capability module’s own time binding with a fake-clock namespace that delegates other attributes to the real module.

BLOCKING -- test/test_mediated_request_dispatch.py:391 -- Correct deadline handling fails under scheduling delays

assert time.monotonic() - started < 0.1
Trigger: A loaded worker is descheduled for over 100 ms between the timestamp reads around the already-expired deadline call.
Outcome: Correct immediate-return behavior fails the test. The elapsed-time ceiling at line 360 and remaining-budget assertion at line 378 likewise make passing depend on worker scheduling.
Anchor: tests-are-deterministic
Fix: Assert the scheduled waits and cancellation behavior using a module-local controlled clock instead of real-time execution ceilings.

[BLOCK-MERGE] 4779ec7
[GPT-REVIEWED] 4779ec7

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F2: This is a determinism-class flake, a timing degradation inside one worker while the patch is active, so the harm itself is LOW to MEDIUM. cap.time is the stdlib module (src/kiro_crew/mediated_request_capability.py:10), and the patch at test/test_mediated_secret_request_handler.py:796 and :812 swaps monotonic on it for the whole worker. The anchor rule tests-are-deterministic carries blocking: true in .review-base-rules/AUTOSDE.yaml:369-370, and that flag outranks any weighing.

F3: Also a determinism flake. The test asserts real-time upper bounds: <0.1 at test/test_mediated_request_dispatch.py:391, <5.0 at :360, and the 3.0 < pads[0] floor at :378. A loaded worker can miss them. The anchor is the same blocking rule (.review-base-rules/AUTOSDE.yaml:369-370), so it stays upheld.

F1 (fenced): client_permissions.py:322 mints the capability before _send_response waits for the write lock. The withdrawal check before_write runs only inside that wait. On failure, the finally block calls only revoke_pending, so a grant that was claimed during the wait survives. The claim-during-wait sequence is ordinary concurrency, not an extreme condition combination.

[ADJUDICATION] 4779ec730dcf4ef9563b77091f02b1407cc9520b total=2 uphold=2 downgrade=0
UPHOLD F2 test/test_mediated_secret_request_handler.py:796 reason=autosde-blocking-rule
UPHOLD F3 test/test_mediated_request_dispatch.py:391 reason=autosde-blocking-rule
[GPT-ADJUDICATED] 4779ec730dcf4ef9563b77091f02b1407cc9520b

[ADJUDICATION-FENCED] 4779ec730dcf4ef9563b77091f02b1407cc9520b fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/acp/client_permissions.py:322 -- The token is minted before the awaited write-lock recheck and only pending grants are revoked when the write fails, so a claim made during that ordinary await window keeps a live credential-bearing grant after the approval is withdrawn.
[GPT-ADJUDICATED-FENCED] 4779ec730dcf4ef9563b77091f02b1407cc9520b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 4779ec730dcf4ef9563b77091f02b1407cc9520b false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- ✅ PASS

Which legitimate operations does 4779ec730dcf4ef9563b77091f02b1407cc9520b newly refuse? Updated in place on each push. A script-confirmed regression blocks; the model proposes candidates and never decides a refusal.

Verdict basis: adjudicated, zero confirmed regressions.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 11 classified, 0 newly refused, 11 still allowed.
  • ubuntu-latest (platform posix): 11 classified, 0 newly refused, 11 still allowed.
  • windows-latest (platform windows): 9 classified, 0 newly refused, 9 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: PASS

Reason: The only existing guards this change makes stricter are path-based. It adds a new secret-request-policy leaf to the agent file-tool floor (_CREW_SECRET_LEAVES) and to the sandbox mask/precreate lists. The shell deny composite does not match paths in command text (security/paths.py:628), so the shell rows are neighbour probes that should come back unchanged. The file-tool floor and the sandbox mask can't be classified, so that gap is named below. Everything else in the diff is a new opt-in surface: the kirocrew-secrets MCP server, the /api/mediated-secret-* routes and kirocrew secrets authorize. None of it narrows an existing operation.

TIGHTENING: Agent file-tool floor and sandbox hidden-leaf mask now cover the crew-home secret-request-policy directory -- they refuse an agent reading the policy-signing key or writing its own egress allowlist: + # Mediated-secret signing key + owner-signed egress policy: writable, it would let an / + # agent authorize its own origin. Only the gateway and owner CLI open it, directly. / + "secret-request-policy", (src/kiro_crew/security/paths_lists.py), mirrored by + _SECRET_REQUEST_POLICY_LEAF, in _CREW_HIDDEN_LEAVES (sandbox_leaves.py) and _CREW_PRECREATE_HIDDEN_DIR_LEAVES (sandbox_precreate.py).

ADJUDICATED: 14 candidates, 0 confirmed newly-refused

PLATFORM COVERAGE: posix: ~/.kiro/crew/... reads and listings, grep over the leaf name, the .venv/bin/python pytest run and an ordinary curl read. These probe the posix spelling of the crew data-home parent the new leaf sits in. windows: the PowerShell $env:USERPROFILE\... and cmd %USERPROFILE%\... config reads, and the .venv\Scripts\python.exe test run. These cover the drive/backslash and %VAR% spellings of the same parent. any: the existing kirocrew secrets import [--apply], the new kirocrew secrets authorize forms (--remove, --header) and kirocrew mcp-secrets. These strings carry no paths or separators. The diff assumes no interpreter, executable name or environment variable specific to one platform in any shell-visible check. The _CREW_HOME_PREFIXES × leaf derivation is posix-spelled (f"{prefix}/{leaf}"), but it feeds only the file-tool path gate, so it falls under UNADJUDICATED.

UNADJUDICATED:

  • Guard: is_sensitive_path / is_sensitive_write_path, the agent file-tool floor. _SENSITIVE_HOME_DIRS is extended through _CREW_SECRET_LEAVES, and _KEYSTONE_ARTIFACT_PARENTS derives from the same list. Call path: an agent file-tool call (read/write/edit) goes through hooks.on_tool_call and then security.paths.is_sensitive_path(resolved). A path equal to <crew-prefix>/secret-request-policy, or starting with it plus a separator, is refused. Inputs I would have submitted:
    • a file-tool read of ~/.kiro/crew/config.json, and of C:\Users\<u>\.kiro\crew\config.json
    • a read of ~/.kiro/crew/sessions.db
    • a read of a lookalike sibling such as ~/.kiro/crew/secret-request-policy-notes.md, to confirm the match is anchored to the directory boundary and not a raw prefix
    • a read of a *.tmp or *.lock file directly under ~/.kiro/crew/
      The last one is not new: the crew-home root was already an artifact parent through the existing bare leaves. No verdict is available for any of these.
  • Guard: the sandbox bind-mask (_CREW_HIDDEN_LEAVES) and spawn-time precreate (_CREW_PRECREATE_HIDDEN_DIR_LEAVES). Call path: every agent spawn runs sandbox setup, which precreates <crew-home>/secret-request-policy and masks it inside the namespace. Inputs I would have submitted:
    • a sandboxed ls ~/.kiro/crew/ that should still list the other entries
    • a spawn on a fresh install where the crew home is read-only or full, checking that precreating the new directory doesn't stop the spawn
      No verdict is available for either.
  • Guard: the new mediated endpoints' member-scope plus single-use capability checks (handlers/mediated_secrets.py, mediated_request_capability.py), and _STRICT_INTERNAL_API_PATHS. These are new routes with no earlier legitimate callers. The approval-path mint/revoke hooks in acp/client_permissions.py and acp/session_handle_permissions.py run on every tool approval and rejection, but they never refuse an approval. A risk I can argue but not confirm: if mint_for_gate_event or invalidate_for_gate_event raised for a gate event of an ordinary tool, every approval or rejection would fail. The PR says both are a no-op for every tool except kirocrew-secrets. An ACP flow can't be written as a shell row.

[SCOPE-REVIEWED] 4779ec7

Address the first review round on the mediated-secret call:

- Route the mediated dispatch through link_unfurl.vet_unfurl_url and
  pinned_connector instead of a second SSRF vet, DNS pin and
  requests/urllib3 transport; drop secrets_mediation/ssrf.py and the
  direct urllib3 dependency.
- Give an approved, not-yet-claimed grant a lifetime that covers the
  bounded shared-dispatch queue, so a call queued behind a 60 s call is
  no longer refused; a claimed grant keeps the short redemption TTL.
- Point the feature-map secrets row at handlers/mediated_secrets.py.
- Shorten the Custom-secrets card copy in all 13 catalogs and label
  `kirocrew secrets authorize` as a terminal command.
- Re-pin the dashboard composition census for the two new routes and
  the post-bind signing-root kick.
@RohanK6

RohanK6 commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 4779ec7
  • What rule changed: One new data-home directory, secret-request-policy/, is added to the crew hidden leaves (sandbox_leaves.py), precreated as a hidden directory before every spawn (sandbox_precreate.py), and added to the agent file-tool secret deny list (security/paths_lists.py). secrets_mediation/dispatch.py is registered in NON_EGRESS_REDACTION_MODULES (security_posture.py) as a refusal gate.
  • Before -> after (what was allowed/blocked, now): Before, the directory did not exist and nothing read it. After, every sandbox tier masks the whole directory (not readable or writable by agent processes), and the agent file tools refuse it. Only the host gateway and the owner kirocrew secrets authorize CLI open it. No existing path gains or loses access. The posture entry only classifies the dispatcher: it runs both redactors over agent-supplied URL/body/headers/query only to refuse the request when either would change a value, before any vault read, and returns a fixed constant, never redacted text.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): If the mask failed, an agent process could read the policy-signing key or rewrite the policy, so it could authorize its own origin for a Custom secret. If the precreate failed, a key or policy published after a sandbox started would sit outside the mask. A wrong posture classification would only mislabel a module that returns no redacted text. No existing command or user path is touched, so nothing existing breaks and no one is locked out.
  • Evidence checked (which sandbox result proves it): The sandbox leaf-only census tests count one more hidden leaf per tier, and test/test_sandbox_precreate_secret_dirs.py passes with the new directory precreated before spawn. test/test_secrets_authorize_cli.py proves the CLI refuses to publish without the gateway-owned directory and only publishes inside it. test/test_mediated_request_provenance.py and test/test_mediated_signing_root.py prove a tampered or unsigned policy is refused.
  • No regression:
    • Tools still work (which tools/commands were run, result): The full targeted suites ran on this head (CLI, doctor, MCP secrets stub, secrets handler, link unfurl, dashboard composition contract): 800 passed. SecretsPanel.test.tsx: 63 passed. flake8, black, isort and mypy are clean on the changed files, and the feature-map gate passes.
    • Backward compatible (old config / old data / old callers still work, how checked): The directory is new and the opt-in kirocrew-secrets server is new. secret:// launch injection and every existing deny or mask entry are unchanged (the diff only adds entries). Existing secrets handler and secret:// resolution tests pass unchanged.
    • Existing tests (which suites passed on this head): test_mediated_, test_mcp_secrets, test_secrets_authorize_cli, test_secrets_handler, test_link_unfurl, test_check_feature_map, test_cli, test_cli_doctor, test_dashboard_server_composition_contract*, test_sandbox_precreate_secret_dirs, SecretsPanel.test.tsx.
  • How to undo: Revert this PR's two commits. That removes the leaf, precreate, deny-list and posture entries together with the feature. Any leftover secret-request-policy/ directory in a data home is inert once nothing reads it, and can be deleted by hand.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 24, 2026
@RohanK6

RohanK6 commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #23843: the same change rebuilt as one commit on current main, with the round-2 review fixes (capability minted under the ACP write lock and revoked pending or claimed on an undelivered answer, module-local test clocks, no secret-derived staging names). A third commit here would have broken the two-commit limit.

@RohanK6 RohanK6 closed this Oct 24, 2026
@bolichen97
bolichen97 deleted the feat/mediated-secret-egress-v2 branch November 6, 2026 07:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(secrets): mediate custom-secret API calls from chat

2 participants