wip: hand the runtime authoring gate the redaction context

Claude-Session: https://claude.ai/code/session_01DEvba2nBuD4tWzfq8r8NFY
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/lint/src/authoring-rules.ts

@@ -337,6 +337,28 @@ export interface AuthoringRuleContext {
    * this input or does not judge.
    */
   judgeFilter?: IObjectQLEngine['judgeFilter'];
+  /**
+   * [#20611] The credential positions of the WRITTEN item that the write path
+   * restores from the stored row before it persists the item — stack-relative,
+   * in the rules' own finding-path spelling (`flows[0].nodes[1].config.secret`).
+   *
+   * Set only by the runtime publish gate (`runtime-gate.ts`), from what its host
+   * states; ABSENT on the three CLI commands, whose stacks carry the author's
+   * own values. It exists because the read path withholds a credential from
+   * every served definition (a flow's start-node `config.secret`), so a body
+   * saved back after a read arrives WITHOUT it, and the host's carry-forward
+   * puts the stored value back only after every gate has run — on purpose, so
+   * that no gate handles a restored credential. A rule therefore cannot tell a
+   * withheld credential from a missing one by reading the body, and this set is
+   * how it is told: a path listed here is WITHHELD AND STORED, and a rule
+   * judging whether a credential is present reads it as present. A path not
+   * listed is judged on the body as sent, so a credential that is absent and
+   * not stored is missing.
+   *
+   * ⛔ Positions only, never values: the gate never sees a restored credential.
+   * Read by `validateFlowApiTriggerSecret` only.
+   */
+  restoredCredentialPaths?: ReadonlySet<string>;
 }
 
 export interface AuthoringRule {
@@ -1113,7 +1135,8 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
   // routes nowhere, silently demoting it to a manual flow. #20553 made it five: an
   // `api`-bound flow with no usable `config.secret`, which the engine's own
   // `registerFlow` refuses (ADR-0041) — on its OWN entry below
-  // (`validateFlowApiTriggerSecret`), because it is CLI-only for now. None of those verdicts
+  // (`validateFlowApiTriggerSecret`), because it reads a context input this entry
+  // has no use for (#20611). None of those verdicts
   // can be changed by installing a package, so there is no reading under which
   // the flow fires. `flow-trigger-unknown-object` deliberately stayed `warning`
   // (the object may come from another installed package — a hedge this rule
@@ -1144,33 +1167,32 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
     run: (stack) => validateFlowTriggerReadiness(stack),
   },
   // #20553 — `flow-api-trigger-secret-missing`, split out of the entry above as
-  // its own exported rule (the `validateSecurityRoleWord` precedent: one rule id
-  // sits on ONE side of the runtime wall). Same family, same `error`, all three
-  // commands — but NOT the runtime publish gate yet, and #20611 is the card that
-  // moves it across. The flow read path withholds `config.secret` from every
-  // served definition (#20552) and `saveMetaItem` restores the stored secret only
-  // just before the put, AFTER this table has judged the body the caller sent —
-  // so on the gate, a signed flow's ordinary GET → edit → PUT reads as
-  // secretless. Measured on `825c33ff9f`: with this id on the gate, the two
-  // round-trip pins in `protocol.metadata-redaction.test.ts` fail; off it, 26/26.
-  // The `/meta` door therefore keeps its pre-rule behaviour (it stores a
-  // secretless flow, and the engine refuses it at registration) until the gate
-  // judges the carried-forward body — then this entry becomes `CLI_AND_RUNTIME`
-  // with `runtimeTypes: ['flow']`, like the one above.
+  // its own exported rule. Same family, same `error`, all three commands.
+  //
+  // #20611 — and the runtime publish gate too. The flow read path withholds
+  // `config.secret` from every served definition (#20552), and `saveMetaItem`
+  // restores the stored secret only just before the put, AFTER this table has
+  // judged the body the caller sent — deliberately, so no gate handles a
+  // restored credential. So the gate is handed the POSITIONS that restore will
+  // fill (`AuthoringRuleContext.restoredCredentialPaths`), and the rule reads a
+  // withheld-and-stored secret as present: a signed flow's ordinary
+  // GET → edit → PUT passes, and a secretless `api` flow is refused at `/meta`
+  // with this id instead of being stored for the engine to refuse at
+  // registration.
   {
     name: 'validateFlowApiTriggerSecret',
     tier: 'gating',
     input: 'normalized',
     commands: ALL,
     source: 'packages/lint/src/validate-flow-trigger-readiness.ts',
-    surfaces: CLI_ONLY,
-    surfaceReason:
-      'Not yet runtime-safe: the publish gate judges a /meta save BEFORE saveMetaItem restores the ' +
-      'inbound-hook secret the flow read path withholds, so a signed api flow\'s ordinary GET, edit, PUT ' +
-      'round trip reaches this rule secretless and would be refused. It crosses when the gate judges the ' +
-      'carried-forward body (the seam follow-up named in the comment above); until then the engine\'s ' +
-      'registerFlow refusal is what a secretless flow saved through /meta meets.',
-    run: (stack) => validateFlowApiTriggerSecret(stack),
+    // Runtime publish gate (#20611): judged on the per-write snapshot like the
+    // entry above, with the host's restored-credential positions read as
+    // present. The CLI never sets that input, so there the author's own
+    // `config.secret` is the whole answer.
+    surfaces: CLI_AND_RUNTIME,
+    runtimeTypes: ['flow'],
+    run: (stack, ctx) =>
+      validateFlowApiTriggerSecret(stack, { restoredCredentialPaths: ctx.restoredCredentialPaths }),
   },
   // ADR-0090 D3 fallout — an approval `{ type: 'role' }` resolves against the
   // better-auth org-membership tier, not positions, so a position name authored

packages/lint/src/runtime-gate.ts

@@ -832,6 +832,49 @@ export function nameKeyFindingPath(path: string, candidate: AnyRec): string {
   return `${stackKey}.${name}${rest}`;
 }
 
+/**
+ * [#20611] The host's restored-credential positions, re-spelled from the
+ * redactor registry's item-relative dotted form (`nodes.1.config.secret`) into
+ * the finding-path form the rules emit and compare against, anchored at the
+ * written item's place in `candidate` (`flows[0].nodes[1].config.secret`).
+ *
+ * The written item is the LAST member of its collection in the candidate —
+ * {@link buildRuntimeWriteSnapshots} appends it — so that index is the anchor.
+ * Each segment is spelled `[n]` exactly where the item holds an array at that
+ * point of the walk and `.key` everywhere else: read off the item, never
+ * guessed from the segment's digits, so a record key that happens to be
+ * numeric keeps its key spelling. A path that walks off the item keeps the key
+ * spelling from there on; it names no position any rule reports, so it
+ * excuses nothing.
+ */
+function restoredCredentialStackPaths(
+  candidate: AnyRec,
+  type: string,
+  dottedPaths: readonly string[],
+): ReadonlySet<string> {
+  const stackKey = stackKeyForType(type);
+  const collection = stackKey ? candidate[stackKey] : undefined;
+  if (!stackKey || !Array.isArray(collection) || collection.length === 0) return new Set();
+  const index = collection.length - 1;
+  const item: unknown = collection[index];
+  const out = new Set<string>();
+  for (const dotted of dottedPaths) {
+    let path = `${stackKey}[${index}]`;
+    let node: unknown = item;
+    for (const segment of dotted.split('.')) {
+      if (Array.isArray(node) && /^(0|[1-9][0-9]*)$/.test(segment)) {
+        path += `[${segment}]`;
+        node = node[Number(segment)];
+      } else {
+        path += `.${segment}`;
+        node = node !== null && typeof node === 'object' ? (node as AnyRec)[segment] : undefined;
+      }
+    }
+    out.add(path);
+  }
+  return out;
+}
+
 function runRules(
   rules: readonly AuthoringRule[],
   stack: AnyRec,
@@ -894,6 +937,20 @@ export function runRuntimeAuthoringRules(args: {
    * it skip the engine's judgement and answer as they did without it.
    */
   judgeFilter?: IObjectQLEngine['judgeFilter'];
+  /**
+   * [#20611] The positions in `item` at which the host's write path restores a
+   * credential from the stored row before it persists the item — dotted and
+   * item-relative, the `@objectstack/spec/kernel` redactor registry's
+   * `redactedKeys` spelling (`nodes.1.config.secret`). The read path withholds
+   * those credentials, so a body saved back after a read arrives without them,
+   * and the host restores them only after this gate has run.
+   *
+   * Handed to the rules as `AuthoringRuleContext.restoredCredentialPaths`,
+   * translated into the candidate snapshot's finding-path spelling; see
+   * {@link restoredCredentialStackPaths}. Omitted, every position is judged on
+   * the body as sent. ⛔ Positions only: no credential value reaches this gate.
+   */
+  restoredCredentialPaths?: readonly string[];
 }): RuntimeGateResult {
   const rules = runtimeAuthoringRulesFor(args.type);
   const empty: RuntimeGateResult = { errors: [], advisories: [], rulesRun: [] };
@@ -921,6 +978,19 @@ export function runRuntimeAuthoringRules(args: {
     sduiManifest: args.sduiManifest,
     runtimeWriteType: args.type,
     judgeFilter: args.judgeFilter,
+    // [#20611] Spelled against the CANDIDATE, the one snapshot that holds the
+    // written item. The baseline pass shares the set and cannot match it: the
+    // item is not in the baseline, and every other entry sits at an index the
+    // item does not.
+    ...(args.restoredCredentialPaths !== undefined && args.restoredCredentialPaths.length > 0
+      ? {
+          restoredCredentialPaths: restoredCredentialStackPaths(
+            snapshots.candidate,
+            args.type,
+            args.restoredCredentialPaths,
+          ),
+        }
+      : {}),
   };
   const before = new Set(runRules(rules, snapshots.baseline, ctx).map(fingerprint));
   const added = runRules(rules, snapshots.candidate, ctx)

packages/lint/src/validate-flow-trigger-readiness.ts

@@ -57,9 +57,10 @@
 //      arm it — yet `os validate` never builds the engine, so until this rule
 //      it answered "passed" for a flow no runtime will ever register. It is its
 //      OWN exported rule, `validateFlowApiTriggerSecret` (1h, at the foot of
-//      this file), because it runs on the CLI surface only until #20611 — see
-//      its docblock for why, and see `FLOW_API_TRIGGER_SECRET_MISSING` for why
-//      the judgement is carried here rather than read from the runtime.
+//      this file), because at the runtime publish gate it reads one input the
+//      rest of the family does not (#20611) — see its docblock for why, and see
+//      `FLOW_API_TRIGGER_SECRET_MISSING` for why the judgement is carried here
+//      rather than read from the runtime.
 //
 //   ⚠️ One more rule lived here and is RETIRED (#17396):
 //      `flow-schedule-organization-missing`, a `warning` on a time-triggered
@@ -140,13 +141,14 @@
 // flows keep being served. What IS refused is the dead flow's own publish — and,
 // on the CLI surface, a package build whose stack contains one.
 //
-// ⚠️ All of the above is about `validateFlowTriggerReadiness`. The sixth id,
-// `flow-api-trigger-secret-missing`, lives in `validateFlowApiTriggerSecret` on
-// its own registry entry, which is CLI-only until #20611: the publish gate
-// judges a `/meta` save before the stored `config.secret` the read path withheld
-// is restored, so at that door a signed flow's round trip would read as
-// secretless. That door still stores a secretless flow today, and the engine
-// refuses it at registration.
+// The sixth id, `flow-api-trigger-secret-missing`, lives in
+// `validateFlowApiTriggerSecret` on its own registry entry, which crosses the
+// runtime wall too (#20611) on the same per-write snapshot. It reads one more
+// input there: the publish gate judges a `/meta` save before the stored
+// `config.secret` the read path withheld is restored, so the gate hands the rule
+// the positions that restore fills, and a withheld-and-stored secret reads as
+// present. A secretless `api` flow is refused at that door; a signed flow's
+// round trip is not.
 
 import {
   TimeRelativeTriggerSchema,
@@ -773,8 +775,9 @@ export function validateFlowTriggerReadiness(stack: AnyRec): FlowTriggerReadines
 
     // 1h. ⚠️ NOT here — the `api` trigger's secret (#20553) is its own exported
     //     rule, {@link validateFlowApiTriggerSecret} below, on its own registry
-    //     entry: it sits on the OTHER side of the runtime wall (CLI-only until
-    //     #20611), and one rule id sits on ONE side of it.
+    //     entry: at the runtime publish gate it reads the host's
+    //     restored-credential positions (#20611), an input nothing else in this
+    //     family has a use for.
 
     // 2. Auto-triggered flow whose status is 'draft' — authored or defaulted
     //    (defineFlow parses at definition time, so the two are the same here).
@@ -822,32 +825,45 @@ export function validateFlowTriggerReadiness(stack: AnyRec): FlowTriggerReadines
  * engine reads its `config` as `{}` and refuses it for the same reason — and is
  * located at `nodes`, since there is no start node to point at.
  *
- * ## Why this is a separate function from {@link validateFlowTriggerReadiness}
+ * ## At the runtime publish gate: a withheld-and-stored secret is present (#20611)
  *
- * A surface boundary, not taste — the registry's `validateSecurityRoleWord`
- * split is the precedent. `validateFlowTriggerReadiness` runs on the runtime
- * publish gate too; this rule cannot, yet (#20611). The flow read path withholds
- * `config.secret` from every served definition (#20552), and `saveMetaItem`
- * restores the stored secret only just before the put — AFTER the runtime
- * authoring gate has judged the body the caller sent. So an ordinary `/meta`
- * GET → edit → PUT of a SIGNED flow reaches the gate secretless, and this rule
- * would refuse a save that keeps the secret. Measured on `825c33ff9f`: with this
- * id at the gate, `protocol.metadata-redaction.test.ts` fails exactly its two
- * round-trip pins; with it dropped there, 26/26 pass. So this id stays CLI-only
- * (`os validate` / `os build` / `os lint`, whose stacks carry the author's own
- * secret) until the gate judges the carried-forward body, and it is split out
- * WHOLE rather than filtered at one entry: one rule id sits on ONE side of the
- * wall. Meanwhile the `/meta` door behaves as it did before this rule existed:
- * it stores a secretless flow, and the engine refuses it at registration.
+ * The flow read path withholds `config.secret` from every served definition
+ * (#20552), and `saveMetaItem` restores the stored secret only just before the
+ * put — AFTER the runtime authoring gate has judged the body the caller sent,
+ * and deliberately so: no gate handles a restored credential. So an ordinary
+ * `/meta` GET → edit → PUT of a SIGNED flow reaches this rule without its
+ * secret, exactly like a flow that never had one. The body alone cannot tell
+ * the two apart; the host can, and the gate passes its answer in as
+ * `options.restoredCredentialPaths` (`AuthoringRuleContext`): the positions the
+ * host's carry-forward will fill from the stored row. The start node's secret
+ * path listed there is WITHHELD AND STORED, and reads as present; one not
+ * listed is judged on the body as sent, so a secret that is absent and not
+ * stored is missing, and the save is refused. The CLI never sets the option —
+ * its stacks carry the author's own secret.
+ *
+ * It is a separate function from {@link validateFlowTriggerReadiness} because
+ * that option is its input alone: the rest of the family judges nothing the
+ * read path withholds.
+ *
+ * @param options.restoredCredentialPaths Stack-relative paths, in this rule's
+ *   own finding-path spelling (`flows[0].nodes[1].config.secret`), that the
+ *   write path restores from the stored row. Positions only, never values.
  */
-export function validateFlowApiTriggerSecret(stack: AnyRec): FlowTriggerReadinessFinding[] {
+export function validateFlowApiTriggerSecret(
+  stack: AnyRec,
+  options: { restoredCredentialPaths?: ReadonlySet<string> } = {},
+): FlowTriggerReadinessFinding[] {
   const findings: FlowTriggerReadinessFinding[] = [];
   recordsOf(stack.flows).forEach((flow, flowIndex) => {
     const flowName = typeof flow.name === 'string' ? flow.name : `#${flowIndex}`;
     const start = startNodeOf(flow);
     const config = (start?.node.config ?? {}) as AnyRec;
     const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
     const bindsApiTrigger = !isArrayRecordTriggerType(config) && resolveFlowTriggerKind(flow) === 'api';
+    const secretPath = start ? `flows[${flowIndex}].nodes[${start.index}].config.secret` : undefined;
+    // [#20611] Withheld and stored ⇒ present: the host restores the stored
+    // secret at exactly this position before the item is persisted.
+    if (secretPath !== undefined && options.restoredCredentialPaths?.has(secretPath)) return;
     const secretProblem = bindsApiTrigger ? describeUnusableSecret(start, config) : undefined;
     if (!secretProblem) return;
     // Which declaration binds it — the engine's own message names the same
@@ -864,9 +880,7 @@ export function validateFlowApiTriggerSecret(stack: AnyRec): FlowTriggerReadines
       severity: 'error',
       rule: FLOW_API_TRIGGER_SECRET_MISSING,
       where: start ? `flow "${flowName}" › start node` : `flow "${flowName}"`,
-      path: start
-        ? `flows[${flowIndex}].nodes[${start.index}].config.secret`
-        : `flows[${flowIndex}].nodes`,
+      path: secretPath ?? `flows[${flowIndex}].nodes`,
       message:
         `binds the inbound api trigger (${binds.join(' and ')}) but ${secretProblem}. An inbound hook ` +
         `is armed only with a per-flow secret that every post is HMAC-verified against (ADR-0041), so the ` +