Skip to content

fix(FIX-1955): a resource's secret fields never leave the server, debug routes included - #3268

Merged
jhoffner merged 5 commits into
mainfrom
claude/project-thread-rjvsrj
Oct 13, 2026
Merged

jhoffner merged 5 commits into
mainfrom
claude/project-thread-rjvsrj

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

The problem

With debug endpoints on (fsdev dev, the Shift Manager Lab), GET /api/flows/sessions/:id/debug/resources/mcpCredentials/items returned a user's stored MCP key in full. The debug routes skip client.* shaping by design, so the expose: ["setAt"] on the key collection did not cover them, and nothing else could.

What this does

  • Core: defineResource and defineResourceCollection take a new top-level secret list of state fields. A name not on the schema, or one client.expose also names, throws at definition time. New resolveClientData(config, state) runs the client projection on the full state and drops any secret field from the top level of its result.
  • Engine: the debug tree and item listing return raw state with secret fields omitted. Every client view (snapshot including prefetched items, list-state and get-state routes, live deltas, the debug client view) goes through resolveClientData, so a client.data function sees the full state and can derive from a secret (keyTail: s.value.slice(-4)) but cannot return one. The flow registry refuses two declarations of one shared cell that mark different secret fields (secret-mismatch). The engine learns only the generic marker; nothing Workforce-specific lands in L1.
  • Workforce: mcp-credentials/* declares secret: ["value"].

Before: a debug read of a stored key returned { value: "<key>", setAt }. After: it returns { setAt }.

What's asked of you

One call on an open review thread: Codex asks that scope-level client.derived projections also be handed secret-stripped resources. I recommend not doing that: derived is author-written projection code like client.data, a leak needs an explicit read-and-return, and stripping would break derivations like hasKey. If you disagree, it's a follow-up.

This is stacked on #3261 (the key store it protects lives there); it retargets to main when #3261 merges.

Parts worth reviewing closely

  1. packages/core/src/helpers/client-projection.ts (resolveClientData) and its engine call sites. Is any other server-leaving state read not going through it or omitSecretFields? If so, a secret leaks through that path.
  2. packages/engine/src/registry/flow-registry.ts, checkResourcePair. Does every shared-cell comparison carry the secret list?
  3. Known limits, documented on the Secret fields page: secret covers state, not content (a contentTemplate that interpolates a secret field renders it). The derived ClientDataOf type still lists a secret field under the identity or exclude projection, so pair secret with expose. Model resource tools read through the server-side handle and are not affected.

Fixes FIX-1955 · Found in #3261 (FIX-1905) · Bug route, no spec.

Verification
  • packages/engine/test/secret-resource-fields.test.ts (10) and a live-delta case in test/context/resource-registry.spec.ts. Red states: with the engine change stashed, the debug tree, debug items, snapshot, list/get-state and live-delta cases fail; on the previous head, the client.data derivation case (throws on s.value) and the shared-cell refusal case fail. All pass now. Each read test also asserts the non-secret field arrives and the store holds the key.
  • packages/workforce/test/mcp-credentials-debug-read.test.ts: the real collection through the real router's debug item route. Without secret: ["value"] it fails with the key in the body; with it, it passes.
  • Suites: core 2390 passed, engine 3748 passed (6 skipped), workforce 1279 passed.
  • Typecheck: core and engine clean. Workforce shows 3 errors (coordinator-flow.ts, delegated-post.ts) that are identical with this change stashed.
  • Lint clean. apps/docs build exit 0. Changeset check passes.
  • Docs written by docs-writer, reviewed by docs-editor (all findings applied).

Changeset: core, engine, workforce patch.

🤖 Generated with Claude Code

https://claude.ai/code/session_0149AEso8yp91qXPZtLjKe6z


Note

Medium Risk
Changes how all outbound resource state is shaped and closes a debug-endpoint credential leak; misconfigured or bypassed read paths could still expose secrets, but coverage is broad and regression-tested.

Overview
Adds a top-level secret list on defineResource / defineResourceCollection so named state fields never appear in any server response path—client snapshots, list/get-state, live deltas, and debug endpoints (which previously returned full state regardless of client.expose).

Core validates secret against the schema and blocks overlap with client.expose, and introduces resolveClientData (projection on full state, then strip secrets) plus omitSecretFields for raw debug payloads. client.data can still derive from secrets; returning a secret key in the result is stripped.

Engine switches those read paths from resolveClientProjection to resolveClientData and omits secrets in debug snapshots; the flow registry rejects shared storage cells whose flows disagree on secret (secret-mismatch).

Workforce marks MCP credential value as secret (FIX-1955). Docs and tests cover the contract and limits (state only, not content; scope client.derived unchanged).

Reviewed by Cursor Bugbot for commit 95e15c0. Configure here.

@vercel

vercel Bot commented Oct 13, 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 Oct 13, 2026 11:27pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 13, 2026 11:27pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 13, 2026 11:27pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 13, 2026

Copy link
Copy Markdown

FIX-1955

@jhoffner jhoffner self-assigned this Oct 13, 2026
@cursor

cursor Bot commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: fff52bde-c317-4a04-a237-44693b036af5)

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 13, 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-10-13T22:24:34.383157Z db7c2f9 Manual request
ℹ️ 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.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (FIX-1955)

Verdict: the approach is right and proportionate. A declarative secret list validated at definition time, applied at the engine's read seams, is the lean shape. The alternatives I considered were worse: a client.hidden flag would not cover the debug routes, and encrypting at rest is a much bigger change. Findings below, most important first. I did not run the suites.

1. Leak audit (the "parts worth reviewing" question)

I traced every resolveClientProjection / clientData / raw persisted.resources[...] use in packages/engine/src. Snapshot (single and prefetched), list-state, get-state, search-hit clientData (resource-routes.ts:514), live deltas and both debug builders are covered. I found no missed read of resource state on a route. Two things I could not confirm from the diff, so please check them before merge:

  • Resource-load records and traces. ResourceLoadRecord (core items) and trace/NDJSON output may carry loaded resource state. If they do, a secret reaches the stream or the run log by a path that never touches the routes. If they carry only refs and keys, say so in the PR.
  • resource_change for collection items. createExecutionContext.ts:2334-2354 decides what the change emitter sends. The delta now goes through liveProjection, but confirm that no non-live branch ships full state.

2. Six call sites each remember to call omitSecretFields (architecture)

The invariant is now "every server-leaving read calls omitSecretFields(config, state) before projecting". That is enforced only by convention, and each new route has to remember it. Here are two inexpensive options:

  • Preferred: give the engine one helper, e.g. clientVisibleState(config, state) in route-utils.ts. It would do the omit and the resolveClientProjection call. The three route files and the registry would then share it, which removes the applyClientData wrapper in resource-routes.ts and the duplicated call in route-utils.ts. The debug builders would keep calling omitSecretFields directly, since they are raw by design.
  • If you leave it as is, add a test that fails when a new resolveClientProjection caller appears without the omit. A grep-based guard test would do. Otherwise the next route added is a quiet regression.

This is in scope because the PR is the one introducing the invariant. I would not restructure beyond that.

3. Fail-open on a typo when the schema can't be introspected

validateSecretFields skips the unknown-key check when introspectStateKeys returns undefined (a non-ZodObject schema, as with expose). For expose, a typo hides nothing from the client. For secret, a typo is a silent leak, so this is the fail-open direction. Options: throw when the schema can't be introspected and secret is set (recommended, since this is a security option), or document the limit on the Secret fields page. Add a test for whichever you choose.

4. Type gap documented instead of closed

The PR notes that ClientDataOf still lists a secret field under the identity/exclude projection. The type promises a field that never arrives at runtime. Because secret is not const-inferred, this is hard to fix cleanly. A cheaper guard is to make the definition-time check also reject secret together with an identity projection (client.state.read and no expose/data), but that would break the workforce-style pattern in the new test. Probably leave it, but file a follow-up issue so the known limit has an owner (BP-035 second-path checklist).

5. contentTemplate interpolation

This is the larger remaining hole, and it is documented. Consider failing at definition time when secret is set together with a contentTemplate / render that could reference it, or at least when a template string contains {{<secretKey>}}. If templates are free-form, the static check is best effort, so documenting is acceptable. The ask is a deliberate decision, not silence.

Nits

  • types/resource-collection.ts and types/resource.ts: the secret JSDoc has a mid-sentence overlong line ("A client.data projection is handed each instance's state without them. Blocks running on"). Re-wrap.
  • debug-snapshot.ts header: the new sentence broke the existing line wrapping ("It does not bypass a definition's secret fields… Off-by-default at the route").
  • The changeset marks core and engine minor for a bug fix. That is defensible, since it adds public API, but pre-1.0 convention is usually patch for fixes. Confirm.

Not worth doing

No broader refactor of the projection or debug code is warranted here.


Generated by Claude Code

@cursor

cursor Bot commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 7e0999a4-72f8-46e1-bb59-a6604c1bda82)

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

Simplify review (FIX-1955)

Verdict: The feature shape is the right one — a definition-time secret list plus stripping on egress is simpler and clearer than bolting redaction onto debug-only routes, using a generic path-redaction library (fast-redact, etc.), or Zod transforms that would also shrink what blocks see on the server. Reusing the existing private omit() beside exclude keeps one omission implementation. I’m approving because the surfaces that matter today are covered and the integration tests (including the workforce router path) make the security intent hard to regress accidentally.

The main complexity cost is not the API; it’s enforcement spread. omitSecretFields is wired in five engine places (route-utils, resource-routes/applyClientData, resource-registry live deltas, debug-snapshot ×2). Each pairing is only two lines, but every new “state leaves the server” path must remember the dance. That’s the classic “went far enough to be safe, one step short of being simple.”

Cleaner approach (optional follow-up, not a merge blocker)

Export a single core helper, e.g. resolveClientData(config, state) → resolveClientProjection(client, omitSecretFields(config, state)), and make that the only supported way to build client-facing state. Engine call sites (including liveProjection and debug computeClientView) would call it instead of open-coding the pair. Benefits:

  • One place to document the contract (“secrets never reach projection”).
  • computeClientView stops depending on callers having already redacted state.
  • Slightly easier to fold secret keys into pick/exclude in one pass later (today expose + secret does omit then pick — fine for MCP-sized state).

I would not hide omission inside resolveClientProjection(client, state) alone — it needs the resource config’s secret, so a thin wrapper is the right seam.

Smaller notes (unsure = treat as suggestions)

  • Projected collections: defineProjectedResourceCollection still validates client projection without secret on the config type. If projected rows can ever hold credentials, this is a gap; if not, a one-line doc call-out avoids surprise.
  • Validation parity: Unknown secret keys are skipped when introspectStateKeys returns undefined (same as expose). For secrets I’d consider requiring a plain ZodObject when secret is non-empty — not sure that’s worth the inconsistency cost.
  • Tests: secret-resource-fields.test.ts header promises a live-delta check; that lives in resource-registry.spec.ts instead — align the comment or add one case here.
  • Core unit tests: Behavior is pinned via engine integration tests; a couple of cases in client-projection.test.ts would keep the helper honest if engine imports drift.
  • Docs/types: Documented honestly that ClientDataOf still lists secret fields under identity/exclude — runtime omit is the real guarantee; type-level Omit would be a larger follow-up.

What I would not change

  • Third-party redaction libs for a fixed key list at definition time.
  • Redacting content (correctly out of scope; contentTemplate leakage is a separate author concern).
  • Duplicating the workforce debug test entirely — the real-router proof is worth keeping even though engine tests overlap.

Nice, focused product fix with tests that match the threat model.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

@cursor

cursor Bot commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: fbcdb5fb-a89e-43a7-b019-0307124c4476)

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

Code Snob. I tried one helper for the projection reads. It tied. No POC.

omitSecretFields is the strip. The two debug builders call it, then computeClientView on that state. applyClientData is already omit-then-project for list, get, and search. The snapshot and the live delta each do that pair once, in files that do not import the route module.

I folded those four pairs into projectClientState and deleted applyClientData. The helper is 11 lines, with a cast because omit returns JsonObject. The call sites lose 15. Against this head (those call sites are unchanged since db7c2f941) that is +21/−26. A new export for five lines ties. Debug still calls omitSecretFields.

The line above secret: ["value"] repeats the header. One line. The new omitSecretFields cases pin the same-object return; the drop is already the engine reads.

Left as recorded: secret stays its own list.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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: db7c2f9418

ℹ️ 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".

Comment thread packages/core/src/types/resource.ts Resolved
Comment thread .changeset/resource-secret-fields.md Resolved
Comment thread .changeset/resource-secret-fields.md Resolved
@cursor

cursor Bot commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 117d82f3-8e1a-4407-a0e7-d2e37ed03baf)

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. The Codex P1 on scope-level client.derived (packages/core/src/types/resource.ts:263; raw resource state reaches it through createScopeResources in packages/engine/src/routes/route-utils.ts) is left open for your call. I agree with the reply that a derived projection is author-written like client.data, so accepting it as a documented limit is fine by me. To unblock: resolve that thread (or ask for the redaction), and once CI is green on c361335 the label goes on.

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. An open Codex P1 remains on scope client.derived still receiving raw secret resource state (packages/core/src/types/resource.ts near the secret declaration / scope projection path). Either resolve that thread as wontfix (author-written projection, same class as the documented contentTemplate limit) with a one-line note on the Secret fields page, or land a fix on this PR. Unblock: close that P1 thread with an explicit owner decision, or merge the fix.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet — Codex P1 on scope-derived projections is still unresolved (packages/core/src/types/resource.ts / scope handles in route-utils). You left it open for a PR-owner call. Resolve that thread (accept the won't-fix-in-this-PR rationale) or redact state passed into scope client.derived. CI is also still running.

@cursor

cursor Bot commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: c8c3b985-7fa4-4149-b6ab-5cc21485ebae)

@jhoffner
jhoffner added this pull request to stack #3270 October 13, 2026 22:37
Base automatically changed from claude/project-thread-i3njgj to main October 13, 2026 23:22
…e server, debug routes included (FIX-1955)

Resources and collections take a `secret` list of state fields. Every read
the engine serves omits them: the client snapshot, the list-state and
get-state routes, live deltas, and the debug routes, which otherwise return
full state. Workforce's mcp-credentials collection declares `value` secret,
so a stored MCP key no longer comes back from /debug/resources*.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0149AEso8yp91qXPZtLjKe6z
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0149AEso8yp91qXPZtLjKe6z
… redacted state (FIX-1955)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0149AEso8yp91qXPZtLjKe6z
…om its result; shared cells must agree on secret fields (FIX-1955)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0149AEso8yp91qXPZtLjKe6z
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0149AEso8yp91qXPZtLjKe6z
@jhoffner
jhoffner force-pushed the claude/project-thread-rjvsrj branch from f84e4b7 to 95e15c0 Compare October 13, 2026 23:22
@cursor

cursor Bot commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 141dec1a-57bd-4a97-8731-6028544be4b0)

@jhoffner
jhoffner merged commit 25636f1 into main Oct 13, 2026
17 of 19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants