@substrat-run/control-plane-api
The HTTP surface over HostAdmin — the audited control-plane transport (control-plane.md §4.5). It is the seam between the platform's admin operations (provision a scope, bind a hostname, grant a role, deploy a vertical) and whatever runs them: the CLI, the Console, and the Dashboard all call this one surface.
It is a transport, not a source of truth. Every route lands on a HostAdmin method, every mutation is audited there, and the same API runs over any scope host — the pure-SQLite adapter in CI, Durable Objects in production.
pnpm add @substrat-run/control-plane-apicreateControlPlaneApi
A Hono app that exposes HostAdmin over HTTP, with authentication and the audit trail wired in. It takes a ScopeHost (whose .admin is the HostAdmin it projects) plus the auth, deploy, and observability seams, and returns a plain Hono app you serve on Node, Workers, or in tests:
import { createControlPlaneApi } from '@substrat-run/control-plane-api';
const app = createControlPlaneApi({ host /* ScopeHost */, /* auth, deploy, … */ });
export default app;Every request is authenticated to a PlatformActorId (staff SSO/session) or a builder principal (a scoped push token), and that actor is the same one HostAdmin stamps into every audit row — the transport never invents authority, it carries it.
The surface
Route groups map one-to-one onto the HostAdmin capability groups:
- Tenants —
/tenants(+/status,/reap,/identities,/entitlements): the tenant registry, lifecycle, identity links, and per-tenant SKU grants. - Scopes —
/scopes,/tenants/:t/scopes/:sand its lifecycle verbs (configure,version,snapshots,restore,rewind,bookmarks,migrations,reap), the read-only data window (tables,tables/:table,query,export,health, and the six event reads over it —history, one record's story;facets, the outbox narrowed, grouped and counted;causeandeffects, one event walked backwards to what started it or forwards to what it set off;invocation, everything one call recorded, which is the grouping neither walk can reach;dead-letters, every delivery in the scope that gave up, newest event first;lifecycle-flow, a POST carrying one entity's declared lifecycle, which the scope's outbox is replayed against for the process map — edge counts, instances per state, time in state, the longest stuck, the funnel;operation-series, a POST carrying(entityType, operation)pairs and a window of at most seven days, answered with the calls that made each move per time bucket — Pulse's business volumes), and/fleet/migrations. The table, query, health, denial and event reads (tables,tables/:table,query,health,denials,denials/summary,capabilities,history,facets,cause,effects,invocation,dead-letters,lifecycle-flow,operation-series) run one ladder: resolve the scope record, then ask the vertical's own/internal/*route when one is bound and the co-located host otherwise. The vertical's answer is relayed as it came, with one exception: afacetsanswer is normalized, and a payload grouping from a vertical whose kernel predates #1762 is refused — no buckets, the events counted inwithheldPersonal, andwithheldReason: 'vertical-predates-rule'— since that kernel groups personal data. On the delegated branch the transport writes the K-24 access row itself, throughHostAdmin.recordDelegatedRead, so an auditor cannot tell which branch served a read from the row it left. Afacetsrow also records the answer'swithheldPersonaland anywithheldReason, on both branches. Two scope reads sit outside that ladder on purpose:exportalways goes throughHostAdmin.exportScopefirst, because that is the call that writes its access-log entry (the vertical supplies only the bytes when one is bound), andmigrationsis schema metadata, read from whichever side holds it with no access row at all. Two routes are forwarded to the scope's own vertical host rather than answered from the directory:GET …/owner-seatreads whether the instance's owner seat has been claimed, andPOST …/owner-claimmints the short-lived claim link (201), addressed to the scope's boundapphostname.owner-claimanswers409when no hostname is bound or the seat is already claimed; either route answers501when the scope is bound to no vertical (with the diagnosis) or the bound vertical keeps no owner seat — both callbacks are optional invertical-host, and the vertical's own status is forwarded unchanged. The member routes are forwarded the same way:GET …/members(the roster),POST …/memberswith{ roleKey, email? }(an invite:201and a one-time accept link on the scope'sapphostname),POST …/members/:principal/rolewith{ from, to }, andPOST …/members/:principal/remove. A change is made as the person the tenant credential was minted for, and the vertical bounds it by what that person holds in the instance. A credential naming nobody (a builder, staff, or a tenant token minted without a person) is refused403on the three writes; the roster still reads. Each write leaves twomanageScopeMemberrows on the admin log, the intent and thenapplied,refusedorfailed, paired by theoperationIda refusal also answers with. The vertical's own status (403past the person's authority,409for the owner of record,501for an app that declares no member roles) is forwarded unchanged. A third,POST …/owner-transferwith{ from, to }, hands the owner seat to another member of the instance. It is staff-only: a tenant credential or a builder is refused403. The vertical moves its owner of record, seatstoin the owner role, revokesfrom's, and closes the hand-over. A repeat after that answersoutcome: 'done'and changes nothing. It refuses with409, changing nothing, when the seat is still unclaimed,fromis not the owner of record, no login is bound toto,toholds no role in the instance (grant one first: an entity-narrowed grant is not a role), or another hand-over on the same instance is still unfinished (resend that one first). It answers501, changing nothing, for a scope no vertical serves or an app that keeps no owner seat, for a deployment whose scope host cannot seat a new owner (redeploy it), and for one whose scope host cannot judge the new owner's seat as a person's: an adapter older than the@substrat-run/vertical-hostbeside it, which is upgraded with it (#2531). A hand-over that can no longer finish, becausetowas removed after it started, is refused on every resend and blocks any other. Staff close it with{ from, to, abandon: true }on the same route. It closes only that open hand-over, and only when it is wedged like this — one that can still finish is refused ("resend it instead"). It seats and revokes nothing, and leaves the owner of record onto, from where a new hand-over starts. The originalfromkeeps any owner seat it still holds, since the abandon revoked nothing; the next owner removes it in the app. Its rows carryabandon: true. Every attempt writes twotransferOwnerrows to the admin log, paired by theoperationIdthe route answers with: anintentbefore the vertical is asked, thenapplied,refusedorfailed. Afailedhand-over may have stopped part-way, and sending the same request again completes it. When an outcome row cannot be written (on either route), the answer still reflects what the vertical did. A refusal or failure keeps the vertical's own status, and the missing row is logged asaudit-outcome-unrecordedwith theoperationId. A change that went through is answered as the success it is (200, or201for an invite, with the result: an invite keeps its accept link), carryingauditWarningbeside theoperationIdevery answer carries. A client shows the warning and does not offer the change again. The call to the vertical has a 60 s deadline: past it the route answers504, auditedfailed. The platform's scheduled pass closes an intent that still has no outcome an hour later. It writes anunknownrow, saying the log cannot tell whether the change happened, and an ops-failure row that the staff failure digest reports, both in one transaction, and only if no outcome exists by then. A real outcome that lands later is still recorded. Every reader resolves an operation by priority, never by row order or timestamp: a real outcome (applied,refused,failed) beatsunknown, and two real outcomes for one operation readconflictingand are logged, never guessed past. An operation is its action, itsoperationId, its tenant and its scope. The schedule and peer kill switches (revokeFromSystem,restoreToSystem,revokeFromPeer,restoreToPeer) are audited the same way: a refused switch whose outcome row cannot be written still answers its own error, a switch that moved answers success withauditWarning, and the scheduled pass closes the intent asunknown.GET /admin-logreturns the rows as written, and gives each row of these six actions anauditedfield: itsoperationId, theoutcomethe operation stands at (pendinguntil it has one), andsupersededon anunknowna real outcome beat. Each page is resolved with one batched read of its own operations through an index on the operation id. The console shows the same reading. The failure digest leaves out anunknownwhose operation has since recorded one real outcome. The answer'sfromRevokedis about the instance's own owner seat only.falsemeansfromheld none there; iffromholds the owner role at the tenant level, that grant is untouched and still applies, and it is taken back through the tenant's role assignments. - Verticals —
/verticals(+versions,versions/:id/admit|reject,channels,channels/:c/promote,deploy,instances,listing,publish-request,install-block): the registry, admission, promotion, and the deploy path. A staff or service caller may narrowGET /verticalsto one tenant's slice —?ownerTenant=<id>for what it owns,?visibleTo=<id>to add the published tier, which is what its install catalog shows; both only narrow, and both are ignored for a builder session, whose list is already fixed to what it owns. A vertical has one channel —prod(dev/staging retired);channels/:c/promoterefuses a non-prodchannel with a400.GET /verticals/:slug/egress(staff-only, like the other observability reads) lays each deployed version's observed outbound hosts beside the ones it declared (D-46), so an admit decision can see the difference;?hours=(1–72, default 24) and?limit=(1–1000, default 500) bound the read, and the report says out loud when it is sampled or truncated — an absent host is not proof a version never called it.501on a control plane with no observed-egress seam. - Hostnames —
/hostnames(+/status,/verify): the K-26 hostname map and its Cloudflare-for-SaaS issuance/verification. - Connections —
/tenants/:t/connections(+/verify,/credential,/activity,/connection-grants): the integrations hub. A credential is verified against the provider when it is connected rather than merely stored,/credentialsays which one is loaded without revealing it, and/activityreads what the connection actually did. - Copies and erasure —
/directory/backupsand/directory/restorefor the directory itself,/scopes/:s/backupsand/snapshotsfor a scope. A scope backup is stored as entries: its pages, and the writes caught while it was taken.POST /scopes/:s/backups/:capturedAt/restoreloads one back into the scope, entry by entry, and is what a reap'sbackupRefnames.GET /scopes/:s/backups/:capturedAtreturns the whole dump only for a backup stored in one entry, and answers413for one stored in several. Then there is/scopes/:s/subjects/:id/shred, which redacts the spine payloads and destroys the sealing key in one audited, idempotent call — returning a receipt the DSAR response is written from. Deliberately staff-only: a builder forwards the request, the platform executes it. - Email permission —
GET /verticals/:slug/email-senderreads{ slug, emailSender };POSTwith{ granted: boolean }enables or disables transactional mail for every installation of the vertical. The owning team's dashboard manages this under Settings → Permissions; tenant credentials are checked against registry ownership, and staff retain an override. Deployment manifests cannot grant it. - Provisioner grant —
/verticals/:slug/tenant-provisionerremains staff-only. - Ownership history —
GET /verticals/:slug/owners(staff-only) lists every period of a slug's ownership, oldest first: the owning tenant (or none, for a platform vertical), from when, until when. A period opens when the slug is registered and closes when it is deleted, so a deleted slug still answers with its history. It takes the vertical's full slug and ignores the tenant pin: the pin resolves a bare name through the registry row, which a deleted slug no longer has. A bare name is read as a slug of its own, and one never registered answers with no periods.501on a control plane that keeps none. - Roles, admin-log, ops-failures, meters (
/meters/requestsis the daily request count per tenant, app and scope, kept from the router's sampled datapoints: every count is an estimate, and the answer names which days have been read;/meters/daysis each tenant's scope and entitlement counts as the first scheduled pass of each day found them, kept, with the record of which days were taken), model-usage (meter 3: the lines a vertical's model host raised asmodel-usageintents, listed and folded per tenant × model with the platform's margin applied at read time), and observability (/observability/logs,/observability/metrics,/observability/metrics-series— staff-only, script-grain, and/observability/tenant-metrics,/observability/tenant-metrics-series,/observability/tenant-logs— the only observability routes a non-staff builder may reach, because they answer about one tenant: a builder's tenant is forced from the principal, and a staff caller must name one, since answering fleet-wide on a forgotten parameter is the leak these exist to close; both log routes setx-substrat-logs-incomplete: 1beside the list when the page may be missing lines) — the permission surface, the append-only audit history, operational failures, billable readings, and fleet telemetry. - Tenant metered usage —
GET /tenants/:tenantId/metered-usageis a path-pinned, read-only answer for that tenant's dashboard owner or admin (the dashboard's Billing view). It meters usage and does not charge: it carries no prices, person or scope identifiers. It returns, for the last 30 closed UTC days, four sections, each with its ownstate(complete,partial,truncated,empty,unavailable, and for storage alsostale,failingandnot-sampled), alowerBoundflag and a breakdown by vertical:storage(the stored scope-database gauge),requests(estimated daily router requests, withcoveredDaysoftotalDays),models(recorded calls and provider-reported tokens) andbuilds.buildsanswersbuilds(a count),ms(milliseconds) andbyVertical{ vertical, builds, ms }, over the windowsince..until. It counts successful hosted source builds, from leaving the queue to collecting the release; queue time and failed builds are not counted, and a later deployment refusal does not undo a build's usage. No successful build isemptywith null totals; at 500 rows the section istruncatedand a lower bound; the breakdown is cut at 50 entries and says so inbreakdownTruncated.daysholds one row per closed day; a null there is a day with no reading, not zero.retentionstates how long each source is kept. Capped scans are labelled as truncated, and an absent source isunavailable, never zero. The fleet meter and model-usage routes above remain staff-only. - Model usage for a call outside a scope —
POST /model-usage(staff-only) records one line for a model call that ran in no tenant's scope, so no intent could carry it to the drain. The body is validated as a model-usage record; a tenant the directory does not hold answers404, and a non-staff caller403. The studio's turns reach a team's usage through this door. - Source build records —
GET /builder-builds/:tenantId/:buildId(staff client:getBuilderBuild(tenantId, buildId)) returns the retained record of one hosted source build: its outcome, the steps it reached, each command's exit code, duration and output, and what interrupted it when something did. It is a source-build record, not a studio turn (/builder-turns). Staff-only, because a record carries what the tenant's build printed, so any other caller gets403;501when the host has no source-build service;404for a build with no retained record. Keep its contents out of tenant-facing instructions. - Sweep runs —
/sweep-runs: the durable record of what a sweep pass touched, one row per unit (a connection swept, skipped or failed, a schedule run, a freshness verdict). Staff read fleet-wide; a builder's tenant is forced from the principal, the/ops-failuresposture exactly. - Service refs —
/service-refs: what a Cloudflare service ref means — each owned vertical's serving script and per-version archive scripts, mapped to the signals stamp{vertical, version}plus the label beside it. A directory read, deliberately outside the observability501guard, so the release-health and issues views can join whether or not a telemetry backend is configured. - Issues —
/issuesandPUT /issues/status: operational failures grouped by fingerprint into failure classes, most recently seen first, and the staff verdict on one (resolve, ignore, reopen —regressedis ingest's word and is refused). Staff-only: an issue is a fleet-scoped aggregate with no tenant column, so the forced-filter posture cannot narrow it. No cursor, by design — the grouping is the compression. - Findings —
GET /findings, filtered bystatusandkind, withlimitandcursorpaging. Staff can select a tenant; a tenant credential is confined to its own tenant.PUT /tenants/:t/findings/:id/statusacknowledges, resolves or reopens one.GET/POST /tenants/:t/finding-ruleslist or create suppress rules, andDELETE /tenants/:t/finding-rules/:ruleIdrevokes one. Builders have no access to these routes. The dashboard checks its member's findings permissions before making the tenant-scoped call; see the Findings inbox. - Lake reads —
GET /tenants/:t/lake/events: an audited read of one tenant's event envelopes, with no event payload. It returns501unless the host supplieslakeQuery. The gateway forces the tenant and refuses a result containing another tenant's row. Staff reads are unwindowed. A tenant credential reaches its own path only, and its read must carrysinceand span at most 31 days, ending at the earlier ofuntiland now; otherwise it is refused with a validation error. The dashboard's team route checksdashboard:read-event-lake(held by owner and admin) before it makes that call. Builders are refused. The R2 SQL transport is implemented but remains unverified against the real lake; this is not yet a history browser. - Capabilities —
/tenants/:t/scopes/:s/capabilities(#1686): the operator's read of the directory behind link shares and claim links — what each may do (mode, entity, keys, operation allowlist, or the principal a claim link yields), who minted and revoked it, its expiry, use limit and use count. Newest first, live ones unless?includeRevoked=true, narrowed with?entityType=…&entityId=…(both or neither), and keyset-paged like the other list reads:?limit(1–200, default 50) and?cursor, answering{ entries, nextCursor }.nextCursoris set only when more records follow (a malformed cursor is a 400), so a screen can always tell a complete list from a first page. Staff-only — a builder or a tenant credential is refused 403 even for its own tenant, because a row names the vertical's end users — and ladder-delegated like the denial log. Records only: no secret is stored and no hash is ever selected or returned. - Peer bindings —
GETandPUT /tenants/:t/scopes/:s/peer-bindings(#1720): the tenant's explicit target for a call made by scopes.GET ?vertical=acme/crmreturns one binding ornull; without that query it lists all bindings for the caller.PUTaccepts{ "vertical": "acme/crm", "targetScopeId": "…" }, ornullto clear. The caller and target must be live primary scopes of the addressed tenant. The write records an intent and outcome in the admin log, and responds with its operation id. A target archived after binding remains invalidated even if later unarchived; an admin must bind it again. Queued peer calls read the binding when they execute. - Denials —
/tenants/:t/scopes/:s/denialsand…/denials/summary: the refusals a scope recorded (K-35). The third log beside the two above — the admin log holds staff mutations, the K-24 access log staff reads, and this one the operations that were refused. Scope-local rather than directory-side, because a denial rolls its own operation back and so must be written where that operation ran; the summary is bucketed per (actor, permission) so a prober's volume cannot hide a quiet actor, or per operation with?groupBy=operation— the answer echoesgroupByso a caller can tell which question a vertical pushed before that parameter existed actually answered. An operation bucket's key is nullable: refusals that unwound no operation invocation form oneoperation: nullbucket that still counts towardtotal. /push-tokens— mints the scoped builder tokens asubstrat pushauthenticates with.
Routes are the shape only; enumerate the OpenAPI document for the exact request/response schemas. The package also ships the typed clients that consume this surface — ControlPlaneClient (Console/CLI) and the narrowed, tenant-scoped VerticalClient (an app provisioning itself) — plus the deploy helpers (deployManifest, createWfpUploader) that validate a bundle against the sandbox contract and upload it to Workers-for-Platforms.
The audited-transport role
The one property that must not be retrofitted (K-20): a surface that can act on the directory without a durable record of who acted is worse than none. This package is that guarantee at the network edge — it authenticates the actor, forwards to HostAdmin, and lets the kernel write the append-only row. Staff auth (SSO, MFA) gates exposing the surface; the audit property is built into it. See The control plane.
Versioning
AGPL-3.0-only. Pre-release (0.x): the surface changes without notice until the platform GAs.