Repository navigation
spec(epic): verified identity by default (FIX-1503) - #2034
Conversation
Direction-only epic-spec: host-proof mint, verified-by-default /api/flows, and a child cut sequenced around consumers. Mint trust is recorded as settled. No framework implementation. Co-authored-by: Jake Hoffner <jhoffner@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
Direction
Reachable /api/flows should stop trusting caller-written userId, with a host-proof mint as the issue/sign sibling to today's verify helpers — not a new login product. That framing matches FIX-1442 and the code you already have (createHs256JwtVerifier, scheduled gateway bearer patterns). I would not simplify the epic down to a one-line default flip; D1's engine vs cutover split matches where the cost actually lives.
Simpler alternatives considered
| Alternative | Verdict |
|---|---|
Flip resolvePrincipal default only |
Rejected — red repo, teaches the wrong posture |
| One mega-issue | Rejected — caller churn buries the small engine change |
OAuth2 /oauth/token or jose in engine |
Rejected — invent-kill in Settled; extend existing HS256 verify/sign in engine |
Kinds-per-principal on list_flows |
Rejected — third registry; D2 is the right fence |
| Drop retained POC | Keep — same class as FIX-817 census; --plant is good discipline |
Where this went farther than necessary (spec hygiene, not architecture)
-
consumer-corpus/census.mjsoverclaims. Prose (PLAN, DECISIONS, ER-5, ER-2) reads like it re-derives the full named HTTP cutover set (Devtool, MCP, docs examples, transports). The script only classifiesfsdev.config.ts/.mtsunder scan roots and checks nine directories exist. It does not prove those families send Bearer on/api/flows. That is fine for a host-config census — but then say that everywhere, and plan cutover durable checks viarg/tests (FIX-1481 style) for caller wiring. -
Dead / misleading table rows.
CLASSIFICATION["apps/docs"]is a directory key that never appears in the walk;http-cutover-docsis unused in assertions.NAMED_FAMILIESalready covers docs viaexists(). -
Duplicate proof rules. ER-21, ER-6, and ER-23 restate the same CyberForce bar; collapse or differentiate (process gate vs observable).
-
Prose repetition. In-process exclusions, FIX-906 leftover, and no-second-gate on
execute_action/create_sessionappear in SPEC, DECISIONS, and PLAN — one canonical home (BUSINESS-RULES + pointers) would shrink sync cost. -
Optional third issue. A standalone CyberForce proof ticket is thin if cutover CI already mints + 401s; D1's collapse trigger already allows merging — consider filing two children unless the programme truly needs an independent proof gate.
At implement time (not blockers for this spec)
- Align config discovery with
packages/cliCONFIG_FILENAMES(.js/.mjshosts today would bypass census regex). - Cutover should cache JWT until near
exp, not mint per poll — Devtool/listFlowsfrequency after D2 closes exemptions. - Close
list_flows/capabilitiesinroute-auth.tsin place; mint is the sole intentional open route.
Verdict
Approve direction on D1–D3 and FIX-906 absorb. Tighten census wording (or scope the script) before implementers treat ER-5's "consumer-corpus" as proof of Bearer wiring — see inline comments.
Sent by Cursor Automation: Review For Best Approach
| /** | ||
| * FIX-1503 · Consumer corpus — the epic's factual base, re-derived. | ||
| * | ||
| * The epic claims the expensive part is a named set of HTTP callers that today |
There was a problem hiding this comment.
The header says this re-derives the named set of HTTP callers that send no token today. The implementation only totality-classifies fsdev.config.* paths under SCAN_ROOTS. It does not inspect Devtool client code, MCP/scheduled/voice/BullMQ HTTP adapters, or docs examples.
Suggestion (should): Retitle to "host-config census" in the header, PLAN, and DECISIONS — keep the script, but pair cutover proof with durable git grep / integration tests for Bearer on /api/flows (same pattern as FIX-1481's run.mts). Otherwise ER-5's "Checked at · consumer-corpus" overpromises.
| /** Every scanned host config must appear here. */ | ||
| const CLASSIFICATION = { | ||
| "apps/kitchen-sink/fsdev.config.ts": "http-cutover", | ||
| "apps/docs": "http-cutover-docs", |
There was a problem hiding this comment.
"apps/docs": "http-cutover-docs" never participates in totality: the walk only keys file paths, and there is no apps/docs/fsdev.config.*. Docs cutover is prose/examples, already covered by NAMED_FAMILIES + exists().
Suggestion: Drop this row or move docs intent to a comment; the unused http-cutover-docs label is easy drift.
| "packages/integration-tests", | ||
| ]; | ||
|
|
||
| const CONFIG_NAME = /^fsdev\.config\.m?ts$/; |
There was a problem hiding this comment.
Config matching is /^fsdev\.config\.m?ts$/ only. CLI's canonical list includes .js / .mjs (packages/cli/src/load-config.ts). A host added as fsdev.config.mjs would not fail this census today.
Suggestion (implement-time, maybe spec footnote): Align enumerator with CONFIG_FILENAMES when refreshing CLASSIFICATION.
| | # | Rule | Owner | Checked at | | ||
| |---|---|---|---| | ||
| | ER-1 | A reachable `/api/flows` deployment requires a verified principal on every route except mint | FIX-XXX engine | Engine tests · CyberForce | | ||
| | ER-2 | Mint is the sole unauthenticated HTTP route the engine adds | FIX-XXX engine | Engine route table · the corpus checker's HTTP face | |
There was a problem hiding this comment.
"the corpus checker's HTTP face" implies the script validates HTTP clients send Bearer. Today it only classifies host configs + directory presence. Consider "host-config census" or split checkers: census for configs, cutover PR tests/grep for Bearer wiring.
| | ER-18 | A child's Linear state is mirrored when it changes | The wake derives blocked-by from Linear | | ||
| | ER-19 | A cross-cutting question comments up on the epic; after merge, amendments are a follow-up PR | Retained decisions are canonical | | ||
| | ER-20 | Every child's route reads *spec* by default | Fail-closed routing | | ||
| | ER-21 | The epic finishes only when CyberForce's goal check passes | [D1](DECISIONS.md#d1). Surface without proof does not move the lead measure | |
There was a problem hiding this comment.
ER-21 (epic finishes when CyberForce passes), ER-6 (CyberForce proof child), and ER-23 (same observable) triple-describe one bar. Suggestion: Keep ER-6 + one wrap rule (ER-21 or ER-23), drop the duplicate row in "The proof" — less table noise for child specs to mirror.
|
|
||
| ## POC | ||
|
|
||
| `poc/consumer-corpus/` re-derives the named HTTP-cutover list (totality + `--plant` |
There was a problem hiding this comment.
"Re-derives the named HTTP-cutover list" reads broader than the script delivers (see census header comment). Suggestion: "Re-derives the fsdev host-config list (totality + --plant)" and point cutover's Bearer proof at tests/grep in the cutover issue-spec.
| ## What the end-state POC showed | ||
|
|
||
| No end-state POC. The division into issues is the locked sequence (engine small, callers | ||
| expensive, CyberForce proves). A consumer-corpus checker re-derives the named cutover list |
There was a problem hiding this comment.
Calling this a re-derived "named cutover list" is the main place implementers will anchor ER-5. If you keep the script unchanged, I'd qualify: factual base for discovered host configs, not for MCP/Devtool/docs HTTP wiring — those need their own checklist in the cutover child.
| ## Settled | ||
|
|
||
| - **Mint trusts host-owned proof only** (Jake via Architect, 2026-09-21). Human: host session / | ||
| OAuth, then host service secret or host-signed assertion carrying `userId` and optional org |
There was a problem hiding this comment.
D1 split still looks right. Optional simplification (maybe): the third "CyberForce proof" issue is small relative to cutover; if cutover already includes mint+401 integration checks, filing two children (engine + cutover∪proof) is defensible unless the programme needs CyberForce as an independent wrap gate. The collapse trigger here already covers the one-PR case.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 01330a3b33
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| 1. **This epic-spec is approved and merged** → the three gaps are filed and may be specced. | ||
| FIX-906 stays Backlog until mint exists. | ||
| 2. **The engine child merges** → cutover can mint; FIX-906 can consume the same principal; |
There was a problem hiding this comment.
Stage the default flip with the consumer migration
When step 2 runs, the engine child has already merged the verified-by-default flip, but the subsequently unblocked cutover child is what updates kitchen-sink, Devtool, goals/labs, and integration tests to mint or explicitly select the escape. Those existing callers therefore still send only userId, leaving main in the exact red-repo state that SPEC.md:36-43 says this split must avoid. Land mint before enforcement, merge the flip and cutover atomically, or move the flip into the cutover child.
Useful? React with 👍 / 👎.
| - **Mint trusts host-owned proof only** (Jake via Architect, 2026-09-21). Human: host session / | ||
| OAuth, then host service secret or host-signed assertion carrying `userId` and optional org | ||
| claims the host alone may assert. Machine: API key or HMAC → same mint. Dev: explicit |
There was a problem hiding this comment.
Require organization identity for every successful mint
For a host assertion that omits the organization as permitted here, the mint has no trusted value for the org/org_id claim that D3 requires on every access token (DECISIONS.md:54), while the existing authentication contract rejects a configured principal without an organization (docs/architecture/authentication.md:73-80). Implementing both statements either produces unusable tokens or pressures the mint to invent identity data and weaken the org boundary. Require the proof to contain an organization, or define a trusted server-side derivation that runs before minting.
Useful? React with 👍 / 👎.
| const missingFamily = NAMED_FAMILIES.filter((f) => !exists(f)); | ||
| if (missingFamily.length) { | ||
| throw new Error(`named cutover family missing from disk: ${missingFamily.join(", ")}`); |
There was a problem hiding this comment.
Enumerate HTTP callers in the corpus check
For named families such as Devtool, goals, MCP, scheduled, voice, BullMQ, and integration tests, this check proves only that the directory exists; found contains only fsdev.config.* files. Adding or overlooking an unauthenticated /api/flows call anywhere inside an existing family therefore leaves the check green, even though the spec relies on it to establish the complete cutover scope. The --plant control likewise proves only config-file discovery, so the checker should scan concrete HTTP call sites or validate an explicit caller manifest.
Useful? React with 👍 / 👎.
jhoffner
left a comment
There was a problem hiding this comment.
Second-look review (automated)
Verdict: appropriately scoped. No findings.
This is a retained epic-spec PR — 10 changed files, all under specs/epics/FIX-1503/: 6 spec docs, 3 SVG figures, and one throwaway POC script (poc/consumer-corpus/census.mjs). No production code changes.
Ran a second-look retrospective on whether the epic's cut (token-exchange mint + closing list_flows/capabilities + an explicit local-dev escape hatch + FIX-906 as thin leftover) is the right approach, and separately checked whether this PR is an opportunity for an improve-codebase-architecture pass. It isn't: that pass only applies when a PR is implementing, fixing, or refactoring actual code, and this one carries none — that belongs on the engine/cutover child-issue PRs once they land, not here.
Verification performed (against real code and live state, not just the spec's word):
list_flows/capabilitiesinpackages/engine/src/routes/http-handlers.ts, plus theexemptsubject path inroute-auth.ts, genuinely run zero auth today — the epic's central claim ("two reads answer with no credential at all") holds.- D3's "reuse today's HS256 verify" checked against
createHs256JwtVerifier(packages/engine/src/transports/auth/createBearerTokenVerifier.ts) — verify-only reuse is accurate; signing is correctly scoped as new work, not glossed over. - The node bind-guard claim (escape hatch still can't reach the network) checked against
packages/node/src/bind-guard.ts— real, not aspirational. census.mjsre-run clean against the live repo (10 realfsdev.config.tsfiles matched);--plantcorrectly fails closed; no secrets, no new dependencies, not wired into any build/CI path — matches the PR's own "throwaway" claim.- Linear state cross-checked via API: FIX-1503 In Spec Review, FIX-906 Backlog and correctly parented, FIX-1442/FIX-23 Done, FIX-1486 Backlog — matches every status claim in SPEC/PLAN/EVOLUTION.
- PRs #1223 and #2027, cited in PLAN.md as touching the same files, are real and do.
- The three sign-off items in SPEC.md map cleanly onto D1–D3 (DECISIONS.md) and ER-1–ER-4 (BUSINESS-RULES.md) with no contradiction across documents.
Considered and judged justified, not a finding (noting for the record):
- CyberForce proof stays its own issue rather than folding into cutover — an independent pass/refuse check outweighs one fewer issue, and D1's own collapse condition is a different one.
- BUSINESS-RULES.md's "what no child may do" section density matches
epic-spec-template.md's own worked example — not extra ceremony. - Two new doc pages for a new auth primitive is less surface than comparable existing features (
scheduled,webhooks) get. - D2's "authenticated-global, not kinds-per-principal" — checked for cross-tenant leakage; the registry only exposes structural kind/schema data, not tenant rows, so it holds.
No architecture-refactor findings — this PR is direction-setting only.
Generated by Claude Code
…d one import model Three findings folded. PLAN.md said "POC: none built" while this amendment adds poc/read-gate/ and EVOLUTION cites it as the evidence. An implementer asking whether there is a POC got two answers from one document. Split in two: none for the navigator, whose premises are shipped code, and poc/read-gate/ for the two panel premises that could not be read off the code. read-gate-probe's second case was named for two claims — the refusal and the ledger declaring no client config — and asserted only the first. The declaration was a console.log, so half of what the test's name promised could not fail. Now an assertion, with its own red state verified: assigning a client config onto the ledger turns it red before the route is called. Recorded in EVOLUTION as well as fixed, because it is the same defect class the rest of the page is about, one level in. premise-proof imported from "../src" while read-gate-probe imported by package name, giving one POC folder two mental models. Both now import by package name. Verified it resolves and passes that way rather than assumed. Re-verified every cited line against main at 1196611 after rebasing across #2027, #2033, #2034 and #2037; all still resolve. Observed output in the README re-derived from a fresh run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB


A reachable Flow State Dev host that has not wired its own identity check is unauthenticated by design. Anyone who can reach
/api/flowsis whoever they typed in the body. Two reads — the flow list and capabilities — answer with no credential at all./api/flowsis whoever they typed in the bodyuserIdin JSON and it worksInside the box is a token-exchange mint and a closed
/api/flows. Login stays with the host.Why now. Organization identity is already principal-owned (FIX-1442). Identity itself is still something the caller writes. That makes org fences advisory and teaches a default the node host already refuses to bind.
The set: three unfiled children and one filed leftover. Engine (mint + default + close the two open reads), consumer cutover (the expensive part), CyberForce proof, and FIX-906 as thin leftover. As of 2026-09-22: 0 done, 1 leftover, 3 named gaps. The spec records that snapshot.
Sequence around the callers, not a one-line default flip.
Every rule has one owner. Two would be a seam; none would be a gap.
Sign off
list_flowsandcapabilitiesbecome authenticated-global, not kinds-per-principal. If wrong: a third inventory of truth, or a gated route that still leaks to the internet.subandorg; reuse today's HS256 verify. If wrong: tokens that live as long as a session, or a second auth algorithm the verifiers do not speak.What would change my mind on 1: a measured cutover so small that engine and callers fit one review. Reasoning and what lost: DECISIONS.md. The rules every child obeys: BUSINESS-RULES.md.
Mint trust is settled, not a card. Open: none.
Reviewers · look here
list_flowswithout inventing kinds-per-user. If that falls, FIX-1486 has started early.Not here: any single issue's mint path spelling, escape-flag letters, or test plan. Those are the issue-spec PRs. No changeset — direction only, no published package change.
Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1503 · Project: Framework simplification · merges after human approval and required checks
How to review this — an epic-spec, not an implementation plan
This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design.
In scope to challenge:
That question can only be asked here.
DECISIONS.md— shared surface, naming, sequencing, contracts.BUSINESS-RULES.mdwith no owner, or two.DOCS.md; missing or misleadingpredecessor treatment in conditional
EVOLUTION.md.Out of scope — owned by the individual issue specs:
poc/show shape and scoping, not shippable implementation. Directional evidence, experimental
isolation and absence of secrets/generated dependencies remain in scope.
Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.
Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.
Engineering calls
defaultBodyUserIdPrincipalResolveras explicit opt-in; node still refuses network bind. Flag spelling is issue-spec.transcribeparity). Default-posture absorbed here.execute_action/create_sessionget no second gate.runAction/testFlow/fsdev runkeep explicituserId.poc/consumer-corpus/) re-derived the HTTP host list and found two extra labs the Linear cost list omitted:labs/conductor,labs/fsd-coding-skill.