Skip to content

fix(apps): give an in-process app its app token after the secret left its folder - #35533

Merged
bolichen97 merged 1 commit into
mainfrom
pearcekieser/inproc-app-secret-and-agent-mcp-token
Nov 12, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
pearcekieser/inproc-app-secret-and-agent-mcp-token

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app whose backend runs in the gateway process can call the gateway REST API with an app token again, and the first load of its hooks moves the folder secret of an older install out of the folder.

An app with backend.hooks and no entryPoint runs in the gateway process, so the gateway never spawns a backend for it. Since #34762 the secret lives in member-records/app-secrets/, the gateway never accepts the folder .app_secret, and only a backend spawn moves the secret of an older install. An app that runs in the gateway process gets no secret through any channel. An app installed before #34762 gets 403 invalid secret on every POST /api/apps/<name>/token, and a disable and enable does not change that.

Why it matters

Every third-party app that runs its backend in the gateway process and calls the gateway REST API stops working after the update to #34762. On one host, one app got 196 refusals in 97 minutes and no grant.

Not a goal

  • A credential for the agent MCP servers of an app (stdio servers that kiro-cli starts in the agent sandbox). They still get no secret and no app token. The API reference states this gap. A separate issue and PR will let a third-party app declare agentTools that the owner approves, so the call goes through the gateway and no sandboxed process holds a credential. The linked issue compares this with a scoped token per agent session.
  • A change to the token exchange route, the token lifetime, or what an app token can reach.
  • Any read of the old folder file. The gateway still refuses its value.

What changed (motivation → approach → change)

Every token exchange from such an app fails because the gateway moves a secret only when it spawns a backend, and code in the gateway process has no channel for the secret. The hooks now get the token itself, and the hook load does the move:

Part Change
ctx.app_token() A new AppContext method returns the token that POST /api/apps/<name>/token issues, with no secret, behind the same owner-enable marker. It returns "" after a disable. The gateway audits each call as app_token_exchange with source app_context.
ctx.gateway_origin() A new AppContext method returns the loopback origin a spawned backend gets in KIROCREW_GATEWAY_ORIGIN, read from KIROCREW_BOUND_PORT and KIROCREW_BOUND_HOST. It returns "" when the gateway is bound to one specific interface. Without it a hook has no base_url, and the Python client falls back to KIROCREW_PORT or port 5476, which can be another gateway. The new apps/gateway_origin.py holds the one copy of this logic, and apps/backend.py now calls it for the spawn environment, with the same output for every port and host value.
Hook load Before the hooks load, the boot and enable paths run hooks_integration._prepare_hook_load. It calls replace_legacy_app_secret, the same one-time move the spawn does: store a new secret and remove the folder file.
Seam level APP_SDK_LEVEL is 5 in apps/app_sdk_level.py and app-sdk/sdkLevel.ts, and the adoption pin tool (scripts/adoption_pin.py) maps ctx.app_token and ctx.gateway_origin to level 5.
Docs The API reference documents ctx.app_token() and ctx.gateway_origin(), the Python client setup for hooks (build no client when the origin is "") and the agent MCP server gap. The app-kit-platform and dashboard-token-auth specs name the hook load as a place where the secret moves.

The starting idea was an App Kit call that returns the secret. Code in the gateway process needs the secret only to exchange it for a token, so the context returns the token. The secret never leaves the gateway record, so a hook cannot pass it to a child process in a sandbox. The context is the proof of identity, because the gateway builds each context for one app.

Backwards compatibility

Compatible: the exchange route, the spawn path and stored secrets do not change, and an app that reads .app_secret is refused as on main.

Reader: packages/kirocrew-client-py/kirocrew_client/client.py:_read_app_secret -- app -- reads the folder file only as a fallback for an older gateway, and the gateway refuses that value on main already
Reader: src/kiro_crew/apps/manager_install.py:update_app -- app -- keeps the folder file only when one exists, and the moved secret is not in the folder (test_enable_moves_the_secret_of_an_app_installed_and_then_updated)
Reader: src/kiro_crew/dashboard/token_auth_tokens.py:replace_legacy_app_secret -- app -- a later spawn or hook load finds the stored secret and returns it unchanged (test_enable_moves_the_secret_of_an_app_installed_and_then_updated)

Tests

  • test/test_app_in_process_secret.py installs, updates, enables and disables a real app with backend.hooks and stubs only the hook body. Boot and enable both move the secret of an older install, also after an update that keeps the folder file. The hook context mints a token whose app claim is the app, and a context kept past a disable mints nothing. Six cases check that ctx.gateway_origin() uses the bound port and not KIROCREW_PORT, and returns "" for a specific interface or a missing, zero or invalid port.
  • test/test_builtin_adoption_pins.py adds the cases that the pin tool reads ctx.app_token and ctx.gateway_origin as level 5.
  • test/integration/test_builtin_adoption_boot.py adopts an app whose backend is only in-process hooks. On main, nothing moved that app's folder secret, so the test read the old file after the restart. Now the hook load on that restart moves it, so the test checks that the folder file is gone and that the gateway holds a new secret. If the adoption lost the file, the app would have no secret and the test fails.

Repeats: 20 runs at -n0, and 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 with test/test_app_trust_enabled.py and test/test_lifecycle_data_dir_off_loop.py as co-tenants, all green. Shuffled order: green with seed 21766, 27 ids.

Proof: PROVEN test/test_app_in_process_secret.py::test_boot_moves_the_secret_of_an_app_installed_before_it_left_the_folder, test/test_app_in_process_secret.py::test_enable_moves_the_secret_of_an_app_installed_and_then_updated, test/test_builtin_adoption_pins.py::test_the_pin_tool_finds_every_seam_above_level_one[manifest7-files7-uses7], test/test_builtin_adoption_pins.py::test_the_pin_tool_finds_every_seam_above_level_one[manifest8-files8-uses8] (head 57ef4fa)

Gate proof: tree 8e96a5293da5; ran 24; skipped none

Manual verification

N/A: unit coverage is sufficient. The tests drive the real install, update, enable, boot and disable paths and the real token validation, with only the hook body stubbed.

Screenshots / video

Why no screenshot: the only frontend change is the exported seam level constant, which renders nothing.

Related Issues

Fixes #35532

Regression from #34762.

Sibling sweep

Swept: git grep -nE "replace_legacy_app_secret|KIROCREW_PROXY_SECRET|read_app_secret" -- src/
Sibling: src/kiro_crew/apps/backend.py -- not affected -- the spawn path moves the secret and hands it over in KIROCREW_PROXY_SECRET
Sibling: src/kiro_crew/apps/builtins/dev_fleet/http_api.py -- not affected -- a spawned backend that reads KIROCREW_PROXY_SECRET
Sibling: src/kiro_crew/apps/manager_external.py -- not affected -- a self-managed app gets its new secret in its registration response

Pattern harvest

Rule candidate: review-prompt
Pattern: a credential moved to a store no sandbox reads needs a delivery channel for every runtime shape an app can have (spawned backend, self-managed, hooks in the gateway process, agent MCP servers), not only the shape the change was tested with.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check: the diff adds or changes no user-visible control. The only frontend change is the APP_SDK_LEVEL constant (4 → 5), so the missing screenshots leave no evidence gap.

[UX-REVIEWED] 57ef4fa

Description read

[DESCRIPTION-READ] 51b77fda74d3d6a780fa499ab73e7e2e34d0582fa4826ce4d9160e7acd35a5e1

That sha256 names everything this verdict read: the PR description, plus the 3 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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 57ef4fa4e29d6f9fc40c05063260980b57044930 — 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

Nothing blocks. One rider: ctx.gateway_origin() fixes a separate wrong-port problem, not the 403 regression the Goal names.

Notes

  • Item 2: rides along. The Goal is "call the gateway REST API with an app token again", and before fix(apps): keep an enabled app's secret and approved grants out of its folder #34762 a hook could already reach the gateway through the client's KIROCREW_PORT/5476 fallback. The description's case ("which can be another gateway") is a separate problem from the refused secret. Subtraction: defer AppContext.gateway_origin and its _CONTEXT_SEAMS row to their own fix, unless a hook on a non-default --port shows that the token cannot be used without it.

What this change ships

Inventory (7 items) — 6 justified

Intent: a FIX. A third-party app whose backend runs as hooks in the gateway process can get an app token again after #34762.

  1. Hooks can get an app token from ctx.app_token() without holding a secret — justified
  2. Hooks can read the gateway's loopback origin from ctx.gateway_origin() — rides along
  3. On boot or enable, the hook load moves an older install's folder secret into the gateway's store — justified
  4. Each in-process token request is audited as app_token_exchange with source app_context — justified
  5. Seam level goes from 4 to 5 in Python and TS — justified
  6. The adoption pin tool maps the two new seams to level 5 — justified
  7. Spawn-origin logic moves into apps/gateway_origin.py and is shared with the context — justified

[FIRST-PRINCIPLES-REVIEWED] 57ef4fa

Description read

[DESCRIPTION-READ] eecb07f1367166d85ae05150cae8c05dda2dc91e5f6906120e21197cc143b13f

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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns. Hooks that run in the gateway process now get a minted app token instead of the secret. The secret moves on the hook-load path through the same one-time replace_legacy_app_secret. The origin logic now has one owner. Nothing taken away breaks a reader in this tree.

Notes

  • Once gateway_origin.py is the only copy, the spawn path's warning branch re-reads KIROCREW_BOUND_HOST itself. Having loopback_gateway_origin also return the reason it refused would keep the two from drifting.

[DESIGN-REVIEWED] 57ef4fa

Description read

[DESCRIPTION-READ] 7b7b205ec7813ec0b35aa2d2c3b2175cd2555ab8626a11b0c8fbe3e009b65fe2

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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 57ef4fa4e29d6f9fc40c05063260980b57044930 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 57ef4fa

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

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 446 lines, more than the 400 it may approve on its own.

The fix achieves its goal. AppContext.app_token() issues the same token as the exchange route, through the same generate_token call, after checking the same owner-enable marker. It is audited, and it returns "" once the app is disabled. Code that runs in the gateway process could already create tokens, so this opens no new trust boundary. Both hook-loading paths (gateway startup and app enable) now call replace_legacy_app_secret through _prepare_hook_load. That move is idempotent, runs under a lock with the spawn path, and catches disk errors (RecordsNotMoved is an OSError). The new loopback_gateway_origin helper behaves exactly like the inline code it replaces in backend.py, and backend.py's warning path still reads the bound-host setting. The seam level is 5 in both the Python and TS constants, and the existing test that keeps them equal still passes. No current source reads the new seam names from a context, so the pin tool's new entries change no built-in app. The tests use the real install, update, enable, startup and disable paths. Most CI was pending or failed on infrastructure (rate limits, merge-base reads), not on the code.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 7c8fb66161 · 446 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 57ef4fa4e29d6f9fc40c05063260980b57044930 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 57ef4fa

Verdict parsed from the review's SHA-scoped output markers for commit 57ef4fa4e29d6f9fc40c05063260980b57044930.

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

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 11, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/inproc-app-secret-and-agent-mcp-token branch 3 times, most recently from 7186993 to a6ef297 Compare November 12, 2026 05:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 12, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/inproc-app-secret-and-agent-mcp-token branch from a6ef297 to 81cfef3 Compare November 12, 2026 06:16
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 12, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/inproc-app-secret-and-agent-mcp-token branch from 81cfef3 to 57ef4fa Compare November 12, 2026 07:45
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/app-kit/api-reference.md and docs/system-specs/modules/app-kit-platform.md (2d4848e -> 9dc068e).

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 12, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Thanks for the fix. The review of this head found no blocking issue, but a maintainer needs to approve it, because it adds a new way to mint a credential.

What the review checked on this head:

  • issue_in_process_app_token uses the same owner-enable marker and the same generate_token(app_name, app=app_name) as the exchange route. It denies by default and writes an audit row whether it grants or denies.
  • _prepare_hook_load runs replace_legacy_app_secret off the event loop, on both the boot path and the enable path, and only after the execution-denied check.
  • The extracted loopback_gateway_origin computes the same origin as the inline spawn block on main.
  • The new tests drive the real install, update, enable, boot and disable paths. Removing the move or the enable check turns them red.

Done well: hooks get a token, not the raw secret. The secret never leaves the gateway record, so a hook has no secret it could pass to a sandboxed child.

Security: on main, an app whose backend runs in the gateway process gets no app token. With this change, hook code gets one from ctx.app_token() without a secret check. The owner-enable marker still gates it, and code in the gateway process could already reach generate_token, so the review found no new trust boundary. Still, this is a wider credential path than main has, so a maintainer decides on it. A maintainer will post the decision here.

Optional:

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the full diff. Fixes #35532.

On scope: issue_in_process_app_token mints with generate_token(app_name, app=app_name), the same call main's POST /api/apps/<name>/token makes (handlers/core.py). So the token carries the same app claim, and _enforce_app_scope confines it to the manifest's permissions.api as before. It is gated on the same owner-enable marker validate_app_secret checks first, so a context kept past a disable gets "", and both outcomes are audited as app_token_exchange / app_context. The grant is no wider than main's, and code already running in the gateway process gets nothing it could not reach before.

The hook load now calls replace_legacy_app_secret, the same move a spawn does. That adds no refusal, because the folder value was already refused. loopback_gateway_origin is the spawn's host logic moved unchanged, and the spawn now calls it, so both paths share one rule. The seam level goes to 5 in both the backend and the website. No regex. LGTM.

@bolichen97
bolichen97 merged commit a6922e6 into main Nov 12, 2026
99 of 100 checks passed
@bolichen97
bolichen97 deleted the pearcekieser/inproc-app-secret-and-agent-mcp-token branch November 12, 2026 10:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 12, 2026
KiroCrewCaptain added a commit to KiroCrewCaptain/kirocrew-app-spec-builder that referenced this pull request Nov 12, 2026
Kiro Crew gave App Kit level 5 to ctx.app_token
(kirodotdev/KiroCrew#35533), and the agentReadOnlyDirs seam
(kirodotdev/KiroCrew#33589) now lands at level 6. Gating on 5 would
move the decision record into a data/trust/ that a level-5 host does
not fence. Raise READONLY_DIRS_SDK_LEVEL to 6, update the docs and
tests that named level 5, and pin that a level-5 host keeps the record
where it gates it.

Co-authored-by: KiroCrewCaptain <312312717+KiroCrewCaptain@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(apps): an in-process app gets no app token after #34762

3 participants