| name | service-plane |
| description | Activate when building, extending, reviewing, or debugging code that uses the service-plane TypeScript library: defining abilities or capability scopes, wiring a ServicePlaneService or ServicePlaneControlPlane, opening ability sessions, issuing or verifying capability tokens, configuring ingress or the broker, or projecting abilities to OpenAPI, Swagger, or MCP. Also activate when a repo depends on the service-plane npm package and the task touches service-to-service auth, Cap'n Web RPC, service discovery, or tool metadata, even if the user does not name the library explicitly. |
service-plane
service-plane is a TypeScript library for ability-first service APIs. It
replaces the usual sprawl of REST routes, internal RPC, hand-written OpenAPI
files, ad hoc auth checks, and separate AI-tool metadata with one source of
truth: the ability.
An ability is a schema-backed RPC surface owned by a service. Each method
declares one Zod input schema, one Zod output schema, required scopes, and
optional REST and MCP metadata. Those schemas drive runtime validation,
service discovery, OpenAPI generation, and MCP tool metadata — define once,
project everywhere.
Mental model
Three roles, three responsibilities. Keep them separate; most mistakes with
this library come from blurring them.
| Role | Owns | Package entry |
|---|
| Service | Defines abilities, verifies tokens, validates input/output, enforces scopes | service-plane/service |
| Control plane | Discovers services, checks grants, issues short-lived capability tokens, brokers calls, projects OpenAPI/MCP | service-plane/control-plane |
| Caller | Requests a token, opens an ability session, invokes methods | service-plane/service (session + transports) |
The control plane is the only component that issues capability tokens
(short-lived ES256 JWS). Services verify issuer, audience, expiry, signature,
and scopes against the plane's JWKS before any handler runs. Only the control
plane should call services — no direct ingress.
Hono is the HTTP shell (middleware, discovery, request ids); Cap'n Web is the
RPC engine (HTTP-batch, WebSocket, Cloudflare bindings). Method auth and
validation live in the Service Plane ability wrapper, not in Hono
middleware — Hono sees the HTTP request, Cap'n Web sees the logical method
call.
The four knobs
Every ability decision reduces to four independent settings. Never conflate
them:
exposure — discoverability in user-facing projections.
'private' (default) keeps the ability out of OpenAPI/Swagger/MCP;
'published' makes methods with rest/mcp metadata projectable.access — who the broker serves. 'plane' (default): the control
plane or gateway owns any product-level user/API-key/anonymous decision.
'service': brokered only for authenticated service callers
(service-to-service). Never use it to model end-user authentication.scopes — what a signed token may do once the service receives it.
Declared in the service capability catalog (defineCapabilities),
referenced at ability level (maximum surface) and method level (minimum for
one operation). A method must not require a scope its ability does not
declare.ingress — whether the service accepts only brokered Service Plane
calls. With ingress: {}, a valid but non-brokered token is rejected with
403 before input validation or handler creation.
Dos
- Do define Zod schemas once and let them drive validation, discovery,
OpenAPI, and MCP. Never hand-maintain a parallel JSON Schema or OpenAPI file.
- Do declare every scope in
defineCapabilities first; the service fails
at setup if an ability or method references an unknown scope — that is a
feature, not a bug to route around.
- Do keep
exposure: 'private' as the default and publish only abilities
meant to become product or integration surfaces.
- Do let the ability wrapper do its job: handlers receive
already-validated input, and output is validated after return. Add
requireScopes(...) inside a handler only when custom logic needs the
identity object.
- Do enable
ingress: {} on services that must only process brokered
traffic, and route their callers through the control-plane broker.
- Do pass product context (tenant, user, connection) through validated
input or project-specific token claims — identity stays small: caller
service id, audience, scopes, token id.
- Do use the simplest caller auth that matches the boundary: service
bindings on same-account Cloudflare, JWK for external callers holding a
private key, HMAC only as a shared-secret fallback.
- Do configure a
caller resolver for the broker and MCP endpoints. They
fail closed: no resolver → 500, resolver returns nothing → 401. Anonymous
access is only ever an explicit fixed caller, never a default.
- Do keep code runtime-agnostic: the same ability definitions run on
Cloudflare Workers and Node 20+ (
@hono/node-server); only transports and
JWKS sourcing differ.
Don'ts
- Don't put provider OAuth tokens or credentials in Service Plane
identity or workflow metadata. Store them in service-owned storage (e.g. a
Durable Object per connection) and route to it via validated input claims.
- Don't share the STS signing secret beyond the control plane. Services
verify via JWKS; callers only ever hold short-lived tokens.
- Don't use
access: 'service' to model end-user authentication — it
restricts the broker to service callers, nothing more.
- Don't weaken scope checks, grant checks, token validation, replay
protection, or ingress protection to make tests pass. The security model is
core package behavior.
- Don't call an ingress-protected service directly (HTTP-batch or native
binding RPC) with an ordinary token — it will 403 by design. Go through the
broker so the token carries the signed broker claim.
- Don't generate OpenAPI in services. Services expose discovery at
/.well-known/service-plane/service.json; the plane builds /openapi.json
and the MCP tool list from published metadata.
- Don't default to WebSocket for worker-to-worker calls. Prefer bindings
on Cloudflare and HTTP-batch elsewhere; reserve WebSocket for long-lived,
interactive sessions.
- Don't invent new secrets when an existing signed token claim or
caller-auth mechanism can express the boundary safely.
Going deeper
The bundled references are the library's full documentation set. Load the
one that matches the task; they cross-link with relative links, so follow
those within references/ as needed.
- Concept, request flow, where auth and validation live, core terms:
LOAD references/architecture.md
- Creating or changing a service (capabilities, abilities, handlers,
mounting the shell): LOAD references/service-creation.md
- Creating or changing a control plane (grants, broker, ingress, caches):
LOAD references/plane-creation.md
- Token flow, caller auth options, identity vs. context, scope checks:
LOAD references/auth.md
- Streaming ability methods, session transports, broker/MCP streaming:
LOAD references/streaming.md
- Which transport to use between services (environment, performance, cost):
LOAD references/transports.md
- API lookup: option shapes, routes, transports, logging events, errors:
LOAD references/reference.md
- OpenAPI, Swagger UI/Scalar, MCP tools and their fail-closed callers:
LOAD references/openapi-mcp.md
- Cloudflare Workers, bindings, Durable Objects, edge caching:
LOAD references/cloudflare.md
- Node.js and self-hosted services: LOAD references/nodejs.md
When working inside the service-plane repository itself (not a consumer),
docs/ is the source of truth for these files (synced via
npm run sync:skill-docs), and AGENTS.md defines the package boundaries.
Verifying changes
In a consumer repo, run its normal checks. In the service-plane repo itself:
npm run check && npm run typecheck && npm run test && npm run build
