@substrat-run/control-plane-api 0.107.0 → 0.109.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,5 +1,5 @@
 import { Hono } from 'hono';
-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, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, 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, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, createOrgInput, roleKey as roleKeySchema, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, 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 { attributeFailure } from './failure-attribution.js';
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { TENANT_HEADER } from './auth.js';
@@ -288,6 +288,32 @@ const issueStatusUpdate = z.object({
     fingerprint: z.string().min(1),
     status: issueStatusInput,
 });
+/**
+ * A TENANT-LEVEL role assignment under an addressed tenant (#1343) — which is
+ * what a team membership is, and all this surface does.
+ *
+ * `scopeId` is deliberately absent, and `.strict()` REFUSES one rather than
+ * stripping it. An earlier draft accepted a body `scopeId` and pinned only the
+ * tenant from the path, which pins nothing: `assignRole` addresses a scope DO
+ * directly when the node carries a scope (`writeScopeTuple` → `scopeStub(scopeId)`,
+ * no tenant cross-check anywhere below it), so a body naming another tenant's
+ * scope would have written a role tuple into it. Silently stripping the field
+ * would be almost as bad — a caller who believes they scoped an assignment and
+ * silently got a tenant-wide one is worse off than one who got a 400.
+ *
+ * If scope-level assignment is ever needed it wants its own route under
+ * `/tenants/:tenantId/scopes/:scopeId/role-assignments`, deriving the node from
+ * the PATH after `getScopeRecord(actor, tenantId, scopeId)` returns — the K-3
+ * cross-check every other scope-addressed route here already performs.
+ */
+const tenantRoleAssignmentBody = z
+    .object({
+    principalId: principalIdSchema,
+    roleKey: roleKeySchema,
+})
+    .strict();
+/** A new org under an addressed tenant (#1343) — `tenantId` comes from the path. */
+const tenantOrgBody = createOrgInput.omit({ tenantId: true });
 const sweepRunsQuery = z.object({
     kind: sweepRunKind.optional(),
     unit: z.string().optional(),
@@ -465,6 +491,13 @@ export function createControlPlaneApi(options) {
         // go. Tenant-narrowed in the handler (the forced-filter pattern); the allowlist
         // alone is not authz.
         { method: 'GET', re: /\/sweep-runs$/ },
+        // MY traffic and MY logs — the tenant grain (observability.md §3 view 4). The only
+        // observability routes a non-staff caller may reach, and safe to reach precisely
+        // because they are a different grain: their backends are keyed on the tenant, so
+        // there is no fleet-wide answer for a forgotten filter to fall back to. Narrowed in
+        // the handler by the forced-filter pattern; the allowlist alone is not authz.
+        { method: 'GET', re: /\/observability\/tenant-metrics$/ },
+        { method: 'GET', re: /\/observability\/tenant-logs$/ },
     ];
     app.use('*', async (c, next) => {
         if (c.get('principal').kind === 'builder') {
@@ -1493,6 +1526,49 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
+    // #1239: facets over one scope's outbox — narrow, group, count. Delegated like
+    // the history read below: through the vertical that holds the data when one
+    // resolves, the co-located host otherwise.
+    app.get('/tenants/:tenantId/scopes/:scopeId/facets', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const input = eventFacetInput.parse({
+            groupBy: c.req.query('field') !== undefined
+                ? { kind: 'payload', field: c.req.query('field') }
+                : { kind: c.req.query('groupBy') },
+            type: c.req.query('type') ?? undefined,
+            since: c.req.query('since') ?? undefined,
+            until: c.req.query('until') ?? undefined,
+            limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
+        });
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        const vertical = await verticalForScope(c, scope);
+        return c.json(vertical
+            ? await vertical.facetEvents(scopeId, input)
+            : await admin.facetEvents(c.get('actor'), tenantId, scopeId, input));
+    });
+    // #1235: one record's event history — the per-entity pivot of the audit spine.
+    // Delegated exactly like the table reads: through the vertical that holds the
+    // scope's data when one resolves, the co-located host otherwise.
+    app.get('/tenants/:tenantId/scopes/:scopeId/history', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const input = entityHistoryInput.parse({
+            entityType: c.req.query('entityType'),
+            entityId: c.req.query('entityId'),
+            limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
+            cursor: c.req.query('cursor') ?? undefined,
+        });
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        const vertical = await verticalForScope(c, scope);
+        return c.json(vertical
+            ? await vertical.entityHistory(scopeId, input)
+            : await admin.entityHistory(c.get('actor'), tenantId, scopeId, input));
+    });
     app.get('/tenants/:tenantId/scopes/:scopeId/tables/:table', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -3551,6 +3627,75 @@ export function createControlPlaneApi(options) {
         });
         return c.json(await options.observability.recentLogs(input));
     });
+    // -- the TENANT grain (observability.md §3 view 4, §4.2) -----------------------
+    //
+    // Everything above is script grain: one deployed unit, which serves every tenant that
+    // installed the vertical. Safe for staff and for the vertical's builder, forbidden to
+    // an installer — §3 is explicit that per-tenant numbers from script-grain data leak.
+    // These two routes are the other grain, and the difference is not a filter over the
+    // same data: they read the router's own tenant-stamped datapoints and the verticals'
+    // stamped log lines, which is the only place the tenant dimension exists at all.
+    //
+    // Unlike their neighbours these ARE in BUILDER_ROUTES, because the whole point is that
+    // an installer may read them — about themselves. The tenant comes from the principal
+    // for a builder and must be named explicitly by a staff/service caller: the
+    // `/service-refs` forced-filter pattern, for its reason, since answering fleet-wide on
+    // a forgotten parameter is the exact leak being closed here.
+    app.get('/observability/tenant-metrics', async (c) => {
+        if (!options.observability?.tenantMetrics) {
+            return c.json({ error: 'tenant-grain observability is not configured on this control plane' }, 501);
+        }
+        const p = c.get('principal');
+        const tenantId = p.kind === 'builder' ? p.tenantId : c.req.query('tenantId');
+        if (!tenantId)
+            throw new ControlPlaneError(400, 'tenantId is required');
+        const input = z
+            .object({
+            tenantId: tenantIdSchema,
+            // Narrowing WITHIN the tenant. Neither can widen the answer — the reader always
+            // applies the tenant predicate — so a foreign scope id yields zero rows rather
+            // than somebody else's, and needs no ownership check of its own to be safe.
+            scopeId: z.string().min(1).max(64).optional(),
+            vertical: z.string().min(1).max(200).optional(),
+            hours: z.coerce.number().int().min(1).max(72).default(24),
+        })
+            .parse({
+            tenantId,
+            scopeId: c.req.query('scopeId') || undefined,
+            vertical: c.req.query('vertical') || undefined,
+            hours: c.req.query('hours'),
+        });
+        return c.json(await options.observability.tenantMetrics(input));
+    });
+    app.get('/observability/tenant-logs', async (c) => {
+        if (!options.observability?.tenantLogs) {
+            return c.json({ error: 'tenant-grain observability is not configured on this control plane' }, 501);
+        }
+        const p = c.get('principal');
+        const tenantId = p.kind === 'builder' ? p.tenantId : c.req.query('tenantId');
+        if (!tenantId)
+            throw new ControlPlaneError(400, 'tenantId is required');
+        const input = z
+            .object({
+            tenantId: tenantIdSchema,
+            scopeId: z.string().min(1).max(64).optional(),
+            vertical: z.string().min(1).max(200).optional(),
+            level: z.enum(['log', 'info', 'warn', 'error', 'debug']).optional(),
+            search: z.string().min(1).max(200).optional(),
+            hours: z.coerce.number().int().min(1).max(72).default(24),
+            limit: z.coerce.number().int().min(1).max(200).default(100),
+        })
+            .parse({
+            tenantId,
+            scopeId: c.req.query('scopeId') || undefined,
+            vertical: c.req.query('vertical') || undefined,
+            level: c.req.query('level') || undefined,
+            search: c.req.query('search') || undefined,
+            hours: c.req.query('hours'),
+            limit: c.req.query('limit'),
+        });
+        return c.json(await options.observability.tenantLogs(input));
+    });
     /**
      * Observed-vs-declared outbound egress for a vertical's deployed versions (#859, D-46).
      *
@@ -3901,7 +4046,7 @@ export function createControlPlaneApi(options) {
             throw new ControlPlaneError(409, `no platform base domain configured — a clean-room preview has no source URL to derive from`);
         }
         // Mint under `<label>.<jurisdiction>.<baseDomain>`, exactly as provisioning does
-        // (provision.ts `bindDefaultHostname` → `egeryds.global.substrat.run`). A clean-room
+        // (provision.ts `bindDefaultHostname` → `acme.global.substrat.run`). A clean-room
         // preview scope is provisioned `global` by construction (see the caller), and the
         // wildcard DNS/cert lives on `*.global.substrat.run` — NOT the certless apex
         // `*.substrat.run`. `platformBaseDomains` lists every platform suffix for custom-hostname
@@ -4204,6 +4349,59 @@ export function createControlPlaneApi(options) {
         // cursor shape (scope-host.ts listRoles).
         return c.json(pageOf(entries, page.limit, (r) => `${r.tenantId}|${r.key}`));
     });
+    // -- role ASSIGNMENTS, and orgs (#1343) ------------------------------------
+    //
+    // The line these sit on the far side of, and why. `defineRole` says what a role
+    // MEANS — a permission change, and the permission diff is a human checkpoint
+    // (D-22/D-29). It still gets no route, for the reason stated above the read.
+    // ASSIGNING an already-defined role is a different act: per-principal, runtime,
+    // and the same shape as the entity grants control-plane.md §4.5 already calls a
+    // runtime console concern rather than a checkpoint artifact. `unassignRole`'s own
+    // contract anticipates this caller — "decided above the kernel (e.g. the
+    // dashboard's manage-members check)".
+    //
+    // Service/staff only, absent from BUILDER_ROUTES: a builder must no more be able
+    // to assign itself a role than to write the directory that authenticates it.
+    // Fail-closed, same law as the identity mirror. TENANT-LEVEL only — see the
+    // body schema for why a scope cannot be named here.
+    app.post('/tenants/:tenantId/role-assignments', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const body = tenantRoleAssignmentBody.parse(await c.req.json());
+        // The whole node comes from the path. Pinning only the tenant would pin
+        // nothing — see the schema's note: a node carrying a scope is written to that
+        // scope's DO directly, with no tenant cross-check below.
+        await admin.assignRole(c.get('actor'), {
+            principalId: body.principalId,
+            roleKey: body.roleKey,
+            node: { tenantId, scopeId: null },
+        });
+        return c.body(null, 204);
+    });
+    app.delete('/tenants/:tenantId/role-assignments', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const body = tenantRoleAssignmentBody.parse(await c.req.json());
+        // Tombstones rather than deletes (K-21) and is idempotent — unassigning what
+        // was never assigned is a silent no-op, so a retry is safe. Node from the
+        // path, for the same reason as the assign above.
+        await admin.unassignRole(c.get('actor'), {
+            principalId: body.principalId,
+            roleKey: body.roleKey,
+            node: { tenantId, scopeId: null },
+        });
+        return c.body(null, 204);
+    });
+    // Orgs: the portal-customer grouping (§4.1). Creating one mints no permission —
+    // members reach what the org was GRANTED, and granting stays off this surface.
+    app.post('/tenants/:tenantId/orgs', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const body = tenantOrgBody.parse(await c.req.json());
+        await admin.createOrg(c.get('actor'), { ...body, tenantId });
+        return c.body(null, 201);
+    });
+    app.get('/tenants/:tenantId/orgs', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        return c.json(await admin.listOrgs(c.get('actor'), tenantId));
+    });
     // -- the admin log (§4.4/§4.5) ---------------------------------------------
     app.get('/admin-log', async (c) => {
         const filter = auditLogQuery.parse({