@substrat-run/control-plane-api 0.92.1 → 0.95.0

package/dist/api.d.ts

@@ -45,6 +45,12 @@ export interface ConnectionInspector {
     probeCandidate?: (secret: Record<string, string>) => Promise<ConnectionProbe>;
 }
 export interface ControlPlaneApiOptions {
+    /**
+     * The platform's margin over list price for model usage it provides (#1054), whole
+     * percent, applied at read time by `GET /model-usage/summary`. One global number
+     * today; a per-provider rate is an additive change later. Default 20.
+     */
+    modelMarginPercent?: number;
     host: ScopeHost;
     /**
      * How to reach each vertical, by slug (K-31). Absent slugs simply cannot be
@@ -158,6 +164,17 @@ export interface ControlPlaneApiOptions {
      * token; set once, out of routine rotation (rotating it revokes every issued token).
      */
     pushTokenSecret?: string;
+    /**
+     * Keys the pseudonymizer behind a masked export (#1034, `pseudonymize.ts`). The salt
+     * never reaches the dump and no mapping is stored, so it is not a decryption key —
+     * what it buys is STABILITY: with one configured, two pulls of the same scope read
+     * the same, which is what makes a masked copy usable as a standing preview.
+     *
+     * Absent ⇒ a fresh random salt per export. Still deterministic within one response
+     * (a customer reads the same on every screen and in the timeline) and strictly
+     * safer, since two exports cannot be correlated — just not stable across pulls.
+     */
+    maskSalt?: string;
     /**
      * Cloudflare-native observability reads (design/observability.md §4.1) —
      * host-injected like `deployVertical`, so this package holds no credential and the
@@ -248,6 +265,7 @@ type Vars = {
     actor: PlatformActorId;
     principal: Principal;
 };
+export declare const DEFAULT_MODEL_MARGIN_PERCENT = 20;
 /**
  * The audited HTTP surface over `HostAdmin` (control-plane.md §4.5).
  *

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;AA4C5B,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EAGf,eAAe,EAMhB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAkBrF,OAAO,KAAK,EAEV,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAyBtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAEV,oBAAoB,EAEpB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,CACT,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,wBAAwB,CAAA;KAAE,KACtD,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACxF;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC9D;;;;;;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;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACpF;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,sBAAsB,CAAC;IAC9C;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAC1C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,qBAAqB,CAAC;IAC5C;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;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;IACpC;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC3D;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;IACxC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IAC9C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAyQ7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAw6HhG"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, registerVerticalInput, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, } from '@substrat-run/contracts';
+import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, registerVerticalInput, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, } from '@substrat-run/contracts';
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { TENANT_HEADER } from './auth.js';
 import { connectionGrantsForScope } from './vertical-client.js';
@@ -9,6 +9,7 @@ import { ControlPlaneError } from './client.js';
 import { provisionSiblingScope } from './platform-drain.js';
 import { mapError } from './errors.js';
 import { maskDump, maskRecords } from './mask.js';
+import { createPseudonymizer } from './pseudonymize.js';
 import { openDump, sealDump } from './seal.js';
 import { assertSandboxContract, deployManifest, storedDeployManifest, deploymentRefFor, stableDeploymentRefFor, nextMigrationTag, upstreamStatusOf, } from './deploy.js';
 /**
@@ -260,6 +261,22 @@ const opsFailuresQuery = z.object({
     // Bounded by default exactly as /admin-log, and for the same reason.
     ...listPageQuery.shape,
 });
+const modelUsageQuery = z.object({
+    tenantId: tenantIdSchema.optional(),
+    scopeId: scopeIdSchema.optional(),
+    vertical: z.string().optional(),
+    model: z.string().optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    ...listPageQuery.shape,
+});
+/** The summary window: a half-open `[since, until)`; defaults to the current calendar month so far. */
+const modelUsageSummaryQuery = z.object({
+    tenantId: tenantIdSchema.optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+});
+export const DEFAULT_MODEL_MARGIN_PERCENT = 20;
 /** 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;
@@ -1992,7 +2009,14 @@ export function createControlPlaneApi(options) {
             const dump = await admin.exportScope(actor, tenantId, scopeId);
             const vertical = await verticalForScope(c, scope);
             const tables = vertical ? await vertical.exportScope(scopeId) : dump.tables;
-            return c.json({ ...dump, tables: full ? tables : maskDump(tables), masked: !full });
+            if (full)
+                return c.json({ ...dump, tables, masked: false });
+            // One pseudonymizer for the whole response (#1034): the same customer has to read
+            // the same in their own row, in every event payload that quoted them, and in the
+            // timeline — a per-table generator would break exactly the joins that make a
+            // masked copy worth pulling.
+            const mask = await createPseudonymizer(options.maskSalt ?? crypto.randomUUID());
+            return c.json({ ...dump, tables: await maskDump(tables, mask), masked: true });
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
@@ -2062,13 +2086,17 @@ export function createControlPlaneApi(options) {
             // a vertical-held scope's real tables overlay it. A reaped scope has no storage
             // left to read, so it is skipped here while its RECORD stays above — the tombstone
             // is honest, an error would not be.
+            // ONE pseudonymizer for the whole export (#1034), shared by the directory half
+            // and every scope's tables: the person named in `members` has to read the same in
+            // the scope row that references them and in the event payload that quoted them.
+            const mask = full ? undefined : await createPseudonymizer(options.maskSalt ?? crypto.randomUUID());
             const live = scopes.filter((s) => s.status !== 'reaped');
             const data = [];
             for (const scope of live) {
                 const dump = await admin.exportScope(actor, tenantId, scope.id);
                 const vertical = await verticalForScope(c, scope);
                 const tables = vertical ? await vertical.exportScope(scope.id) : dump.tables;
-                data.push({ ...dump, tables: full ? tables : maskDump(tables) });
+                data.push({ ...dump, tables: mask ? await maskDump(tables, mask) : tables });
             }
             // The admin log is FULL-only (#36): it records what STAFF did, so it is not the
             // customer's Art. 20 data, and it carries staff actor ids and internal action
@@ -2079,19 +2107,19 @@ export function createControlPlaneApi(options) {
                 tenantId,
                 capturedAt: new Date().toISOString(),
                 masked: !full,
-                tenant: full ? tenant : maskRecords([tenant])[0],
-                scopes: full ? scopes : maskRecords(scopes),
-                orgs: full ? orgs : maskRecords(orgs),
-                members: full ? members : maskRecords(members),
+                tenant: mask ? (await maskRecords([tenant], mask))[0] : tenant,
+                scopes: mask ? await maskRecords(scopes, mask) : scopes,
+                orgs: mask ? await maskRecords(orgs, mask) : orgs,
+                members: mask ? await maskRecords(members, mask) : members,
                 // Roles, entitlements and hostnames are configuration rather than personal data,
                 // so they read the same in both fidelities — but they still go through the sweep,
                 // because deciding per-collection what "cannot contain PII" means is exactly the
                 // assumption that ages badly. One rule, applied everywhere.
-                roles: full ? roles : maskRecords(roles),
-                entitlements: full ? entitlements : maskRecords(entitlements),
+                roles: mask ? await maskRecords(roles, mask) : roles,
+                entitlements: mask ? await maskRecords(entitlements, mask) : entitlements,
                 // Identity links are the sharpest item here: `externalId` is usually an email.
-                identityLinks: full ? identityLinks : maskRecords(identityLinks),
-                hostnames: full ? hostnames : maskRecords(hostnames),
+                identityLinks: mask ? await maskRecords(identityLinks, mask) : identityLinks,
+                hostnames: mask ? await maskRecords(hostnames, mask) : hostnames,
                 stores: [...stores, ...blobStores].map((s) => ({
                     kind: s.kind,
                     vertical: s.vertical,
@@ -2099,7 +2127,7 @@ export function createControlPlaneApi(options) {
                     ref: s.ref,
                     createdAt: s.createdAt,
                 })),
-                connections: full ? connections : maskRecords(connections),
+                connections: mask ? await maskRecords(connections, mask) : connections,
                 adminLog,
                 data,
             };
@@ -2746,6 +2774,9 @@ export function createControlPlaneApi(options) {
             modules,
             doClasses: manifest.doClasses,
             bindings: [...manifest.bindings, ...storeBindings],
+            // #1054: the model runtime is bound only for a version that ASKED for it, so the
+            // capability is visible in the manifest diff at admit rather than fleet-wide.
+            ...(manifest.usesModels ? { usesModels: true } : {}),
             // #340/#578: the version's static files travel with it onto the serving script —
             // from the RETAINED manifest, with no bytes. The runtime's asset store dedupes
             // per SCRIPT (not namespace-wide — the #578 finding), so the serving script only
@@ -3602,8 +3633,10 @@ export function createControlPlaneApi(options) {
      *  hostname `<label>--<tag>.<domain>` bound to `previewId`. Non-canonical, so it never
      *  demotes the prod surface. Shared by the fork and clean-room paths. */
     const bindPreviewHostname = async (actor, baseHostname, tenantId, previewId, tag, surface) => {
-        const [label, ...rest] = baseHostname.split('.');
-        const hostname = `${label}--${tag}.${rest.join('.')}`;
+        const parsed = parseHostname(baseHostname);
+        if (!parsed)
+            throw new ControlPlaneError(400, `'${baseHostname}' is not a hostname a preview can be minted beside`);
+        const hostname = withLabel(parsed, `${parsed.label}${RESERVED_LABEL_SEPARATOR}${tag}`);
         const existing = (await admin.listHostnames(actor, { scopeId: previewId })).find((h) => h.hostname === hostname);
         if (!existing) {
             await admin.bindHostname(actor, {
@@ -3658,7 +3691,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const surface = opts.surface ?? 'app';
         // #527 guard: a preview MUST serve the version it just bound. Routing resolves
-        // `COALESCE(scope.servingRef, version.deploymentRef)` (control-plane-do `readHostname`),
+        // `COALESCE(scope.servingRef, version.deploymentRef)` (control-plane-do `readRoute`),
         // so a preview that still carries an inherited `serving_ref` — or otherwise resolves away
         // from this version's own dispatch script — would answer with OTHER code (the promoted
         // prod build) while we report success. That is worse than a failure: it sends a reviewer
@@ -3981,6 +4014,39 @@ export function createControlPlaneApi(options) {
         const entries = await admin.listOpsFailures(c.get('actor'), filter);
         return c.json(pageOf(entries, filter.limit, (e) => e.id));
     });
+    // -- model usage (#1054): meter 3, the one D-30 could not compute -------------
+    // The ledger the `model-usage` intents drain into. Staff-only: the tenant-facing
+    // read is the vertical's own usage screen over its metering engine; this is the
+    // platform's copy, the one an invoice reconciles against.
+    app.get('/model-usage', async (c) => {
+        const filter = modelUsageQuery.parse({
+            tenantId: c.req.query('tenantId'),
+            scopeId: c.req.query('scopeId'),
+            vertical: c.req.query('vertical'),
+            model: c.req.query('model'),
+            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.listModelUsage(c.get('actor'), filter);
+        return c.json(pageOf(entries, filter.limit, (e) => e.id));
+    });
+    // Folded per (tenant, vertical, model) with the platform's margin applied at read
+    // time. Nothing is stored by the read: D-30's "meter, don't bill" holds.
+    app.get('/model-usage/summary', async (c) => {
+        const q = modelUsageSummaryQuery.parse({
+            tenantId: c.req.query('tenantId'),
+            since: c.req.query('since'),
+            until: c.req.query('until'),
+        });
+        const now = new Date();
+        const since = q.since ?? new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString();
+        const until = q.until ?? now.toISOString();
+        const summary = await admin.summarizeModelUsage(c.get('actor'), { ...(q.tenantId ? { tenantId: q.tenantId } : {}), since, until }, options.modelMarginPercent ?? DEFAULT_MODEL_MARGIN_PERCENT);
+        return c.json(summary);
+    });
     return app;
 }
 //# sourceMappingURL=api.js.map