Skip to content

spec(epic): verified identity by default (FIX-1503) - #2034

Merged
jhoffner merged 1 commit into
mainfrom
cursor/epic-fix-1503-verified-identity-22f6
Sep 22, 2026
Merged

jhoffner merged 1 commit into
mainfrom
cursor/epic-fix-1503-verified-identity-22f6

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

A reachable Flow State Dev host that has not wired its own identity check is unauthenticated by design. Anyone who can reach /api/flows is whoever they typed in the body. Two reads — the flow list and capabilities — answer with no credential at all.

A team that… Today After this epic
exposes a host to the network Anyone who can reach /api/flows is whoever they typed in the body Every route except mint requires a verified principal
already has login Writes a custom resolver or ships open Exchanges the host session for a short Bearer and keeps its login
lists flows from a browser Those reads answer with no credential The same reads require a token; kinds stay a host-wide registry
runs kitchen-sink, Devtool, or a Lab Sends userId in JSON and it works Mints, or names the local-dev escape; CyberForce proves the real path

What's in the box: host-proof mint, verified /api/flows, closed exemptions, named escape. Login stays with the host. FSD does not provide login.

Inside 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.

The path: FIX-1442 done input, then unfiled engine, cutover, leftover, and CyberForce proof. Now line is 22 September 2026.

Sequence around the callers, not a one-line default flip.

Who owns what: six rules by four columns, each rule with exactly one owner.

Every rule has one owner. Two would be a seam; none would be a gap.

Sign off

  1. Three new issues and the leftover, sequenced around callers. If wrong: a one-line default flip that paints the repo red, or a mega-issue nobody can review.
  2. list_flows and capabilities become authenticated-global, not kinds-per-principal. If wrong: a third inventory of truth, or a gated route that still leaks to the internet.
  3. Fifteen-minute JWT; host-asserted sub and org; 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

  • Is three new issues the right cut? The collapse trigger is in D1. A docs-only or tests-only fifth child is the overbuild.
  • Rules → ER-3 / D2. Gating list_flows without inventing kinds-per-user. If that falls, FIX-1486 has started early.
  • Settled mint practice. Re-open only if product wants FSD to ship login.

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:

  • The objective — is this body of work worth doing, and is the outcome the right one?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in BUSINESS-RULES.md with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.
  • Shared promises and publication ownership in DOCS.md; missing or misleading
    predecessor treatment in conditional EVOLUTION.md.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's 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
  • Mint trust: host-proof token exchange. FSD does not provide login. Recorded as settled.
  • Escape hatch keeps defaultBodyUserIdPrincipalResolver as explicit opt-in; node still refuses network bind. Flag spelling is issue-spec.
  • FIX-906 stays thin leftover (session/resource/transcribe parity). Default-posture absorbed here.
  • execute_action / create_session get no second gate.
  • In-process runAction / testFlow / fsdev run keep explicit userId.
  • Consumer-corpus checker (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.
Open in Web Open in Cursor 

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>
@vercel

vercel Bot commented Sep 22, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 22, 2026 2:29am UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 22, 2026 2:29am UTC
flow-state-dev-ui Ignored Ignored Sep 22, 2026 2:29am UTC

Request Review

@jhoffner jhoffner added the spec label Sep 22, 2026 — with Cursor
@linear-code

linear-code Bot commented Sep 22, 2026

Copy link
Copy Markdown

FIX-1503

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-22T02:37:39.303844Z 01330a3 PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor cursor Bot 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.

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)

  1. consumer-corpus/census.mjs overclaims. 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 classifies fsdev.config.ts / .mts under 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 via rg/tests (FIX-1481 style) for caller wiring.

  2. Dead / misleading table rows. CLASSIFICATION["apps/docs"] is a directory key that never appears in the walk; http-cutover-docs is unused in assertions. NAMED_FAMILIES already covers docs via exists().

  3. Duplicate proof rules. ER-21, ER-6, and ER-23 restate the same CyberForce bar; collapse or differentiate (process gate vs observable).

  4. Prose repetition. In-process exclusions, FIX-906 leftover, and no-second-gate on execute_action/create_session appear in SPEC, DECISIONS, and PLAN — one canonical home (BUSINESS-RULES + pointers) would shrink sync cost.

  5. 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/cli CONFIG_FILENAMES (.js/.mjs hosts today would bypass census regex).
  • Cutover should cache JWT until near exp, not mint per poll — Devtool/listFlows frequency after D2 closes exemptions.
  • Close list_flows / capabilities in route-auth.ts in 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.

Open in Web View Automation 

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

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.

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",

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.

"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$/;

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.

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 |

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.

"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 |

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.

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`

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.

"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

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.

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

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.

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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 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;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge 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 👍 / 👎.

Comment on lines +84 to +86
- **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

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge 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 👍 / 👎.

Comment on lines +116 to +118
const missingFamily = NAMED_FAMILIES.filter((f) => !exists(f));
if (missingFamily.length) {
throw new Error(`named cutover family missing from disk: ${missingFamily.join(", ")}`);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge 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 jhoffner left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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/capabilities in packages/engine/src/routes/http-handlers.ts, plus the exempt subject path in route-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.mjs re-run clean against the live repo (10 real fsdev.config.ts files matched); --plant correctly 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

@jhoffner
jhoffner merged commit 1196611 into main Sep 22, 2026
14 checks passed
@jhoffner
jhoffner deleted the cursor/epic-fix-1503-verified-identity-22f6 branch September 22, 2026 13:21
jhoffner pushed a commit that referenced this pull request Sep 22, 2026
…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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants