fix(gateway): N83 operator contracts — owner-set availability, no silent drops (R0 G8/G9/G11/G12)

[LamaSu]

Summary

This is board N83 (steward #3960). The first ADK dress rehearsal (R0, returns/pcc-refvertical-work/rehearsal/R0-findings.md, G8/G9/G11/G12) found four places where an onboarding agent hit a gateway contract that contradicts itself. This PR fixes the code halves; adk documents what is true.

Everything was reproduced before being fixed (goal-root review loop), against master ac86a404 and R0's own call log (rehearsal/r0-run-1/calls.log). The PR is built from master and does not stack on any open PR (WIP rule).

Finding	Reproduced	Fix
G11: availability cannot be set	operator-status.ts:184-197 marks the operator partial and says to set availability. calls.log:1038/1086/1110: PATCH and PUT /api/capabilities/:id return 404, and a re-POST returns the existing row unchanged	New PUT /api/capabilities/:capId/availability for the owner only (details below)
G12: create drops fields silently	calls.log:371-393: requirementsSchema is sent, and the 201 neither stores it nor says so (CreateCapabilityInput has no such field)	The 201 now lists ignoredFields. requirementsSchema gets a hint: typed parameters belong in the capability's CSD. A re-POST says it never updates. Persistence is unchanged: no DDL, since a new column is a parked schema change
G8: register-device	setup.ts:547-549 returns a bare missing_required_fields, and setup.ts:614 hard-codes firmware "unknown" (calls.log:511)	The 400 now names the missing fields and says deviceId is operator-chosen and stable. A top-level firmware string is stored, trimmed and capped at 64 characters
G9: storage upload message	storage.ts:160 says "PUT raw bytes", but there is no PUT route	The message says POST. Status and error code are unchanged

G11: the availability route (security notes)

• Actor: the principal api-gate authenticated: the API key's operatorId, else the SIWE userId. A body field or header never counts. With no actor the route returns 401.
• Ownership: the actor must be the capability's kernel operatorAddress, compared with WP-A's fold (trimmed, case-insensitive, never true for an empty id). Anyone else gets 403, and so does a capability whose kernel is missing.
• Path: the route sits under /availability on purpose. Master's public allowlist matches /api/capabilities/:id for every method, so a PATCH on that path would skip authentication. WP-A fix(gateway)!: WP-A scope hardening — wildcard is not money/admin authority, fail-closed scopes, identity binding (P0 MUST-CLOSE 6-10) #326 makes the allowlist method-aware.
• Body: strict zod.
  • Accepted modes are always, windows, cron and manual-claim.
  • A recurring window uses HH:mm (overnight is allowed); a one-shot window uses ISO instants with start before end.
  • cron has 5 fields; the timezone must be IANA-shaped; unknown keys are refused.
  • Values are stored through serializeAvailability(), the canonical column shape.
• delegate-to-agent and any agentEndpoint are refused (400 unsupported_mode). That endpoint is a URL the gateway would POST to, which invites SSRF. Nothing calls it today. This refusal is local to this route. Three other writers still store availability verbatim, all pre-existing and unchanged here: POST /api/capabilities at creation, the A2A author-integration skill (a2a-tasks.ts:707) and kernel announce (kernel.facade.ts:534). delegate-to-agent is also a documented mode (FOUR_SLOTS.md:149). So the real SSRF guard must sit at whatever first POSTs to an agentEndpoint: validate the target at CALL time, because DNS rebinding defeats a check made when the value is stored. Reported to the steward.
• Merge order: this is an owner guard, so it merges after WP-A fix(gateway)!: WP-A scope hardening — wildcard is not money/admin authority, fail-closed scopes, identity binding (P0 MUST-CLOSE 6-10) #326 (board rule 6). It does not import fix(gateway)!: WP-A scope hardening — wildcard is not money/admin authority, fail-closed scopes, identity binding (P0 MUST-CLOSE 6-10) #326's or fix(gateway): bind job-offer claims/events, tool-catalog entries and templates to their authenticated owners (kits K0 slice 2; merge after WP-A) #395's helpers (WIP rule), and should converge on WP-A's sameIdentity once those land.

Found while reproducing, NOT changed here (reported to the steward)

• POST /api/capabilities stores caller-supplied assuranceTiers verbatim, defaulting to [0,1]. Tiers are therefore self-declared unless something else caps them. That is a trust question for evidence/gateway, not a contract bug.
• The operator-channels routes (POST /api/operators/:slug/channels, PATCH/DELETE /api/operators/channels/:id) have no ownership check at all.

Tests (run on the Spark, worktree wt-kits-n83)

Command	Result
packages/gateway: npx vitest run src/__tests__/capability-availability.test.ts	8/8
G11 mutation check: owner check, actor check and delegate guard each disabled in turn	2, 1 and 1 fail; all 8 pass once restored
setup.test.ts, cid-storage.test.ts, capabilities-create-contract.test.ts (new)	61/61
G8/G9/G12 mutation checks: the fix reverted	3/4, 1/1 and 2/4 of the new tests fail (the rest pin pre-existing behaviour)
packages/gateway: npx tsc --noEmit	exit 0
full gateway suite	189 files: 2998 passed, 6 skipped (pre-existing), 0 failed

🤖 Generated with Claude Code