@antasphere/chassis-server 1.0.0

package/dist/api/create-api.js

@@ -0,0 +1,1165 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { matchedRoutes } from 'hono/route';
+import { createEmailVerificationToken } from 'better-auth/api';
+import { jwtVerify } from 'jose';
+import { registerOpenApiDoc } from './index.js';
+import { ulid } from 'ulid';
+import { and, asc, desc, eq } from 'drizzle-orm';
+import { ACTIVE_WORKSPACE_HEADER } from '@antasphere/chassis-contract';
+import { instanceRoute, setupRoute } from '@antasphere/chassis-contract/routes';
+import { account, instanceSettings, user as userTable, userOnboarding, workspaceMembers, workspaces } from '@antasphere/chassis-db';
+import { hubConfig } from '../env.js';
+import { DEMO_SESSION_REFUSED_API_ROUTES, demoSessionApiRefusalMessage, demoSessionAuthRefusal } from '../identity/index.js';
+import { DemoPassService } from '../identity/demo-pass.js';
+import { auditMiddleware } from '../audit/index.js';
+import { isDeferringGate, registerEntitlementGate } from '../entitlements/index.js';
+import { constantTimeEquals } from '../util/index.js';
+import { isSecureSetupOrigin } from '../util/index.js';
+import { authBodyGuard } from '../middleware/index.js';
+import { admitPrincipal, authContext, resolveSessionPrincipal } from '../middleware/index.js';
+import { idempotency } from '../middleware/index.js';
+import { crossSiteGuard } from '../middleware/index.js';
+import { jsonDepthLimit } from '../middleware/index.js';
+import { deferrableBodyCap } from '../middleware/body-cap.js';
+import { noStoreAuthenticated } from '../middleware/index.js';
+import { oauthPublicEndpoints } from '../middleware/index.js';
+import { createRequestQuota, emailKeyOf, makeClientIp, rateLimit } from '../middleware/index.js';
+import { HUB_SSO_PROVIDER_ID } from '../identity/index.js';
+import { registerBreakGlassRoutes } from './index.js';
+import { registerCliAuthRoutes } from './index.js';
+import { registerOnboardingRoutes } from './index.js';
+import { registerWorkspaceRoutes, workspaceCreationPolicy, workspaceCreationRefusal, workspaceCreateWallClosed } from './index.js';
+import { registerSsoConnectRoutes } from './index.js';
+import { registerSsoLogoutRoutes } from './index.js';
+import { registerMemberRoutes } from './index.js';
+import { demoSessionJudge, demoSignInOn, registerDemoPassRoutes } from './index.js';
+import { registerProjectRoutes } from './index.js';
+import { registerTeamRoutes } from './index.js';
+import { registerApiKeyRoutes } from './index.js';
+import { registerInvitationRoutes } from './index.js';
+import { registerAuditRoutes } from './index.js';
+import { registerFileRoutes } from './index.js';
+import { registerExportRoutes } from './index.js';
+/** Inline error body matching the wire shape; keeps openapi handlers typed. */
+const err = (code, message) => ({ error: { code, message } });
+/** Where the sign-in library is mounted: the full path a middleware on `api` sees starts with it. */
+const AUTH_MOUNT = '/api/v1/auth';
+/**
+ * PRDCT-1437 door 1: neutralize the change-email consume's account-existence
+ * oracle by rewriting the REQUEST before Better Auth reads the token.
+ *
+ * The consume of a `change-email-verification` link updates the target's email
+ * to the new address; when that address already belongs to ANOTHER user the
+ * update dies at the `user.email` UNIQUE constraint as a raw 500, while a free
+ * address answers a 302 — a mint-then-consume "does this email exist anywhere
+ * on the instance" for any workspace owner, and a robustness bug. Rather than
+ * reimplement the consume (LESSONS.md M6: never hand-roll the Better Auth
+ * flow), on a collision we re-sign the token so its target is the member's
+ * CURRENT address — a no-op change that runs Better Auth's ENTIRE success path
+ * (its own `callbackURL` origin check, the session mint, the set-cookie, the
+ * 302-or-JSON, the audit hook) with no unique violation. Redirect, cookie, and
+ * origin-check verdict are then byte-identical to the free case BY
+ * CONSTRUCTION, and no `callbackURL` handling is added here, so no open-redirect
+ * surface is introduced (the route's own originCheck stays the only judge).
+ *
+ * The one residual tell — the success JSON echoes the resulting email in its
+ * `user` record — is reachable only WITHOUT a `callbackURL` (a real consume
+ * always carries one and redirects) and is stripped to `user:null` by the
+ * wrapper below. The honest, inherent residual (email uniqueness is
+ * instance-global, so the change's outcome is readable one step later on the
+ * roster) is documented in ADR 013's amendment. It runs in a before-hook only
+ * as a query mutation, which the endpoint's own parsed query never sees, so it
+ * MUST rewrite the request here. Re-verify the token shape and the
+ * `change-email-verification` requestType on ANY Better Auth bump.
+ */
+/**
+ * Constrain a verify-email redirect Location to the instance's own origin
+ * (Major 3, PRDCT-1437 hardening). DEFENCE-IN-DEPTH, not a hole being closed:
+ * on the pinned Better Auth, `/verify-email` DOES run its own callbackURL
+ * origin check in production (the `originCheck` factory has no GET skip; only
+ * `originCheckMiddleware` does) — but the test harness disables that guard
+ * (`NODE_ENV=test` sets `skipOriginCheck`), and a future bump could regress
+ * it, so we constrain the redirect ourselves and the no-op collision rewrite
+ * routes the taken branch through the same constraint. A same-origin (or
+ * public-origin) target is returned
+ * as a relative path; anything off-origin is neutralized to `/`. Legitimate
+ * consumes send a relative `callbackURL` and are untouched; applied to every
+ * response the wrapper sees, so the taken and free branches stay identical.
+ */
+function safeRedirectLocation(location, requestUrl, publicBaseUrl) {
+    let resolved;
+    let servingOrigin;
+    try {
+        servingOrigin = new URL(requestUrl).origin;
+        resolved = new URL(location, requestUrl);
+    }
+    catch {
+        return '/';
+    }
+    let publicOrigin = null;
+    try {
+        publicOrigin = new URL(publicBaseUrl).origin;
+    }
+    catch {
+        publicOrigin = null;
+    }
+    if (resolved.origin === servingOrigin || resolved.origin === publicOrigin) {
+        return resolved.pathname + resolved.search + resolved.hash;
+    }
+    return '/';
+}
+async function rewriteChangeEmailCollision(auth, authSecret, request) {
+    const url = new URL(request.url);
+    const token = url.searchParams.get('token');
+    if (!token)
+        return request;
+    let payload;
+    try {
+        const verified = await jwtVerify(token, new TextEncoder().encode(authSecret), {
+            algorithms: ['HS256']
+        });
+        payload = verified.payload;
+    }
+    catch {
+        return request; // a bad token is Better Auth's to reject (uniform error redirect)
+    }
+    const email = payload.email;
+    const updateTo = payload.updateTo;
+    if (payload.requestType !== 'change-email-verification' ||
+        typeof email !== 'string' ||
+        typeof updateTo !== 'string' ||
+        email === updateTo) {
+        return request;
+    }
+    try {
+        const authCtx = await auth.$context;
+        const target = await authCtx.internalAdapter.findUserByEmail(email);
+        if (!target)
+            return request; // user_not_found — uniform on both branches
+        // A signed-in NON-target redirectOnErrors identically on both branches, so
+        // only the state that actually reaches the update needs neutralizing.
+        const session = await auth.api.getSession({ headers: request.headers }).catch(() => null);
+        if (session && session.user.email !== email)
+            return request;
+        const holder = await authCtx.internalAdapter.findUserByEmail(updateTo);
+        if (!holder || holder.user.id === target.user.id)
+            return request; // no collision
+        // Collision: re-sign as a no-op (change email → same email). Better Auth
+        // then updates the row to its own value (no 23505) and runs the full
+        // success path off the rewritten request.
+        const noopToken = await createEmailVerificationToken(authCtx.secret, email, email, 3600, {
+            requestType: 'change-email-verification'
+        });
+        url.searchParams.set('token', noopToken);
+        return new Request(url.toString(), request);
+    }
+    catch {
+        // A lookup failure must not turn into a distinguishing error — let Better
+        // Auth answer, and the wrapper's 5xx→uniform mapping backstops it.
+        return request;
+    }
+}
+/** Control-flow marker: the singleton claim lost (instance already set up). */
+class SetupAlreadyDone extends Error {
+}
+/**
+ * The versioned API, mounted at /api/v1. Every route is defined by a contract
+ * in the tool's contract package (`<tool contract>/routes`); the OpenAPI document is generated from those
+ * contracts and served at /api/v1/openapi.json.
+ */
+export function createApiApp(deps) {
+    const { db, env, auth, registry, logger, apiKeys: apiKeyService, audit, email, limiters, tool } = deps;
+    const { meRoute, apiKeysListRoute, apiKeyCreateRoute, apiKeyRevokeRoute, cliAuthCompleteRoute } = tool.scopes.contractRoutes;
+    const { ssoCliConnectRoute } = tool.scopes.contractRoutes;
+    // The registry as the chassis routers read it (the generic events only):
+    // the same seams, the same bus, seen through its chassis view.
+    const chassisRegistry = { ...registry, events: registry.events.chassisView() };
+    // What every positional hook of the tool receives.
+    const hookContext = {
+        db,
+        env,
+        auth,
+        registry,
+        logger,
+        audit,
+        email,
+        limiters,
+        storage: deps.storage,
+        fileService: deps.fileService,
+        authSecret: deps.authSecret,
+        hubSso: deps.hubSso
+    };
+    // P7 (internal/federation.md): on EDITION=cloud, membership of a hub-origin
+    // (projected) workspace is managed at the hub — this is the pointer the
+    // membership-mutation gates and /me carry. Same single `hubConfig` switch
+    // as every cloud seam: null on oss, so oss wires no gate and /me answers
+    // hubManageUrl null.
+    const hub = hubConfig(env);
+    const hubManaged = hub ? { manageUrl: hub.issuerUrl } : undefined;
+    // Demo sign-in (the demo pass spec): DEMO_SIGN_IN on the self-hosted
+    // edition only. Off, no demo route, wall or discovery key exists.
+    const demoSignIn = demoSignInOn(env, hub, logger);
+    const api = new OpenAPIHono({
+        // Validation failures use the same wire shape as every other error.
+        defaultHook: (result, c) => {
+            if (!result.success) {
+                return c.json({
+                    error: {
+                        code: 'validation_error',
+                        message: 'Request validation failed',
+                        details: result.error.issues
+                    }
+                }, 400);
+            }
+        }
+    });
+    // NOTE (release-gate fix): malformed/empty JSON bodies used to 500 here —
+    // hono's json validator throws HTTPException(400) BEFORE zod runs, so the
+    // defaultHook above never fires. Hono routes thrown errors straight to the
+    // top-level errorHandler from the throwing frame (an upstream middleware
+    // try/catch never sees them), so the mapping to the 400 wire shape lives
+    // in app.ts app.onError — the one seam that covers every body route.
+    // ── Public OAuth endpoints first: wildcard CORS + OPTIONS 204 + no-store
+    // on token responses. Before the rate limits so preflights cost nothing.
+    api.use('/auth/*', oauthPublicEndpoints());
+    // ── Cross-site (CSRF) gate, before ANY other work: an unsafe method driven
+    // from another origin is refused before a body is buffered, before a
+    // limiter bucket is touched, and before a credential resolves. Sessions are
+    // ambient credentials — every business route below (the tool's resources,
+    // its tokens and collaborators, api-keys) would otherwise be drivable
+    // from any page the user happens to have open.
+    //
+    // SCOPED TO /api/v1 ON PURPOSE. The public viewer (`/v/:secret`) is mounted
+    // on the root app and is DELIBERATELY embeddable cross-origin (ADR 021 +
+    // /embed.js), including its password-form POST — mounting this guard there
+    // would break every legitimate embed. The viewer authenticates on the share
+    // secret and its own scoped cookie, not on the dashboard session, so it is
+    // not the ambient-credential surface this closes.
+    api.use('*', crossSiteGuard({
+        publicBaseUrl: env.PUBLIC_BASE_URL,
+        // The tool's never-trusted origins (e.g. a viewer origin, PRDCT-1352:
+        // the origin author-controlled script runs on): never a trust
+        // grant here, even if it is the serving origin.
+        deniedOrigins: deps.untrustedOrigins,
+        // `/api/v1/viewer/*` is the share-token annotation API, and it is a
+        // DELIBERATE wildcard-CORS surface (viewer/annotations-api.ts): it is
+        // called by the overlay client running inside the sandboxed viewer
+        // iframe, whose origin is the opaque `null`. Nothing there is
+        // cookie-authenticated — the share token in the path is the credential —
+        // so it is not the ambient-credential class this guard closes, and
+        // refusing `Origin: null` would break annotations outright.
+        isExempt: (path) => tool.api.csrfExempt?.(path) ?? false
+    }));
+    // ── Authenticated responses are never cached. Registered ABOVE the
+    // credential middleware so it wraps every route under /api/v1, and it reads
+    // the principal AFTER the inner chain has resolved it. Routes that set their
+    // own Cache-Control (public discovery, the OpenAPI document) keep it.
+    api.use('*', noStoreAuthenticated());
+    // The public viewer-token annotation surface (Phase 5): same posture — the
+    // overlay calls cross-origin from the sandboxed opaque origin (Origin:
+    // null), token-authed, never cookie-authed, so wildcard CORS is safe.
+    tool.api.early?.(api, hookContext);
+    // ── Body size caps, path-routed. 1 MiB is generous for every JSON/auth
+    // body. Exceptions:
+    //  - /files: streamed uploads with their own mid-stream cap
+    //    (MAX_FILE_SIZE_MB) plus a Content-Length entitlement check;
+    //  - the tool's multipart asset uploads (its `bodyLimit` slot) — capped at
+    //    MAX_FILE_SIZE_MB (+1 MiB multipart framing headroom) so an unbounded
+    //    body can never balloon the buffering parse;
+    //  - the rest of the tool's routes, which are JSON, but commit manifests are legal up to
+    //    5000 entries × 1 KiB paths — a 16 MiB cap fits any contract-valid
+    //    manifest while still bounding abuse.
+    const jsonBodyCap = {
+        maxBytes: 1024 * 1024,
+        onError: (c) => c.json(err('payload_too_large', 'Request body exceeds the 1 MiB limit'), 413)
+    };
+    // The tool's own caps, declared ONCE (the slot's factory runs here, never
+    // per request) and built into middleware per cap object below.
+    const toolBodyLimit = tool.api.bodyLimit?.(hookContext);
+    //  - the viewer's form file upload (PRDCT-2403): one raw streamed file per
+    //    request, capped MID-STREAM by the form-upload ceiling in its handler.
+    //
+    // A declared Content-Length over a cap on a route whose gate judges a
+    // PLAN LIMIT is not refused here (PRDCT-2632): the entitlement gate must
+    // see the declared size first, so a metered account meets 403
+    // `plan_required` with its upgrade link at any size and the cap's 413
+    // answers only when the plan allows the size. `deferrableBodyCap`
+    // (middleware/body-cap.ts) parks the refusal on the context and DROPS the
+    // request's body, keyed on the gate itself being on the matched route;
+    // the gate fires it. Every cap goes through it, the tool's and the
+    // default JSON one alike, so a future declared-limit route left under
+    // the default cap is never shadowed either. An undeclared body is still
+    // counted and cut by the cap.
+    const deferring = (c) => matchedRoutes(c).some((route) => isDeferringGate(route.handler));
+    const capMiddleware = new WeakMap();
+    const capped = (cap) => {
+        let built = capMiddleware.get(cap);
+        if (!built) {
+            built = deferrableBodyCap(cap, deferring);
+            capMiddleware.set(cap, built);
+        }
+        return built;
+    };
+    api.use('*', (c, next) => {
+        const path = c.req.path;
+        if (path.startsWith('/api/v1/files'))
+            return next();
+        const verdict = toolBodyLimit?.(path);
+        if (verdict === 'exempt')
+            return next();
+        return capped(verdict ?? jsonBodyCap)(c, next);
+    });
+    // ── JSON nesting cap, right after the size cap (so the scan is bounded by
+    // it): `JSON.parse` accepts any depth but `JSON.stringify` is recursive, so
+    // a small body of nothing but `[` turns any echo/audit/log of it into a
+    // RangeError 500 inside the shipped node:22-alpine image.
+    // The form file upload is exempt: its body is a FILE, never parsed, and a
+    // respondent's `.json` sent with a JSON content type would otherwise be
+    // cloned into memory whole (up to the upload ceiling) by the scan.
+    const depthLimit = jsonDepthLimit();
+    api.use('*', (c, next) => (tool.api.jsonDepthExempt?.(c.req.path) ? next() : depthLimit(c, next)));
+    // ── Auth-surface rate limits: registered FIRST so they run before auth
+    // resolution — abusive traffic is rejected before it costs a DB query.
+    const clientIp = makeClientIp(env.TRUST_PROXY);
+    // Login keys by IP AND email: Docker NAT (or a rotating attacker) can
+    // collapse/expand the IP dimension, so per-account protection must not
+    // depend on it. emailKeyOf returns [] for bodyless social sign-in.
+    //
+    // consumeOn: 'failure' — see rate-limit.ts. The email key is derived from
+    // the REQUEST BODY, i.e. from an address anyone can type, so consuming it on
+    // arrival made the wall an account-lockout tool: ten POSTs naming a victim
+    // emptied that account's bucket for the window. Consuming only when the
+    // credential was actually refused keeps the brute-force budget identical and
+    // makes the owner's own successful sign-ins free.
+    //
+    // The federated start (`/auth/sign-in/oauth2`, the silent start toward the
+    // hub) presents no credential: it only answers the hub's authorize URL, and
+    // the hub checks the person with its own wall. It stays off this one, so a
+    // wall drained by wrong passwords behind a shared address does not also
+    // close the hub sign-in to everyone behind it (PRDCT-2830).
+    const loginWall = rateLimit(limiters.login, clientIp, emailKeyOf, { consumeOn: 'failure' });
+    api.use('/auth/sign-in/*', (c, next) => c.req.path.endsWith('/auth/sign-in/oauth2') ? next() : loginWall(c, next));
+    api.use('/auth/email-otp/*', rateLimit(limiters.otp, clientIp, emailKeyOf));
+    api.use('/auth/sign-up/*', rateLimit(limiters.login, clientIp));
+    // Password reset: request keys by IP AND email (tight); reset + change key
+    // by IP (brute-forcing a token / the current password). The deprecated
+    // emailOTP forget-password alias shares the reset wall.
+    api.use('/auth/request-password-reset', rateLimit(limiters.passwordReset, clientIp, emailKeyOf));
+    api.use('/auth/reset-password', rateLimit(limiters.passwordReset, clientIp));
+    api.use('/auth/reset-password/*', rateLimit(limiters.passwordReset, clientIp));
+    api.use('/auth/forget-password/*', rateLimit(limiters.passwordReset, clientIp, emailKeyOf));
+    // Email change mints sign-in-equivalent tokens and sends mail — same tight
+    // wall as the reset surface (per IP; the route is session-gated anyway).
+    api.use('/auth/change-email', rateLimit(limiters.passwordReset, clientIp));
+    api.use('/auth/change-password', rateLimit(limiters.login, clientIp));
+    // The 2FA surface: verify-totp / verify-backup-code guess a 6-digit code or
+    // a backup code behind the 10-minute pending-sign-in cookie; enable/disable
+    // present the current password. Same brute-force wall as login (per IP).
+    api.use('/auth/two-factor/*', rateLimit(limiters.login, clientIp));
+    // Account deletion presents the current password — same brute-force wall.
+    api.use('/auth/delete-user', rateLimit(limiters.login, clientIp));
+    api.use('/auth/oauth2/register', rateLimit(limiters.oauthRegister, clientIp));
+    api.use('/auth/oauth2/token', rateLimit(limiters.oauthToken, clientIp));
+    api.use('/setup', rateLimit(limiters.setup, clientIp));
+    api.use('/invitations/accept', rateLimit(limiters.invitationAccept, clientIp));
+    api.use('/invitations/lookup', rateLimit(limiters.invitationAccept, clientIp));
+    // Collaborator claims are invitation acceptances in per-resource clothing —
+    // the same public token-redemption surface, the same wall.
+    const rateLimitContext = { ...hookContext, clientIp };
+    tool.api.rateLimits?.(api, rateLimitContext);
+    // Break-glass: a rare superadmin recovery action — a tight per-IP wall
+    // bounds allowlist probing before the handlers' own session checks run.
+    api.use('/admin/break-glass/*', rateLimit(limiters.breakGlass, clientIp));
+    // CLI email-OTP sign-in (api/cli-auth.ts): request = an OTP send (the OTP
+    // wall, per IP + email); complete = a credential guess (the login wall,
+    // per IP + email) on top of better-auth's own 3-attempts-per-code limit.
+    api.use('/cli/auth/request', rateLimit(limiters.otp, clientIp, emailKeyOf));
+    api.use('/cli/auth/complete', rateLimit(limiters.login, clientIp, emailKeyOf, { consumeOn: 'failure' }));
+    // The demo pass redeem (identity/demo-pass-plugin.ts): a secret presented
+    // anonymously, so every arrival costs, per address only. In front of the
+    // sign-in handler, and only where the endpoint exists.
+    if (demoSignIn) {
+        // Only a REFUSED redeem costs: the wall is there against guessing, and a
+        // person playing a demonstration opens many valid links in a row from one
+        // address (found on the pair: the 21st valid click in fifteen minutes was
+        // refused). A drained wall still refuses everything until it refills.
+        api.use('/auth/demo/redeem', rateLimit(limiters.demoRedeem, clientIp, undefined, { consumeOn: 'failure' }));
+    }
+    // The OpenAPI document is unauthenticated (PUBLIC_API_PATHS) so it never
+    // reaches the per-principal quota; the buffer is generated once at boot
+    // (openapi-doc.ts) and this wall is the defence in depth on top.
+    api.use('/openapi.json', rateLimit(limiters.openapiDoc, clientIp));
+    // CLI cross-tool connect (cloud only, api/sso-connect.ts): presenting an
+    // exchange token is a credential presentation, walled per client address
+    // on its own bucket sized for a room (CLI_CONNECT_IP_LIMIT_PER_15_MIN): on
+    // the login wall (10 per 15 minutes) the 11th `<tool> login` behind one
+    // venue address was refused (PRDCT-2958, verifier F1). The token itself is
+    // one-time and the hub's walls bound each person. Conditional like the
+    // route itself: oss mounts zero hub surface.
+    if (deps.hubSso) {
+        api.use('/sso/cli-connect', rateLimit(limiters.cliConnect, clientIp));
+    }
+    // ── JSON pre-validation in front of the Better Auth mount (AF-1 + the
+    // update-user half of SL-B4, PRDCT-1358): Better Auth answers its own 500
+    // on a malformed/empty JSON body and on a NUL that reaches Postgres —
+    // responses app.onError never sees, so the app-level mappings cannot help.
+    // Registered here, after the size and depth caps, so the guard's body read
+    // is bounded.
+    api.use('/auth/*', authBodyGuard());
+    // Demo sign-in, the second door of "a session a pass opened lives only
+    // while its pass does": the sign-in library's mount runs BEFORE the
+    // credential resolver, and it is where a session authorizes an OAuth client
+    // and answers get-session. A dead pass's session is deleted here first, so
+    // the library sees none. A live pass's session is a visit: the library
+    // paths that would leave a credential, a grant or an account change behind
+    // it are refused here (identity/demo-pass-rules.ts
+    // `DEMO_SESSION_REFUSED_AUTH_PATHS`). And the library's own session deletes
+    // (a pass session's sign-out, a person's own revoke of one) delete the
+    // session row only: those sessions are ended the pass's way first
+    // (`endSessions`), so their OAuth tokens and link rows go with them.
+    // The revoking caller is verified by the library: a forged or dead cookie
+    // ends nothing.
+    if (demoSignIn) {
+        const judge = demoSessionJudge(db);
+        const demoPassService = new DemoPassService(db);
+        api.use('/auth/*', async (c, next) => {
+            if (!c.req.header('cookie'))
+                return next();
+            const verdict = await judge(c.req.raw.headers);
+            const authPath = c.req.path.startsWith(AUTH_MOUNT) ? c.req.path.slice(AUTH_MOUNT.length) : c.req.path;
+            if (verdict && verdict !== 'ended') {
+                if (demoSessionAuthRefusal(authPath)) {
+                    return c.json(err('demo_session', 'A session opened by a demo link cannot do this: sign in with your password'), 403);
+                }
+                // A pass session that signs itself out ends the pass's way; the
+                // library then answers as usual.
+                if (authPath === '/sign-out')
+                    await demoPassService.endSessions([verdict.sessionId]);
+            }
+            else if (authPath === '/revoke-session' ||
+                authPath === '/revoke-sessions' ||
+                authPath === '/revoke-other-sessions') {
+                // A person's OWN session revoking a pass session (a pass session is
+                // refused these paths above). The caller is verified by the library
+                // (`getSession`, the cookie's signature checked): a forged or dead
+                // cookie ends nothing. The body is read from a clone: the library
+                // gets the request untouched. The exact path compare loses nothing:
+                // the library's router answers 404 to any other spelling.
+                const verified = await auth.api.getSession({ headers: c.req.raw.headers }).catch(() => null);
+                if (verified?.session?.id && verified?.user?.id) {
+                    let bodyToken = null;
+                    try {
+                        const body = await c.req.raw.clone().json();
+                        if (body && typeof body === 'object' && typeof body.token === 'string') {
+                            bodyToken = body.token;
+                        }
+                    }
+                    catch {
+                        // No JSON body: nothing names a session (the library answers as it does).
+                    }
+                    const passSessions = await demoPassService.passSessionsRevokedBy(authPath, { sessionId: verified.session.id, userId: verified.user.id }, bodyToken);
+                    if (passSessions.length > 0)
+                        await demoPassService.endSessions(passSessions);
+                }
+            }
+            return next();
+        });
+    }
+    // Better Auth owns /api/v1/auth/* (mounted before the credential middleware
+    // — it IS the credential machinery). On cloud the whole mount runs inside
+    // the hub-SSO login scope: an AsyncLocalStorage span carrying the verified
+    // hub assertion from the SSO callback's getUserInfo to its after-hook —
+    // request-scoped, so concurrent logins can never cross-wire (ADR 015).
+    const { hubSso } = deps;
+    // The change-email consume, wrapped (PRDCT-1437). The request is rewritten
+    // on a collision (rewriteChangeEmailCollision above), then two response
+    // normalizations keep the taken and free cases indistinguishable:
+    //
+    //  - JSON success body: the change-email success echoes the resulting email
+    //    in its `user` record — the one observable the no-op rewrite leaves
+    //    differing between the taken and free cases. It is reachable ONLY without
+    //    a `callbackURL` (a real consume always carries one and redirects, never
+    //    hitting this JSON), so stripping `user` to null for every change-email
+    //    consume touches no legitimate flow. Only the change/legacy branches
+    //    return a non-null user; the plain verify-email success is already null.
+    //  - a residual 5xx: the rewrite closes the DECIDABLE collision, but two
+    //    concurrent mints claiming one FRESH address (no pre-existing account —
+    //    so NOT an existence probe) can still lose at the DB. Map it to the same
+    //    benign JSON so it never surfaces a raw 500. No redirect is issued here —
+    //    every redirect stays Better Auth's, judged by its own originCheck, so
+    //    this wrapper adds no open-redirect surface.
+    //
+    // Registered BEFORE the wildcard mount so the exact route wins.
+    api.on(['GET'], '/auth/verify-email', async (c) => {
+        const req = await rewriteChangeEmailCollision(auth, deps.authSecret, c.req.raw);
+        const res = await (hubSso ? hubSso.runWithLoginScope(() => auth.handler(req)) : auth.handler(req));
+        if (res.status === 200 && (res.headers.get('content-type') ?? '').includes('application/json')) {
+            const body = (await res
+                .clone()
+                .json()
+                .catch(() => null));
+            if (body && body.status === true && body.user != null) {
+                const headers = new Headers(res.headers);
+                headers.delete('content-length');
+                return new Response(JSON.stringify({ status: true, user: null }), { status: 200, headers });
+            }
+            return res;
+        }
+        // A 3xx: constrain the Location to this origin (Major 3). Better Auth's
+        // GET verify-email skips originCheck (no Origin header on a navigation) and
+        // redirects to any callbackURL — an open redirect for anyone holding a
+        // verify token, applied to BOTH branches so it stays uniform.
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (location) {
+                const safe = safeRedirectLocation(location, c.req.url, env.PUBLIC_BASE_URL);
+                if (safe !== location) {
+                    const headers = new Headers(res.headers);
+                    headers.set('location', safe);
+                    return new Response(null, { status: res.status, headers });
+                }
+            }
+            return res;
+        }
+        if (res.status < 500)
+            return res;
+        logger.warn({ status: res.status }, 'verify-email answered 5xx — mapped to the uniform non-revealing response');
+        return c.json({ status: true, user: null }, 200);
+    });
+    api.on(['GET', 'POST'], '/auth/*', (c) => hubSso ? hubSso.runWithLoginScope(() => auth.handler(c.req.raw)) : auth.handler(c.req.raw));
+    api.use('*', authContext({
+        registry: chassisRegistry,
+        isApiKeyToken: apiKeyService.isToken,
+        resolveApiKey: (token, requested) => apiKeyService.resolve(token, requested),
+        resolveOauthJwt: (token, requested) => deps.oauthJwt.resolve(token, requested),
+        keyFailureLimiter: limiters.apiKeyFailures,
+        clientIp,
+        // General per-principal quota (I3): runs inside authContext, after the
+        // credential resolves (the bucket key IS the principal identity) and
+        // before the scope gate. Public paths and /auth/* never reach it (no
+        // principal), so the auth-surface limiters above are not doubled.
+        // Limits ride the EntitlementService seam; buckets ride the same
+        // Redis-or-memory backend as every other limiter.
+        requestQuota: createRequestQuota({
+            entitlements: registry.entitlements,
+            make: limiters.make,
+            logger
+        }),
+        // Cloud edition's post-resolution veto (internal/federation.md P4);
+        // undefined on oss.
+        principalGate: deps.principalGate,
+        // Demo sign-in: a session a demo pass opened lives only while its pass
+        // does, and its audit rows carry the pass's id. Absent while the switch is off.
+        ...(demoSignIn ? { demoSession: demoSessionJudge(db) } : {}),
+        // The composed fail-closed allowlist: chassis rules, then the tool's rules.
+        requiredScopeFor: tool.scopes.requiredScopeFor,
+        guestForbiddenMessage: tool.copy.guestForbidden
+    }));
+    // A session a demo link opened is a visit (identity/demo-pass-rules.ts
+    // `DEMO_SESSION_REFUSED_API_ROUTES`): the routes that mint a credential or
+    // make something the person keeps refuse it here, at one place, right after
+    // the credential resolves and before anything claims an idempotency key.
+    // `demoPassId` is only ever set while the switch is on. The tool's own
+    // routes of the kind (its `demoSessionRefusedRoutes` slot) join the list here.
+    for (const rule of [...DEMO_SESSION_REFUSED_API_ROUTES, ...(tool.demoSessionRefusedRoutes ?? [])]) {
+        const gate = async (c, next) => {
+            if (c.get('demoPassId')) {
+                return c.json(err('demo_session', demoSessionApiRefusalMessage(rule.does)), 403);
+            }
+            return next();
+        };
+        if (rule.method === 'ALL')
+            api.use(rule.path, gate);
+        else
+            api.on(rule.method, rule.path, gate);
+    }
+    // Idempotency sits strictly BETWEEN authContext (it needs the resolved
+    // principal to scope claims) and auditMiddleware (a replayed short-circuit
+    // never reaches the audit layer, so a retry cannot land a second audit row).
+    api.use('*', idempotency({
+        db,
+        authSecret: deps.authSecret,
+        ...(tool.api.idempotencyTargets ? { toolTargets: tool.api.idempotencyTargets } : {})
+    }));
+    api.use('*', auditMiddleware(audit, clientIp, tool.api.auditExempt ? { exempt: tool.api.auditExempt } : {}));
+    // Instance id for usage-event sources, cached after first read.
+    let cachedInstanceId = null;
+    const instanceId = async () => {
+        if (cachedInstanceId)
+            return cachedInstanceId;
+        const [row] = await db.select({ id: instanceSettings.instanceId }).from(instanceSettings).limit(1);
+        cachedInstanceId = row?.id ?? 'unsetup';
+        return cachedInstanceId;
+    };
+    // ── The entitlement gate (the billing rail, §7) — AFTER the scope gate
+    // (inside authContext), the idempotency claim and the audit middleware,
+    // BEFORE every handler: one middleware per declared route, so a route
+    // that declares a meter, a limit or a feature is checked here and its
+    // usage event emitted here, and no handler checks or emits by hand. The
+    // dashboard, the CLI and the MCP tools all pass through it.
+    registerEntitlementGate(api, {
+        declarations: deps.entitlements.routes,
+        tool: deps.entitlements,
+        entitlements: registry.entitlements,
+        usage: registry.usage,
+        cloud: deps.entitlementCloud,
+        source: async () => ({ instanceId: await instanceId(), edition: env.EDITION, version: env.APP_VERSION }),
+        logger
+    });
+    // ── GET /instance — unauthenticated discovery ────────────────────────────
+    api.openapi(instanceRoute, async (c) => {
+        const [row] = await db.select().from(instanceSettings).limit(1);
+        c.header('Cache-Control', 'public, max-age=60');
+        return c.json({
+            name: row?.name ?? tool.identity.displayName,
+            instanceId: row?.instanceId ?? null,
+            edition: env.EDITION,
+            version: env.APP_VERSION,
+            apiVersion: 'v1',
+            setupRequired: !row,
+            auth: {
+                ...registry.identity.describe(),
+                // Cloud only (SL-1): the hint-cookie contract the dashboard's
+                // silent auto-connect reads — spread-gated on the same single
+                // `hub` switch as every cloud seam, so the oss discovery bytes
+                // never carry the key.
+                ...(hub
+                    ? { sso: { hintCookieName: hub.hintCookieName, hintCookieDomain: hub.hintCookieDomain } }
+                    : {})
+            },
+            features: { mcp: true, oauth: true, files: true },
+            // Present only while demo links sign people in here (the banner's cue).
+            ...(demoSignIn ? { demoSignIn: true } : {}),
+            // Present only on a cloud instance whose operator restricted the tool
+            // (PRDCT-2947): organizations are opened by Antasphere, not created here.
+            ...(hub && env.TOOL_RESTRICTED ? { restricted: true } : {}),
+            // What this version declares for the billing rail (§7): the hub seeds
+            // from it, staff read it, a client reads the limit it is held to.
+            entitlements: {
+                actions: deps.entitlements.actions,
+                limits: deps.entitlements.limits,
+                features: deps.entitlements.features
+            }
+        }, 200);
+    });
+    // ── POST /setup — one-shot first-boot wizard ─────────────────────────────
+    api.openapi(setupRoute, async (c) => {
+        const body = c.req.valid('json');
+        // BEFORE the token check: an instance reachable only over plaintext on a
+        // non-loopback origin must not accept the owner password at all, whether
+        // or not the caller holds the token (setup-transport.ts).
+        if (!env.ALLOW_INSECURE_SETUP && !isSecureSetupOrigin(env.PUBLIC_BASE_URL)) {
+            logger.warn({ publicBaseUrl: env.PUBLIC_BASE_URL }, 'refused setup over plaintext on a non-loopback origin');
+            return c.json(err('insecure_transport', 'Setup over plaintext HTTP on a non-loopback origin is refused. Put TLS in front, reach the instance through an SSH tunnel, or set ALLOW_INSECURE_SETUP=true.'), 403);
+        }
+        const [existing] = await db.select({ id: instanceSettings.id }).from(instanceSettings).limit(1);
+        if (existing) {
+            return c.json(err('already_setup', 'This instance has already been set up'), 410);
+        }
+        // ALWAYS required (PRDCT-1347): the claim decides who owns the instance.
+        // `deps.setupToken` is SETUP_TOKEN or the boot-generated token; it is
+        // null only for a set-up instance, which the 410 above already answered
+        // — so a null here is a claim with no credential to compare against and
+        // fails closed rather than falling through to a free claim.
+        if (!deps.setupToken || !constantTimeEquals(body.setupToken ?? '', deps.setupToken)) {
+            return c.json(err('invalid_setup_token', 'A valid setup token is required'), 403);
+        }
+        // Create the owner user through Better Auth so credential hashing and
+        // account rows follow its rules exactly. Better Auth cannot join our
+        // transaction, so this happens first; a setup that later loses the claim
+        // race leaves an orphaned user who can sign in but reaches nothing (401
+        // on every route — no membership).
+        let ownerUserId;
+        try {
+            const created = await auth.api.signUpEmail({
+                body: { email: body.owner.email, password: body.owner.password, name: body.owner.name }
+            });
+            ownerUserId = created.user.id;
+        }
+        catch (cause) {
+            // Retry after a crashed earlier attempt: the user may already exist.
+            // Reuse it ONLY if the presented credentials actually sign in — never
+            // attach a workspace to an account the caller cannot prove they own.
+            try {
+                const signedIn = await auth.api.signInEmail({
+                    body: { email: body.owner.email, password: body.owner.password }
+                });
+                ownerUserId = signedIn.user.id;
+            }
+            catch {
+                logger.error({ err: cause }, 'setup: owner creation failed');
+                return c.json(err('owner_creation_failed', 'Could not create the owner user'), 400);
+            }
+        }
+        // The operator drove the wizard (holding the setup token when one is
+        // set) — their address needs no mailbox dance, and on the cloud edition
+        // it MUST be verified (D9, internal/federation.md): under hub-only login the
+        // operator's only entrance is the hub trusted-link, and Better Auth
+        // refuses to link a trusted provider onto an UNVERIFIED local email
+        // (requireLocalEmailVerified stays on). An unverified operator bricks a
+        // cloud instance at bootstrap. The hub's own setup does the same.
+        await db.update(userTable).set({ emailVerified: true }).where(eq(userTable.id, ownerUserId));
+        // Claim the singleton and — on the OSS edition — create the FIRST
+        // workspace + owner membership in ONE transaction: either the instance
+        // is fully set up or nothing persisted. The workspace goes through the
+        // registry's WorkspaceService (ADR 014) — the same path product flows
+        // use for every LATER workspace. On CLOUD (`hub` set — the same single
+        // switch as every cloud seam) setup creates NO workspace: every cloud
+        // workspace is a hub-org projection (user-scoped federation), so the
+        // operator bootstrap mints a verified, break-glass capable USER only —
+        // the singleton claim, the edition stamp, and the D9 emailVerified
+        // force above all stay.
+        const instanceId = ulid();
+        let workspaceId;
+        try {
+            workspaceId = await db.transaction(async (tx) => {
+                const claimed = await tx
+                    .insert(instanceSettings)
+                    // The edition stamp is what the R7 boot guard compares against
+                    // (boot.ts, internal/federation.md): setup records the edition this
+                    // instance was born under.
+                    .values({
+                    id: 'instance',
+                    instanceId,
+                    name: body.instanceName,
+                    edition: env.EDITION,
+                    // The durable operator record (CLOUD-3): survives the orphan purge.
+                    operatorUserId: ownerUserId
+                })
+                    .onConflictDoNothing()
+                    .returning({ id: instanceSettings.id });
+                if (claimed.length === 0)
+                    throw new SetupAlreadyDone();
+                if (hub)
+                    return null;
+                const created = await registry.workspaces.create(body.instanceName, ownerUserId, tx);
+                return created.workspaceId;
+            });
+        }
+        catch (cause) {
+            if (cause instanceof SetupAlreadyDone) {
+                return c.json(err('already_setup', 'This instance has already been set up'), 410);
+            }
+            logger.error({ err: cause }, 'setup: transaction failed (nothing persisted)');
+            return c.json(err('internal', 'Setup failed; the instance remains uninitialized — retry'), 500);
+        }
+        chassisRegistry.events.emit('setup.completed', { workspaceId, instanceId });
+        logger.info({ workspaceId, instanceId }, 'first-boot setup completed');
+        // The generated token has done its one job; a leftover copy in the data
+        // volume is a secret with no purpose (it would ride in every backup).
+        await deps.clearGeneratedSetupToken().catch((cause) => {
+            logger.warn({ err: cause }, 'setup: could not remove the generated setup-token file');
+        });
+        // The genesis privileged action: audited directly (no principal in
+        // context yet — the middleware exempts /setup).
+        await audit.write({
+            workspaceId,
+            principal: null,
+            action: 'instance.setup',
+            resourceType: 'instance',
+            resourceId: instanceId,
+            requestId: c.get('requestId'),
+            metadata: { ownerUserId, ownerEmail: body.owner.email }
+        });
+        return c.json({ instanceId, workspaceId, ownerUserId }, 201);
+    });
+    /**
+     * SL-6 /me extras — CLOUD + SESSION callers only (both spread-gated
+     * below; machine credentials and every oss response never carry the
+     * keys):
+     *
+     *  - `firstRunPending`: tool-local, retry-safe banner truth —
+     *    `NOT EXISTS (user_onboarding row WHERE dismissed_at IS NOT NULL)`.
+     *    A missing row (lost first-login insert) still shows the welcome;
+     *    only an explicit dismissal (or the deploy backfill) hides it.
+     *  - `ssoOnly`: the hint-watch discriminator — the user holds an
+     *    `antasphere` account row AND no local credential (password) row.
+     *    'credential' is better-auth's password-account providerId (pinned
+     *    1.6.15; re-verify on bump). A break-glass-capable operator always
+     *    has a credential row (setup mints it), so they are NEVER ssoOnly
+     *    and the dashboard's hint-watch can never sign them out.
+     *  - `hubDenied`: the organizations the person's last definitive hub
+     *    list named as not opening this tool to them (a hint for the
+     *    refusal page; the hub is the truth), and `hubNoAccessUrl`, the
+     *    hub's page that lists whom to ask, ready-made with this tool's
+     *    client id.
+     */
+    // `/me.canCreateWorkspace` and POST /workspaces judge through the SAME
+    // rule (api/workspaces.ts), so the flag never promises what the route
+    // refuses. Never throws into /me: a failed read answers false.
+    const creationPolicy = workspaceCreationPolicy({
+        maxPerUser: env.MAX_WORKSPACES_PER_USER,
+        restricted: env.TOOL_RESTRICTED,
+        cloud: deps.workspaceCloud
+    });
+    const creationWall = { person: limiters.workspaceCreate, address: limiters.workspaceCreateAddress };
+    const canCreateWorkspace = async (userId, via, address) => {
+        try {
+            if ((await workspaceCreationRefusal(db, creationPolicy, { userId, via })) !== null)
+                return false;
+            // Honest about the rate wall too (read-only, nothing is spent): a
+            // person the route would answer 429 is not offered the entry.
+            return !(await workspaceCreateWallClosed(creationWall, address, userId));
+        }
+        catch (cause) {
+            logger.warn({ err: cause }, '/me: canCreateWorkspace could not be computed — answering false');
+            return false;
+        }
+    };
+    const CREDENTIAL_PROVIDER_ID = 'credential';
+    // Cloud only (null on oss): the hub's no-access url, built once here where
+    // the hub is known and handed to the session extras by both callers.
+    const hubNoAccessUrl = hub
+        ? `${hub.issuerUrl.replace(/\/+$/, '')}/no-access?client_id=${encodeURIComponent(hub.clientId)}`
+        : null;
+    const cloudSessionExtras = async (userId, noAccessUrl) => {
+        const [onboardingRows, accountRows] = await Promise.all([
+            db
+                .select({ dismissedAt: userOnboarding.dismissedAt })
+                .from(userOnboarding)
+                .where(eq(userOnboarding.userId, userId))
+                .limit(1),
+            db.select({ providerId: account.providerId }).from(account).where(eq(account.userId, userId))
+        ]);
+        const providers = new Set(accountRows.map((r) => r.providerId));
+        return {
+            firstRunPending: onboardingRows[0]?.dismissedAt == null,
+            ssoOnly: providers.has(HUB_SSO_PROVIDER_ID) && !providers.has(CREDENTIAL_PROVIDER_ID),
+            hubDenied: deps.hubDeniedOrgs?.(userId) ?? [],
+            hubNoAccessUrl: noAccessUrl
+        };
+    };
+    // The zero-state re-admission: one cached reconcile pass, then the
+    // session is resolved again (the selection rule picks the workspace) and
+    // passed through the live gate exactly as authContext would. Any verdict
+    // other than a resolved, admitted principal keeps the zero state.
+    const readmitAfterReconcile = async (c, userId) => {
+        try {
+            await deps.reconcileForZeroState?.(userId);
+            const resolved = await resolveSessionPrincipal(c, chassisRegistry);
+            if (!resolved || resolved.userId !== userId)
+                return null;
+            const admitted = await admitPrincipal(c, resolved, deps.principalGate);
+            return admitted.ok ? admitted.principal : null;
+        }
+        catch (cause) {
+            logger.warn({ err: cause, userId }, '/me: zero-state re-admission failed — answering the zero state');
+            return null;
+        }
+    };
+    // ── GET /me — whoami across all credential paths ─────────────────────────
+    // No blanket requireAuth: the ZERO-MEMBERSHIP session state is route-local
+    // (user-scoped federation). A LIVE session whose user holds no active
+    // membership — the cloud operator before break-glass, a hub user whose
+    // last org was removed — resolves to a null principal (principal
+    // resolution requires a membership) but must NOT read as "signed out":
+    // /me answers 200 with `workspaces: [], workspace: null` so the dashboard
+    // renders the no-organization zero state instead of a login bounce.
+    // Machine credentials keep their 401: an invalid/zero-membership key or
+    // bearer dies inside authContext before this handler ever runs, so the
+    // session lookup below can only ever fire for cookie-authenticated
+    // requests.
+    api.openapi(meRoute, async (c) => {
+        let principal = c.get('principal');
+        let zeroStateUser = null;
+        if (!principal) {
+            // The zero state exists ONLY for the selector-less default request: a
+            // session that NAMED a workspace and failed its membership check must
+            // keep the fail-closed 401 (no oracle about the workspace, and the
+            // dashboard's stale-selection self-heal keys on that failure). With
+            // no selector, a live session resolving to null principal means
+            // exactly "zero active memberships" (the shared resolveMembership
+            // default rule).
+            if (c.req.header(ACTIVE_WORKSPACE_HEADER)?.trim()) {
+                return c.json(err('unauthenticated', 'Authentication required'), 401);
+            }
+            const session = await auth.api.getSession({ headers: c.req.raw.headers });
+            if (!session?.user) {
+                return c.json(err('unauthenticated', 'Authentication required'), 401);
+            }
+            // Re-admission (cloud): the live gate never runs for a principal-less
+            // session, so the zero-state read runs the reconciler's pass itself
+            // (cached ~10 s, single-flight, retry-throttled — a polling refusal
+            // page is not a hub call per request). When the pass re-projected a
+            // membership, the session resolves again through the SAME resolver
+            // and gate authContext uses, and the answer is the normal shape.
+            if (deps.reconcileForZeroState) {
+                principal = await readmitAfterReconcile(c, session.user.id);
+            }
+            if (!principal)
+                zeroStateUser = session.user;
+        }
+        if (!principal) {
+            const user = zeroStateUser;
+            if (!user)
+                return c.json(err('unauthenticated', 'Authentication required'), 401);
+            return c.json({
+                user: { id: user.id, email: user.email, name: user.name },
+                workspace: null,
+                role: null,
+                origin: null,
+                via: 'session',
+                scopes: null,
+                apiKeyExpiresAt: null,
+                workspaces: [],
+                activeWorkspaceId: null,
+                // The zero state's CTA target on cloud: organizations are created
+                // at the hub, never locally (internal/federation.md).
+                hubManageUrl: hubManaged?.manageUrl ?? null,
+                // oss: always false here — a zero-membership user is not an active
+                // member of this instance. cloud: true with a live hub link (their
+                // next organization is created from this very state).
+                canCreateWorkspace: hub ? await canCreateWorkspace(user.id, 'session', clientIp(c)) : false,
+                // Cloud + session extras (SL-6): the zero state is session-only
+                // by construction, so only the edition gate applies here.
+                ...(hubNoAccessUrl !== null ? await cloudSessionExtras(user.id, hubNoAccessUrl) : {})
+            }, 200);
+        }
+        // Workspaces this credential can name (user-scoped credential model):
+        // EVERY credential kind lists ALL of the user's active memberships — a
+        // credential is the user, and the org is a per-request parameter. The
+        // order mirrors the selection rule (default first, then oldest), but
+        // clients must read the `default` flag explicitly, never infer it from
+        // the index. (A PINNED key still lists everything: the pin restricts
+        // which workspace the key can REACH, not what its holder may see —
+        // /me answers about the user behind the credential.)
+        const memberships = await db
+            .select({
+            id: workspaces.id,
+            name: workspaces.name,
+            role: workspaceMembers.role,
+            centralAccountId: workspaces.centralAccountId,
+            hubStatus: workspaces.hubStatus,
+            isDefault: workspaceMembers.isDefault,
+            lookTheme: workspaces.lookTheme,
+            lookPattern: workspaces.lookPattern,
+            lookField: workspaces.lookField,
+            lookGrain: workspaces.lookGrain
+        })
+            .from(workspaceMembers)
+            .innerJoin(workspaces, eq(workspaceMembers.workspaceId, workspaces.id))
+            .where(and(eq(workspaceMembers.userId, principal.userId), eq(workspaceMembers.isActive, true)))
+            .orderBy(desc(workspaceMembers.isDefault), asc(workspaceMembers.createdAt), asc(workspaceMembers.id));
+        // hubOrigin is the BOOLEAN projection flag (P7); the hub org id rides
+        // beside it since PRDCT-2947 (the person's own organization ids, which
+        // `--org <name>` resolves against). Map explicitly, never spread the row.
+        const wireWorkspaces = memberships.map((m) => ({
+            id: m.id,
+            name: m.name,
+            role: m.role,
+            hubOrigin: m.centralAccountId !== null,
+            centralAccountId: m.centralAccountId,
+            look: { theme: m.lookTheme, pattern: m.lookPattern, field: m.lookField, grain: m.lookGrain },
+            suspended: m.hubStatus === 'suspended',
+            default: m.isDefault
+        }));
+        const active = wireWorkspaces.find((m) => m.id === principal.workspaceId);
+        return c.json({
+            user: { id: principal.userId, email: principal.email, name: principal.name },
+            workspace: {
+                id: principal.workspaceId,
+                name: active?.name ?? '',
+                // The ACTIVE workspace's flag comes from the principal itself —
+                // accountRef IS the request workspace's centralAccountId, read
+                // live by every credential resolver.
+                hubOrigin: Boolean(principal.accountRef),
+                look: active?.look ?? { theme: null, pattern: null, field: null, grain: null }
+            },
+            role: principal.role,
+            origin: principal.origin,
+            via: principal.via,
+            scopes: principal.scopes ? [...principal.scopes] : null,
+            apiKeyExpiresAt: principal.apiKeyExpiresAt ?? null,
+            workspaces: wireWorkspaces,
+            activeWorkspaceId: principal.workspaceId,
+            hubManageUrl: hubManaged && principal.accountRef ? hubManaged.manageUrl : null,
+            // A session a demo link opened creates no workspace (POST /workspaces
+            // refuses it before the rule), so it is not offered one.
+            canCreateWorkspace: c.get('demoPassId')
+                ? false
+                : await canCreateWorkspace(principal.userId, principal.via, clientIp(c)),
+            // Cloud + SESSION only (SL-6): machine credentials never carry the
+            // onboarding/hint-watch keys — the banner and the auto-sign-out are
+            // browser concerns.
+            ...(hubNoAccessUrl !== null && principal.via === 'session'
+                ? await cloudSessionExtras(principal.userId, hubNoAccessUrl)
+                : {})
+        }, 200);
+    });
+    // First-run onboarding dismiss (SL-6): cloud-only — an oss boot leaves
+    // POST /me/onboarding/dismiss to the JSON 404 terminator. Session-only
+    // (unlisted in the machine scope allowlist; route-local session check).
+    if (hub) {
+        registerOnboardingRoutes(api, { db, auth });
+    }
+    // Workspace creation (PRDCT-2444 / PRDCT-2443): one route, both editions.
+    // Session-only — unlisted in the machine scope allowlist, re-checked in
+    // the handler; self-audited into the NEW workspace (audit-exempt path).
+    registerWorkspaceRoutes(api, {
+        db,
+        auth,
+        audit,
+        registry: chassisRegistry,
+        logger,
+        clientIp,
+        wall: creationWall,
+        maxPerUser: env.MAX_WORKSPACES_PER_USER,
+        restricted: env.TOOL_RESTRICTED,
+        cloud: deps.workspaceCloud,
+        guestForbiddenMessage: tool.copy.guestForbidden,
+        displayName: tool.identity.displayName
+    });
+    // ── Platform modules ─────────────────────────────────────────────────────
+    // Break-glass first: it self-authenticates (superadmin sessions may carry
+    // NO membership, so principal can be null) and is deliberately UNLISTED in
+    // the machine scope allowlist — keys/tokens 403 fail-closed above.
+    registerBreakGlassRoutes(api, {
+        db,
+        auth,
+        audit,
+        logger,
+        superadminEmails: env.SUPERADMIN_EMAILS
+    });
+    // CLI email-OTP → API-key mint: PUBLIC pre-auth routes (listed in
+    // PUBLIC_API_PATHS) riding the emailOTP plugin; rate-limited above. Also
+    // registers DELETE /cli/auth/key — the authenticated self-revoke (CLI
+    // logout), NOT public, open to machines under the tool's write scope. On
+    // cloud (hubSso present) the mint pair refuses 403 cli_otp_disabled — the
+    // D1 hub-only entrance closure; the self-revoke stays open.
+    registerCliAuthRoutes(api, {
+        db,
+        auth,
+        email,
+        apiKeys: apiKeyService,
+        audit,
+        logger,
+        hubSso,
+        cliKeyScopes: tool.scopes.cliKey,
+        routes: { cliAuthCompleteRoute },
+        displayName: tool.identity.displayName
+    });
+    // CLI cross-tool connect (internal/federation.md P5): PUBLIC exchange of a
+    // hub-minted 120 s JWT (+ its H3 offline grant) for a USER-scoped API
+    // key. Registered ONLY on cloud — an oss boot leaves the path to the JSON
+    // 404 terminator below, so the self-host edition provably carries zero
+    // hub surface here.
+    if (hubSso && deps.hubGrant) {
+        registerSsoConnectRoutes(api, {
+            db,
+            auth,
+            hubSso,
+            grant: deps.hubGrant,
+            apiKeys: apiKeyService,
+            audit,
+            logger,
+            cliKeyScopes: tool.scopes.cliKey,
+            routes: { ssoCliConnectRoute }
+        });
+    }
+    // Single logout (SL-2): cloud-only like /sso/cli-connect — an oss boot
+    // leaves POST /sso/logout to the JSON 404 terminator. Deliberately
+    // UNLISTED in the machine scope allowlist: sessions only (incl.
+    // zero-membership — the handler resolves the session route-locally).
+    if (hubSso && deps.hubLogout && hub) {
+        registerSsoLogoutRoutes(api, {
+            auth,
+            logout: deps.hubLogout,
+            hint: {
+                name: hub.hintCookieName,
+                domain: hub.hintCookieDomain,
+                secure: env.PUBLIC_BASE_URL.startsWith('https://')
+            },
+            logger
+        });
+    }
+    registerMemberRoutes(api, {
+        db,
+        auth,
+        publicBaseUrl: env.PUBLIC_BASE_URL,
+        accountDeletion: deps.accountDeletion,
+        hubManaged,
+        guestTargetMessage: tool.copy.guestTarget,
+        onMembershipRemoval: tool.membershipRemoval
+    });
+    // Teams: the tool's own on self-hosted (and in a cloud-local workspace), the
+    // hub's projection in a hub-origin workspace, where the members' gate refuses the writes.
+    registerTeamRoutes(api, { db, hubManaged });
+    if (demoSignIn) {
+        registerDemoPassRoutes(api, {
+            db,
+            publicBaseUrl: env.PUBLIC_BASE_URL,
+            emailDomains: env.DEMO_SIGN_IN_EMAIL_DOMAINS,
+            guestTargetMessage: tool.copy.guestTarget
+        });
+    }
+    registerApiKeyRoutes(api, db, apiKeyService, { apiKeysListRoute, apiKeyCreateRoute, apiKeyRevokeRoute });
+    registerInvitationRoutes(api, {
+        db,
+        env,
+        auth,
+        email,
+        audit,
+        registry: chassisRegistry,
+        logger,
+        mailBrand: { name: tool.identity.displayName, tagline: tool.copy.mail.tagline },
+        inviteMail: { pitch: tool.copy.mail.invitePitch, preheader: tool.copy.mail.invitePreheader },
+        hubManaged,
+        // CLOUD-5: no local-password accounts minted through invitations on cloud.
+        ssoOnly: Boolean(deps.hubSso),
+        ...(demoSignIn ? { demoSession: demoSessionJudge(db) } : {})
+    });
+    // Projects: a subgroup of the workspace with its own members. Deliberately
+    // handed NO `hubManaged`: project membership is the tool's own on both
+    // editions, picked among the workspace's existing members.
+    registerProjectRoutes(api, { db });
+    registerAuditRoutes(api, db);
+    registerExportRoutes(api, {
+        db,
+        env,
+        storage: deps.storage,
+        audit,
+        limiters,
+        clientIp,
+        logger,
+        workspaceExportRoute: tool.scopes.contractRoutes.workspaceExportRoute,
+        // The tool's export entries, bound to its domain once, here. No slot: no field.
+        ...(tool.api.exportEntries ? { exportEntries: tool.api.exportEntries(deps.domain) } : {})
+    });
+    registerFileRoutes(api, {
+        service: deps.fileService,
+        storage: deps.storage,
+        registry: chassisRegistry,
+        env,
+        logger,
+        // The tool's blob policy. ADR 011 sharp edge closed: a blob referenced
+        // by a live version manifest of the tool's resource is not deletable
+        // through the generic files surface; SL-B1: the generic files surface
+        // authorizes per RESOURCE, not per workspace — the ADR 013 policy expressed
+        // as a WHERE predicate.
+        ...tool.api.filePolicy(deps.domain),
+        fileDeleteRoute: tool.scopes.contractRoutes.fileDeleteRoute,
+        fileInUse: tool.copy.fileInUse
+    });
+    // The tool's own routes: AFTER the files routes, BEFORE the OpenAPI
+    // document and the JSON 404. The tool keeps its own internal order.
+    const routesContext = { ...rateLimitContext, instanceId };
+    tool.api.routes?.(api, routesContext, deps.domain);
+    // Generated ONCE here, at the end of route registration — never per
+    // request (api/openapi-doc.ts explains why that mattered).
+    registerOpenApiDoc(api, {
+        openapi: '3.1.0',
+        info: {
+            title: 'Platform API',
+            version: env.APP_VERSION
+        },
+        servers: [{ url: '/api/v1' }]
+    });
+    // ── JSON 404 terminator — registered LAST ────────────────────────────────
+    // An unmatched /api/v1 path answers the API wire shape instead of falling
+    // through to the SPA catch-all (which would hand a browser session the
+    // dashboard HTML with a 200). Machine principals never reach this: the
+    // fail-closed scope gate already 403s every unlisted endpoint above.
+    api.all('*', (c) => c.json(err('not_found', 'Not found'), 404));
+    return api;
+}
+//# sourceMappingURL=create-api.js.map