fix(trigger-api,service-automation): refuse an api flow with no per-flow secret, at arm time and at registration (#20529)

[objectstack-fleet]

Fixes #20529

Clause-②: no (narrowing)

What this changes

ADR-0041 (status Accepted), trigger-api acceptance criteria: "Per-flow inbound endpoint (...) with a per-flow secret; HMAC signature verification (GitHub/Stripe style) and a constant-time compare." The trigger armed a flow's inbound hook with no secret, logging only a warning, and such a hook skipped signature verification. An api trigger with no secret is now refused at arm time and at registration.

• @objectstack/trigger-api
  • ApiTrigger.start() throws when the binding's config.secret is absent, blank after trim, or not a string. The error names the flow and config.secret. It throws before anything is stored in the hook map and before any queue consumer is subscribed.
  • The arm-time warning is removed, because the state it described no longer exists.
  • ArmedHook.secret is now non-optional. handleRequest verifies every post, so the type system has no unsigned branch left to reach.
  • The route ledger's note, which recorded an unsigned posture, now records that every hook this door serves is signed.
• @objectstack/service-automation
  • registerFlow gains validateApiTriggerSecret, placed after the three existing hard-fail validations.
  • It judges the binding that deriveTriggerBinding computes. That is the body of resolveTriggerBinding, split out so it also runs over a flow that is not registered yet. So the rule reads the very config object that activateFlowTrigger would hand start(), including the array-form precedence.
  • It applies whatever the flow's status, like the other registration refusals.
  • What callers see is unchanged in kind:
    • The /automation create, update and clone doors answer 400 VALIDATION_FAILED with details.fields[0] = { field: '(body)', code: 'invalid_value' }. This throw has the same plain-Error shape (the flow-rejected message) that packages/runtime/src/domains/automation-register-error-class.test.ts case 4 already pins.
    • Boot skips the flow with the existing [Automation] failed to register flow warning.
• No new error code, and no packages/spec edit.

Why the rule lives in two places. @objectstack/trigger-api and @objectstack/service-automation have no dependency on each other. At boot the trigger registers on kernel:ready, after the flow pull, so the engine cannot ask it at registration time. The engine's copy is the publish-time refusal the author sees. The trigger's copy protects a host that binds without the engine. Both read the same binding config, so they cannot disagree about which flows need a secret. A single home that also reaches os validate would be a packages/spec rule (see below). That is the spec lane's call and is not made here.

Breaking. The changeset .changeset/20529-api-trigger-requires-secret.md bumps both packages minor. Its BREAKING paragraph gives the remedy: set a non-blank config.secret on the start node. A flow that is only ever started explicitly is type: 'autolaunched', with no triggerType: 'api', and needs no secret. Its ADR-0087 disposition is not-required (no-migration-prescription), accepted by check-adr-0087-registration.

Pin sweep

• Pins of the old semantics, repo-wide. A repo-wide git grep for the warning text, "unsigned post" and "accepts unsigned" (CHANGELOGs excluded) hit four places:
  • the test pin, flipped;
  • the trigger docblock, rewritten;
  • the route-ledger note, rewritten;
  • skills/objectstack-automation/SKILL.md:356. That file is a Tier H governed surface outside this card's file surface, so it is reported, not edited.
• The flipped pin carries weight. "accepts unsigned posts when no secret is configured" became three cases, for a missing, a blank and a non-string secret. Each asserts all of the following:
  • start() throws, naming the flow and config.secret;
  • listHooks() is [];
  • no queue subscription happened, and no armed: log line was written;
  • a post to that flow answers 404 with the full RESOURCE_NOT_FOUND body;
  • nothing was published or delivered, and the flow never ran.
• The guarded surface is kept verbatim. The 401 missing-or-bad-signature assertions are unchanged; only the test title lost its "when the flow declares a secret" clause. Every other case that armed with {} now arms with a secret and signs its body, and its assertion is unchanged.
• Fixture triage. Three existing fixtures registered an api flow with no secret:
  • engine.test.ts: the execution-history fixture changes type to autolaunched. It is only ever run through engine.execute, never an inbound hook.
  • flow-trigger-kind-shared-resolver.test.ts (the type: 'api' and triggerType: 'api' rows) and flow-activation-ledger.test.ts (the api entry path) now declare the secret. Their subject is kind resolution and ledger refusal, so they must stay api.
  • A repo-wide scan for api-kind flow definitions found no other fixture that reaches a real engine. The only other hits are in packages/lint and packages/spec tests, which never call registerFlow.
• New registration pins (api-trigger-secret-registration.test.ts):
  • Five refusal cases: a type: 'api' flow with no, blank or non-string secret; a start-node triggerType: 'api' flow; and an obsolete flow. Each asserts that the flow is absent afterwards (getFlow is null and it is not in the runtime states) and that the api trigger was never started.
  • Two contrast cases: a signed flow registers, binds, and hands the trigger its secret; an autolaunched flow needs no secret and runs.
  • One re-registration case: a re-registration that drops the secret is refused, and the stored signed version stays, neither stopped nor re-started.

Verification record (HEAD b7325134)

• Build. I built the dependency closure of both packages, then ran a full turbo run build --filter=!@objectstack/docs --concurrency=2: 72/72 tasks, 0 cached. It was needed for the dist-reading gates.
• Tests
  • @objectstack/service-automation: 150 files, 1845 tests, all passed.
  • @objectstack/trigger-api: 2 files, 26 tests, all passed.
  • Both suites ran on b7325134, after the last commit.
• Typecheck
  • @objectstack/trigger-api passes. tsc --listFiles counts both of its test files.
  • @objectstack/service-automation passes, including check:test-typecheck.
• Ablation 1: arm-time refusal. scripts/ablation-replace.mjs replaced the throw with the old logger.warn.
  • Landed: anchor 1 to 0, blob 7e60a8ab to cc123fba.
  • Red: Tests 3 failed | 8 passed (11). All three refusal cases failed with AssertionError: expected [Function] to throw an error.
  • Restored: blob equals HEAD 7e60a8ab, and git diff HEAD is empty.
  • Green before and after: 26/26.
• Ablation 2: registration refusal. The validateApiTriggerSecret call was deleted.
  • Landed: anchor 1 to 0, blob 679f73dd to e66c2db2.
  • Red: Tests 6 failed | 2 passed (8). All five refusal cases and the re-registration case failed with expected [Function] to throw an error. The two contrast cases stayed green.
  • Restored: blob equals HEAD 679f73dd, and git diff HEAD is empty.
  • Both suites import the subject from relative source, so no dist/ was involved.
• Gates. dispatch-gates --commands, derived over this diff's 9 paths, gave 62 commands. All 62 exited 0. Reconciling with --ran gave "62 derived, 62 run, 0 NOT-MEASURED (a DERIVED zero)". check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (exit 3, not a measurement). After the full build it exited 0. check:dts-closure and check:lean-entry-closure were re-run after the full build too.
• Lint, narrowed and proven. eslint --no-inline-config --format json over the 8 changed .ts files reported 8 files, 0 errors and 0 warnings. Three facts make that narrowing a measurement rather than a skip:
  • The population comes from the config: each file matches the packages/**/*.{ts,tsx,mts,cts} blocks, and none reported "File ignored".
  • The count comes from the JSON output.
  • The config never enables type-aware linting (no parserOptions.project; eslint.config.mjs states this at lines 326–328), so this diff cannot move any untouched file's verdict.
• Declared to CI: the repo-wide pnpm lint, the downstream consumer suites of @objectstack/service-automation, and the full farm.

The three measurements

1. Run identity: yes, for the documented pattern. The inbound trigger supplies no user. A fired run takes the identity of the flow's declared runAs, which defaults to 'user'.
   • Under the default, data nodes are refused for want of a principal.
   • A flow that declares runAs: 'system' runs its data nodes with system elevation. The shipped worked example declares runAs: 'system', because it creates a record.
2. Can a non-admin read config.secret: yes, by source reading. I reported it to the seat as an out-of-scope security finding. It is not changed here.
3. Shipped examples, templates, scaffolds: no. The only shipped api flow is the showcase's worked example, and it carries a secret, so examples/** needs no edit. packages/create-objectstack declares no api flow. One thing did turn up: the published automation skill describes the secret as optional (reported below).

os validate reach

No. os validate never builds an AutomationEngine or calls registerFlow. packages/cli/src/commands/validate.ts runs the defineStack parse, the @objectstack/lint authoring rules and the capability preflight. I measured it on a throwaway stack (deleted afterwards) that declares one type: 'api' flow with no secret and requires: ['automation', 'triggers', 'queue']: os validate printed ✓ Validation passed, exit 0. #20367 (PR #20460) runs the stack's defineStack refusals, and this refusal is not one of them. For os validate to see it, the rule would need to be a defineStack refusal next to the trigger-capability refusal (keyed on resolveFlowTriggerKind), or a validate-flow-trigger-readiness rule in packages/lint. Both belong to another lane.

Acceptance notes

• hookId fallback left as is. A secret is now mandatory for every armed hook, so the fallback token no longer has an unsigned form and nothing concrete argues for changing it here.
• Out-of-scope findings, reported to the seat and not filed from here:
  • skills/objectstack-automation/SKILL.md (lines 52 and 356) calls the secret "strongly recommended" and describes type: 'api' as "invoked explicitly … or bound as an inbound webhook". The engine binds every type: 'api' flow to the inbound trigger, so an author following it now writes a flow the runtime refuses. The file is Tier H.
  • os validate passes a flow the engine refuses (measured above).
  • The measurement ② finding.
• content/docs/**. No line calls the inbound secret optional (0 hits), so there is no docs edit. Two observations, not filed:
  • content/docs/automation/flows.mdx says an api flow "inherits its organization from whoever triggered it". The inbound trigger passes no caller session.
  • content/docs/automation/webhooks.mdx §16 still lists inbound webhooks as a non-goal with "no runtime".
  • Carrier for both: none.
• Not done here:
  • No scripts/adr-anchors/ entry for ADR-0041 was added. That path is outside this card's file surface.
  • Whether the Studio flow designer (objectui) can author an api flow's config.secret is not measured. The sibling repo is not checked out in this container.
• Gate list size. Derived over the paths this diff actually touches, the list is 62 commands. The dispatch-time list over the expected paths was 92, because it also included examples/** and content/docs/** paths this diff never touched.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-automation, @objectstack/trigger-api, touching 7 documentable anchor(s).

4 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via registerFlow (symbol, a method of class AutomationEngine))
• content/docs/data-modeling/formulas.mdx (via registerFlow (symbol, a method of class AutomationEngine))
• content/docs/kernel/contracts/auth-service.mdx (via handleRequest (symbol, a method of class ApiTrigger))
• content/docs/permissions/authentication.mdx (via handleRequest (symbol, a method of class ApiTrigger))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via AutomationEngine (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via AutomationEngine (symbol, a top-level class), registerFlow (symbol, a method of class AutomationEngine))
• content/docs/releases/v17/17-4.mdx (via registerFlow (symbol, a method of class AutomationEngine))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 6 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json ba5927f714af7516105706b36a05cedf34d5fa1b → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 9a2dc358228242b8aada7f4c41a3acf6c575e1ff — the merge of head b73251341bdcb5d4d345a75af0a7602fdbe669af into base ba5927f714af7516105706b36a05cedf34d5fa1b, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 9a2dc358228242b8aada7f4c41a3acf6c575e1ff && git checkout 9a2dc358228242b8aada7f4c41a3acf6c575e1ff
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ba5927f714af7516105706b36a05cedf34d5fa1b b73251341bdcb5d4d345a75af0a7602fdbe669af && git checkout -B drift-repro ba5927f714af7516105706b36a05cedf34d5fa1b && git merge --no-ff b73251341bdcb5d4d345a75af0a7602fdbe669af

node scripts/docs-audit/affected-docs.mjs --json ba5927f714af7516105706b36a05cedf34d5fa1b

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs ba5927f714af7516105706b36a05cedf34d5fa1b → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: b73251341bdcb5d4d345a75af0a7602fdbe669af
Local-runs: none

Card #20529 (security, priority:p1) · PR #20551 (draft, head repo = base repo, base main, merge-base 288611e, mergeable: true) · 9 files, +326/−39; the PR file list and the net diff against main agree on the set. Inputs: the card's body and all three comments (triage 5881532933, claim 5881845145, os-dev-report 5882379577), the PR body, its file list, the net diff, and the head's check-runs. Read-only: no worktree, build, test or gate run.

Check-runs on the head, latest run per check name, read at 2026-09-29T02:29:36Z: 34 names — 31 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke (opt-in) — path/opt-in skips, not verdicts on this diff), 0 failure, 0 in_progress. An earlier read at 2026-09-29T02:23:45Z still had Lint & Repo Gates, four Test Core shards and the Dogfood Regression Gate rollup in progress; all six have since concluded success. Check Changeset and Governed Surface Queue Guard are among the successes.

① Derived judgments

Every accept-set and public-surface change the diff implies, named and judged:

1. @objectstack/trigger-api — ApiTrigger.start() accept set narrows. RIGHT. A binding whose config.secret is absent, blank after trim, or not a string now throws (naming the flow and config.secret) before the hook-map write and before the queue subscribe, so a refused flow leaves no hook and no consumer. The refused set is exactly the set the pre-existing normalisation line already collapsed to undefined and then armed unsigned — nothing that used to arm signed is refused. The start() signature and FlowTriggerBinding are unchanged. Governing text: ADR-0041 (Accepted), trigger-api acceptance criteria, docs/adr/0041-flow-trigger-family.md:117-119 — a per-flow secret, HMAC verification, constant-time compare. The engine's existing bind catch (engine.ts:3690, warn, "Failed to bind flow") already handles a trigger that throws at bind, so a host reaching this path gets the established registered-but-unbound outcome.

2. @objectstack/trigger-api — handleRequest loses its unsigned branch. RIGHT. Every stored hook now carries a secret, so the branch had no reachable input left; the response set (404 / 401 / 400 / 202 / 503) and every body shape are unchanged. A post to a refused flow answers the same 404 body an unknown flow gets — the no-probing-oracle property is kept and now pinned.

3. ArmedHook.secret becomes required. RIGHT, and not a published-surface change: ArmedHook is a non-exported interface, unreachable from src/index.ts (which exports ApiTriggerPlugin, HOOKS_PATH, ApiTrigger, verifySignature and the four types FlowTrigger, FlowTriggerBinding, QueueServiceSurface, TriggerLogger). Under the exports-map rule it is shipped bytes, not a published accept set — no Clause-② effect. Correctly left out of the semver reasoning.

4. Trigger docblock and TRIGGER_API_ROUTE_LEDGER note. RIGHT. Prose only; the ledger table is entry-unreachable and read by its conformance test. The two remaining in-tree statements of the old posture are corrected; the one outside the diff is a Tier H file (③.g).

5. @objectstack/service-automation — AutomationEngine.registerFlow() accept set narrows. RIGHT. validateApiTriggerSecret runs after the three existing hard-fail validators (validateNodeConfigKeys, validateDecisionModes, validateFlowExpressions) and before the version-history push and this.flows.set (engine.ts:4193-4222), so a refused first registration stores nothing, and a refused re-registration leaves the stored definition, its history and its armed trigger untouched (pinned by the re-registration case). It throws a plain Error; all six registerFlow callers at the head are per-flow try/caught — service-automation/src/plugin.ts:984, :2014, :2059 (boot, re-sync, cold-boot bind — each logs the existing "failed to register flow" warning and continues) and runtime/src/domains/automation.ts:2105, :2397, :2993 (create, clone, update — each maps the throw through flowDefinitionRefusal to 400 VALIDATION_FAILED). No new error code. What callers see is unchanged in kind.

6. The rule is keyed on the resolved trigger kind, not on type. RIGHT. deriveTriggerBinding is resolveTriggerBinding's body moved verbatim (array-form pre-check, then resolveFlowTriggerKind, then the per-kind switch), so the refusal judges the very binding.config — the start node's config object — that activateFlowTrigger hands start(). Spec's resolver answers api only from type: 'api' or a start-node triggerType: 'api', and only after the record- / timeRelative / schedule precedence, so a type: 'api' flow whose start node carries a schedule resolves to schedule, needs no secret, and binds to that trigger exactly as before; the refusal message's parenthetical is never empty. Both new methods are private, so the entry .d.ts gains only private member names — not a published surface.

7. Status-agnostic refusal (an obsolete api flow with no secret is refused too). RIGHT. It matches the three existing hard-fail validators, none of which reads status; an obsolete flow re-enabled by toggle would otherwise reach activateFlowTrigger and be refused there with a warn, so refusing at registration is the loud, earlier form of the same outcome. The changeset discloses it ("whatever the flow's status").

8. hookId 'default' fallback left unchanged. RIGHT. Triage's ⛔ was against a default token standing in for an unset one without a secret; with a secret mandatory for every armed hook, the fallback has no unsigned form.

9. Pins. RIGHT. The test that encoded the defect is replaced by three refusal cases (missing / blank / non-string), each asserting the substance — a throw naming the flow and config.secret, listHooks() empty, no queue subscribe, no armed: log line, a full-body 404 on a post, nothing published, delivered or run. The 401 missing-or-bad-signature assertions are verbatim; every other case that armed with {} now arms with a secret and signs, assertion unchanged. beforeEach rebuilds the fake queue (with its new subscribed recorder), the trigger and the runs list and clears the mocks, so the "nothing subscribed, nothing logged" assertions are sound. The registration suite asserts absence (getFlow null, not in runtime states, trigger never started) for all five refusals, plus two contrast cases and the re-registration case.

10. Fixture triage. RIGHT. The engine.test.ts execution-history fixture goes api → autolaunched (its only entry is engine.execute, and its subject is execution history); flow-activation-ledger.test.ts and flow-trigger-kind-shared-resolver.test.ts add a secret rather than change kind, since their subject is the api kind.

11. Reach of the narrowing across the repo at the head, outside the nine edited files. By source reading the narrowing reds no untouched suite: the only flow-shaped api definition is the showcase inbound flow (examples/app-showcase/src/automation/flows/index.ts:1562-1582), which carries a literal secret; packages/create-objectstack declares no api flow; trigger-api/src/plugin.ts constructs no binding itself; every other type: 'api' hit in packages/** and examples/** is an action, a connector or a metadata item type, not a flow. The live measurement is the full Test Core farm, which is green on the head.

12. Correctly not changed. packages/spec untouched (the start-node config is an open record; spec carries no secret typing on it, so no published type documents the inbound secret as optional — the secret / signingSecret optionals in spec belong to the outbound webhook and IO-node schemas). content/docs has no inbound-secret wording to correct (every HMAC/secret hit is outbound webhook delivery). No examples/** edit needed.

② Semver level

• Changeset .changeset/20529-api-trigger-requires-secret.md: @objectstack/trigger-api: minor, @objectstack/service-automation: minor. Both publish — neither is private, both carry an exports map, both are in the 69-member fixed group — and they are the only two packages whose published source moves. Set: RIGHT.
• Clause-②: no (narrowing) — the PR body, the changeset body and the claim agree on the one spelling. Nothing widens: no new export, no new accepted key, no new response shape, and the only type change (ArmedHook) is entry-unreachable. The accept sets of ApiTrigger.start() and AutomationEngine.registerFlow() narrow, which is breaking for any flow that binds the api trigger without a secret. yes would be false; a bare no would hide the break. Arm: RIGHT.
• Level. Under the launch-window convention (scripts/check-changeset-no-major.mjs) major is refused and a breaking change ships as minor, with breaking-ness carried by the BREAKING banner and the ADR-0087 disposition. The changeset carries the banner, the FROM → TO remedy (set a non-blank config.secret on the start node; a flow that is only ever started explicitly is type: 'autolaunched' with no triggerType: 'api'), and an adr-0087 marker comment reading not-required (no-migration-prescription) with its reasoning (nothing authorable changes spelling or type; the missing value is a shared secret no migration can synthesise; the other categories closed on facts). minor is the highest level the window allows, and patch would be wrong for a narrowing. Check Changeset and Lint & Repo Gates — the workflows that run the level axis and the ADR-0087 registration gate — are success on the head. Level: RIGHT.

③ Boundary flags

The report's open_questions is empty. Its five deviations, three out_of_scope_findings and the PR body's "Not done here" items, each answered or escalated:

• a–d. Three git pushes against a budget of one; model-free commit trailers; a full turbo build for the dist-reading gates; a throwaway os validate fixture deleted before commit. Answered: process notes with no contract effect; the file list confirms no stray fixture path landed. Nothing to escalate.
• e. Status-agnostic refusal — "the seat may want to confirm". Answered, confirmed: ①.7.
• f. Out-of-scope, class b, security — a stored flow definition, start-node config.secret included, is served verbatim to any authenticated member by the automation domain's definition-read branch (source-read, not live-measured). ESCALATE. This is triage's measurement 2 answered YES, and triage wrote that any yes makes the card p0 and it regrades. It is outside this PR's file surface and does not make this diff wrong — refusing the anonymous door is strictly better than leaving it open regardless — but until it is closed the secret this PR mandates is readable by any member, so this PR's protection is against unauthenticated senders only. Needs its own security card (redaction or projection on the definition read; the metadata-plane read of the same definition still unmeasured) and a triage regrade.
• g. Out-of-scope, class c — skills/objectstack-automation/SKILL.md:52 and :356 describe type: 'api' as invocable explicitly or bound as an inbound hook, and the secret as "strongly recommended" with unsigned posts accepted. Verified at the head. ESCALATE. Tier H (skills/**), outside the claim's file surface, so reporting rather than editing was the correct discipline. After this lands, an author following the published skill writes a flow the runtime refuses at publish and at boot; needs a Tier H closeout card.
• h. Out-of-scope, class c — os validate passes a stack with a secretless api flow that the engine refuses (dev-measured). ESCALATE to the spec/lint lane: a defineStack refusal beside the trigger-capability refusal (keyed on resolveFlowTriggerKind), or a validate-flow-trigger-readiness rule. [finding] os validate runs only the stack schema parse, so a config that exports a plain object (no defineStack() call) skips every defineStack cross-field refusal and passes #20367 / PR feat(spec,cli)!: one stack authoring shape — os validate / os build refuse a default export defineStack did not build #20460 does not cover it. Same family as g — one closeout card can carry both authoring-time surfaces.
• i. hookId fallback kept. Answered: ①.8.
• j. Rule kept in two places. Answered, agreed: the two packages have no dependency on each other, the trigger registers at kernel:ready after the flow pull, and both copies read the one binding config (①.6). The only single home that would also reach os validate is spec — item h.
• k. No scripts/adr-anchors/ entry for ADR-0041. ESCALATE as a small follow-up, non-blocking: the ADR id is left in the code at both load-bearing spots (Prime Directive [WIP] Add Chinese version of the documentation #13's first half); anchoring them is the second half and sits outside this card's file surface.
• l. Studio flow designer (objectui) authoring of config.secret — not measured, sibling not checked out. ESCALATE as an open item for the seat: if the designer cannot author secret, every designer-authored api flow is now refused. Not measurable from this repo; non-blocking here.
• m. Two content/docs observations (flows.mdx organisation-inheritance sentence; webhooks.mdx §16 listing inbound as a non-goal with no runtime), carrier none. Answered: docs-accuracy drifts predating this card; a docs-audit follow-up, not a condition on this PR.
• n. Serial constraints. The claim read main at 03b19d9, the dev verified premises at 288611e (the merge-base), and main is now ba5927f; the PR is mergeable: true and the net diff against current main is the same nine files. No conflict and no intervening change to the touched files.

Disclosure: this is a security card; the defect and the fix are described here abstractly and no request recipe is given.

Implemented-by: claude/issue-20529-api-trigger-requires-secret
Reviewed-by: session_017B6YKCGu8CTY2KBWgwaHAs

VERDICT: PASS

_{Rendered by an isolated contract-review subagent and adopted by the domain:services seat (#6021, session_017B6YKCGu8CTY2KBWgwaHAs) at 2026-09-29T02:34Z, after a transcript check: 111 harness model stamps, all at CONTRACT_REVIEW_TIER, zero fallbacks; 38 Bash calls and 1 Write (this record, to its own scratch path); zero GitHub writes. The seat's disposition of the four ESCALATE flags:}

• ③.f is filed [security] a flow's inbound-hook secret (config.secret on the start node) is served in cleartext by the flow-definition read; after #20529 every armed hook carries one #20552 ([security], a P0 suspect; triage was knocked at 5882464926 for emergency direct triage and trigger-api arms a flow's inbound hook without a secret and accepts unsigned posts; ADR-0041's trigger-api acceptance criteria name a per-flow secret and HMAC verification #20529's regrade).
• ③.g and ③.h are filed After #20529, authoring surfaces still teach or pass an api flow with no secret: skills/objectstack-automation calls it optional, and os validate passes it #20553, one closeout card for the family, with the Tier H skills half and the lint/spec half enumerated separately.
• ③.k is an Acceptance note (carrier: none).
• ③.l is an Acceptance note (carrier: none, unmeasurable from this repo). It is also named to the maintainer in the round report.
  None of the four blocks landing. This PR closes the unauthenticated door, which the record judges strictly better whatever those four answer.

---

Generated by Claude Code