@substrat-run/control-plane-api 0.52.0 → 0.54.0

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -1,11 +1,12 @@
 import { Hono } from 'hono';
-import { adminAction, ASSET_PART_PREFIX, assetHash, channelName, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, listPageQuery, pageOf, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, registerVerticalInput, scopeDump, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, z, } from '@substrat-run/contracts';
+import { adminAction, ASSET_PART_PREFIX, assetHash, channelName, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, listPageQuery, pageOf, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, registerVerticalInput, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, z, } from '@substrat-run/contracts';
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { TENANT_HEADER } from './auth.js';
 import { ControlPlaneError } from './client.js';
 import { provisionSiblingScope } from './platform-drain.js';
 import { mapError } from './errors.js';
 import { maskDump, maskRecords } from './mask.js';
+import { openDump, sealDump } from './seal.js';
 import { assertSandboxContract, deployManifest, storedDeployManifest, deploymentRefFor, stableDeploymentRefFor, nextMigrationTag, upstreamStatusOf, } from './deploy.js';
 import { blobStoreBindings, collectBlobStoreHandles, collectTenantStoreHandles, tenantStoreBindings, } from './tenant-stores.js';
 import { mintPushToken, pushActorFor } from './push-token.js';
@@ -218,6 +219,21 @@ const auditLogQuery = z.object({
     // everything) — only the HTTP egress vectors are bounded by default.
     ...listPageQuery.shape,
 });
+const opsFailuresQuery = z.object({
+    tenantId: tenantIdSchema.optional(),
+    scopeId: scopeIdSchema.optional(),
+    vertical: z.string().optional(),
+    operation: z.string().optional(),
+    // Exact match — the lookup a CI log's `reference = <id>` line lands on.
+    reference: z.string().optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    // Bounded by default exactly as /admin-log, and for the same reason.
+    ...listPageQuery.shape,
+});
+/** The upstream provider's trace handle, when a failure message carries one —
+ *  Cloudflare's `internal error; reference = <id>` shape (#559). */
+const UPSTREAM_REFERENCE = /\breference\s*=\s*([a-z0-9]+)/i;
 /**
  * The audited HTTP surface over `HostAdmin` (control-plane.md §4.5).
  *
@@ -339,6 +355,18 @@ export function createControlPlaneApi(options) {
         }
         await next();
     });
+    // Fire-and-forget ops-failure write (#559): a recorder that throws must never
+    // mask the failure it is recording, so every path through this swallows its own
+    // errors. The upstream reference is extracted here — one place — so a caller
+    // that only has the message still lands a searchable row.
+    const recordFailure = (entry) => {
+        void admin
+            .recordOpsFailure({
+            ...entry,
+            reference: entry.reference ?? UPSTREAM_REFERENCE.exec(entry.message)?.[1] ?? null,
+        })
+            .catch(() => undefined);
+    };
     // One error boundary for every route: adapters throw plain Errors, and each
     // one is a fail-closed refusal that must reach the caller as a status, not a
     // stack trace.
@@ -347,6 +375,25 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'invalid request', issues: err.issues }, 400);
         }
         const { status, body } = mapError(err);
+        // A 5xx is the PLATFORM failing — an unmapped throw, or a downstream vertical's
+        // own 5xx passing through (a DO storage fault during a preview restore is the
+        // founding case, #559) — so it lands a durable ops-failure row the console can
+        // list and a `reference = <id>` search can find. 501 stays out: an honest
+        // not-implemented is a capability statement, not a failure. 4xx stay out too:
+        // they are refusals the caller can already read. Actor is unset only when the
+        // throw happened before authentication — nothing worth recording refuses there.
+        const actor = c.get('actor');
+        if (status >= 500 && status !== 501 && actor) {
+            recordFailure({
+                actor,
+                operation: `${c.req.method} ${c.req.routePath}`,
+                vertical: c.req.param('slug') ? decodeURIComponent(c.req.param('slug')) : null,
+                tenantId: c.req.param('tenantId') ?? null,
+                scopeId: c.req.param('scopeId') ?? null,
+                status,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
         // A 500 is, by definition, a throw whose message `mapError` did not recognise — so the
         // client gets a GENERIC body that discloses nothing, and until now nothing recorded WHAT
         // threw either. That left every unmapped failure (e.g. a raw SQLite constraint from a
@@ -640,6 +687,19 @@ export function createControlPlaneApi(options) {
     // installed app lags prod. So we prefer bound-version resolution, then fall back to
     // prod-channel/static (a scope with no bound version), then to reading this host's own
     // scope DB directly (a co-located host, or the contract tests — data is right here).
+    /**
+     * The per-subject key operations bound to one scope and one actor (#37) — what
+     * `sealDump`/`openDump` need and nothing more.
+     *
+     * Narrowed on purpose: the seal path gets exactly two capabilities, so a future edit
+     * cannot quietly widen a backup routine into a general admin caller. Every call lands in
+     * the access log under the acting staff member, because reading or minting the keys that
+     * protect a subject's data is itself a thing an incident asks about.
+     */
+    const sealerFor = (c, tenantId, scopeId) => ({
+        seal: (items) => admin.sealSubjectPayloads(c.get('actor'), tenantId, scopeId, items),
+        open: (items) => admin.openSubjectPayloads(c.get('actor'), tenantId, scopeId, items),
+    });
     const verticalForScope = async (c, scope) => {
         if (!scope.vertical)
             return undefined;
@@ -835,9 +895,9 @@ export function createControlPlaneApi(options) {
         // brought — the crossing is then no riskier than an ordinary version bind. Anything
         // else (differing digests, or a scope with no bound version to compare) needs the
         // operator's explicit acknowledgement.
-        const targetV = (await admin.listVersions(actor, target)).find((v) => v.id === serving.versionId);
+        const targetV = await admin.getVersion(actor, serving.versionId, target);
         const currentV = scope.verticalVersionId
-            ? (await admin.listVersions(actor, scope.vertical)).find((v) => v.id === scope.verticalVersionId)
+            ? await admin.getVersion(actor, scope.verticalVersionId, scope.vertical)
             : undefined;
         const digestsMatch = Boolean(currentV && targetV && currentV.migrationDigest === targetV.migrationDigest);
         if (!digestsMatch && !opts.ackMigrations) {
@@ -1143,7 +1203,14 @@ export function createControlPlaneApi(options) {
         const dump = await admin.exportScope(c.get('actor'), tenantId, scope.id);
         const vertical = await verticalForScope(c, scope);
         const tables = vertical ? await vertical.exportScope(scope.id) : dump.tables;
-        return store.put({ vertical: scope.vertical, dump: { ...dump, tables } });
+        // Seal classified payloads per subject on the way in (#37). This copy is full-fidelity
+        // and the platform keeps it, which is precisely why an erasure could never reach it: a
+        // redaction fixes the live scope and does nothing to the object already in R2. Sealed
+        // here, destroying one subject's key reaches backwards into every copy already taken.
+        // Restores open it again (`restoreFromBackup`) — except for subjects shredded in the
+        // meantime, which is the mechanism working rather than the copy being damaged.
+        const sealed = await sealDump(tables, sealerFor(c, tenantId, scope.id));
+        return store.put({ vertical: scope.vertical, dump: { ...dump, tables: sealed } });
     };
     // The copies held for one scope — metadata only, so listing a reaped scope's backups
     // is cheap and hands out no bytes. Readable AFTER the reap (that is the point): the
@@ -1176,7 +1243,13 @@ export function createControlPlaneApi(options) {
         const dump = await options.scopeBackups.get({ tenantId, scopeId, capturedAt });
         if (!dump)
             return c.json({ error: `no backup for scope ${scopeId} at ${capturedAt}` }, 404);
-        return c.json(dump);
+        // Unseal on the way out (#37). The bytes in the store stay sealed — this is the
+        // authorized read opening them with the keys the platform holds. A subject shredded
+        // since the copy was taken opens to a null payload, which is exactly the erasure
+        // working: the ciphertext never left the object, and nothing turns it back into a
+        // person. A dump taken before sealing existed passes through untouched.
+        const opened = await openDump(dump.tables, sealerFor(c, tenantId, scopeId));
+        return c.json({ ...dump, tables: opened });
     });
     // Take a backup WITHOUT reaping — the standalone copy (a pre-migration checkpoint, an
     // export-to-keep). The reap route below takes its own; this is the same act made
@@ -1197,6 +1270,32 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
+    // -- subject erasure (#37) --------------------------------------------------
+    // Erase one data subject from one scope: redact the spine payloads keyed to them, then
+    // destroy the key that seals every platform-retained copy of those payloads.
+    //
+    // Staff-only, and NOT in BUILDER_ROUTES. That placement is the shared-responsibility line
+    // drawn where hosting-and-certification.md §3 already draws it — "we provide extraction,
+    // they define scope". A builder forwards the request; the platform executes it and hands
+    // back a receipt they can answer their data subject with. Making it self-service would
+    // hand a vertical the ability to destroy evidence about a person on its own authority,
+    // which is a different decision than this one and belongs in its own issue.
+    //
+    // Idempotent by construction: a re-run redacts nothing (the payloads are already null),
+    // reports `keyDestroyed: false` (the key is already gone) and still returns
+    // `tombstoned: true`. Safe to retry, which matters because the audited half and the
+    // cryptographic half are two writes.
+    app.post('/tenants/:tenantId/scopes/:scopeId/subjects/:subjectId/shred', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        // A ULID, like every other subject id the spine carries — parsed rather than trusted,
+        // so a wildcard or an injection attempt is a 400 and never reaches the UPDATE.
+        const subjectId = dataSubjectIdSchema.parse(c.req.param('subjectId'));
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        return c.json(await admin.shredSubject(c.get('actor'), tenantId, scopeId, subjectId));
+    });
     // -- directory backups (#40) -----------------------------------------------
     // The platform's own disaster recovery, on the same store posture as the scope
     // backups above and deliberately on a different axis from them: a scope has ~30-day
@@ -1518,11 +1617,24 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'restore refused: the backup has no tables — not a scope dump' }, 422);
         }
         try {
-            await host.restoreScope(actor, tenantId, scopeId, dump);
+            // Belt and braces for #37: a caller who fetched the object bytes by some other route
+            // may POST a still-sealed dump, and a scope restored full of ciphertext is a silent
+            // data-loss bug. `openDump` skips cells that are not sealed, so a plaintext dump —
+            // the normal case, since the GET above already opened it — costs one pass and
+            // changes nothing.
+            //
+            // Opened against the dump's OWN provenance, not the destination. Subject keys are
+            // keyed by (scope, subject), so a copy of scope A landing in scope B — a backout onto
+            // a different scope, a world loaded sideways — must be opened with A's keys. Using
+            // the destination's would find no key, null every payload, and call it a restore.
+            const origin = { tenantId: tenantIdSchema.parse(dump.tenantId), scopeId: scopeIdSchema.parse(dump.scopeId) };
+            const tables = await openDump(dump.tables, sealerFor(c, origin.tenantId, origin.scopeId));
+            const landing = { ...dump, tables };
+            await host.restoreScope(actor, tenantId, scopeId, landing);
             const vertical = await verticalForScope(c, scope);
             if (vertical)
-                await vertical.restoreScope(tenantId, scopeId, dump.tables);
-            return c.json({ restored: scopeId, tables: dump.tables.length });
+                await vertical.restoreScope(tenantId, scopeId, tables);
+            return c.json({ restored: scopeId, tables: tables.length });
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
@@ -1686,9 +1798,10 @@ export function createControlPlaneApi(options) {
                 // Delegated path: the digest compare lives here (the in-process path does
                 // it below the seam). Snapshot only a migration-crossing bind.
                 if (scope.vertical && scope.verticalVersionId) {
-                    const versions = await admin.listVersions(actor, scope.vertical);
-                    const current = versions.find((v) => v.id === scope.verticalVersionId);
-                    const incoming = versions.find((v) => v.id === versionId);
+                    const [current, incoming] = await Promise.all([
+                        admin.getVersion(actor, scope.verticalVersionId, scope.vertical),
+                        admin.getVersion(actor, versionId, scope.vertical),
+                    ]);
                     if (current && incoming && current.migrationDigest !== incoming.migrationDigest) {
                         await orchestratedSnapshot(c, tenantId, scope, {});
                     }
@@ -1801,6 +1914,19 @@ export function createControlPlaneApi(options) {
             // must act on, and indistinguishable from "the vertical is broken" once it
             // has been flattened.
             if (e instanceof ControlPlaneError) {
+                // The retry above already rode out the transient window, so a 5xx here is a
+                // provision the platform could not complete — record it (#559). Refusals
+                // (4xx, and 501 = not implemented) stay unrecorded: the caller can read them.
+                if (e.status >= 500 && e.status !== 501) {
+                    recordFailure({
+                        actor: c.get('actor'),
+                        operation: 'install.provision',
+                        vertical: slug,
+                        tenantId: input.tenantId,
+                        status: e.status,
+                        message: e.message,
+                    });
+                }
                 return c.json({ error: e.message }, e.status);
             }
             throw e;
@@ -1918,7 +2044,7 @@ export function createControlPlaneApi(options) {
         }
         input.verticalSlug = slug;
         await admin.publishVersion(c.get('actor'), input);
-        const version = (await admin.listVersions(c.get('actor'), slug)).find((v) => v.id === input.id);
+        const version = await admin.getVersion(c.get('actor'), input.id, slug);
         return c.json(version, 201);
     });
     // The declared permission registry (D-39, #336) that ships inside one version's manifest:
@@ -1957,14 +2083,14 @@ export function createControlPlaneApi(options) {
         const slug = c.req.param('slug');
         const id = c.req.param('id');
         await admin.admitVersion(c.get('actor'), id);
-        return c.json((await admin.listVersions(c.get('actor'), slug)).find((v) => v.id === id));
+        return c.json(await admin.getVersion(c.get('actor'), id, slug));
     });
     app.post('/verticals/:slug/versions/:id/reject', async (c) => {
         const slug = c.req.param('slug');
         const id = c.req.param('id');
         const { note } = rejectVersionBody.parse(await c.req.json());
         await admin.rejectVersion(c.get('actor'), id, note);
-        return c.json((await admin.listVersions(c.get('actor'), slug)).find((v) => v.id === id));
+        return c.json(await admin.getVersion(c.get('actor'), id, slug));
     });
     // A builder REQUESTS publication of a vertical it owns (marketplace-publish.md §5) — any owner
     // may ask; the staff `listing` flip below is the review gate. Owner-checked (like promote).
@@ -2066,7 +2192,7 @@ export function createControlPlaneApi(options) {
     const serveVersionInPlace = async (actor, slug, versionId) => {
         if (!options.deployVertical || !options.fetchVerticalModules)
             return; // not configured: pre-#286 behavior
-        const version = (await admin.listVersions(actor, slug)).find((v) => v.id === versionId);
+        const version = await admin.getVersion(actor, versionId, slug);
         if (!version?.deploymentRef) {
             throw new ControlPlaneError(502, `version ${versionId} has no archive script to serve from`);
         }
@@ -2395,7 +2521,20 @@ export function createControlPlaneApi(options) {
             const detail = e instanceof Error ? e.message : String(e);
             const upstream = upstreamStatusOf(e);
             console.error('deploy.upload.failed', { slug, deploymentRef, detail, upstream });
-            return upstream !== undefined && upstream >= 400 && upstream < 500
+            const rejected = upstream !== undefined && upstream >= 400 && upstream < 500;
+            // Both outcomes land an ops-failure row (#559): the 502 is the platform's to
+            // explain, and the 422 is what the builder-facing failure view (step 5) will
+            // list — a red push should be explainable from a durable record either way.
+            recordFailure({
+                actor: c.get('actor'),
+                operation: 'deploy.upload',
+                stage: 'wfp-upload',
+                vertical: slug,
+                tenantId: ownerTenant ?? null,
+                status: rejected ? 422 : 502,
+                message: detail,
+            });
+            return rejected
                 ? c.json({ error: 'deploy rejected', detail }, 422)
                 : c.json({ error: 'deploy upload failed', detail }, 502);
         }
@@ -2450,14 +2589,19 @@ export function createControlPlaneApi(options) {
         const warnings = [];
         if (manifest.surfaces?.length) {
             const declared = new Set(manifest.surfaces.map((s) => s.name));
-            const bound = await admin.listHostnames(c.get('actor'), {});
+            // Narrowed to THIS vertical's bindings in the query. It used to read every
+            // hostname on the platform and filter in JS, which made an advisory warning about
+            // one push depend on every other tenant's routing rows parsing cleanly — a
+            // malformed cert-validation blob on an unrelated domain took the whole deploy down
+            // with a blank 500, after the version had already been published.
+            const bound = await admin.listHostnames(c.get('actor'), { verticalSlug: slug });
             for (const h of bound) {
-                if (h.verticalSlug === slug && !declared.has(h.surface)) {
+                if (!declared.has(h.surface)) {
                     warnings.push(`hostname '${h.hostname}' is bound to surface '${h.surface}', which this version no longer declares`);
                 }
             }
         }
-        const version = (await admin.listVersions(c.get('actor'), slug)).find((v) => v.id === id);
+        const version = await admin.getVersion(c.get('actor'), id, slug);
         return c.json({ ...version, ...(warnings.length ? { warnings } : {}) }, 201);
     });
     // -- where this platform runs (ops ergonomics) -----------------------------
@@ -2801,7 +2945,7 @@ export function createControlPlaneApi(options) {
         // prod build) while we report success. That is worse than a failure: it sends a reviewer
         // to redo correct work. So refuse to return success for a URL that would serve other code.
         const assertServesBoundVersion = async (previewId) => {
-            const bound = (await admin.listVersions(actor, slug)).find((v) => v.id === opts.versionId);
+            const bound = await admin.getVersion(actor, opts.versionId, slug);
             // A co-located / embedded vertical has no per-version dispatch script (deploymentRef
             // null) and routes via the static fallback — nothing to compare, so nothing to guard.
             if (!bound?.deploymentRef)
@@ -3070,6 +3214,27 @@ export function createControlPlaneApi(options) {
         // page carries its own continuation and the console never assembles one.
         return c.json(pageOf(entries, filter.limit, (e) => e.id));
     });
+    // The recorded operational failures (#559) — the console's failures view, and the
+    // "what does this `reference = <id>` belong to" lookup. Staff-only by omission from
+    // BUILDER_ROUTES (a builder-scoped slice is step 5's concern, deliberately not
+    // pre-opened here). Newest first by default, unlike /admin-log: an operator asks
+    // "what broke lately".
+    app.get('/ops-failures', async (c) => {
+        const filter = opsFailuresQuery.parse({
+            tenantId: c.req.query('tenantId'),
+            scopeId: c.req.query('scopeId'),
+            vertical: c.req.query('vertical'),
+            operation: c.req.query('operation'),
+            reference: c.req.query('reference'),
+            since: c.req.query('since'),
+            until: c.req.query('until'),
+            limit: c.req.query('limit'),
+            cursor: c.req.query('cursor'),
+            order: c.req.query('order'),
+        });
+        const entries = await admin.listOpsFailures(c.get('actor'), filter);
+        return c.json(pageOf(entries, filter.limit, (e) => e.id));
+    });
     return app;
 }
 //# sourceMappingURL=api.js.map