Skip to content

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

sh
pnpm add @substrat-run/control-plane-api

createControlPlaneApi ​

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:

ts
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/:s and 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; cause and effects, 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: a facets answer is normalized, and a payload grouping from a vertical whose kernel predates #1762 is refused — no buckets, the events counted in withheldPersonal, and withheldReason: 'vertical-predates-rule' — since that kernel groups personal data. On the delegated branch the transport writes the K-24 access row itself, through HostAdmin.recordDelegatedRead, so an auditor cannot tell which branch served a read from the row it left. A facets row also records the answer's withheldPersonal and any withheldReason, on both branches. Two scope reads sit outside that ladder on purpose: export always goes through HostAdmin.exportScope first, because that is the call that writes its access-log entry (the vertical supplies only the bytes when one is bound), and migrations is 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-seat reads whether the instance's owner seat has been claimed, and POST …/owner-claim mints the short-lived claim link (201), addressed to the scope's bound app hostname. owner-claim answers 409 when no hostname is bound or the seat is already claimed; either route answers 501 when the scope is bound to no vertical (with the diagnosis) or the bound vertical keeps no owner seat — both callbacks are optional in vertical-host, and the vertical's own status is forwarded unchanged. The member routes are forwarded the same way: GET …/members (the roster), POST …/members with { roleKey, email? } (an invite: 201 and a one-time accept link on the scope's app hostname), POST …/members/:principal/role with { from, to }, and POST …/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 refused 403 on the three writes; the roster still reads. Each write leaves two manageScopeMember rows on the admin log, the intent and then applied, refused or failed, paired by the operationId a refusal also answers with. The vertical's own status (403 past the person's authority, 409 for the owner of record, 501 for an app that declares no member roles) is forwarded unchanged. A third, POST …/owner-transfer with { from, to }, hands the owner seat to another member of the instance. It is staff-only: a tenant credential or a builder is refused 403. The vertical moves its owner of record, seats to in the owner role, revokes from's, and closes the hand-over. A repeat after that answers outcome: 'done' and changes nothing. It refuses with 409, changing nothing, when the seat is still unclaimed, from is not the owner of record, no login is bound to to, to holds 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 answers 501, 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-host beside it, which is upgraded with it (#2531). A hand-over that can no longer finish, because to was 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 on to, from where a new hand-over starts. The original from keeps any owner seat it still holds, since the abandon revoked nothing; the next owner removes it in the app. Its rows carry abandon: true. Every attempt writes two transferOwner rows to the admin log, paired by the operationId the route answers with: an intent before the vertical is asked, then applied, refused or failed. A failed hand-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 as audit-outcome-unrecorded with the operationId. A change that went through is answered as the success it is (200, or 201 for an invite, with the result: an invite keeps its accept link), carrying auditWarning beside the operationId every 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 answers 504, audited failed. The platform's scheduled pass closes an intent that still has no outcome an hour later. It writes an unknown row, 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) beats unknown, and two real outcomes for one operation read conflicting and are logged, never guessed past. An operation is its action, its operationId, 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 with auditWarning, and the scheduled pass closes the intent as unknown. GET /admin-log returns the rows as written, and gives each row of these six actions an audited field: its operationId, the outcome the operation stands at (pending until it has one), and superseded on an unknown a 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 an unknown whose operation has since recorded one real outcome. The answer's fromRevoked is about the instance's own owner seat only. false means from held none there; if from holds 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 narrow GET /verticals to 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/promote refuses a non-prod channel with a 400. 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. 501 on 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, /credential says which one is loaded without revealing it, and /activity reads what the connection actually did.
  • Copies and erasure — /directory/backups and /directory/restore for the directory itself, /scopes/:s/backups and /snapshots for a scope. A scope backup is stored as entries: its pages, and the writes caught while it was taken. POST /scopes/:s/backups/:capturedAt/restore loads one back into the scope, entry by entry, and is what a reap's backupRef names. GET /scopes/:s/backups/:capturedAt returns the whole dump only for a backup stored in one entry, and answers 413 for 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-sender reads { slug, emailSender }; POST with { 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-provisioner remains 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. 501 on a control plane that keeps none.
  • Roles, admin-log, ops-failures, meters (/meters/requests is 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/days is 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 as model-usage intents, 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 set x-substrat-logs-incomplete: 1 beside 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-usage is 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 own state (complete, partial, truncated, empty, unavailable, and for storage also stale, failing and not-sampled), a lowerBound flag and a breakdown by vertical: storage (the stored scope-database gauge), requests (estimated daily router requests, with coveredDays of totalDays), models (recorded calls and provider-reported tokens) and builds. builds answers builds (a count), ms (milliseconds) and byVertical{ vertical, builds, ms }, over the window since..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 is empty with null totals; at 500 rows the section is truncated and a lower bound; the breakdown is cut at 50 entries and says so in breakdownTruncated. days holds one row per closed day; a null there is a day with no reading, not zero. retention states how long each source is kept. Capped scans are labelled as truncated, and an absent source is unavailable, 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 answers 404, and a non-staff caller 403. 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 gets 403; 501 when the host has no source-build service; 404 for 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-failures posture 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 observability 501 guard, so the release-health and issues views can join whether or not a telemetry backend is configured.
  • Issues — /issues and PUT /issues/status: operational failures grouped by fingerprint into failure classes, most recently seen first, and the staff verdict on one (resolve, ignore, reopen — regressed is 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 by status and kind, with limit and cursor paging. Staff can select a tenant; a tenant credential is confined to its own tenant. PUT /tenants/:t/findings/:id/status acknowledges, resolves or reopens one. GET / POST /tenants/:t/finding-rules list or create suppress rules, and DELETE /tenants/:t/finding-rules/:ruleId revokes 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 returns 501 unless the host supplies lakeQuery. 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 carry since and span at most 31 days, ending at the earlier of until and now; otherwise it is refused with a validation error. The dashboard's team route checks dashboard: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 }. nextCursor is 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 — GET and PUT /tenants/:t/scopes/:s/peer-bindings (#1720): the tenant's explicit target for a call made by scope s. GET ?vertical=acme/crm returns one binding or null; without that query it lists all bindings for the caller. PUT accepts { "vertical": "acme/crm", "targetScopeId": "…" }, or null to 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/denials and …/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 echoes groupBy so 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 one operation: null bucket that still counts toward total.
  • /push-tokens — mints the scoped builder tokens a substrat push authenticates 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.