Control plane overview

A hosted backend platform gives you a dashboard because it already holds your data. Pithy does not hold your data, so a dashboard has to reach into your Worker to see any — and that reach is the thing that has to be designed rather than assumed.

control-plane is a verification strategy, like bearer or session. A route declaring it accepts calls from a registered management client and nobody else: the hosted dashboard, an AI agent you connect with pithy mcp, or a client you write yourself.

Present, and denying by default

A Worker that composes the capability and has never been connected answers every control-plane route with controlplane/not_connected.

There is no flag to leave off, no backdoor, and nothing enabled silently. Connecting a client is a deliberate act, and until you perform it the seam’s only behavior is refusal.

Your Worker is the authority. The management client is a client. It holds a private key and you hold the public one, or, for a CI job, neither end holds a key and you hold a trust in the job’s own identity. Either way you decide what it may do, and you can revoke it without asking anyone.

The credential is asymmetric, and that is the whole design

The management client signs each call with an Ed25519 private key. You register the matching public key.

Or no key at all. A client running unattended — a CI job, a scheduled agent — has nowhere sensible to keep a private key, so it can register an OIDC trust instead: an issuer such as GitHub Actions, and the claims a token must carry, such as the repository’s numeric id and its environment. The job presents the short-lived token its own provider minted for this environment, and your Worker checks the signature, the issuer, the audience and those claims on every call. A trust with no claim constraint is refused at registration, because the issuer signs for every workload it serves.

Nothing secret of yours ever reaches them, and nothing they hold is worth stealing from you. Every other property follows from that one.

Three alternatives were considered and rejected:

Not a shared secret. Simpler, and strictly weaker: their breach becomes your breach. A per-customer shared secret means a compromise on their side yields keys replayable against every customer’s production Worker until each of them rotates. Under asymmetric, a full compromise leaks private keys that are useless the moment you revoke the corresponding public one — and revoking is a row you delete.

Not OAuth. OAuth exists so a third party can act on behalf of an end user without seeing their credentials, and it needs an authorization server with consent and token endpoints. There is no user delegation on this leg, and turning every adopter’s Worker into an OAuth provider is a large surface for a property nobody needs here. Where there is user delegation — your users connecting their own AI agents — it is OAuth, on a different leg: letting your users’ agents in.

Not Cloudflare Access or mTLS. Both work, and both move the authorization decision out of your Worker into edge configuration. That requires you to run Zero Trust, and it breaks the one sentence this design exists to keep true.

Every call is narrow

A browser cannot hold a long-lived signing key, so the management client’s server mints a short-lived, single-scope, body-bound token and hands it to the browser, which calls your Worker directly.

Sixty seconds. One scope. Bound to a digest of its own body. Checked for replay.

Under a trust, the token is the job’s own, minted by its provider for this environment’s origin and live for the provider’s lifetime, minutes. An identity token proves who, not what, so every call still names the one scope it exercises, and the grant is checked each time exactly as for a key. There is no jti to spend, so a captured token is replayable at this one environment until it expires. Nothing exchanges it for a longer-lived credential, because whatever it was exchanged for would be a key on the job’s host.

Your Worker does not distinguish a browser call from a machine call, deliberately: both are the same token, verified by the same code. There is no second token class to get wrong, and no route whose auth model depends on which client made the call.

Every call lands in your audit trail marked with the kind of client that made it — dashboard, agent or script — so what the dashboard did, or an agent, is answerable separately from what your users did, reads included. Reading the user table hands a management client every customer’s address; if only the writes were recorded, the trail would show one revoked session and say nothing about the customer list walked on the way there.

Every connection names the person who authorized it, read from the signed-in session that registered it, never typed. When that person leaves, pithy dashboard connections --principal <email> lists every key and trust they authorized across your environments, and --revoke --reason <text> ends them, recording each revocation.

Rotation is append, prove, then expire

Never replace, and the order is the entire safety property.

  1. Append the new public key, in a call signed with the current one. Trust flows forward from existing trust. Both keys are now valid.
  2. Prove it with a real call signed by the new key.
  3. Expire the old one — and that call must itself be signed with the successor. Naming a live key is not proof that you can sign with it; only signing with it is.

Reverse those, or swap without proving, and a bad rotation locks the client out permanently with no authenticated path back. Two live keys is a normal state, not an exception.

Capabilities bring their own admin routes

A capability contributing a management surface declares its admin routes with the scope each one needs, and the seam serves a manifest of them. So adding a capability adds its management surface with nothing to wire, and a client discovers what it may call rather than hardcoding paths.

Scopes are exact, and there are many of them. Reading a user is a privacy operation; revoking their sessions is an availability one. Scope matching has no prefix rule, so holding one confers exactly the routes that require it and nothing adjacent.

And every scope says what kind of thing it does: reads, writes, sends, charges, deletes or credentials. The manifest carries the kind on every scoped route, so a management client can cap a role by what a scope does rather than by a list of names that goes stale the day a capability adds one. A route from a Worker that states no kind is read as credentials, the most restrictive.

What each capability exposes

This is what you consent to when you connect a client, so it is stated here rather than left to be read off a manifest. A capability you do not compose exposes nothing. In the scopes column, the reads come first and the acts after the semicolon.

CapabilityWhat a management client readsWhat it can doScopes
AuthUsers with their sessions and devices, where each account stands, and the ledger of sign-in links and codes sentRevoke a session or a device, sign a user out everywhere, suspend and reinstate, delete (soft or hard) and restore, export everything held about one personauth:users:read, auth:devices:read, auth:verifications:read; auth:sessions:revoke, auth:users:logout, auth:devices:revoke, auth:users:suspend, auth:users:delete, auth:users:export
OrganizationThe account list, one account’s roster, and the role catalog with the owning role a roster write refusesAdd, remove and re-role members, and list, resend or revoke invitations; rename an account, move its short name, set its seat limit; force ownership onto a member; suspend, reinstate, delete and restore an account, each with a preview of who its cascade would reachorganization:accounts:read, organization:members:read; organization:members:write, organization:accounts:write, organization:ownership:transfer, organization:accounts:suspend, organization:accounts:delete
PaymentsWhat the project sells, the purchase log, subscriptions, entitlements and overrides, discount codes, the reconciliation and usage-reporting logs, and every webhook event a store sentGrant or revoke an entitlement; set, clear or lift every limit with an override; mint a discount code; start a reconciliation passpayments:catalog:read, payments:purchases:read, payments:subscriptions:read, payments:entitlements:read, payments:discounts:read, payments:reconcile:read, payments:usage:read, payments:webhooks:read; payments:entitlements:grant, payments:entitlements:revoke, payments:overrides:set, payments:overrides:clear, payments:overrides:unrestricted, payments:discounts:create, payments:reconcile:run
LedgerBalances and transaction historyCredit, debit, reverse an entry, release a holdledger:accounts:read, ledger:transactions:read; ledger:accounts:adjust
LeaderboardEvery board, one window’s entries with hidden ones in place, and the rank-refresh lockHide, unhide and correct an entry; clear a stale lockleaderboard:entries:read; leaderboard:entries:moderate
RatingPools, a pool’s ratings, and one player’s rating with the outcomes behind itRecalculate a rating from its outcome log, or reset itrating:players:read; rating:players:adjust
MatchmakingThe configured games, a game’s queue, its open rooms, and every pending inviteCancel an invite, drop a player from a queuematchmaking:queues:read; matchmaking:queues:moderate
MultiplayerThe sessions in flight, one session, and the results, never a game’s hidden stateClose a session, void a resultmultiplayer:sessions:read; multiplayer:sessions:moderate
ArtifactsRepositories with their owners, grants and history, and the tokens on one with their holdersRevoke one token, or every live oneartifacts:repos:read; artifacts:tokens:revoke
SupportThe inbox, a conversation with the sender’s account and purchases, and the canned repliesReply, assign, archive or reopen, reclassify, flagsupport:threads:read; support:threads:reply, support:threads:assign, support:threads:archive, support:threads:reclassify, support:threads:flag
EmailThe send log and one job in full, and the suppression listRetry a failed job, block an address, unblock oneemail:jobs:read, email:suppressions:read; email:jobs:retry, email:suppressions:write, email:suppressions:delete
ConsentCounts per purpose and notice version with the expired grants among them, the grants expired or expiring soon, one subject’s record, and the signed documents and drawn signatures behind itNothing. Consent is the person’s to give and to take backconsent:read
SecretsEvery declared secret’s status and one secret’s rotation history, never a valueRotate one secretsecrets:status:read; secrets:rotate
AuditThe trail, one event in full, which scopes a connection used and was refused, what one credential reached, the access history, the hash chain’s verify and export, and how delivery to each SIEM sink standsNothing. The trail is read-only, and a sink changes only with a deployaudit:events:read, audit:events:read_detail, audit:events:export
TestersEvery cohort with its roster, each tester’s activity, the forecast and the trendInvite, resend an invitation, take a tester off a roster; nudge testerstesters:roster:read; testers:roster:write, testers:nudge:send
Media and storageRecords and bytes per organization, or per owner within one; what media was servedNothingmedia:usage:read, storage:usage:read, media:delivery:read
TurnstileWhich widget guards the environment, and how its challenges wentNothingturnstile:widgets:read
VectorEach declared index, as config, Vectorize and the provision record see itNothingvector:indexes:read
Presence roomsWho else has a record open, liveJoin a record’s room with a single-use ticketNo scope of its own: the room kind’s read scope, such as support:threads:read
The seam itselfThe manifest, the registered keys, where each database’s migrations stand, the privacy inventory, the evidence pack, the record of processing, the erasure attestation, and the legal holdsRegister a key and expire the one it replaces; place and release a legal holdmanifest:read, migrations:read, privacy:read, evidence:read, processing:read, erasure:read, retention:read; keys:rotate, retention:hold

Three things a reader of that list tends to assume, and should not. Audit’s usage, reach and access-history reads take audit:events:read and never the detail scope, because none of them returns an IP, a user-agent or a free metadata key. An organization’s cascade preview is gated by the write it previews, because who belongs to no other organization is itself a disclosure. And presence adds no grant: anyone who may read a record may see who else has it open.

What it deliberately does not do

It grants no writes by default. A connect’s default grant is every declared read, derived from the route table — a scope joins it only when every route requiring it is a GET, or a POST whose path ends /lookup and that declares itself a read, which is how a lookup carries a person’s address in its body instead of its URL. One mutating route anywhere makes the whole scope a write, however it is spelled.

It does not let anyone sign in as your users. No route mints a session, and no read projects a session token.

It does not require the hosted dashboard. The seam is MIT and gated by nothing. Register a key you generated yourself and write your own management client against the published contract.

It does not phone home. Registration is a row in your D1. Revocation is that row deleted — immediate, unilateral, and needing nothing from the client.

When you would reach for it

When you want the hosted dashboard, when you want an AI agent to administer production through pithy mcp, or when you want to build an internal admin tool that reads production without a second copy of production.

Not for your app’s own admin screens. Those are ordinary routes with an ordinary session and a role check of your own — this seam is for a client that is not a user of your app. An agent acting for one of your users is not this seam either: it is that user, through your own routes, with mcp().

What it needs

Nothing, and it is already installed: it ships inside @pithy-sh/core. pithy add controlplane composes it; connecting a client is the deliberate second step.

ESC