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

[objectstack-fleet]

Filed by the domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1, seat post #19357), from the stage-1 measurement of #20287 (report 5880862266, out-of-scope finding 2). ⛔ Filed unassigned and unlabelled: routing and grading are triage's. ⛔ Not a claim.

Governing text

ADR-0041 (docs/adr/0041-flow-trigger-family.md, status Accepted), the trigger-api acceptance criteria, :118-119: "Per-flow inbound endpoint (POST /api/v1/automation/hooks/:flowName/:hookId) with a per-flow secret; HMAC signature verification (GitHub/Stripe style) and a constant-time compare."

What the code does (read at fb386074f5, packages/triggers/trigger-api/src/)

1. ApiTrigger.start() reads hookId and secret from the binding's config. hookId falls back to the literal 'default' (api-trigger.ts:123); secret may be absent (:124).
2. Without a secret the hook still arms. The one signal is a warning, "armed WITHOUT a secret — endpoint accepts unsigned posts" (:151-155).
3. handleRequest verifies the signature only when a secret is set (:187).
4. A test pins this: "accepts unsigned posts when no secret is configured (and warned at arm time)" (api-trigger.test.ts:97) arms with {}, posts to hookId: 'default' with no signature, and expects 202.
5. The route is mounted on the raw HTTP app (plugin.ts:83). The stage-1 report enumerated the raw-app middlewares and found none that authenticates this path; this seat did not re-run that enumeration.

Also measured

• hookId and secret live in the start node's config, an open record (packages/spec/src/automation/flow.zod.ts:591). The engine's api binding carries them from there (packages/services/service-automation/src/engine.ts:3546-3554). The stage-1 report found 0 hookId hits in spec schema code.
• The secret is a literal in flow metadata. The showcase flow says "real deployments inject this from configuration" (examples/app-showcase/src/automation/flows/index.ts:1581); the stage-1 report found no injection seam. Outbound webhook signing secrets have a persistence seam since [security] The webhook signing secret is stored in cleartext in sys_webhook.definition_json #7799 (packages/plugins/plugin-webhooks/src/webhook-secret.ts:4).
• The signature covers the raw body. The stage-1 report found no timestamp or replay window in it.

Not measured

• Whether a non-admin can read a flow's config.secret through the metadata API.
• Whether any deployment arms a hook without a secret.

Dedupe words: trigger-api unsigned posts · hookId default · flow start node config.secret · x-objectstack-signature

[objectstack-fleet]

Path: approvals and automation — a flow runs only for whoever may run it | 缺项 (an inbound hook armed without a secret accepts unsigned posts) | P1

Triage: first grade — bug · security · priority:p1 · domain:services · area:workflow · pm:queue. Direction: fail closed, as ADR-0041 already says. Measure the three p0 questions first

Triage: lands in packages/triggers/trigger-api/src/api-trigger.ts (start() :121–124, the arm-without-secret warning :151, the conditional verify :187 on origin/main) ⇒ domain:services, by the lane table's packages/triggers/* row.

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-09-29T00:52Z. ⛔ Not a claim, ⛔ not a dispatch. Graded ahead of the round's order as a P0 suspect.

Read at source. With no config.secret, the hook arms anyway. hookId falls back to the literal 'default', the only signal is a warning, and handleRequest verifies a signature only if (hook.secret). So POST /api/v1/automation/hooks/<flowName>/default with no signature runs the flow. The path is guessable and, per the stage-1 report, unauthenticated. ADR-0041's trigger-api criteria (Accepted, :118–119) require a per-flow secret, HMAC verification and a constant-time compare, so the code does not meet its own accepted contract.

Why p1 and not p0 yet. It is an unauthenticated door that runs a flow, so it is security, and it fails open by design. Its reach is not measured, though. It needs an author to arm an api trigger without a secret, and no deployment is known to do so. The showcase flow carries one.

First step: three measurements. Any one of them answering yes makes it p0, and triage regrades.

1. Who does the flow run as on an unsigned post? If it runs as system, or with any identity that can write records, the internet can write data.
2. Can a non-admin read a flow's config.secret through the metadata API? If yes, every signed hook is forgeable by any member.
3. Does any shipped example, template or scaffold arm an api trigger without a secret?

Direction: fail closed, as the accepted ADR says.

• An api trigger with no secret is refused, both at start() (not armed, with an error naming the flow) and at publish or validate, so the author learns before deploying. ⛔ No warning-and-arm, and ⛔ no 'default' hookId standing in for an unset one without a secret.
• Re-pin api-trigger.test.ts:97 ("accepts unsigned posts when no secret is configured") to the refusal. The test encodes the defect.
• Not in this card: a replay window (the ADR does not name one), and a secret-injection seam like outbound webhooks' webhook-secret.ts ([security] The webhook signing secret is stored in cleartext in sys_webhook.definition_json #7799). File either one if the maintainer wants it. The stored literal is a separate question for measurement 2.

[objectstack-fleet]

Claim: PM loop round 3
Session: session_017B6YKCGu8CTY2KBWgwaHAs
Account: os-warren (the seat's linked user as GET /user answers it; always the card's assignee)
Branch: claude/issue-20529-api-trigger-requires-secret
Worktree: objectstack-issue-20529
Domain: domain:services
Seat: domain:services#1
File surface: packages/triggers/trigger-api/src/ (api-trigger.ts: start() and handleRequest, plus its tests); packages/services/service-automation/src/engine.ts, only for a registration-time refusal beside the existing registerFlow validations, plus its tests under packages/services/service-automation/src/; any examples/** flow the dev measures arming an api trigger with no secret; content/docs/** lines that call the inbound hook's secret optional; .changeset/20529-*.md. ⛔ No packages/spec: a schema-level requirement on the start node's config is the spec lane's, reported rather than made. ⛔ No new error code. (Stop on breach; explain in the report.)
Container & model: M, mode:subagent, model: opus (dispatch-gates --tier on 03b19d9c: no path-derived mandate for these paths, floor sonnet · default opus · ceiling fable). This is a security-behaviour change that narrows what is accepted, so the contract review runs at CONTRACT_REVIEW_TIER.
Clause-②: no (narrowing)
Thread-read: 5881532933
Serial constraints cleared: read at 2026-09-29T01:23Z on origin/main 03b19d9c.

• packages/triggers/trigger-api: last touched by ecf56e79 (fix(platform-objects): decide the hook panel's execution en-echoes per leaf, and pay round 5's cross-panel exclusion #19530). No open PR touches it.
• service-automation/src/engine.ts: last touched by 0283cb92 (A decision node with no declared config.conditions takes EVERY out-edge whose condition holds, in parallel — nothing enforces or warns that intended-exclusive edges partition #15429 / PR feat(automation)!: edge-branched decision is exclusive; mode: 'inclusive' takes every branch (#15429) #20344). No open PR touches it or service-automation/src/plugin.ts.
• None of the 12 open pm:dispatched cards fleet-wide declares any of these paths in its claim's file surface.
• Sibling reading: [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 (domain:spec, in flight, PR feat(spec,cli)!: one stack authoring shape — os validate / os build refuse a default export defineStack did not build #20460) makes os validate run the stack's defineStack refusals. It declares none of these paths. A registration-time refusal added here reaches os validate only if that path calls the engine's registration, which the dev measures and reports.

_{Clause-②: no (narrowing): nothing is widened. ADR-0041 (Accepted) already names a per-flow secret and HMAC verification in trigger-api's acceptance criteria. An api trigger that arms with no secret is accepted today and will be refused, so the change is breaking for any flow that carries no secret. The accepted contract is being enforced, not changed. The security-family disclosure rule of this lane applies to everything written for this card: defects and fixes are described abstractly, with no reproduction steps on any public surface.}

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report
{
"issue": 20529,
"status": "done",
"branch": "claude/issue-20529-api-trigger-requires-secret",
"pr": "#20551",
"session": "session_017B6YKCGu8CTY2KBWgwaHAs — subagent of the domain:services seat; the dispatching seat's session id",
"premise_still_valid": true,
"summary": "An api-kind flow with no non-blank config.secret is now refused in two places, both reading the same binding config. (1) @objectstack/trigger-api: ApiTrigger.start() throws naming the flow and config.secret before it stores a hook or subscribes a consumer; the arm-time warning is gone; ArmedHook.secret is non-optional, so handleRequest verifies every post and has no unsigned branch. (2) @objectstack/service-automation: registerFlow runs a new validateApiTriggerSecret beside the three existing hard-fail validations. It judges the binding deriveTriggerBinding computes (resolveTriggerBinding's body, split out so it also runs over an unregistered flow), refuses whatever the status is, and answers 400 VALIDATION_FAILED on the /automation create, update and clone doors; boot skips the flow with the existing failed-to-register warning. There is no new error code, no packages/spec edit and no examples or docs edit (none was needed). The changeset is minor with a BREAKING paragraph and the remedy, plus Clause-②: no (narrowing). Premises 1-6 were verified on origin/main 288611e (the PM read 03b19d9; main moved and no trigger-api or engine file changed in between). Premise 1: api-trigger.ts:123-124, :151-155. Premise 2: :187. Premise 3: test :97 plus the {} arms at :81, :105, :111, :120, :126. Premise 4: engine.ts activateFlowTrigger catch at warn, anchor 'Failed to bind flow'. Premise 5: plugin.ts:983-997 per-flow catch; the doors map through flowDefinitionRefusal to 400 VALIDATION_FAILED, a class already pinned by runtime automation-register-error-class.test.ts case 4. Premise 6: the showcase flow carries a literal secret.",
"tests": "At HEAD b732513, after the last commit. Unit tests: service-automation full suite (vitest --maxWorkers=2) 'Test Files 150 passed (150) / Tests 1845 passed (1845)'; trigger-api 'Test Files 2 passed (2) / Tests 26 passed (26)'. Typecheck: trigger-api (tsc --listFiles counts both test files) and service-automation (tsc --noEmit plus check:test-typecheck) both VERDICT command-exit 0. Build: dependency closure of both packages, both packages themselves, and a full turbo build (72/72 tasks) so the dist-reading gates could run. Ablation 1, arm-time refusal: scripts/ablation-replace.mjs replaced the throw with the old logger.warn; landed with anchor 1 to 0 and blob 7e60a8ab to cc123fba; red run 'Tests 3 failed | 8 passed (11)', each failure 'AssertionError: expected [Function] to throw an error'; restored with blob == HEAD 7e60a8ab and git diff HEAD empty; green before and after 26/26. Ablation 2, registration refusal: the validateApiTriggerSecret call was deleted; landed with anchor 1 to 0 and blob 679f73dd to e66c2db2; red run 'Tests 6 failed | 2 passed (8)' (5 refusal cases plus the re-registration case), while the 2 contrast cases stayed green; restored with blob == HEAD 679f73dd and git diff HEAD empty. Both suites import their subject from relative src, so no dist was in the resolution path. Narrowed eslint (--no-inline-config --format json) over the 8 changed .ts files: 8 files, 0 errors, 0 warnings. Its population is the packages//*.{ts,tsx,mts,cts} config blocks, with no 'File ignored'; the count is read from the JSON output; and the result cannot shift for untouched files because the config never enables type-aware linting (eslint.config.mjs:326-328). os validate was measured on a throwaway stack (deleted afterwards) with one type 'api' flow and no secret: 'Validation passed', exit 0. Declared to CI: repo-wide pnpm lint, downstream consumer suites of service-automation (a repo-wide scan found no api-kind flow fixture outside the edited files that reaches a real engine), and the full farm. PR CI at report time: 31 check runs, 11 success, 3 skipped, 17 in_progress.",
"gates": "dispatch-gates --repo objectstack-ai/objectstack --commands over the actual 9 changed paths gave 62 commands, and all 62 exit 0 at b732513. 'dispatch-gates --ran' reconciliation: '62 derived, 62 run, 0 NOT-MEASURED (a DERIVED zero — all 62 recorded an exit code and none of them is 3)'. check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (exit 3, not a measurement) and exited 0 after the full build; check:dts-closure and check:lean-entry-closure were re-run after the full build, exit 0. check-adr-0087-registration accepts 'not-required (no-migration-prescription)'. The PM's dispatch-time list (92) was over expected paths including examples/ and content/docs/, which this diff does not touch.",
"line_budget": "+326 / -39 = 365 changed lines over 9 files (dispatch-gates count), under the 5000 human-merge threshold. No skills/ file is touched, so no skill line ledger applies.",
"files_changed": [
".changeset/20529-api-trigger-requires-secret.md",
"packages/triggers/trigger-api/src/api-trigger.ts",
"packages/triggers/trigger-api/src/api-trigger.test.ts",
"packages/triggers/trigger-api/src/trigger-api-route-ledger.ts",
"packages/services/service-automation/src/engine.ts",
"packages/services/service-automation/src/api-trigger-secret-registration.test.ts",
"packages/services/service-automation/src/engine.test.ts",
"packages/services/service-automation/src/flow-activation-ledger.test.ts",
"packages/services/service-automation/src/flow-trigger-kind-shared-resolver.test.ts"
],
"measurements": {
"line_numbers_read_at": "b7325134 (the api-trigger premise lines are cited at origin/main 288611e)",
"1_run_identity": "YES for the documented pattern. The api trigger's context carries no user (api-trigger.ts:161-165: record, params, event only). The run's identity is the flow's runAs, default 'user' (engine.ts:5115-5117). Under the default, data nodes are refused for want of a principal (runtime-identity.ts:343; resolveRunDataContext). A flow declaring runAs 'system' runs data nodes system-elevated (runtime-identity.ts:130, :187). The shipped worked example declares runAs 'system' with a create_record node (examples/app-showcase/src/automation/flows/index.ts:1572). Non-data nodes run under either value.",
"2_non_admin_reads_config_secret": "YES, by source reading; not live-measured. The automation domain's flow-definition read branch (packages/runtime/src/domains/automation.ts:2956-2961) serves engine.getFlow verbatim, which is the stored parsed flow with the start-node config (engine.ts:4450). The domain's only read gates are the anonymous floor and the run-state read gate (:1955, run reads only), and the audit note at :2060 records definition reads as authenticated-only. The metadata-plane read was not measured. Not fixed here; see out_of_scope_findings.",
"3_shipped_secretless_api_trigger": "NO. The only shipped api flow is examples/app-showcase/src/automation/flows/index.ts:1566-1582, and it carries a literal secret, so examples/** needs no edit. packages/create-objectstack declares no api flow. The published skill skills/objectstack-automation/SKILL.md:52 and :356 teaches the secret as optional; that is reported below, not edited (Tier H, outside the file surface)."
},
"os_validate_reach": "NO. os validate never constructs an AutomationEngine or calls registerFlow; packages/cli/src/commands/validate.ts runs the defineStack parse, the @objectstack/lint authoring rules and the capability preflight. Measured: a stack with one type 'api' flow and no secret gets 'Validation passed', exit 0. #20367 (PR #20460) runs defineStack refusals, and this engine refusal is not one of them. For os validate to see it, the rule needs to be a spec-lane defineStack refusal beside the trigger-capability refusal (keyed on resolveFlowTriggerKind), or a packages/lint validate-flow-trigger-readiness rule.",
"hookid_default_call": "Left unchanged. A secret is now mandatory for every armed hook, so the fallback path token no longer has an unsigned form, and nothing concrete argues for changing it on this card.",
"single_home_call": "The rule is kept in two places on purpose. trigger-api and service-automation have no dependency on each other, and at boot the trigger registers at kernel:ready, after the flow pull, so the engine cannot ask the trigger at registration time. The engine's check reads the binding the engine hands start(), so the two copies judge one input. The only single home that would also reach os validate is packages/spec, which belongs to the spec lane.",
"deviations": [
"git push ran 3 times: the empty-branch probe, the WIP commit d5c202d, and the fixture commit b732513. The budget named git push once; the per-step commit-and-push rule accounts for the rest.",
"Commit trailers use the model-free pair AGENTS.md prescribes (Claude-Session plus Co-authored-by: Claude), not the harness-suggested model-named trailer.",
"A full turbo build (6m10s under the verify lock) ran because check:dual-build-cjs-loads reads every package's dist.",
"One temporary fixture file was created under examples/app-todo/tmp-20529/ for the os validate measurement and deleted immediately; it was never committed.",
"Registration refusal is status-agnostic: an obsolete api flow without a secret is refused too, consistent with the three existing registration validators, and pinned by one test case. The seat may want to confirm this."
],
"mcp_calls": "0",
"api_writes": "3 REST writes via the fleet-write relay, each sent as one POST /repos/objectstack-ai/objectstack/dispatches (HTTP 204) and executed as objectstack-fleet[bot]. (1) pr_create: POST /repos/objectstack-ai/objectstack/pulls, draft #20551, relay run 36511633121. (2) label-write --assign os-warren: POST /repos//issues/20551/assignees, relay run 36511694164, read back as a MATCH. (3) This os-dev-report comment: POST /repos//issues/20529/comments via post-stamped. Also 3 git pushes to the branch, which are not REST writes. Reads were single-card REST GETs only.",
"open_questions": [],
"out_of_scope_findings": [
"class: b · Seam: spec:flow start-node config.secret (open config record, packages/spec/src/automation/flow.zod.ts) → runtime:packages/runtime/src/domains/automation.ts flow-definition read branch :2956-2961 | consumer: none · reach: exception: security (could leak data): source-read, not live-measured. A member-level authenticated caller receives a flow's full stored definition, start-node config.secret included, with no projection or redaction (engine.ts:4450 getFlow returns the stored parsed flow; the domain's read gates cover only run-state reads, :1955; the audit note :2060 keeps definition reads authenticated-only). Any member can therefore obtain the per-flow HMAC secret ADR-0041 requires. The metadata-plane read of the same definition was not measured. · dedupe words: flow definition read config.secret · start node secret redaction · automation flow read authenticated-only · trigger-api secret readable",
"class: c · reach: named producer skills/objectstack-automation/SKILL.md:52 and :356, the published skill corpus an authoring AI reads. It calls the api-trigger 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 after this PR a flow authored from that text without a secret is refused at registration and at arm time. Tier H governed surface, outside this card's file surface. Same family as the next entry: authoring-time surfaces that do not know an api flow requires a secret, so one closeout card fits. · dedupe words: objectstack-automation skill api secret optional · type api invoked explicitly · inbound webhook secret recommended",
"class: c · reach: public door os validate, measured. A stack declaring one type 'api' flow with no config.secret gets 'Validation passed', exit 0, while registerFlow now refuses the flow at boot and at publish. The fix lives in the spec lane (a defineStack refusal beside the trigger-capability refusal, keyed on resolveFlowTriggerKind) or the lint lane (validate-flow-trigger-readiness); #20367 / PR #20460 does not cover it. Same family as the previous entry. · dedupe words: os validate api flow secret · defineStack api trigger secret · validate-flow-trigger-readiness secret"
]
}

Generated by Claude Code

[objectstack-fleet]

ACCEPT: PR #20551 at head b7325134 (R3). Landing waits on the at-tier contract review and on every check being green

domain:services seat (#6021) · session_017B6YKCGu8CTY2KBWgwaHAs · 2026-09-29T02:26Z. Checked against GitHub and origin/main, not against the report's own account (5882379577).

Shape. Draft, targeting main. Line 1 of the body is Fixes #20529, and a scan of the whole body finds no other closing keyword. Clause-②: no (narrowing) starts a line in both the PR body and the changeset. check-governed-merges --pr 20551: 0 of 9 paths governed, 365 changed lines, so this is an ordinary queue landing.

Scope. 9 files, all inside the claimed surface:

• trigger-api/src: api-trigger.ts, its test, and the route-ledger note.
• service-automation/src: engine.ts, a new registration test, and three fixture test files that registered a secretless api flow.
• .changeset/20529-api-trigger-requires-secret.md.

There is no content/docs/releases/ change. examples/** and content/docs/** were measured and needed nothing.

Changeset. It covers both published packages (@objectstack/trigger-api has no private; @objectstack/service-automation has access: public) at minor, with a BREAKING paragraph and its remedy. The minor follows the launch-window rule check-changeset-no-major states. The ADR-0087 disposition is not-required (no-migration-prescription). The at-tier review judges the level.

Spot readings by the seat:

• The refusal survives the HTTP boundary as a 400. flowDefinitionRefusal (packages/runtime/src/domains/automation.ts) wraps any thrown plain Error with no status as validationFailure(message, [{ field: '(body)', code: 'invalid_value' }]), which is 400 VALIDATION_FAILED. That is the same class automation-register-error-class.test.ts case 4 pins for the Flow '…' rejected: family. The new throw is that shape, so the door answers 400, not 500. The engine-level cases assert the throw, the flow's absence, and that the trigger never started. The envelope is pinned once, at the door, for the class. The seat accepts that division.
• The engine change is additive. deriveTriggerBinding is resolveTriggerBinding's body moved verbatim; resolveTriggerBinding now delegates to it. resolveFlowTriggerKind yields api only from type: 'api' or a start-node triggerType: 'api', so the refusal's "binds the inbound api trigger (…)" clause can never render empty.
• The trigger refuses before any state exists. The start() check runs before the hook-map store and before the queue subscribe. ArmedHook.secret is now required, and handleRequest's if (hook.secret && …) became an unconditional verify, so an unsigned branch has no shape left to live in.

Evidence. Local union taken at b7325134, after the last commit: service-automation 1845/1845, trigger-api 26/26, both typechecks, and 62/62 derived gates reconciled with --ran. Both negative pins were ablated with their red output recorded, satisfying the lane's standing rule:

• arm time: 3 failed / 8;
• registration: 6 failed / 8, with the 2 contrast cases green.

CI on b7325134 at this reading: 17 success, 3 skipped, 11 in progress, 0 red. Readiness waits on the rest.

Dev deviations.

• Three pushes, under the per-step commit rule: accepted.
• The model-free trailers AGENTS.md prescribes: accepted.
• A full turbo build for the dist-reading gates: accepted.
• A throwaway os validate fixture, never committed: accepted.
• A status-agnostic registration refusal (an obsolete secretless api flow is refused too): accepted, because all three existing registerFlow validators (validateNodeConfigKeys, validateDecisionModes, validateFlowExpressions) are status-agnostic in the same way.

Measurements (triage's three).

• ① Yes, for the documented pattern: the worked example declares runAs: 'system'.
• ② Yes, by source reading.
• ③ No.

By triage's own rule in 5881532933 that is a regrade to p0. The seat knocked triage at 5882464926. Scheduling does not change: the fix is this PR.

Out-of-scope findings, one line each:

• Entry 1, a flow's inbound secret served by the definition read: 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 (P0 suspect; emergency triage knocked).
• Entries 2 and 3, the published skill calling the secret optional, and os validate passing a secretless api flow: 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.
• hookId fallback left as is: Acceptance notes. No action, since every armed hook is now signed.
• The two docs observations: Acceptance notes (carrier: none). webhooks.mdx §16 scopes inbound webhooks out of the OUTBOUND plugin, which the seat does not read as wrong. flows.mdx's organization sentence was not measured.
• The ADR-0041 anchor entry and the objectui designer's authoring of config.secret: Acceptance notes (carrier: none).

Landing criteria.

• A same-shape contract-review PASS at CONTRACT_REVIEW_TIER on the landing head.
• Every check green.
• Then ready, and auto-merge through the queue.

---

Generated by Claude Code