Repository navigation
feat(apps): inject gateway origin into backends - #6599
Conversation
GPT 5.6 Review (fork) — 🔴 changes requested (blocking)Reviewed Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging. BLOCKING -- src/kiro_crew/dashboard/server.py:2315 -- unknown reclaim outcomes trigger a four-minute boot stall FINDING -- docs/app-kit/api-reference.md:962 -- FINDING -- test/test_dashboard_server_startup_coverage.py:476 -- changing [GPT-REVIEWED] 82b2033 Adjudication (Opus 4.8) — is blocking on each finding proportionate?The finding names The finding cites anchor MEDIUM harm: up to a 240s boot stall on Windows on a rare port-collision outcome ( |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed Review detailsI've validated the candidate list (which reported no candidates) and independently examined every changed hunk: the bound-port-gated origin/proof injection in Verified as correct rather than defective: the env vars are read from the gateway's No findings. [OPUS-REVIEWED] 9ca5383 |
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Guard recovery may now die on Windows TIME_WAIT: the exclusive rebind keeps the ~15s ladder the boot path itself deemed too short for that refusal. WatchThe PR's own reservation analysis says an [DESIGN-REVIEWED] 9ca5383 |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (10 items) — 6 justifiedIntent: give every spawned entryPoint app backend a trustworthy address for the gateway that spawned it, so channel-declaring apps can push notifications back — an ADDITION.
Capped at 10: an eleventh rider, the "KiroCrew"→"Kiro Crew" respelling of two log lines, is declared and mandated by the brand rule. [FIRST-PRINCIPLES-REVIEWED] 9ca5383 |
commented
Aug 29, 2026
|
Status update and one request for a maintainer. Every CI/test check on this PR passes or is skipped except a single Windows test shard: Backend Tests (Windows) (3) (run 33216936703, job 99006265019). Windows shards 1, 2, and 4 pass. That failure is not in this patch. It is a worker crash / timeout in the git-subprocess-heavy test/test_md_notebook.py (worker gw0 crashed with worker restart disabled, e.g. test_sync_refuses_rather_than_pushing_a_subset), none of which this change touches. The diff only modifies src/kiro_crew/apps/backend.py, test/test_app_backend.py, and two docs files - there is no patch-owned test failure. I cannot rerun it as a fork contributor: the re-run-failed-jobs API returns 403 "Must have admin rights to Repository". Could a maintainer please rerun just that one job (Backend Tests (Windows) (3)) once? A single rerun should clear the flake. I am not asking for a rerun-all and I am not claiming CI is green. For reference: the PR is mergeable, head 36abf95, two commits. PR Readiness is still red on one blocking item because maintainer review has not happened yet - review is still required. Thanks. |
left a comment
There was a problem hiding this comment.
Description ↔ code mismatch: the KIROCREW_GATEWAY_ORIGIN_PROOF mechanism is not in this diff
Blocking finding from a Description-vs-code consistency audit. Criterion: the description claims a behaviour that is absent from the code, and the absent behaviour is the security property this PR is advertised on.
The claim
The PR body describes a proof mechanism in six places, including an end-to-end verification claim:
KIROCREW_GATEWAY_ORIGIN_PROOF=HMAC-SHA256(app_secret, origin)hex, injected only when the app has a.app_secret. The child recomputes it with its secret …
- The proof lets a backend distinguish a gateway-minted origin from an inherited or spoofed env value before trusting it as a callback base.
TestGatewayOriginInjection(test/test_app_backend.py): exact origin/proof off the bound port (distinct from the appPORT), proof accepted under the right secret and rejected under a wrong key …
- Verified end to end with an isolated app on port 6777: the backend received the gateway origin and a valid proof …
What the code actually does
src/kiro_crew/apps/backend.py injects exactly two variables:
+ env["KIROCREW_GATEWAY_ORIGIN"] = f"http://127.0.0.1:{int(bound_port)}"
...
+ _proxy_secret = secret_path.read_text().strip()
if _proxy_secret:
env["KIROCREW_PROXY_SECRET"] = _proxy_secret
Across all four changed files, the string KIROCREW_GATEWAY_ORIGIN_PROOF appears 0 times, and there is no HMAC computation. The only hmac token in src/kiro_crew/apps/backend.py is a pre-existing comment about the X-KiroCrew-Proxy header the gateway signs on forwarded requests — a different mechanism, unrelated to this env var.
test/test_app_backend.py's TestGatewayOriginInjection asserts on KIROCREW_GATEWAY_ORIGIN and KIROCREW_PROXY_SECRET only. There is no "accepted under the right secret / rejected under a wrong key" case, because there is nothing to accept or reject.
Why this blocks
The stated security property — that a child can tell a gateway-minted origin from an inherited or spoofed one — does not hold as implemented. KIROCREW_GATEWAY_ORIGIN arrives unauthenticated, so a spoofed env value is indistinguishable from a real one, which is precisely the case the description says is covered. A reviewer reading the body will approve on the assumption that an HMAC binding exists, and the "verified end to end … a valid proof" line asserts observed behaviour that the diff cannot produce.
The docs in this same PR (docs/app-kit/api-reference.md, docs/system-specs/features/app-notifications.md) are consistent with the code — they document KIROCREW_GATEWAY_ORIGIN + KIROCREW_PROXY_SECRET and never mention a proof. So the PR body contradicts both the code and its own docs.
Required change — pick one
- Implement it: inject
KIROCREW_GATEWAY_ORIGIN_PROOF = HMAC-SHA256(app_secret, origin)gated on.app_secretexisting, document it alongside the other two variables, and add the right-secret/wrong-key test cases the body already claims exist. - Or correct the description: delete the proof/HMAC bullets, the
rejected under a wrong keytest claim, and theand a valid proofend-to-end line, so the body matches the actual change — inject the bound-port origin, plus the raw proxy secret when one exists.
Everything else in the description checks out and is not at issue: the bound-port-only guard on KIROCREW_BOUND_PORT, the restrict_to_owner-before-read_text (0600-before-read) ordering, fail-closed omission of the origin, missing-secret silent tolerance, and no-injection for non-entryPoint apps all match the diff and its tests.
Automated Description↔code consistency audit. Only these five classes are treated as blocking: described behaviour absent from code; undisclosed change to user-visible behaviour/API/permissions/security boundary; test-pass claims contradicted by evidence; undisclosed scope beyond what the description says; conflict with spec/docs/an invariant. Wording and style are never flagged.
commented
Sep 4, 2026
Open PR relationship auditThis is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion. Relationship findings
No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit. |
36abf95 to
cb42102
Compare
commented
Sep 8, 2026
|
Rebased onto main Conflicts resolved:
Gates run locally on changed files: isort, flake8, black (both files are in Please review the resolution. A maintainer push makes the maintainer the last pusher, so a second approver is needed under the repo's last-push rule. Reply if anything looks wrong. |
commented
Sep 18, 2026
|
commented
Sep 18, 2026
|
commented
Sep 18, 2026
|
commented
Sep 18, 2026
|
commented
Sep 18, 2026
|
commented
Sep 18, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
commented
Sep 22, 2026
|
The gateway spawns each backend.entryPoint app child with KIROCREW_GATEWAY_ORIGIN, its own http://127.0.0.1:<bound port> address (or http://[::1]:<port> for a v6-loopback bind), so the backend can call back to the gateway (for example POST /api/notifications/push on a declared channel). The origin is built ONLY from KIROCREW_BOUND_PORT, the port this gateway actually owns, and only for the loopback bind shapes: a backend callback carries no Origin header, and the CSRF barrier trusts an Origin-less mutating request only from a loopback peer, so a specific-interface bind omits the origin rather than mint one whose every callback would be refused. With no valid evidence both the origin and its proof are omitted, so a backend that needs a callback base fails closed (and the omission is logged at warning when the app declares notification channels, since dormancy is then operator-visible state). When the app has a .app_secret, the gateway also injects KIROCREW_GATEWAY_ORIGIN_PROOF = HMAC-SHA256(app_secret, origin), hex — a spawn-time attestation that the origin was planted by a gateway holding that secret rather than an inherited or spoofed env value. A secret-less backend gets the origin only. At boot the gateway RESERVES its port — binds and listens, with accept deferred to the SockSite handoff — before the app-backend spawn pass and exports the reserved socket's real name as the evidence: the port is kernel-owned and overlap-proof before any child exists; nothing is served during the pass, so no lifecycle handler can race it; and --port auto is real before the spawn, so boot-spawned backends get the true origin for fixed and auto ports alike. A failed reservation dies before anything spawns; every failure after it — spawn pass, runner setup, serve — runs one unconditional handler that sweeps the backends this boot spawned and closes the socket, so no child ever outlives a boot whose port promise failed. On Windows, an EADDRINUSE with no live holder (the TIME_WAIT signature) stretches the reservation's wait to TcpTimedWaitDelay, because the exclusive bind refuses the port while remnant connections expire and a routine restart must out-wait them. The Windows listener guard (main's rebind-on-dead-listener watchdog) now accepts the SockSite this handoff serves on: bind parameters are captured from the live socket's real name — never wider than the reservation — and recovery rebinds through the reservation's own bind primitive into a fresh SockSite, so a recovered listener carries the same exclusive option set the reservation held. Original feature authored by Diego Magalhaes (dgomesbr). Rebase onto current main, restoration of the origin-proof from the predecessor PR, the port-reservation boot contract, and removal of the pre-read chmod of .app_secret (symlink-following os.chmod flagged in review; the writer already enforces 0600) by Kiro Crew. Co-authored-by: Kiro Crew <noreply@kirodotdev.github.io>
commented
Sep 23, 2026
|
commented
Sep 23, 2026
|
commented
Sep 23, 2026
|
commented
Sep 23, 2026
|
commented
Sep 23, 2026
|
left a comment
There was a problem hiding this comment.
Re-reviewed at head 9ca5383. The blocking description↔code mismatch is resolved by implementing the advertised mechanism: KIROCREW_GATEWAY_ORIGIN_PROOF is injected in apps/backend.py as HMAC-SHA256(app_secret, origin), only when the secret is readable and the origin was itself injected; it is documented in the api-reference table and the app-notifications spec, and the right-key / wrong-key / secret-less / no-evidence cases are pinned by tests that drive the real spawn path. Body, docs and code now agree.
Independently verified the rest: bound-port-only, loopback-only origin ([::1] for v6 binds; specific-interface binds fail closed with a warning for channel-declaring apps); the port reservation (_bind_once: family-resolved, SO_REUSEADDR / IPV6_V6ONLY / SO_EXCLUSIVEADDRUSE, immediate listen) precedes the backend spawn pass; one failure handler sweeps spawned backends and closes the socket; SockSite handoff and ListenerGuard recovery use the same bind primitive; the shutdown sweep survives a list_apps failure. 446 tests across the ten touched test files pass locally; flake8 / isort / brand gate clean; the branch merges cleanly onto current main. Approving.
Residual nits, non-blocking (fine as follow-ups): the config / cli / dev-fleet specs and the mcp_core.py / port_resolution.py docstrings still say _export_bound_port republishes after the reservation, which the dashboard path no longer does; the new KIROCREW_BOUND_HOST variable is undocumented in config.md; app-notifications.md omits the [::1] origin shape; the reservation window vs a different-home peer's reclaim probe stays tracked in #11633. Note for other reviewers: server.py is +229/-22 under git diff -w — the large raw diff is indentation from the try/except wrap.
Problem / Motivation
A
backend.entryPointapp child has no reliable way to learn the address of the gateway that spawned it. The gateway's port can be configured, OS-assigned (--port auto), or changed between generations — so a backend that needs to call back into the gateway (for examplePOST /api/notifications/pushon a declared channel) today has to guess from config, an inherited variable, or a hardcoded default, and every one of those can point at a sibling gateway or at a port nothing listens on.Why it matters
Without a trustworthy callback base, notification-declaring backend apps either cannot push at all or push to the wrong gateway — silent misdelivery that is worst exactly when several gateways or generations coexist on one host. A wrong-port callback is also a credential hazard: a conforming backend authenticates with its per-app secret, so an address that does not belong to its own gateway is a place that secret should never be sent.
What changed (motivation → approach → change)
Goal: hand every spawned backend its gateway's true origin — evidence, never a guess.
KIROCREW_GATEWAY_ORIGIN— set in the spawn env tohttp://<bound host>:<bound port>, built ONLY from the gateway's own bound-address evidence (KIROCREW_BOUND_PORT). The host follows the bind's family:127.0.0.1for IPv4 loopback/wildcard,[::1]for IPv6 loopback/wildcard (exported asKIROCREW_BOUND_HOST=::1— an IPv6-only bind leaves IPv4 loopback seizable). Loopback shapes only: backend callbacks carry no Origin header, which the CSRF barrier trusts only from loopback peers — a specific-interface bind omits the origin instead of minting a refused one. With no valid evidence nothing is injected — fail closed, logged at warning when the app declares notification channels.KIROCREW_GATEWAY_ORIGIN_PROOF— when the app has a readable.app_secret, the gateway also injectsHMAC-SHA256(app_secret, origin)(hex): a spawn-time attestation that the origin was planted by a gateway holding that app's secret. Not a liveness signal; a secret-less backend gets the origin only. The remedy named in bolichen97's blocking review.Port-reservation boot contract (
dashboard/server.py) — the gateway reserves its port (binds AND listens) before the app-backend spawn pass and exports the socket's kernel-assigned name as the evidence. Nothing serves untilSockSitewraps it; early callbacks queue in the backlog:X-App-Secret; a held port fails the boot before anything spawns.SO_REUSEADDRPOSIX-only;IPV6_V6ONLY, so::stays v6-only) plus WindowsSO_EXCLUSIVEADDRUSE— a tightening asyncio never applies.--port autogets a real origin. The socket's name exists before the spawn — true origins for fixed and auto ports alike.The reservation reuses the existing reclaim/retry ladder; on Windows an
EADDRINUSEwith no live holder (TIME_WAIT, where the exclusive bind is refused) stretches the wait toTcpTimedWaitDelayso routine restarts survive; a live holder keeps the fast exit. One failure handler spans the boot pass — spawn, hook wiring, runner setup, serve: any error sweeps the spawned backends (idempotent) and closes the socket, so no child outlives a failed boot.Shutdown hardening — the shutdown sweep runs even when enumerating installed apps fails (
list_appsmoved inside the try whosefinallystops backends).Docs — injected-variables table and security bullets (
docs/app-kit/api-reference.md); freshness, attestation and push-endpoint notes (docs/system-specs/modules/app-notifications.md); reservation-time export passages (config.md,cli.md,dev-fleet.md).Scope note: feature by Diego Magalhaes (@dgomesbr); rebase, proof restoration, the reservation contract, removal of the pre-read
os.chmodof.app_secret, and brand-rule respellings by Kiro Crew.apps/backend.pyis main + the injection block only.mcp_core.pyandport_resolution.pydocstrings state the reservation-time export where readers meet the evidence;pod/runtime.pyscrubs the origin variables at the pod boundary;apps/hooks_integration.pycarries the matching comment.dashboard/listener_guard.py: main's Windows rebind watchdog now accepts theSockSitehandoff — bind parameters read from the live socket's real name; recovery rebinds through_bind_onceinto a freshSockSite, keeping the reservation's exclusive option set.Tests
_bind_onceon an ephemeral port and pins the whole option set — the socket is in the listen state,SO_REUSEADDRon POSIX,IPV6_V6ONLYon an IPv6 bind, and the Windows-exclusivity branch present — so no property can be silently dropped by a later edit (the helper is a module-level function precisely so this test needs no mocks).list_appsraises mid-shutdown.Manual verification
isort/flake8/mypyclean; 437 tests across the five affected backend/dashboard test files pass locally.