[josue-tech-94]

Summary

PR2.2 implements the #674 / Specs 61–64 Host-ref authority and validation correction. Current head 0fbfc9a3aa00ea878f4c2698cb8f61a692ebcb27 is based on PR2.1 / PR #797 at c869d9f1a70752ff29cb3958790cd26e7e218a09. R2-M1 / RP795-001 is closed by a test-only correction that makes the W1 matrix reach W1. Exact-head CI 36486341459, Real PostgreSQL job 109144043026, CodeQL 36486341442 / Analyze 109144041940, and required GHAS 109149600035 passed. Round 3 returned No objection; GitHub still requires human approval. This PR is open and not landed, and #674 remains open.

Stack and lineage

• Stack position: PR1 Remove Team Token PR1: User session, live authorization, and aggregate all-team access #334 → PR2 Remove Team Token PR2: Runtime actions use validated access paths #594 → PR2.1 Remove Team Token PR2.1: Host-route admission security prerequisite #797 → PR2.2 THIS PR → PR3 → PR4.
• Accepted parent layer: PR2.1 / PR Remove Team Token PR2.1: Host-route admission security prerequisite #797, branch fix/host-rpc-admission-spec65, at c869d9f1a70752ff29cb3958790cd26e7e218a09.
• Current head branch: fix/pr2-674-host-ref-validation, at 0fbfc9a3aa00ea878f4c2698cb8f61a692ebcb27.
• R27-M1 implementation: 949f389e1d9bd9036fb9ab1964e0414a5bce26b2.
• Earlier pure PR2 integration: 490b0e3f6dd5781570560fdc2d8c1e899ee1f1fa.
• Earlier Spec 64 ordering adaptation: ac2312d94e8e6fc11fd1bee259dbecb033473ad6.
• Latest-dev parent reconstruction used explicit three-way oracle 122e124e64458b34a6dfaa9b5d0522091af070bb; final head 0fbfc9a3aa00ea878f4c2698cb8f61a692ebcb27 has exactly that tree, including R2-M1.
• Separate Spec 64/65 W1 composition: bae2c298ba0bf524c8de706a5d83c2a48c613247.
• The preceding recovered-linear tree/oracle d8b71f6b03a1edf82b95c4f0593fba0cbde8d942 is historical; the latest-dev reconstruction supersedes it. The current 14-file layer matches its explicit oracle exactly.
• Issue external-rest-api: forward control-api 5xx status and Retry-After instead of answering 500 #801 is verified in the frozen ancestor stack and is outside rpc-proxy: host JWT hostRefs and wildcard hostRef checks are inconsistent across host routes #674/W1; no PR2.2-specific external-rest-api: forward control-api 5xx status and Retry-After instead of answering 500 #801 source correction was required. external-rest-api: forward control-api 5xx status and Retry-After instead of answering 500 #801 remains open pending coordinated landing in dev.

Scope and contract

The change covers the exact 21 public /rpc/hosts/:hostRef... route registrations.

• 674-A: signed hostRefs remains the ceiling, intersected with current live Control API Host authorization.
• 674-B/W1: invalid captured bare Host refs return 400 after existing authentication, parsing, and exact local v2 binding gates, but before remote checkpoint/live Host work.
• 674-C: existing denial/error precedence is preserved; valid inaccessible Host behavior remains unchanged.
• Spec 64 / Spec 65 v2 order: authentication/parser → exact local binding → canonical route preflight → W1 → remote checkpoint → Host-message admission for messages or Host-RPC admission for in-scope non-message operations → live authorization → destination resolution → effect. PR2.1 supplies the admission prerequisite; this PR2.2 supplies W1 and composes the two without changing either authority.
• Legacy routes retain authentication/scope/body precedence → canonical route preflight → W1 → applicable legacy Control API admission/authority → effect.
• Exact v2 binding and no-downgrade remain mandatory. Specs 62 and 63 Host-message shared admission, request-local retry receipt, and derived same-Host host.wake(message_retry) behavior remain compatible.

Recovered linear exact-head security and compatibility status

• Current head: 0fbfc9a3aa00ea878f4c2698cb8f61a692ebcb27 on
  fix/pr2-674-host-ref-validation, based on PR2.1 / Remove Team Token PR2.1: Host-route admission security prerequisite #797 at
  c869d9f1a70752ff29cb3958790cd26e7e218a09. The required title remains
  “Remove Team Token PR2.2: Host-ref authority and validation.” GitHub marks
  this PR REVIEW_REQUIRED.
• The latest-dev reconstruction uses explicit oracle
  122e124e64458b34a6dfaa9b5d0522091af070bb; the published head's tree
  matches exactly. The 14-file PR2.2 layer has 936 additions and 47 deletions.
  The parent chain is linear through PR1 Remove Team Token PR1: User session, live authorization, and aggregate all-team access #334 at
  3a9d2d1dc75d79800e5847df5c19dd97e9c68961, PR2 Remove Team Token PR2: Runtime actions use validated access paths #594 at
  2d6f34b4021a994afd38033192fcde6885ea0204, and PR2.1 Remove Team Token PR2.1: Host-route admission security prerequisite #797 at
  c869d9f1a70752ff29cb3958790cd26e7e218a09, rooted on dev
  21050a2abc459e6c3a8441c024187eb3e3987f04. The stack contains zero
  merge commits.
• R2-M1 / RP795-001 remains closed: four otherwise-valid legacy request bodies
  and three producer-backed v2 cases prove W1 rejection before admission,
  checkpoint, resolver, or effect; valid-Host controls prove preflight passes.
  The W1-bypass mutation made all seven assertions RED. Malformed-body
  precedence remains tested separately.
• Exact-head CI 36486341459 succeeded across the matrix, including Real
  PostgreSQL job 109144043026. CodeQL workflow 36486341442 / Analyze
  109144041940 passed; required GHAS check 109149600035 passed with
  zero annotations. The exact-head alert query returned no current alert
  instance. Historical alert objects 1522–1539 were not dismissed.
• R2-M1 bounded reviews were Code SAFE, Security SAFE, Collateral CLEAN. Round 3 returned
  No objection at current head 0fbfc9a3aa00ea878f4c2698cb8f61a692ebcb27; GitHub still
  requires human approval. No GitHub review or approval was published by this task. rpc-proxy: host JWT hostRefs and wildcard hostRef checks are inconsistent across host routes #674 remains
  open pending landing; control-api: rate-limit POST /admin/auth/login and POST /admin/auth/setup #800 is deferred; external-rest-api: forward control-api 5xx status and Retry-After instead of answering 500 #801 remains open pending landing; PR3 has not started.
• Effective deployment configuration, old-client smoke, and operational
  smoke/soak evidence are NOT VERIFIED here and remain deployment-only gates.

Historical exact-head security status (superseded by current status above)

For the historical PR2.2 head bae2c298ba0bf524c8de706a5d83c2a48c613247:

• Exact-head CI: run 36094982663 completed successfully; the relevant Control API, RPC Proxy, Desktop, External REST, shared-contracts, shell/hygiene, and remaining matrix jobs passed.
• Exact-head Real PostgreSQL: job 107945232677 in run 36094982663 succeeded.
• Exact-head CodeQL/GHAS: workflow-dispatch run 36095276777, Analyze job 107946140858, succeeded for fix/pr2-674-host-ref-validation at bae2c298ba0bf524c8de706a5d83c2a48c613247, category /language:javascript-typescript. Analysis 1837357434 is for refs/heads/fix/pr2-674-host-ref-validation at the same SHA. Required CodeQL check 107949765866 succeeded with zero annotations and “No new alerts in code changed by this pull request.” No current changed-code High/Critical alert was reported; no alerts were dismissed.
• The prior-head check 107448846288 at ac2312d94e8e6fc11fd1bee259dbecb033473ad6 reported 30 High changed-code js/missing-rate-limiting annotations. Those instances were classified as base-equivalent R0 behavior and motivated the separate Spec 65 prerequisite. No alerts were dismissed in that earlier security-stop pass. That prior-head result is historical context only and does not establish the current head's security status.

Historical validation before linearization (superseded by current status above)

Local PR2.2 synchronization validation at bae2c298ba0bf524c8de706a5d83c2a48c613247:

• RPC Proxy: 57 files / 767 tests passed; build passed.
• Focused ordering review validation: 5 files / 112 tests passed.
• Changed-file Prettier, git diff --check, and repository style rules passed. Style rules reported zero errors and one unrelated existing Desktop UI warning.
• Code review: SAFE. Security review: SAFE. Bounded synchronization collateral: CLEAN.
• Local Real PostgreSQL was unavailable because CONTROL_API_REAL_PG_ADMIN_URL is unset. Exact-head CI Real PostgreSQL passed and satisfies the required acceptance gate.
• Exact-head CI 36094982663, Real PostgreSQL job 107945232677, CodeQL run/job 36095276777 / 107946140858, and required CodeQL check 107949765866 were successful at that historical head. Round 1 formal review returned No objection there; no GitHub review/approval was published.

Round 1 No objection was recorded on the prior reviewed head, before the current parent reconstruction and R2-M1 closure. No new formal review decision has been published for the current head. The corrected PR remains open for human review; #674 remains open until the accepted correction lands in dev. PR3 has not started.

[github-advanced-security]

CodeQL found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

[alfredolopez80]

PR Review — Remove Team Token PR2.2: Host-ref authority and validation (#674 / Specs 61-64)

Review verdict

YES with conditions — no production blocker found; one confirmed test-quality defect weakens the W1 evidence.

Reviewed the complete diff at base 2bfe0b8 (PR797 head) → head 7a7cf85 (14 files, +794/−47) in disposable exact-head worktrees, with independent implementation/architecture and security lanes. The W1 grammar was additionally re-verified with a bounded pure-JS regex probe, including a trailing-newline hypothesis raised and retracted during review — JavaScript $ does not match before a final LF/CR (confirmed false positive; the anchors are correct).

Assessed against the Task 106 stack reviewer context as the top layer of the linear stack (334 → 594 → 797 → 795): the W1/Spec 64/65 composition this layer implements is coherent and matches the ordering the context asks reviewers to confirm. The activation-gate model is irrelevant to the one finding below (test quality, not gated behavior).

PR-introduced issue count

• Blocker/Critical/High: 0
• Medium: 1 (test quality)
• Low: 0
• Pre-existing: 0
• Uncertain/unavailable: 0
• Root-cause clusters: 1 (test evidence)

Finding

RP795-001 — Medium — rpc-proxy/src/__tests__/host-ref-validation.test.ts:89

The "comprehensive" invalid-Host matrix uses empty {} bodies for the approval approve/deny, model-selection, and rename routes. Those cases fail canonical preflight (which validates the bodies) before reaching W1, yet satisfy every matrix assertion (status 400 + no downstream effects). Removing W1 from those routes would keep the matrix green.

• Invariant: a W1 regression test must reach W1 after all preceding gates pass, and distinguish W1's rejection from another 400.
• Remedy: supply otherwise-valid bodies and assert {error: 'Invalid hostRef'}; pair each fixture with a valid-ref control proving preflight passes. (Rename has a separate valid-title W1 test; approvals/model still lack one.) Retain separate precedence tests with invalid bodies.

Verified clean

• All 21 /rpc/hosts/:hostRef... registrations verified route-by-route: legacy and v2 gate order matches the Spec 64/65 composition; W1 sits after auth/parsing/exact-binding/preflight and before remote checkpoint/live Host work; the signed hostRefs ceiling is preserved and intersected with live Control API authorization; denial precedence (674-C) is unchanged; the v2 destination remains checkpoint-bound.
• Grammar (HOST_REF_RE): 1–63 lowercase alnum/hyphen with alphanumeric ends; rejects uppercase, underscore, dot, Unicode, percent/slash encodings, control chars, surrounding/trailing whitespace, and >63 length; it inspects the raw captured segment while preflight/binding trim only their own copies. Pure-JS probe: host-a, host-a\n, host-a\r, bad\nhost → true/false/false/false.
• Message retry receipts stay request-local; replacement preserves nonce/expiry; no state moved into shared wake coordination.
• Security: no introduced security defect; exact binding and no-downgrade preserved on all gates.

Limitations and follow-ups

• Static review only — "correct order" means source-inspected, not executed. Coverage gaps (not defects): no v2 W1-reaching matrix for all supported routes, and no end-to-end proxy→Control API ceiling-intersection test.
• Minor architecture note: requireScope(...deferHostV2Checkpoint), validateHostRefAndAuthorize, requireValidHostRef, and the deferred binding helpers have no production callers in the inspected tree — drift risk, not a reachable defect. Prefer retaining one staged binding/preflight/W1/checkpoint mechanism.
• Stack context: this layer composes cleanly with a future PR594 checkpoint fix, but as the top of the stack it cannot be approved for landing while the base is broken — PR594 carries three v2-chain blockers and PR797 a gateway blocker that affects active legacy traffic. Those belong to the parent PRs, not this diff; fixing this layer's test gap now is worthwhile so it does not need another rebase later.