@substrat-run/control-plane-api 0.108.0 → 0.110.0

package/dist/api.d.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono';
+import { z } from '@substrat-run/contracts';
 import type { Connection, ConnectionActivity, ConnectionActivitySource, ConnectionCredential, ConnectionProbe, PlatformActorId } from '@substrat-run/contracts';
 import type { ScopeHost } from '@substrat-run/kernel';
 import type { PlatformActorAuth, BuilderAuth, Principal } from './auth.js';
@@ -288,6 +289,26 @@ type Vars = {
     actor: PlatformActorId;
     principal: Principal;
 };
+/**
+ * The K-35 denial-log filter (#867). Bounded by default like every other HTTP read
+ * here: the log's volume is attacker-influenceable by design (a probing client mints
+ * rows), so an unbounded `GET` is exactly the wrong default.
+ *
+ * The DECODER half of contracts' `denialFilterParams` (#971), and deliberately not the
+ * same schema: a query param arrives as a string, so `limit` is coerced here and given
+ * this route's own default, which the filter itself must not carry. What the two DO owe
+ * each other is the field set — Zod strips an unknown key, so a field added to the
+ * filter and sent by every client would be dropped here in silence. Exported (not from
+ * `index.ts` — this is not public surface) so `api.test.ts` can pin that.
+ */
+export declare const denialLogQuery: z.ZodObject<{
+    actor: z.ZodOptional<z.ZodString>;
+    permission: z.ZodOptional<z.ZodString>;
+    operation: z.ZodOptional<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+    until: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
 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":"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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, entityHistoryInput, 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 { 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';
@@ -248,8 +248,15 @@ const auditLogQuery = z.object({
  * The K-35 denial-log filter (#867). Bounded by default like every other HTTP read
  * here: the log's volume is attacker-influenceable by design (a probing client mints
  * rows), so an unbounded `GET` is exactly the wrong default.
+ *
+ * The DECODER half of contracts' `denialFilterParams` (#971), and deliberately not the
+ * same schema: a query param arrives as a string, so `limit` is coerced here and given
+ * this route's own default, which the filter itself must not carry. What the two DO owe
+ * each other is the field set — Zod strips an unknown key, so a field added to the
+ * filter and sent by every client would be dropped here in silence. Exported (not from
+ * `index.ts` — this is not public surface) so `api.test.ts` can pin that.
  */
-const denialLogQuery = z.object({
+export const denialLogQuery = z.object({
     actor: z.string().optional(),
     permission: z.string().optional(),
     operation: z.string().optional(),
@@ -491,6 +498,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') {
@@ -1519,6 +1533,29 @@ 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.
@@ -2849,6 +2886,39 @@ export function createControlPlaneApi(options) {
         // sibling route would cost a second full parse for a field sitting beside this one.
         return c.json({ schedules: parsed?.schedules ?? null, freshness: parsed?.freshness ?? null });
     });
+    /**
+     * The declared FLOW of one version (#1234): every event type its modules say they
+     * emit or consume, and the providers the vertical requires — the declared half of
+     * a declared-vs-observed finding.
+     *
+     * Its own route rather than a ride on `/model`, unlike freshness on `/schedules`:
+     * the model is the largest thing on a manifest, and the flow card needs none of it.
+     * `declaredEvents` is null for a version pushed before the field existed, which the
+     * caller must keep apart from a version that declares no events at all — the second
+     * is a finding, the first is nothing to say.
+     */
+    app.get('/verticals/:slug/versions/:id/flow', async (c) => {
+        const p = c.get('principal');
+        const slug = await resolveVerticalId(c, c.req.param('slug'));
+        if (p.kind === 'builder' && (await ownerOf(p.actor, slug)) !== p.tenantId) {
+            return c.json({ error: 'not found' }, 404);
+        }
+        const json = await admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
+        const parsed = json ? storedDeployManifest.parse(JSON.parse(json)) : null;
+        return c.json({
+            declaredEvents: parsed?.declaredEvents ?? null,
+            // Whether that surface is the whole declaration or a sample cut at the cap. The
+            // reader's "N of M checked" is a completeness claim, and it may not be made about
+            // a manifest that says it was truncated.
+            declaredEventsTruncated: parsed?.declaredEventsTruncated ?? false,
+            requires: parsed?.requires ?? [],
+            // The other two bands of the flow map (#1234), off the same parse. `schedules`
+            // also has its own route, which answers a different question — did the run
+            // happen — while this one wants the declaration as a node.
+            schedules: parsed?.schedules ?? [],
+            outbound: parsed?.outbound ?? [],
+        });
+    });
     app.get('/verticals/:slug/versions/:id/model', async (c) => {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
@@ -3597,6 +3667,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).
      *