docs(rpc): document service keys; deny zero-consumer providers; close the project

[wmadden-electric]

What

Three things that finish the RPC service-key topic: document it for users and agents, close the last fail-open hole, and close the project.

Live-verified by CI: Deploy, verify, destroy deploys storefront-auth to Prisma Cloud, proves the wired round trip, and tears it down — green on this branch. The code change is additionally unit-tested and mutation-checked; the docs and close-out carry no runtime risk.

1. Docs — the surface changed and nothing said so

RPC bindings became authenticated (ADR-0030/ADR-0031) without the guides or the skill mentioning it. Two consequences read as bugs when they surprise you: a hand-rolled curl of a deployed /rpc/<method> gets 401, and nothing is enforced locally or in tests.

• guides/building-an-app — canonical explanation under Contracts: what's minted, why curl 401s, why local passes through, per-binding isolation, rotation, service-level scope.
• guides/getting-started — the tutorial now walks the reader into the 401 where they'd hit it anyway (curling the quotes service), and ties it back to why the local run needed no key.
• guides/deploying — unwired callers rejected; the COMPOSER_* vars are the deploy's to rewrite, not yours to hand-edit.
• guides/testing — auth is inert under mockService/bootstrapService.
• skills/prisma-composer — the agent-facing rules: don't build your own service-to-service auth, and don't tell a user to curl an RPC endpoint to check a deploy. (Per the skill README, a surface change lands in both the guides and the skill.)
• design/10-domains/connection-contracts — the design point: the key rides the binding, not the contract, which is why one Contract still serves network, in-memory, and mock adapters unchanged.

2. A provider with no wired consumers now denies

The last place this failed open. A provider with zero consumers got no accepted-keys var, which serve() read as pass-through — so a provider nobody was wired to accepted everyone.

It needs three states where there were two, because "no keys" was ambiguous:

Var	Means	Behaviour
absent	never provisioned — local dev, tests, bootstrapService	pass through (unchanged)
"[]"	deployed, exposes RPC, zero wired consumers	deny all
["k1",…]	deployed with peers	enforce membership (unchanged)

acceptedKeys() returns undefined vs []; the check becomes accepted !== undefined, so an empty set denies naturally — no special case. Malformed now denies too (only the trusted target writes it). The target correspondingly writes the var for any service that exposes something, not only one with inbound edges; a pure consumer still writes none. Local and test behaviour is unchanged.

Both files were mutation-checked: reverting each makes the new tests fail, restoring makes them pass.

3. Project closed

DoD verified (both slices merged — #89, #93 — round trip, 401, and stable no-op redeploy all proven live before the workspace broke). The long-lived output already lives in docs/; the remaining spec/plan/slices were coordination artefacts and are deleted. Deferrals recorded in .drive/deferred.md: cross-extension provisioned edges and multi-need connections (both fail closed rather than guess), rotation UX, per-method authz, publishing the provisioning SPI (equally internal to secrets today), and the constraint the mock-bindings slice inherits.

Tests

@internal/rpc serve.test.ts 13 pass; target control-lowering.test.ts 27 pass; typecheck + test:types clean for both; lint:deps clean.

Two operational findings (not blocking this PR)

destroy leaves the Project behind. prisma-composer destroy tears down a stack's resources, but the Prisma Cloud Project shell survives, and CI's sweeper only matches -ci-<runid> names — so hand-run verification stacks accumulate. Three of mine (storefront-auth-s2v, -s3v, -fc) helped push the dev workspace into planLimitReached. I deleted my three and touched nothing else. Worth closing properly: either destroy removes the project, or the sweeper learns to catch hand-run names.

The dev workspace's state database is unhealthy (separate from CI's, which is fine — hence the green deploy checks here). A freshly minted connection to prisma-composer-state's database times out while the API reports it "ready", so it isn't a stale credential. It blocks local prisma-composer deploy from that workspace and needs an account-level look. I did not touch that project — it's control-plane, and deleting it would destroy the deploy state for everything live in the workspace.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@100

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@100

commit: 5c7c398