Control-plane

The problem it solves

The control plane capability is the implementation, pithy dashboard is how you grant and revoke access, and connections explained is what a registration actually is.

A hosted platform can give you a dashboard trivially, because it already holds your data.

Pithy holds none of it. So a management client — the hosted dashboard, an AI agent you connect with pithy mcp, or one you write — has to reach into your Worker to see anything, and that reach is the thing that has to be designed rather than assumed.

Present, and denying by default

control-plane is a verification strategy like bearer or session. A route declaring it accepts calls from a registered management client and nobody else.

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.

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.

And every connection names who sanctioned it. Registering one takes a signed-in session, and the connection records that person’s email, what kind of client it is — dashboard, agent or script — and what it is for, in their words. An account token deploys; it registers nothing. 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.

Asymmetric, and that is the whole design

The 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.

Three alternatives were considered and rejected, and the reasoning is worth having.

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 — it is their server talking to your Worker — and turning every adopter’s Worker into an OAuth provider is a large surface for a property nobody needs here. The one grant that would fit is a shared secret with extra ceremony. 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.

The data path

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.

Response bodies on that path never touch their origin, and their private key never leaves their server.

sequenceDiagram
    participant B as A browser
    participant MS as The client's server
    participant W as Your Worker
    B->>MS: Ask for a token
    MS->>MS: Sign with a key that never leaves
    MS-->>B: 60 seconds. One scope.<br/>Bound to a digest of its own body.
    B->>W: The call itself
    W-->>B: The response
    Note over MS: The response body never<br/>passes through here

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.

Some calls do transit — anything a dashboard aggregates or acts on server-side. For those the commitment is a zero-logging policy on your data: response bodies fetched from your Worker are not logged, cached or persisted.

It answers a preflight, so a browser can actually reach it

A control-plane token rides the pithy-control-plane header, which is not one a browser will send cross-origin without asking first. So every admin route answers OPTIONS — the seam’s own, and every capability’s, derived from the same route table the manifest is built from.

Your Worker answers for issuer out of the box. Nothing to configure: the hosted dashboard reaches a stock Worker on the day you connect it.

Add your own console with allowedOrigins, which is additive — an entry there never removes issuer, so putting your own UI on top cannot lock out the dashboard that was already working:

controlplane({ allowedOrigins: ["https://ops.example.com"] })

Each entry is a scheme and a host: https://ops.example.com, http://localhost:5173, http://[::1]:5173. A trailing slash or an explicit :443 is the same origin spelled differently and is accepted. A path, a query or a credential is refused when the config is parsed, at deploy — those look like they scope the entry, and they do not.

In local dev you configure nothing. When ENVIRONMENT is dev, your Worker answers for any address on your own machine — localhost, 127.0.0.1, [::1], on any port. The dev port allocator picks a console’s port per feature, so there is no value you could write into allowedOrigins that would stay true across checkouts, and this is the rule that does not need one.

It is dev and loopback or it is nothing: in staging and production the allow-list is the config above and nothing else. And it grants no access. Every admin route still demands a verified control-plane token, so what this permits a local page to do is read a reply it could already provoke.

A browser caches a preflight for corsMaxAgeSeconds, ten minutes by default. Set it to 0 while you are working an allow-list out: a browser that has cached a refusal keeps refusing for the whole window after you fix the config, which reads exactly like a change that did not take.

Two properties worth knowing, because both are deliberate. The list is read from config and never from a connection row: a preflight is the one request here that is answered before any credential is read, so consulting the database would turn it into a way for anyone to ask which origins you have registered. And an origin that is not on the list gets the same 204 and the same empty body as one that is, minus the header that permits the read — the browser blocks it, and the answer says nothing about what the list contains. Your browser console will name it as a CORS failure; your Worker will not tell you more than that, on purpose.

Cookies are never in play. The token is a header, so Access-Control-Allow-Credentials is never sent. Registering a connection with --origin writes the issuer into that connection’s row and does not widen what your Worker answers a preflight for; those are two different questions, and only the config answers the second.

One keypair per connection

Per customer, per project, per environment. A leak exposes one connection rather than a fleet, and rotation and revocation are naturally scoped to the same thing.

The client generates the keypair. The private key is born in their infrastructure and never leaves it — the alternative, your CLI generating one and sending it to them, puts key material on the wire for no benefit.

Sibling Workers are not separately addressable, and that is deliberate: the data being administered is shared through binding names by default (naming), so a second connection to a sibling would be a second credential onto the same rows. A Worker that owns its DB through ownBindings is the exception the connection does not cover: it reaches one app database per environment.

Rotation: append, prove, then expire

Never replace. The order is the entire safety property.

  1. Append, in a call signed with the current key. Trust flows forward from existing trust, exactly as a rotated refresh token does. 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. A client still using the old key, naming a successor it has never actually used, would otherwise retire the one key that works.

Reverse those and a bad rotation locks the client out permanently with no authenticated path back. Two live keys is a normal state, which is what the versioned key array is for.

Capabilities bring their own admin routes

A capability contributing a management surface declares its admin routes with the scope each 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. The one address a client cannot discover is the seam’s own mount point, which is why it is stored on the connection.

Each capability names the package it comes from, beside the version. A version is only actionable joined against a release feed, a feed is keyed by package name, and a capability name is not one — controlplane ships inside @pithy-sh/core, so a client deriving @pithy-sh/<name> asks about a package that has never been published and is told nothing, which reads exactly like up to date. package and version are null together: the adopter’s own app capability has a name and neither. A Worker deployed before the field sends no package at all, and a client reads that as null and falls back to whatever it guessed before.

A Worker in a bad state still answers it

The seam is the diagnostic surface, so it cannot sit behind the faults it diagnoses. A capability that has to refuse because the Worker is misconfigured or unprovisioned declares that refusal as a readiness guard, not as middleware. Vector’s drift check is one.

createBackend mounts every readiness guard after every capability’s middleware and before any route, and skips it on the admin surface: every composed capability’s admin routes, the seam’s own included. So a Worker whose vector index drifted still answers ping, the manifest and every admin route, and answers everything else with the drift error. GET /health answers either way.

Only that kind of refusal is exempt. A rate limit, authentication and a CSRF check refuse a caller, so they stay middleware and keep running on the admin surface. So does what the seam stands on: the control-plane verifier and the audit recorder are middleware too, which is why a call that reaches a drifted Worker is still verified and still audited.

Scopes are exact

No prefix rule, no wildcards. Holding a scope confers every route that requires it and nothing adjacent.

A connect’s default grant is every declared read, derived from the route table — and a scope joins it only when every route requiring it is a GET, or a POST that declares both kind: "reads" and readInBody: true. That exception exists because neither a person’s address nor anything a person types travels in a URL: a path or a query string is written to every request log on the way in, so a lookup by an address, a search by a term and an export with its reason are each a POST with the value in its body. One mutating route anywhere makes the whole scope a write, however it is spelled. A CLI older than the release that added readInBody reads those POSTs as writes, so it leaves their scopes out of the default: connect with a current one.

Every scope also 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.

Every call is audited, reads included

Under its own actor type, so what the management client did is answerable separately from what your users did — and stamped with the connection’s kind, so a row also says whether the dashboard, an agent or a script acted.

Reads matter here more than writes. 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.

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 — which is a module you can import rather than a specification you transcribe.

ESC