@substrat-run/control-plane-api 0.138.0 → 0.140.0

package/dist/api.js

@@ -1,15 +1,16 @@
 import { resolveObservabilityWindow } from './observability-window.js';
 import { Hono } from 'hono';
-import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ownerTransferInput, OWNER_TRANSFER_AUDIT_ERROR_MAX, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, platformScriptCollision, platformScriptRefusal, PLATFORM_SCRIPT_NAMES, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, errorCodeOf, capabilityFilterQuery, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, } from '@substrat-run/contracts';
+import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ownerTransferInput, memberInviteInput, memberRoleInput, ASSET_PART_PREFIX, assetHash, channelName, connectLinkId, connectionActivity, connectionActivitySource, connectionCredential, connectionCertificate, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, findingKind, findingRuleInput, findingStatus, findingStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, verticalSlug, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, platformScriptCollision, platformScriptRefusal, PLATFORM_SCRIPT_NAMES, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, errorCodeOf, capabilityFilterQuery, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, } from '@substrat-run/contracts';
 import { attributeFailure } from './failure-attribution.js';
-import { BIND_EXPORT_BREAK_REFUSAL, CARRIED_AWAY_KEY, bindExportBreakRefusal, carriedAwayDump, dumpMetaValue, metaValueIn, crossVerticalHealth, exportBreakRefusal, isBindExportBreakRefusal, isExportBreakRefusal, isPrimaryScope, migrationProgress, ulid, } from '@substrat-run/kernel';
+import { auditedChange, withAuditedOutcomes } from './audited-change.js';
+import { BIND_EXPORT_BREAK_REFUSAL, CARRIED_AWAY_KEY, bindExportBreakRefusal, carriedAwayDump, dumpMetaValue, metaValueIn, crossVerticalHealth, exportBreakRefusal, isBindExportBreakRefusal, isExportBreakRefusal, isPrimaryScope, migrationProgress, ulid, auditWarningOf, } from '@substrat-run/kernel';
 import { TENANT_HEADER, confinedTenant } from './auth.js';
 import { mintTenantToken } from './tenant-token.js';
 import { connectionGrantsForScope } from './vertical-client.js';
 import { oidcCallbackUrl, retireClientsOfReapedScope, wirePreviewAuth } from './preview-auth.js';
 import { versionReachedAt } from './scope-deployment.js';
 import { reconcileConnectionGrants } from './connection-grants.js';
-import { reconcileThenReassert, switchCarryFor } from './reconcile.js';
+import { reconcileThenReassert, reviewedEntityGrants, switchCarryFor } from './reconcile.js';
 import { ConnectionRelayError, relayConnectionUpsert } from './connection-relay.js';
 import { ControlPlaneError } from '@substrat-run/control-plane-client';
 import { provisionSiblingScope } from './platform-drain.js';
@@ -478,6 +479,22 @@ const issueStatusUpdate = z.object({
     fingerprint: z.string().min(1),
     status: issueStatusInput,
 });
+// The findings read (#1748). No cursor, for the issues read's reason: the cardinality is the
+// number of distinct shapes a tenant has. `tenantId` is forced for a confined principal.
+const findingsQuery = z.object({
+    tenantId: tenantIdSchema.optional(),
+    status: findingStatus.optional(),
+    kind: findingKind.optional(),
+    limit: z.coerce.number().int().min(1).max(500).optional(),
+});
+const findingStatusUpdate = z.object({ status: findingStatusInput }).strict();
+const findingRulesQuery = z.object({
+    active: z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((v) => v === 'true'),
+    limit: z.coerce.number().int().min(1).max(500).optional(),
+});
 /**
  * A TENANT-LEVEL role assignment under an addressed tenant (#1343) — which is
  * what a team membership is, and all this surface does.
@@ -579,7 +596,16 @@ const TENANT_ROUTES = [
     { method: 'DELETE', re: /\/tenants\/[^/]+\/connections\/[^/]+$/, pin: 'path' },
     { method: 'GET', re: /\/tenants\/[^/]+\/connections\/[^/]+\/activity$/, pin: 'path' },
     { method: 'GET', re: /\/tenants\/[^/]+\/connections\/[^/]+\/credential$/, pin: 'path' },
+    // #2100: the PUBLIC certificate a connection signs in with — same pin as the credential view.
+    { method: 'GET', re: /\/tenants\/[^/]+\/connections\/[^/]+\/certificate$/, pin: 'path' },
     { method: 'POST', re: /\/tenants\/[^/]+\/connections\/[^/]+\/verify$/, pin: 'path' },
+    // A vertical's mailed connect links (connections.md §3.5.4): the consent landing's liveness
+    // read, the callback's spend and its undo, and the integrations card's list and revoke.
+    { method: 'GET', re: /\/tenants\/[^/]+\/connect-links$/, pin: 'path' },
+    { method: 'GET', re: /\/tenants\/[^/]+\/connect-links\/[^/]+$/, pin: 'path' },
+    { method: 'POST', re: /\/tenants\/[^/]+\/connect-links\/[^/]+\/consume$/, pin: 'path' },
+    { method: 'POST', re: /\/tenants\/[^/]+\/connect-links\/[^/]+\/restore$/, pin: 'path' },
+    { method: 'DELETE', re: /\/tenants\/[^/]+\/connect-links\/[^/]+$/, pin: 'path' },
     // Members: identity links mirrored from the dashboard, orgs, role assignments.
     { method: 'GET', re: /\/tenants\/[^/]+\/identities$/, pin: 'path' },
     { method: 'PUT', re: /\/tenants\/[^/]+\/identities$/, pin: 'path' },
@@ -592,6 +618,12 @@ const TENANT_ROUTES = [
     // grant (`tenantGrantableEntitlement`): the pin alone would let it grant itself any.
     { method: 'PUT', re: /\/tenants\/[^/]+\/entitlements\/[^/]+$/, pin: 'path' },
     { method: 'GET', re: /\/tenants\/[^/]+\/cross-vertical\/edges$/, pin: 'path' },
+    // Findings (#1748): the tenant's inbox, its verdicts and its suppress rules. The dashboard
+    // checks WHO inside the tenant may read or act (its findings permissions) before calling.
+    { method: 'PUT', re: /\/tenants\/[^/]+\/findings\/[^/]+\/status$/, pin: 'path' },
+    { method: 'GET', re: /\/tenants\/[^/]+\/finding-rules$/, pin: 'path' },
+    { method: 'POST', re: /\/tenants\/[^/]+\/finding-rules$/, pin: 'path' },
+    { method: 'DELETE', re: /\/tenants\/[^/]+\/finding-rules\/[^/]+$/, pin: 'path' },
     // Scopes: provision, read, and the lifecycle acts the Data and Deployments tabs offer.
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes$/, pin: 'path' },
     { method: 'GET', re: /\/tenants\/[^/]+\/scopes\/[^/]+$/, pin: 'path' },
@@ -611,6 +643,8 @@ const TENANT_ROUTES = [
     { method: 'GET', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/migrations$/, pin: 'path' },
     { method: 'GET', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/owner-seat$/, pin: 'path' },
     { method: 'GET', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/peer-grants$/, pin: 'path' },
+    { method: 'GET', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/peer-bindings$/, pin: 'path' },
+    { method: 'PUT', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/peer-bindings$/, pin: 'path' },
     // The peer switch (#1706): on is POST, off is DELETE, on the tenant's own scope.
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/peer-grants$/, pin: 'path' },
     { method: 'DELETE', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/peer-grants$/, pin: 'path' },
@@ -624,6 +658,11 @@ const TENANT_ROUTES = [
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/lifecycle-flow$/, pin: 'path' },
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/operation-series$/, pin: 'path' },
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/owner-claim$/, pin: 'path' },
+    // An installed vertical's members (#1150): the roster, an invite, a role move, a removal.
+    { method: 'GET', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/members$/, pin: 'path' },
+    { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/members$/, pin: 'path' },
+    { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/members\/[^/]+\/role$/, pin: 'path' },
+    { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/members\/[^/]+\/remove$/, pin: 'path' },
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/query$/, pin: 'path' },
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/reap$/, pin: 'path' },
     { method: 'POST', re: /\/tenants\/[^/]+\/scopes\/[^/]+\/rebind-vertical$/, pin: 'path' },
@@ -652,6 +691,7 @@ const TENANT_ROUTES = [
     { method: 'GET', re: /\/admin-log$/, pin: 'query' },
     { method: 'GET', re: /\/ops-failures$/, pin: 'query' },
     { method: 'GET', re: /\/sweep-runs$/, pin: 'query' },
+    { method: 'GET', re: /\/findings$/, pin: 'query' },
     { method: 'GET', re: /\/service-refs$/, pin: 'query' },
     { method: 'GET', re: /\/observability\/tenant-metrics$/, pin: 'query' },
     { method: 'GET', re: /\/observability\/tenant-metrics-series$/, pin: 'query' },
@@ -1560,7 +1600,7 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'body tenantId disagrees with the route tenant' }, 400);
         }
         try {
-            return c.json(await relayConnectionUpsert(c.var.host, c.get('actor'), { ...body, tenantId }, { probeCandidate }));
+            return c.json(await relayConnectionUpsert(c.var.host, c.get('actor'), { ...body, tenantId }, { probeCandidate, prepareCandidate }));
         }
         catch (err) {
             if (err instanceof ConnectionRelayError && err.status < 500) {
@@ -1590,6 +1630,80 @@ export function createControlPlaneApi(options) {
             await c.var.admin.revokeConnection(c.get('actor'), row.id);
         return c.body(null, 204);
     });
+    // -- a vertical's mailed connect links, tenant-scoped (connections.md §3.5.4) ---------
+    //
+    // The dashboard's half of a link a VERTICAL minted (`/internal/connections/connect-links`):
+    // its consent landing asks whether the row still stands, its callback spends the row
+    // before storing and restores it if the store fails, and its integrations card lists and
+    // revokes them. The tenant is the path's; the scope is named on every call and is half
+    // the store's key, so another scope's link — or another tenant's — reads as absent (K-3).
+    // Not in BUILDER_ROUTES: a builder has no business spending a tenant's consent round.
+    const connectLinkScope = z.object({ scopeId: scopeIdSchema });
+    app.get('/tenants/:tenantId/connect-links', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const q = connectLinkScope
+            .extend({ provider: connectionProvider.optional(), outstanding: z.literal('1').optional() })
+            .parse({
+            scopeId: c.req.query('scopeId'),
+            provider: c.req.query('provider') || undefined,
+            outstanding: c.req.query('outstanding') || undefined,
+        });
+        return c.json(await c.var.admin.listConnectLinks(c.get('actor'), {
+            tenantId,
+            scopeId: q.scopeId,
+            ...(q.provider ? { provider: q.provider } : {}),
+            ...(q.outstanding ? { outstandingOnly: true } : {}),
+        }));
+    });
+    app.get('/tenants/:tenantId/connect-links/:linkId', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const { scopeId } = connectLinkScope.parse({ scopeId: c.req.query('scopeId') });
+        const link = await c.var.admin.getConnectLink(c.get('actor'), {
+            tenantId,
+            scopeId,
+            id: connectLinkId.parse(c.req.param('linkId')),
+        });
+        return link ? c.json(link) : c.json({ error: 'unknown connect link' }, 404);
+    });
+    // The callback's spend. A refusal is a 200 carrying the typed reason, not an error status:
+    // "already used" is the answer to the question asked, and the callback renders each one.
+    app.post('/tenants/:tenantId/connect-links/:linkId/consume', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const body = connectLinkScope
+            .extend({
+            provider: connectionProvider,
+            accountRef: z.string().max(256).optional(),
+            accountLabel: z.string().max(256).optional(),
+        })
+            .parse(await c.req.json());
+        return c.json(await c.var.admin.consumeConnectLink(c.get('actor'), {
+            ...body,
+            tenantId,
+            id: connectLinkId.parse(c.req.param('linkId')),
+        }));
+    });
+    app.post('/tenants/:tenantId/connect-links/:linkId/restore', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const { scopeId } = connectLinkScope.parse(await c.req.json());
+        const restored = await c.var.admin.restoreConnectLink(c.get('actor'), {
+            tenantId,
+            scopeId,
+            id: connectLinkId.parse(c.req.param('linkId')),
+        });
+        return c.json({ restored });
+    });
+    // Idempotent, as the store is: a revoked or spent link answers 204 again. 404 only for a
+    // link this scope never held.
+    app.delete('/tenants/:tenantId/connect-links/:linkId', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const { scopeId } = connectLinkScope.parse({ scopeId: c.req.query('scopeId') });
+        const link = await c.var.admin.revokeConnectLink(c.get('actor'), {
+            tenantId,
+            scopeId,
+            id: connectLinkId.parse(c.req.param('linkId')),
+        });
+        return link ? c.body(null, 204) : c.json({ error: 'unknown connect link' }, 404);
+    });
     /**
      * The tenant-scoped connection lookup the two inspection routes share. Same K-3
      * existence hiding as the revoke above — a foreign tenant's connection id reads
@@ -1602,6 +1716,8 @@ export function createControlPlaneApi(options) {
      * in which case the upsert behaves exactly as it always did, storing unverified.
      */
     const probeCandidate = async (provider, secret) => options.connectionInspectors?.[provider]?.probeCandidate?.(secret);
+    /** #2100: the provider's own half of a credential, made before the probe sees it. */
+    const prepareCandidate = (provider) => options.connectionInspectors?.[provider]?.prepareCandidate;
     const inspectableConnection = async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const id = c.req.param('id');
@@ -1675,6 +1791,20 @@ export function createControlPlaneApi(options) {
         }
         return c.json(connectionCredential.parse(await credential(c.var.host, row)));
     });
+    /**
+     * The public certificate a connection signs in with (#2100) — what the tenant downloads and
+     * uploads to the provider. Public by construction: the private key never leaves the sealed
+     * credential, and only a provider whose keypair the platform generates has one at all.
+     */
+    app.get('/tenants/:tenantId/connections/:id/certificate', async (c) => {
+        const row = await inspectableConnection(c);
+        if (!row)
+            return c.json({ error: 'unknown connection' }, 404);
+        const certificate = await options.connectionInspectors?.[row.provider]?.certificate?.(c.var.host, row);
+        if (!certificate)
+            return c.json({ error: 'this connection signs in with no certificate' }, 404);
+        return c.json(connectionCertificate.parse(certificate));
+    });
     // -- the scope directory (§3.2/§4.2) ---------------------------------------
     app.get('/scopes', async (c) => {
         const p = c.get('principal');
@@ -2797,6 +2927,9 @@ export function createControlPlaneApi(options) {
             ? await c.var.admin.verticalServing(actor, scope.vertical).catch(() => null)
             : null;
         const ranAs = versionReachedAt(reached.via, scope, serving);
+        // #2071: the shapes this reconcile tops holders up to, from the reviewed registry of the
+        // version it reaches — never anything the vertical's own code names.
+        const entityGrants = scope.vertical && ranAs ? await reviewedEntityGrants(c.var.admin, actor, scope.vertical, ranAs) : undefined;
         try {
             // #1674: the recorded OFF positions go back after the reconcile, before the receipt.
             const result = await reconcileThenReassert(c.var.admin, actor, { tenantId, scopeId }, (carry) => vertical.reconcileInstance({
@@ -2806,6 +2939,7 @@ export function createControlPlaneApi(options) {
                 identityLinks,
                 connectionGrants,
                 connectionKeys,
+                ...(entityGrants ? { entityGrants } : {}),
                 ...carry,
                 // Handed over exactly as at provision: a store minted HERE has never been migrated
                 // by the vertical, so the reconcile must carry it into the same ready-gate — a bound
@@ -3158,6 +3292,19 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
+    /**
+     * The address a link into an instance opens on: the scope's canonical `app` hostname,
+     * preferring one the platform has activated but not requiring it — a platform hostname is
+     * bound `pending` and activated a step later, and that step can fail while the app is fully
+     * reachable (#294). `failed` is the one state that never routes, so only it is skipped. The
+     * platform owns the hostname directory, so the origin is never taken from a body.
+     */
+    const instanceOrigin = async (admin, actor, scopeId) => {
+        const bound = (await admin.listHostnames(actor, { scopeId })).filter((h) => h.status !== 'failed');
+        const pick = (hs) => hs.find((h) => h.surface === 'app' && h.canonical) ?? hs.find((h) => h.surface === 'app') ?? hs[0];
+        const host = pick(bound.filter((h) => h.status === 'active')) ?? pick(bound);
+        return host ? `https://${host.hostname}` : null;
+    };
     app.post('/tenants/:tenantId/scopes/:scopeId/owner-claim', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -3172,18 +3319,97 @@ export function createControlPlaneApi(options) {
         const vertical = await verticalForScope(c, scope);
         if (!vertical)
             return c.json({ error: await diagnoseUnboundScope(actor, scope) }, 501);
-        // The address the link opens on: the scope's canonical `app` hostname, preferring one
-        // the platform has activated but not requiring it — a platform hostname is bound
-        // `pending` and activated a step later, and that step can fail while the app is fully
-        // reachable (#294). `failed` is the one state that never routes, so only it is skipped.
-        const bound = (await c.var.admin.listHostnames(actor, { scopeId })).filter((h) => h.status !== 'failed');
-        const pick = (hs) => hs.find((h) => h.surface === 'app' && h.canonical) ?? hs.find((h) => h.surface === 'app') ?? hs[0];
-        const host = pick(bound.filter((h) => h.status === 'active')) ?? pick(bound);
-        if (!host) {
+        const origin = await instanceOrigin(c.var.admin, actor, scopeId);
+        if (!origin) {
             return c.json({ error: `scope ${scopeId} has no hostname bound — a claim link needs an address to open on` }, 409);
         }
         try {
-            return c.json(await vertical.mintOwnerClaim({ tenantId, scopeId, origin: `https://${host.hostname}`, actor }), 201);
+            return c.json(await vertical.mintOwnerClaim({ tenantId, scopeId, origin, actor }), 201);
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError)
+                return c.json({ error: e.message }, e.status);
+            throw e;
+        }
+    });
+    // An installed vertical's MEMBERS (#1150) — the dashboard's Members section. The roster and
+    // every change live in the VERTICAL (its scope's role tuples, its identity directory), so each
+    // route makes the same K-3 cross-check as the owner seat and then asks the deployment that
+    // holds the scope. One scope per call: no walk across scopes (#1581).
+    //
+    // **Who is acting is the credential's person, and only that.** Every change is bounded in the
+    // vertical by the K-21 set comparison at the vertical's scope, asked about a principal — and
+    // the one principal this plane can vouch for is the `onBehalfOf` the dashboard's tenant token
+    // carries (#977), which only the staff mint writes. A builder session, a staff token or a
+    // tenant token minted for nobody names no person, so the writes refuse it rather than
+    // borrowing an authority it does not have. Being a tenant (dashboard) admin confers nothing in
+    // the vertical's scope: what the person holds THERE is what bounds them.
+    //
+    // Every change is audited intent-first then outcome (`manageScopeMember`), like the hand-over.
+    const memberPerson = (p) => p.kind === 'tenant' && p.onBehalfOf ? p.onBehalfOf.principal : null;
+    /** The scope, its vertical and the acting person, or the answer that refuses the request. */
+    const memberTarget = async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const principal = c.get('principal');
+        const actor = c.get('actor');
+        // K-3: another tenant's pair, or no such scope, reads the same — absent.
+        const scope = outsideTenant(principal, tenantId) ? null : await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!scope)
+            return { refusal: c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404) };
+        const vertical = await verticalForScope(c, scope);
+        if (!vertical)
+            return { refusal: c.json({ error: await diagnoseUnboundScope(actor, scope) }, 501) };
+        return { tenantId, scopeId, actor, vertical, person: memberPerson(principal) };
+    };
+    /**
+     * Answer for one `auditedChange` (#2064). A refusal or failure answers with the vertical's own
+     * status (a non-`ControlPlaneError` throw is rethrown). A change that went through answers
+     * `ok`, with its `operationId`, whether or not its outcome row could be written. When it could
+     * not, the answer also carries `auditWarning`, which says so. That is a success on purpose:
+     * the change happened, so no client should read a retryable error and make it twice (a second
+     * invite, a second hand-over). The missing row is logged, and the scheduled settle closes it.
+     */
+    const auditedAnswer = (c, done, what, ok) => {
+        const { operationId } = done;
+        if ('error' in done) {
+            if (done.error instanceof ControlPlaneError) {
+                return c.json({ error: done.error.message, operationId }, done.error.status);
+            }
+            throw done.error;
+        }
+        if ('unrecorded' in done) {
+            return ok(done.result, {
+                operationId,
+                auditWarning: auditWarningOf(what, done.unrecorded),
+            });
+        }
+        return ok(done.result, { operationId });
+    };
+    /** Run one audited member change: intent, the vertical's call, then the outcome row. */
+    const auditedMemberChange = (c, entry, run, applied) => {
+        const actor = c.get('actor');
+        const operationId = ulid();
+        return auditedChange({
+            flow: 'member-change',
+            operationId,
+            run,
+            // A 4xx is the vertical's refusal: nothing was written there.
+            refused: (e) => e instanceof ControlPlaneError && e.status < 500,
+            record: (row) => c.var.admin.recordMemberChange(actor, {
+                ...entry,
+                operationId,
+                ...(row.phase === 'applied' ? { phase: 'applied', ...applied(row.result) } : row),
+            }),
+        });
+    };
+    const NO_PERSON = 'a member change needs the signed-in person it is made for — this credential names nobody';
+    app.get('/tenants/:tenantId/scopes/:scopeId/members', async (c) => {
+        const target = await memberTarget(c);
+        if ('refusal' in target)
+            return target.refusal;
+        try {
+            return c.json(await target.vertical.listMembers(target.tenantId, target.scopeId));
         }
         catch (e) {
             if (e instanceof ControlPlaneError)
@@ -3191,6 +3417,44 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
+    app.post('/tenants/:tenantId/scopes/:scopeId/members', async (c) => {
+        const target = await memberTarget(c);
+        if ('refusal' in target)
+            return target.refusal;
+        if (!target.person)
+            return c.json({ error: NO_PERSON }, 403);
+        const body = memberInviteInput.parse(await c.req.json());
+        const origin = await instanceOrigin(c.var.admin, target.actor, target.scopeId);
+        if (!origin) {
+            return c.json({ error: `scope ${target.scopeId} has no hostname bound — an invite link needs an address to open on` }, 409);
+        }
+        const { tenantId, scopeId, person } = target;
+        const done = await auditedMemberChange(c, { tenantId, scopeId, change: 'invite', caller: person, roleKey: body.roleKey }, () => target.vertical.inviteMember({ tenantId, scopeId, caller: person, origin, roleKey: body.roleKey, email: body.email ?? null }), (link) => ({ principal: link.principal }));
+        return auditedAnswer(c, done, 'the invite', (link, audit) => c.json({ ...link, ...audit }, 201));
+    });
+    app.post('/tenants/:tenantId/scopes/:scopeId/members/:principal/role', async (c) => {
+        const target = await memberTarget(c);
+        if ('refusal' in target)
+            return target.refusal;
+        if (!target.person)
+            return c.json({ error: NO_PERSON }, 403);
+        const member = principalIdSchema.parse(c.req.param('principal'));
+        const body = memberRoleInput.parse(await c.req.json());
+        const { tenantId, scopeId, person } = target;
+        const done = await auditedMemberChange(c, { tenantId, scopeId, change: 'role', caller: person, principal: member, from: body.from, to: body.to }, () => target.vertical.changeMemberRole({ tenantId, scopeId, caller: person, principal: member, from: body.from, to: body.to }), () => ({}));
+        return auditedAnswer(c, done, 'the role change', (_, audit) => c.json({ principal: member, from: body.from, to: body.to, ...audit }));
+    });
+    app.post('/tenants/:tenantId/scopes/:scopeId/members/:principal/remove', async (c) => {
+        const target = await memberTarget(c);
+        if ('refusal' in target)
+            return target.refusal;
+        if (!target.person)
+            return c.json({ error: NO_PERSON }, 403);
+        const member = principalIdSchema.parse(c.req.param('principal'));
+        const { tenantId, scopeId, person } = target;
+        const done = await auditedMemberChange(c, { tenantId, scopeId, change: 'remove', caller: person, principal: member }, () => target.vertical.removeMember({ tenantId, scopeId, caller: person, principal: member }), (removal) => ({ revoked: removal.revoked }));
+        return auditedAnswer(c, done, 'the removal', (removal, audit) => c.json({ ...removal, ...audit }));
+    });
     // The owner HAND-OVER (#1665). The move runs in the VERTICAL, behind `/internal/owner-transfer`
     // (vertical-host says in what order and why). This route decides who may ask, and audits every
     // attempt: an `intent` row before the vertical is reached, so a row the log cannot take means
@@ -3220,41 +3484,19 @@ export function createControlPlaneApi(options) {
         // An abandon (`abandon: true`) is audited the same way, every row marked, so the log tells
         // a hand-over closed without finishing from one that finished.
         const base = { tenantId, scopeId, operationId, from: body.from, to: body.to, ...(body.abandon ? { abandon: true } : {}) };
-        await c.var.admin.recordOwnerTransfer(actor, { ...base, phase: 'intent' });
-        let moved;
-        try {
-            moved = await vertical.transferOwner({ tenantId, scopeId, ...body });
-        }
-        catch (e) {
-            const refused = e instanceof ControlPlaneError && e.status === 409;
-            const error = (e instanceof Error ? e.message : String(e)).slice(0, OWNER_TRANSFER_AUDIT_ERROR_MAX);
-            await c.var.admin
-                .recordOwnerTransfer(actor, { ...base, phase: refused ? 'refused' : 'failed', error })
-                .catch(() => undefined);
-            if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message, operationId }, e.status);
-            }
-            throw e;
-        }
-        try {
-            await c.var.admin.recordOwnerTransfer(actor, {
-                ...base,
-                phase: 'applied',
-                outcome: moved.outcome,
-                fromRevoked: moved.fromRevoked,
-            });
-        }
-        catch (e) {
-            // The owner HAS moved; only the outcome row is missing. Say exactly that, so nobody retries
-            // a hand-over believing it failed, and name the operation whose intent row stands alone.
-            const why = e instanceof Error ? e.message : String(e);
-            return c.json({
-                error: `the hand-over completed, but its outcome could not be written to the admin log: ${why}`,
-                operationId,
-                ...moved,
-            }, 500);
-        }
-        return c.json({ operationId, ...moved });
+        const done = await auditedChange({
+            flow: 'owner-transfer',
+            operationId,
+            run: () => vertical.transferOwner({ tenantId, scopeId, ...body }),
+            // Only the vertical's 409 is a refusal: anything else may have stopped part-way.
+            refused: (e) => e instanceof ControlPlaneError && e.status === 409,
+            record: (row) => c.var.admin.recordOwnerTransfer(actor, row.phase === 'applied'
+                ? { ...base, phase: 'applied', outcome: row.result.outcome, fromRevoked: row.result.fromRevoked }
+                : { ...base, ...row }),
+        });
+        // A missing outcome row is said in `auditWarning` on a success, so nobody retries a hand-over
+        // believing it failed, under the operation whose intent row stands alone.
+        return auditedAnswer(c, done, 'the hand-over', (moved, audit) => c.json({ ...audit, ...moved }));
     });
     // Deliver per-instance CONFIG to the scope's own storage (vertical-auth-detach.md
     // §2.2) — the missing "delivery" step behind the dashboard's Env tab. Same K-3
@@ -6084,6 +6326,9 @@ export function createControlPlaneApi(options) {
             // `emailSender` grant itself is never touched by a push. Refreshes on every re-push
             // like the rest of the install spec, exactly because it grants nothing.
             ...(manifest.sendsEmail ? { sendsEmail: true } : {}),
+            // Where the scope lifecycle is held (#1713): `'router'` keeps the vertical's scopes out of
+            // the lifecycle delivery. Refreshes on every re-push like the rest of the install spec.
+            ...(manifest.lifecycle ? { lifecycle: manifest.lifecycle } : {}),
             // The declared surfaces (K-26) ride like envSpec: registry metadata for the
             // hostname-binding picker, never behavior. Not part of any admission digest.
             ...(manifest.surfaces ? { surfaces: manifest.surfaces } : {}),
@@ -7527,6 +7772,56 @@ export function createControlPlaneApi(options) {
         }
         return c.json(await c.var.admin.peerGrantsStatus(actor, { tenantId, scopeId }));
     });
+    // #1720: a caller's explicit target is a tenant decision. The dashboard checks its own
+    // app-management permission; this route confines the tenant and both directory endpoints.
+    const peerBindingBody = z.object({ vertical: verticalSlug, targetScopeId: scopeIdSchema.nullable() }).strict();
+    app.get('/tenants/:tenantId/scopes/:scopeId/peer-bindings', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const vertical = c.req.query('vertical');
+        const pin = confinedTenant(c.get('principal'));
+        if (pin !== null && pin !== tenantId)
+            return c.json({ error: 'forbidden' }, 403);
+        const actor = c.get('actor');
+        if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId)))
+            return c.json({ error: 'app not found' }, 404);
+        return c.json(vertical === undefined
+            ? await c.var.admin.peerBindings(actor, tenantId, scopeId)
+            : await c.var.admin.peerBinding(actor, tenantId, scopeId, verticalSlug.parse(vertical)) ?? null);
+    });
+    app.put('/tenants/:tenantId/scopes/:scopeId/peer-bindings', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const pin = confinedTenant(c.get('principal'));
+        // The target choice is the tenant's alone. Staff may inspect it through GET, but cannot
+        // choose a tenant's site on its behalf.
+        if (pin !== tenantId)
+            return c.json({ error: 'forbidden' }, 403);
+        const body = peerBindingBody.parse(await c.req.json());
+        const actor = c.get('actor');
+        if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId)))
+            return c.json({ error: 'app not found' }, 404);
+        const operationId = ulid();
+        const base = { tenantId, scopeId, operationId, vertical: body.vertical, targetScopeId: body.targetScopeId };
+        const done = await auditedChange({
+            flow: 'peer-binding', operationId,
+            run: async () => {
+                try {
+                    return await c.var.admin.setPeerBinding(actor, tenantId, scopeId, body.vertical, body.targetScopeId);
+                }
+                catch (e) {
+                    if (errorCodeOf(e) === 'not_found')
+                        throw new ControlPlaneError(404, e instanceof Error ? e.message : String(e));
+                    throw e;
+                }
+            },
+            refused: (e) => e instanceof ControlPlaneError && e.status < 500,
+            record: (row) => c.var.admin.recordPeerBindingChange(actor, row.phase === 'applied'
+                ? { ...base, phase: 'applied', changed: row.result.changed, previousScopeId: row.result.previous }
+                : { ...base, ...row }),
+        });
+        return auditedAnswer(c, done, 'the peer binding', (result, audit) => c.json({ ...result, ...audit }));
+    });
     // 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) => {
@@ -7553,9 +7848,12 @@ export function createControlPlaneApi(options) {
             order: c.req.query('order'),
         });
         const entries = await c.var.admin.auditLog(c.get('actor'), filter);
+        // #2064: each audited change's row says the outcome its operation stands at — the latest
+        // outcome row wins — beside the raw row, which is returned as written.
+        const resolved = await withAuditedOutcomes(c.var.admin, c.get('actor'), entries);
         // The cursor IS the last entry's id (ULID order is chronological), so the
         // page carries its own continuation and the console never assembles one.
-        return c.json(pageOf(entries, filter.limit, (e) => e.id));
+        return c.json(pageOf(resolved, 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. Newest first by default,
@@ -7674,6 +7972,57 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'unknown issue fingerprint' }, 404);
         return c.json(updated);
     });
+    // -- findings (#1748): the tenant inbox, with a lifecycle and suppress rules ----
+    // Staff read the fleet; a tenant credential's tenant is forced from the principal, the
+    // /ops-failures posture. Builders never reach any of these (absent from BUILDER_ROUTES): a
+    // finding is the tenant's, not the vertical author's.
+    app.get('/findings', async (c) => {
+        const filter = findingsQuery.parse({
+            tenantId: confinedTenant(c.get('principal')) ?? c.req.query('tenantId'),
+            status: c.req.query('status'),
+            kind: c.req.query('kind'),
+            limit: c.req.query('limit'),
+        });
+        return c.json({ entries: await c.var.admin.listFindings(c.get('actor'), filter) });
+    });
+    // A verdict: acknowledge, resolve or reopen. Keyed on the tenant in the path as well as the id,
+    // so another tenant's finding is a 404, never a write.
+    app.put('/tenants/:tenantId/findings/:id/status', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        if (outsideTenant(c.get('principal'), tenantId))
+            return c.json({ error: 'forbidden' }, 403);
+        const { status } = findingStatusUpdate.parse(await c.req.json());
+        const updated = await c.var.admin.setFindingStatus(c.get('actor'), tenantId, c.req.param('id'), status);
+        if (!updated)
+            return c.json({ error: 'unknown finding' }, 404);
+        return c.json(updated);
+    });
+    app.get('/tenants/:tenantId/finding-rules', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        if (outsideTenant(c.get('principal'), tenantId))
+            return c.json({ error: 'forbidden' }, 403);
+        const filter = findingRulesQuery.parse({ active: c.req.query('active'), limit: c.req.query('limit') });
+        const entries = await c.var.admin.listFindingRules(c.get('actor'), tenantId, filter);
+        return c.json({ entries });
+    });
+    // Suppress with a rule: a scope plus an expiry, audited. 201 with the rule and how many
+    // findings it suppressed at once.
+    app.post('/tenants/:tenantId/finding-rules', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        if (outsideTenant(c.get('principal'), tenantId))
+            return c.json({ error: 'forbidden' }, 403);
+        const input = findingRuleInput.parse(await c.req.json());
+        return c.json(await c.var.admin.createFindingRule(c.get('actor'), tenantId, input), 201);
+    });
+    app.delete('/tenants/:tenantId/finding-rules/:ruleId', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        if (outsideTenant(c.get('principal'), tenantId))
+            return c.json({ error: 'forbidden' }, 403);
+        const revoked = await c.var.admin.revokeFindingRule(c.get('actor'), tenantId, c.req.param('ruleId'));
+        if (!revoked)
+            return c.json({ error: 'unknown finding rule' }, 404);
+        return c.json(revoked);
+    });
     // -- 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