@substrat-run/control-plane-api 0.13.0 → 0.16.0

package/README.md

@@ -0,0 +1,58 @@
+# @substrat-run/control-plane-api
+
+The HTTP surface over `HostAdmin` for [Substrat](https://github.com/substrat-run/substrat) —
+the **audited control-plane transport**. 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 console, the CLI, or another service.
+
+It is a transport, not a source of truth. Every call lands on `HostAdmin`, every mutation
+is audited, and the same contract runs over any scope host (the pure-SQLite adapter in
+CI, Durable Objects in production).
+
+## What's in the box
+
+- **`createControlPlaneApi`** — a [Hono](https://hono.dev) app exposing `HostAdmin` over
+  HTTP, with authentication and the audit log wired in.
+- **`ControlPlaneClient`** — the typed client for that surface (what the console and CLI
+  call), plus `ControlPlaneError` for structured failures.
+- **`VerticalClient`** — the narrowed, tenant-scoped seam an app uses to provision itself.
+- **`deployManifest` / `createWfpUploader`** — the deploy path: validate a vertical
+  bundle against the sandbox contract and upload it to Workers-for-Platforms.
+
+## Install
+
+```sh
+pnpm add @substrat-run/control-plane-api
+```
+
+```ts
+import { createControlPlaneApi } from '@substrat-run/control-plane-api';
+
+const app = createControlPlaneApi({ admin /* HostAdmin */, /* auth, audit, … */ });
+export default app; // a Hono app — serve it on Node, Workers, or in tests
+```
+
+```ts
+import { ControlPlaneClient } from '@substrat-run/control-plane-api';
+
+const cp = new ControlPlaneClient({ baseUrl, token });
+await cp.provisionScope({ tenant, slug });
+```
+
+## Documentation
+
+**https://substrat.net/platform/control-plane** — the admin surface, the audit model,
+authentication, and how the console/CLI/router sit on top of it.
+
+## Related packages
+
+- [`@substrat-run/kernel`](https://npmjs.com/package/@substrat-run/kernel) — the
+  scope-host + `HostAdmin` contract this exposes
+- [`@substrat-run/adapter-sqlite`](https://npmjs.com/package/@substrat-run/adapter-sqlite) —
+  the pure-SQLite host it runs against in CI and self-host
+- [`@substrat-run/cli`](https://npmjs.com/package/@substrat-run/cli) — the deploy tooling
+  that drives this surface
+
+## Status
+
+Pre-release (0.x): the surface changes without notice until the platform GAs.

package/dist/api.d.ts

@@ -4,6 +4,7 @@ import type { ScopeHost } from '@substrat-run/kernel';
 import type { PlatformActorAuth, BuilderAuth, Principal } from './auth.js';
 import type { VerticalClient } from './vertical-client.js';
 import type { DeployVerticalFn } from './deploy.js';
+import type { ObservabilityReader } from './observability.js';
 export interface ControlPlaneApiOptions {
     host: ScopeHost;
     /**
@@ -23,6 +24,17 @@ export interface ControlPlaneApiOptions {
      * pushed vertical is provisionable with no redeploy. Absent ⇒ only static bindings.
      */
     resolveVertical?: (slug: string, actor: PlatformActorId) => Promise<VerticalClient | undefined>;
+    /**
+     * Resolves a vertical at a SPECIFIC version — a scope's data DO lives in the
+     * deployment of the version it was provisioned/bound to (`scope.verticalVersionId`),
+     * NOT necessarily the `prod` channel. Because each `substrat push` is a separate WfP
+     * script with its own DO namespace, introspection must reach the BOUND version's
+     * deployment (the same one the router serves the app from), or it reads an empty DO
+     * once an installed app lags prod. The `/tables` route prefers this over
+     * `resolveVertical`; the latter (prod) stays the fallback for a scope with no bound
+     * version. Absent ⇒ the route uses prod-channel/static resolution only.
+     */
+    resolveVerticalVersion?: (slug: string, versionId: string, actor: PlatformActorId) => Promise<VerticalClient | undefined>;
     /**
      * Uploads a built vertical bundle to the platform runtime (a WfP dispatch
      * namespace), injected by the host so this package holds no Cloudflare SDK and the
@@ -44,6 +56,23 @@ export interface ControlPlaneApiOptions {
      * the vertical-management routes and to the verticals their tenant owns.
      */
     authenticateBuilder?: BuilderAuth;
+    /**
+     * Signs tenant-scoped push tokens (push-token.ts) — the CI credential the dashboard
+     * mints into a customer repo. Absent ⇒ the mint route 501s. A dedicated secret,
+     * never PLATFORM_SECRET (injected into pushed verticals) and never the service
+     * token; set once, out of routine rotation (rotating it revokes every issued token).
+     */
+    pushTokenSecret?: string;
+    /**
+     * Cloudflare-native observability reads (design/observability.md §4.1) —
+     * host-injected like `deployVertical`, so this package holds no credential and the
+     * Cloudflare token never leaves the platform (D-34). Absent ⇒ the observability
+     * routes 501. Staff-only for now: the routes are deliberately NOT in
+     * `BUILDER_ROUTES` — the builder view needs owner-narrowing (only scripts whose
+     * registry `ownerTenant` is the caller's) before it can be opened, and default-deny
+     * means forgetting that costs a feature, never a leak.
+     */
+    observability?: ObservabilityReader;
 }
 type Vars = {
     actor: PlatformActorId;

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAoB5B,OAAO,KAAK,EAAE,eAAe,EAAqB,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChG;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;CACnC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAkG7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAmfhG"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAsB5B,OAAO,KAAK,EAAE,eAAe,EAA4B,MAAM,yBAAyB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAM3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChG;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,KACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACzC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAClC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAoH7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAq6BhG"}