feat(gateway): durable, write-once, verified Capability Kit registry (kits K1 slice 1)

[LamaSu]

Summary

Kits K1 slice 1 is the durable Capability Kit registry (technical section 7, MUST-CLOSE 1-2; ledger row 6, "no in-memory-only production catalog").

Stacked on #397 (SHIP 112e, MERGE-READY). It uses #397's CapabilityKitManifestV1, normalizeKitManifest, computeKitDigest and validateKitCompleteness. Merge after #397.

A kit version is the exact canonical bytes of its normalized manifest, keyed by kitDigest = sha256(those bytes). Who published it and when is server metadata, never part of the hashed bytes.

Storage: write-once files on the durable volume

• <root>/manifests/: the manifest bytes, through the existing FsRegistrySnapshotStore (write-once, collision-verified).
• <root>/publications/: one publication record per digest, {schema, kitDigest, publisher, publishedAt}. It is created EXCLUSIVELY (a hard link from a temp file), so the first publisher wins even across processes, and a record is never overwritten.
• Root: PCC_KIT_REGISTRY_DIR, else $RAILWAY_VOLUME_MOUNT_PATH/kit-registry, else ./data/kit-registry. In production with neither variable set, publish answers 503 registry_not_durable.
• Not in capability_template_store: on master any key can rewrite template rows through the generic template routes (kits D5). 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 fix for that waits on WP-A, and a kit row there would also surface in the template list, fork and rate routes. No schema change.

Integrity: verified on every read, fail closed

GET /api/kits/:digest re-reads the bytes and requires all of these:

• sha256(bytes) equals the digest;
• the bytes are exactly the canonical form of a valid manifest;
• a strict, canonical publication record names the same digest.

Anything else answers 500 kit_integrity_failure, and the bytes are not served. The listing is a cache rebuilt from the files at first use; an entry that fails verification is skipped, never listed.

Routes

Route
GET /api/kits	filters csdUrl, deviceFamily, interface, q; limit (max 100) and offset; newest first
GET /api/kits/:digest	{kit: {kitDigest, manifest, publishedAt}}
POST /api/kits	publish: authenticated (401 otherwise); complete kits only (422 incomplete_kit); parent must exist (422 unknown_parent); 256 KiB cap (413); at most PCC_KIT_PUBLISH_DAILY_LIMIT (default 20) new kits per publisher per 24 h (429); re-publishing a digest returns the existing publication (200, created:false)
POST /api/kits/:digest/fork	as publish, plus parentKitDigest must equal :digest (400 parent_mismatch; 404 if absent)

• Scope defaults: POST /api/kits and POST /api/kits/** require template_author, operator or admin, like template authoring. Self-service * keys pass, as everywhere. Deployments that customise endpoint scopes need rows for these two routes.
• Audit: kit.published and kit.forked events (actor, capability-kit, digest).
• Privacy: no response carries the publisher, which may be an email or a wallet.

Not in this slice

• Deprecation: needs publisher ownership under WP-A's identity rules (fix(gateway)!: WP-A scope hardening — wildcard is not money/admin authority, fail-closed scopes, identity binding (P0 MUST-CLOSE 6-10) #326), so slice 2.
• S4 ranking and the tool catalog as a durable view over kits: slice 2.
• The write-once public release ledger (K4a, painpoints #5172): it will reuse this store.

Tests

packages/gateway/src/__tests__/kits-registry.test.ts (44) and kits-scope.test.ts (7) were written black-box from the spec by a Sonnet test writer, then reviewed and extended by me. They cover:

• publish and read round-trips, plus order-insensitive identity;
• integrity: a flipped byte, hash-valid non-canonical bytes, another kit's canonical bytes under a digest, a mismatched or missing record, reload skipping;
• concurrency: same instance, and two instances on one root (exactly one record);
• validation: 400/413/422/404, auth (401) and privacy (the publisher is in no response body);
• quota, including a re-publish at the cap;
• the durability guard and the isDurableKitRoot environment matrix;
• list filters, ordering, pagination and bad queries;
• audit events and scope requirements.

Check	Result
gateway vitest	208 files, 3758 passed / 13 skipped
tsc --noEmit (gateway)	exit 0
test files typecheck	clean
my mutation pass	14/15 killed. The survivor is the route's principal check, equivalent because the service refuses a missing principal too
secret scan over the diff	0

Round 2: astra k1-511 fixes, at fe74533

All 7 findings were reproduced at 47e6eec first.

• Authorization (both HIGHs): POST /api/kits and /fork check the publishing role themselves: an API key with template_author, operator, admin or *, read with getCallerScopes. This holds whatever the governance table holds. A SIWE session is refused (403 kit_publish_requires_api_key) until sessions have a role model.
• No cache: list, get, the existence check and the quota read the files every time. Another process's publish is seen at once, and a file that stops verifying stops being listed.
• No symlinks: files open with O_NOFOLLOW and every registry directory is lstat-checked. The configured root may be a mount symlink, resolved once.
• Hard-link probe before the first write: a volume without links gets 503, and no orphan manifest.
• An exact cross-process quota without a lock: claim n under quota/<sha256(publisher)>/ is an exclusive create, and needs claim n − limit to be at least 24 h old.

Evidence: gateway 208 files, 3774 passed / 13 skipped; tsc 0; mutations 20/20; secret scan 0. Review pack: k1b-511-kits-registry-r2-fe745332.

🤖 Generated with Claude Code

https://claude.ai/code/session_015zYzsSSFUHbPV5DNxssX4A