@antasphere/chassis-contract 0.0.0-stage → 1.0.0

package/src/routes/index.ts

@@ -0,0 +1,1146 @@
+import { createRoute, z } from '@hono/zod-openapi';
+import type { ChassisContract } from '../define.js';
+import type { ToolIdentity } from '../identity.js';
+import { apiErrorSchema, cursorPageQuerySchema } from '../schemas/common.js';
+import { instanceInfoSchema } from '../schemas/instance.js';
+import { setupRequestSchema, setupResponseSchema } from '../schemas/setup.js';
+import { onboardingDismissedSchema } from '../schemas/me.js';
+import {
+  defaultWorkspaceSchema,
+  defaultWorkspaceSetSchema,
+  workspaceCreatedSchema,
+  workspaceCreateSchema,
+  workspaceUpdatedSchema,
+  workspaceUpdateSchema
+} from '../schemas/workspaces.js';
+import {
+  memberChangeEmailLinkRequestSchema,
+  memberChangeEmailLinkSchema,
+  memberResetLinkSchema,
+  membersListSchema,
+  memberSchema,
+  memberUpdateSchema
+} from '../schemas/members.js';
+import {
+  invitationAcceptedSchema,
+  invitationAcceptSchema,
+  invitationCreatedSchema,
+  invitationCreateSchema,
+  invitationLookupSchema,
+  invitationsListSchema
+} from '../schemas/invitations.js';
+import { auditListQuerySchema, auditListSchema } from '../schemas/audit.js';
+import {
+  cliAuthCompleteSchema,
+  cliAuthRequestedSchema,
+  cliAuthRequestSchema,
+  cliAuthRevokedSchema
+} from '../schemas/cli-auth.js';
+import { ssoCliConnectSchema } from '../schemas/sso-connect.js';
+import { ssoLogoutResponseSchema } from '../schemas/sso-logout.js';
+import {
+  breakGlassClaimOwnershipRequestSchema,
+  breakGlassClaimOwnershipSchema,
+  breakGlassResetTwoFactorRequestSchema,
+  breakGlassResetTwoFactorSchema
+} from '../schemas/break-glass.js';
+import { fileSchema, filesListSchema, fileUploadedSchema, fileUploadQuerySchema } from '../schemas/files.js';
+import {
+  demoPassesListSchema,
+  demoPassMintedSchema,
+  demoPassMintSchema,
+  demoPassSchema
+} from '../schemas/demo-passes.js';
+import {
+  projectCreateSchema,
+  projectMemberAddSchema,
+  projectMemberParamsSchema,
+  projectMemberRoleSchema,
+  projectMemberSchema,
+  projectMembersListSchema,
+  projectPersonMemberSchema,
+  projectSchema,
+  projectsListQuerySchema,
+  projectsListSchema,
+  projectTeamMemberSchema,
+  projectTeamParamsSchema,
+  projectUpdateSchema
+} from '../schemas/projects.js';
+import {
+  teamCreateSchema,
+  teamMemberAddSchema,
+  teamMemberParamsSchema,
+  teamMemberSchema,
+  teamMembersListSchema,
+  teamSchema,
+  teamsListQuerySchema,
+  teamsListSchema,
+  teamUpdateSchema
+} from '../schemas/teams.js';
+
+/**
+ * Server-only entry: route contracts for @hono/zod-openapi. Importing this
+ * path pulls Hono — the dashboard and SDK must import the package root
+ * instead. The OpenAPI document at /api/v1/openapi.json is generated from
+ * these definitions; they are the single source of truth for the API shape.
+ */
+
+export const jsonBody = <T>(schema: T, description: string) => ({
+  content: { 'application/json': { schema } },
+  description
+});
+
+/**
+ * JSON REQUEST bodies are marked `required` so @hono/zod-openapi always runs
+ * the body validator. Without the flag, a request with a missing/non-JSON
+ * content-type SKIPS validation entirely and hands the handler `{}` cast as
+ * the body type — a guaranteed TypeError → 500 on every pre-auth body route
+ * (the schema-mismatch 400 path never runs). Responses keep plain jsonBody
+ * (`required` is not a response-object field).
+ */
+export const jsonRequestBody = <T>(schema: T, description: string) => ({
+  ...jsonBody(schema, description),
+  required: true
+});
+
+export const errorResponses = {
+  400: jsonBody(apiErrorSchema, 'Validation error'),
+  401: jsonBody(apiErrorSchema, 'Not authenticated'),
+  403: jsonBody(apiErrorSchema, 'Not authorized'),
+  404: jsonBody(apiErrorSchema, 'Not found'),
+  410: jsonBody(apiErrorSchema, 'Gone'),
+  429: jsonBody(apiErrorSchema, 'Rate limited'),
+  500: jsonBody(apiErrorSchema, 'Internal error')
+} as const;
+
+/** Opt-in retry-safe creates: replay-or-409 semantics per docs/security/security.md. */
+export const idempotencyHeaders = z.object({
+  'idempotency-key': z.string().min(1).max(200).optional()
+});
+
+/**
+ * Every `{id}` path param is a UUID, validated in the contract: a non-UUID
+ * id answers a clean 400 validation_error instead of reaching Postgres and
+ * surfacing its uuid-cast error as a sanitized 500 (see LESSONS.md).
+ */
+export const uuidParams = z.object({ id: z.uuid() });
+
+export const instanceRoute = createRoute({
+  method: 'get',
+  path: '/instance',
+  tags: ['instance'],
+  summary: 'Instance discovery (unauthenticated, cacheable)',
+  responses: {
+    200: jsonBody(instanceInfoSchema, 'Instance descriptor')
+  }
+});
+
+export const setupRoute = createRoute({
+  method: 'post',
+  path: '/setup',
+  tags: ['instance'],
+  summary: 'One-shot first-boot setup: create the owner and the workspace',
+  request: {
+    body: jsonRequestBody(setupRequestSchema, 'Setup payload')
+  },
+  responses: {
+    201: jsonBody(setupResponseSchema, 'Instance initialized'),
+    400: errorResponses[400],
+    403: errorResponses[403],
+    410: errorResponses[410],
+    500: errorResponses[500]
+  }
+});
+
+// ── Onboarding dismiss (cloud edition only) ─────────────────────────────────
+// SESSION-ONLY like /sso/logout: deliberately UNLISTED in the machine scope
+// allowlist (fail-closed 403 for keys/tokens); the handler resolves the
+// session route-locally so zero-membership sessions can dismiss too. The
+// route exists ONLY on EDITION=cloud; oss answers the JSON 404 terminator.
+
+export const onboardingDismissRoute = createRoute({
+  method: 'post',
+  path: '/me/onboarding/dismiss',
+  tags: ['auth'],
+  summary: 'Dismiss the first-run welcome (cloud edition; sessions only; idempotent)',
+  responses: {
+    200: jsonBody(onboardingDismissedSchema, 'Dismissal recorded — firstRunPending is now false'),
+    401: errorResponses[401],
+    403: errorResponses[403]
+  }
+});
+
+// ── Workspace creation (PRDCT-2444 / PRDCT-2443) ────────────────────────────
+// SESSION-ONLY: deliberately UNLISTED in the machine scope allowlist
+// (fail-closed 403 for keys/tokens) and re-checked in the handler. One route
+// for both editions: local creation on self-hosted, creation at the hub AS
+// THE CALLER + immediate local projection on cloud.
+
+export const workspaceCreateRoute = createRoute({
+  method: 'post',
+  path: '/workspaces',
+  tags: ['workspaces'],
+  summary: 'Create another workspace with the caller as its owner (sessions only)',
+  request: { body: jsonRequestBody(workspaceCreateSchema, 'The new workspace'), headers: idempotencyHeaders },
+  responses: {
+    201: jsonBody(workspaceCreatedSchema, 'The created workspace (its LOCAL id)'),
+    400: errorResponses[400],
+    401: jsonBody(
+      apiErrorSchema,
+      'Not authenticated; hub_grant_expired or hub_reauth_required on cloud — both healed by signing in again'
+    ),
+    403: jsonBody(
+      apiErrorSchema,
+      'session_required, guest_forbidden, workspace_creation_disabled, workspace_limit_reached, hub_link_required, hub_unavailable, hub_refused'
+    ),
+    409: jsonBody(apiErrorSchema, 'Idempotency conflict'),
+    429: errorResponses[429]
+  }
+});
+
+// ── The person's default workspace (PRDCT-2815) ─────────────────────────────
+// A setting of the PERSON, not of a workspace: the route names no workspace
+// in its path and is open to every credential of the person (the machine
+// scope allowlist lists it under the write scope, so the CLI sets it), a key
+// pinned to one workspace excepted.
+
+export const defaultWorkspaceSetRoute = createRoute({
+  method: 'put',
+  path: '/me/default-workspace',
+  tags: ['workspaces'],
+  summary: 'Choose the workspace a request naming none resolves to, or clear the choice (self-hosted)',
+  request: {
+    body: jsonRequestBody(defaultWorkspaceSetSchema, 'A workspace the caller is an active member of, or null')
+  },
+  responses: {
+    200: jsonBody(defaultWorkspaceSchema, 'The default as it now is'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: jsonBody(apiErrorSchema, 'hub_managed (cloud: set on the account site), key_pinned'),
+    404: jsonBody(apiErrorSchema, 'Not a workspace the caller is an active member of')
+  }
+});
+
+// ── Members ──────────────────────────────────────────────────────────────────
+
+export const workspaceUpdateRoute = createRoute({
+  method: 'patch',
+  path: '/workspace',
+  tags: ['workspaces'],
+  summary: "Change the active workspace's name or look (owner/admin, sessions only)",
+  request: { body: jsonRequestBody(workspaceUpdateSchema, 'The name, the look, or both') },
+  responses: {
+    200: jsonBody(workspaceUpdatedSchema, 'The workspace as it now is'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: jsonBody(
+      apiErrorSchema,
+      'session_required, insufficient_role, guest_forbidden, hub_managed (a rename of a hub-origin workspace)'
+    )
+  }
+});
+
+export const membersListRoute = createRoute({
+  method: 'get',
+  path: '/members',
+  tags: ['members'],
+  summary: 'List workspace members (cursor-paginated)',
+  request: { query: cursorPageQuerySchema },
+  responses: { 200: jsonBody(membersListSchema, 'Members, newest first'), 401: errorResponses[401] }
+});
+
+export const memberUpdateRoute = createRoute({
+  method: 'patch',
+  path: '/members/{id}',
+  tags: ['members'],
+  summary: 'Change a member role or active state (admin+)',
+  request: {
+    params: uuidParams,
+    body: jsonRequestBody(memberUpdateSchema, 'Fields to change')
+  },
+  responses: {
+    200: jsonBody(memberSchema, 'Updated member'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403],
+    404: errorResponses[404]
+  }
+});
+
+export const memberDeleteRoute = createRoute({
+  method: 'delete',
+  path: '/members/{id}',
+  tags: ['members'],
+  summary: 'Delete a member account (admin+; sessions only — files they uploaded stay)',
+  request: { params: uuidParams },
+  responses: {
+    200: jsonBody(memberSchema, 'Deleted member (final snapshot)'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403],
+    404: errorResponses[404],
+    409: jsonBody(apiErrorSchema, 'Account belongs to other workspaces (member_of_other_workspaces)')
+  }
+});
+
+export const memberRemoveRoute = createRoute({
+  method: 'post',
+  path: '/members/{id}/remove',
+  tags: ['members'],
+  summary:
+    'Remove a member from the workspace: the membership off, their project grants and team seats deleted, the account kept (admin+; sessions only)',
+  request: { params: uuidParams },
+  responses: {
+    200: jsonBody(memberSchema, 'The removed member (inactive)'),
+    400: jsonBody(apiErrorSchema, 'cannot_remove_self, last_owner'),
+    401: errorResponses[401],
+    403: jsonBody(
+      apiErrorSchema,
+      'insufficient_role, forbidden (an owner is removed by an owner), hub_managed'
+    ),
+    404: errorResponses[404]
+  }
+});
+
+export const memberResetLinkRoute = createRoute({
+  method: 'post',
+  path: '/members/{id}/reset-link',
+  tags: ['members'],
+  summary: 'Generate a one-time password reset link for a member (OWNER only)',
+  request: { params: uuidParams, headers: idempotencyHeaders },
+  responses: {
+    200: jsonBody(memberResetLinkSchema, 'Copyable reset link + expiry'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403],
+    404: errorResponses[404],
+    409: jsonBody(apiErrorSchema, 'Idempotency conflict')
+  }
+});
+
+export const memberChangeEmailLinkRoute = createRoute({
+  method: 'post',
+  path: '/members/{id}/change-email-link',
+  tags: ['members'],
+  summary: 'Generate a one-time email change link for a member (OWNER only; the link also signs them in)',
+  request: {
+    params: uuidParams,
+    body: jsonRequestBody(memberChangeEmailLinkRequestSchema, 'The new email address'),
+    headers: idempotencyHeaders
+  },
+  responses: {
+    200: jsonBody(memberChangeEmailLinkSchema, 'Copyable email change link + expiry'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403],
+    404: errorResponses[404],
+    409: jsonBody(apiErrorSchema, 'Email already in use (email_taken) or idempotency conflict')
+  }
+});
+
+// ── Projects ─────────────────────────────────────────────────────────────────
+// A subgroup of a workspace with its own members and roles. The tiered answer
+// on every route: 404 to whoever cannot read the project (its existence is
+// not probeable), 403 to a proven reader who may not do the act, 409
+// `project_archived` on every mutation of an archived project but unarchive.
+// Project membership is LOCAL to the tool on both editions: these routes are
+// never under the hub-managed gate.
+
+const projectErrors = {
+  400: errorResponses[400],
+  401: errorResponses[401],
+  403: jsonBody(apiErrorSchema, 'guest_forbidden, or insufficient_project_role for a proven reader'),
+  404: errorResponses[404]
+} as const;
+const projectArchived409 = jsonBody(apiErrorSchema, 'The project is archived (project_archived)');
+
+export const projectsListRoute = createRoute({
+  method: 'get',
+  path: '/projects',
+  tags: ['projects'],
+  summary: 'List the projects the caller belongs to (every project for a workspace owner or admin)',
+  request: { query: projectsListQuerySchema },
+  responses: {
+    200: jsonBody(projectsListSchema, 'Projects, newest first'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403]
+  }
+});
+
+export const projectCreateRoute = createRoute({
+  method: 'post',
+  path: '/projects',
+  tags: ['projects'],
+  summary: 'Create a project; the caller becomes its first manager',
+  request: { body: jsonRequestBody(projectCreateSchema, 'The new project'), headers: idempotencyHeaders },
+  responses: {
+    201: jsonBody(projectSchema, 'The created project'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403],
+    409: jsonBody(apiErrorSchema, 'Idempotency conflict')
+  }
+});
+
+export const projectGetRoute = createRoute({
+  method: 'get',
+  path: '/projects/{id}',
+  tags: ['projects'],
+  summary: "Read a project, with the caller's own role on it",
+  request: { params: uuidParams },
+  responses: { 200: jsonBody(projectSchema, 'The project'), ...projectErrors }
+});
+
+export const projectUpdateRoute = createRoute({
+  method: 'patch',
+  path: '/projects/{id}',
+  tags: ['projects'],
+  summary: "Change a project's name, description or metadata (manager)",
+  request: { params: uuidParams, body: jsonRequestBody(projectUpdateSchema, 'Fields to change') },
+  responses: {
+    200: jsonBody(projectSchema, 'The project as it now is'),
+    ...projectErrors,
+    409: projectArchived409
+  }
+});
+
+export const projectArchiveRoute = createRoute({
+  method: 'post',
+  path: '/projects/{id}/archive',
+  tags: ['projects'],
+  summary: 'Archive a project: out of the default list and read-only (manager). A project is never deleted',
+  request: { params: uuidParams },
+  responses: {
+    200: jsonBody(projectSchema, 'The archived project'),
+    ...projectErrors,
+    409: projectArchived409
+  }
+});
+
+export const projectUnarchiveRoute = createRoute({
+  method: 'post',
+  path: '/projects/{id}/unarchive',
+  tags: ['projects'],
+  summary: 'Bring an archived project back (manager)',
+  request: { params: uuidParams },
+  responses: {
+    200: jsonBody(projectSchema, 'The project, live again'),
+    ...projectErrors,
+    409: jsonBody(apiErrorSchema, 'The project is not archived (project_not_archived)')
+  }
+});
+
+export const projectMembersListRoute = createRoute({
+  method: 'get',
+  path: '/projects/{id}/members',
+  tags: ['projects'],
+  summary: "List a project's members and their roles (cursor-paginated)",
+  request: { params: uuidParams, query: cursorPageQuerySchema },
+  responses: { 200: jsonBody(projectMembersListSchema, 'Members, newest first'), ...projectErrors }
+});
+
+export const projectMemberAddRoute = createRoute({
+  method: 'post',
+  path: '/projects/{id}/members',
+  tags: ['projects'],
+  summary:
+    "Add one of the workspace's own active members (by user id or email) or one of its teams (by id) to a project (manager)",
+  request: {
+    params: uuidParams,
+    body: jsonRequestBody(projectMemberAddSchema, 'Who, and with which role'),
+    headers: idempotencyHeaders
+  },
+  responses: {
+    201: jsonBody(projectMemberSchema, 'The new project member, a person or a team'),
+    ...projectErrors,
+    403: jsonBody(apiErrorSchema, 'guest_forbidden, insufficient_project_role, or guest_target'),
+    404: jsonBody(apiErrorSchema, 'Project not found, member_not_found or team_not_found in this workspace'),
+    409: jsonBody(apiErrorSchema, 'project_archived, already_member, or idempotency conflict')
+  }
+});
+
+export const projectMemberRoleRoute = createRoute({
+  method: 'patch',
+  path: '/projects/{id}/members/{userId}',
+  tags: ['projects'],
+  summary: "Change a project member's role (manager)",
+  request: {
+    params: projectMemberParamsSchema,
+    body: jsonRequestBody(projectMemberRoleSchema, 'The new role')
+  },
+  responses: {
+    200: jsonBody(projectPersonMemberSchema, 'The member as it now is'),
+    ...projectErrors,
+    409: projectArchived409
+  }
+});
+
+export const projectMemberRemoveRoute = createRoute({
+  method: 'delete',
+  path: '/projects/{id}/members/{userId}',
+  tags: ['projects'],
+  summary: 'Remove a member from a project (manager; a member may remove themselves)',
+  request: { params: projectMemberParamsSchema },
+  responses: {
+    200: jsonBody(projectPersonMemberSchema, 'The removed member (final snapshot)'),
+    ...projectErrors,
+    409: projectArchived409
+  }
+});
+
+export const projectTeamRoleRoute = createRoute({
+  method: 'patch',
+  path: '/projects/{id}/teams/{teamId}',
+  tags: ['projects'],
+  summary: "Change a team's role on a project (manager)",
+  request: {
+    params: projectTeamParamsSchema,
+    body: jsonRequestBody(projectMemberRoleSchema, 'The new role')
+  },
+  responses: {
+    200: jsonBody(projectTeamMemberSchema, 'The team entry as it now is'),
+    ...projectErrors,
+    409: projectArchived409
+  }
+});
+
+export const projectTeamRemoveRoute = createRoute({
+  method: 'delete',
+  path: '/projects/{id}/teams/{teamId}',
+  tags: ['projects'],
+  summary: 'Remove a team from a project (manager); its people keep their own entries',
+  request: { params: projectTeamParamsSchema },
+  responses: {
+    200: jsonBody(projectTeamMemberSchema, 'The removed team entry (final snapshot)'),
+    ...projectErrors,
+    409: projectArchived409
+  }
+});
+
+// ── Teams ────────────────────────────────────────────────────────────────────
+// Named groups of the workspace's people, on both editions (PRDCT-2813). Every
+// non-guest member reads them; owners and admins write, and in a hub-origin
+// workspace every write answers 403 `hub_managed` (the members' pattern).
+
+/** The refusals every team route shares (the writes add their own). */
+const teamErrors = {
+  401: errorResponses[401],
+  403: jsonBody(apiErrorSchema, 'guest_forbidden, forbidden (not an owner or admin), or hub_managed'),
+  404: errorResponses[404]
+};
+const slugTaken409 = jsonBody(
+  apiErrorSchema,
+  'Another team of this workspace already uses that slug (slug_taken)'
+);
+
+export const teamsListRoute = createRoute({
+  method: 'get',
+  path: '/teams',
+  tags: ['teams'],
+  summary: "List the workspace's teams (every member; cursor-paginated)",
+  request: { query: teamsListQuerySchema },
+  responses: {
+    200: jsonBody(teamsListSchema, 'Teams, newest first'),
+    401: errorResponses[401],
+    403: teamErrors[403]
+  }
+});
+
+export const teamGetRoute = createRoute({
+  method: 'get',
+  path: '/teams/{id}',
+  tags: ['teams'],
+  summary: 'Read one team of the workspace (every member)',
+  request: { params: uuidParams },
+  responses: { 200: jsonBody(teamSchema, 'The team'), ...teamErrors }
+});
+
+export const teamCreateRoute = createRoute({
+  method: 'post',
+  path: '/teams',
+  tags: ['teams'],
+  summary: 'Create a team (owner or admin; refused in a hub-origin workspace)',
+  request: { body: jsonRequestBody(teamCreateSchema, 'Name, optional slug'), headers: idempotencyHeaders },
+  responses: {
+    201: jsonBody(teamSchema, 'The created team'),
+    400: errorResponses[400],
+    ...teamErrors,
+    409: jsonBody(apiErrorSchema, 'slug_taken, or idempotency conflict')
+  }
+});
+
+export const teamUpdateRoute = createRoute({
+  method: 'patch',
+  path: '/teams/{id}',
+  tags: ['teams'],
+  summary: 'Rename a team or change its slug (owner or admin; refused in a hub-origin workspace)',
+  request: { params: uuidParams, body: jsonRequestBody(teamUpdateSchema, 'Fields to change') },
+  responses: {
+    200: jsonBody(teamSchema, 'The updated team'),
+    400: errorResponses[400],
+    ...teamErrors,
+    409: slugTaken409
+  }
+});
+
+export const teamDeleteRoute = createRoute({
+  method: 'delete',
+  path: '/teams/{id}',
+  tags: ['teams'],
+  summary: 'Delete a team (owner or admin; the memberships stay; refused in a hub-origin workspace)',
+  request: { params: uuidParams },
+  responses: { 200: jsonBody(teamSchema, 'The deleted team (final snapshot)'), ...teamErrors }
+});
+
+export const teamMembersListRoute = createRoute({
+  method: 'get',
+  path: '/teams/{id}/members',
+  tags: ['teams'],
+  summary: "List a team's members (every member of the workspace; cursor-paginated)",
+  request: { params: uuidParams, query: cursorPageQuerySchema },
+  responses: { 200: jsonBody(teamMembersListSchema, 'Team members, newest first'), ...teamErrors }
+});
+
+export const teamMemberAddRoute = createRoute({
+  method: 'post',
+  path: '/teams/{id}/members',
+  tags: ['teams'],
+  summary: "Seat one of the workspace's own active members in a team, by user id or email (owner or admin)",
+  request: {
+    params: uuidParams,
+    body: jsonRequestBody(teamMemberAddSchema, 'Who'),
+    headers: idempotencyHeaders
+  },
+  responses: {
+    201: jsonBody(teamMemberSchema, 'The team member'),
+    400: errorResponses[400],
+    ...teamErrors,
+    404: jsonBody(apiErrorSchema, 'Team not found, or member_not_found in this workspace'),
+    409: jsonBody(apiErrorSchema, 'already_member, or idempotency conflict')
+  }
+});
+
+export const teamMemberRemoveRoute = createRoute({
+  method: 'delete',
+  path: '/teams/{id}/members/{userId}',
+  tags: ['teams'],
+  summary: 'Unseat a member from a team (owner or admin; the membership stays)',
+  request: { params: teamMemberParamsSchema },
+  responses: { 200: jsonBody(teamMemberSchema, 'The removed team member'), ...teamErrors }
+});
+
+// ── Demo passes ──────────────────────────────────────────────────────────────
+// A link an owner mints so that one member is signed in without a password,
+// for a demonstration (the demo pass spec). The three routes are registered
+// ONLY while DEMO_SIGN_IN is on, on the self-hosted edition: otherwise each
+// path answers what any unknown path answers. OWNER and SESSION only: an
+// admin or a member gets 403, a machine credential never reaches them (the
+// paths are unlisted in the scope allowlist). The redeem,
+// `POST /auth/demo/redeem`, is an endpoint of the sign-in library and has no
+// route contract here (its shapes are `demoPassRedeemSchema` and
+// `demoPassRedeemedSchema`).
+
+const demoPassErrors = {
+  401: errorResponses[401],
+  403: jsonBody(apiErrorSchema, 'forbidden (owners only), or sessions_only for a machine credential')
+} as const;
+
+export const demoPassesListRoute = createRoute({
+  method: 'get',
+  path: '/demo/passes',
+  tags: ['demo'],
+  summary: "List the workspace's demo passes, newest first (owner; never carries a secret)",
+  responses: { 200: jsonBody(demoPassesListSchema, 'Demo passes, newest first'), ...demoPassErrors }
+});
+
+export const demoPassMintRoute = createRoute({
+  method: 'post',
+  path: '/demo/passes',
+  tags: ['demo'],
+  summary: 'Mint a demo pass for a member (owner); the secret is in this answer only',
+  request: { body: jsonRequestBody(demoPassMintSchema, 'The member, the page, the lifetime') },
+  responses: {
+    201: jsonBody(demoPassMintedSchema, 'The pass, its secret and its link, shown once'),
+    400: jsonBody(
+      apiErrorSchema,
+      'validation_error (a lifetime out of 1 to 10080 minutes), or invalid_demo_path: not a same-origin path'
+    ),
+    401: errorResponses[401],
+    403: jsonBody(
+      apiErrorSchema,
+      'In this order: owner_target (another owner), demo_address_required (not a demonstration address), two_factor_enrolled, guest_target, cross_workspace_target; or forbidden (owners only), sessions_only'
+    ),
+    404: jsonBody(apiErrorSchema, 'no_such_member: no member of this workspace holds that address')
+  }
+});
+
+export const demoPassRevokeRoute = createRoute({
+  method: 'delete',
+  path: '/demo/passes/{id}',
+  tags: ['demo'],
+  summary: 'Revoke a demo pass (owner; idempotent). The sessions it opened end with it',
+  request: { params: uuidParams },
+  responses: {
+    200: jsonBody(demoPassSchema, 'The pass, revoked'),
+    400: errorResponses[400],
+    ...demoPassErrors,
+    404: jsonBody(apiErrorSchema, 'not_found: no such pass in this workspace')
+  }
+});
+
+// ── Invitations ──────────────────────────────────────────────────────────────
+
+export const invitationsListRoute = createRoute({
+  method: 'get',
+  path: '/invitations',
+  tags: ['invitations'],
+  summary: 'List invitations (admin+, cursor-paginated)',
+  request: { query: cursorPageQuerySchema },
+  responses: {
+    200: jsonBody(invitationsListSchema, 'Invitations, newest first'),
+    401: errorResponses[401],
+    403: errorResponses[403]
+  }
+});
+
+export const invitationCreateRoute = createRoute({
+  method: 'post',
+  path: '/invitations',
+  tags: ['invitations'],
+  summary: 'Invite by email (admin+). Always returns a copyable accept link.',
+  request: { body: jsonRequestBody(invitationCreateSchema, 'Invitee'), headers: idempotencyHeaders },
+  responses: {
+    201: jsonBody(invitationCreatedSchema, 'Invitation + copyable link'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403],
+    409: jsonBody(apiErrorSchema, 'Already a member, already invited, or idempotency conflict')
+  }
+});
+
+export const invitationRevokeRoute = createRoute({
+  method: 'delete',
+  path: '/invitations/{id}',
+  tags: ['invitations'],
+  summary: 'Revoke an open invitation (admin+)',
+  request: { params: uuidParams },
+  responses: {
+    200: jsonBody(invitationSchemaRef(), 'Revoked invitation'),
+    401: errorResponses[401],
+    403: errorResponses[403],
+    404: errorResponses[404]
+  }
+});
+
+export const invitationLookupRoute = createRoute({
+  method: 'get',
+  path: '/invitations/lookup',
+  tags: ['invitations'],
+  summary: 'Resolve an invitation token (public; drives the accept page)',
+  request: { query: z.object({ token: z.string().min(16) }) },
+  responses: {
+    200: jsonBody(invitationLookupSchema, 'Invitation context'),
+    404: errorResponses[404]
+  }
+});
+
+export const invitationAcceptRoute = createRoute({
+  method: 'post',
+  path: '/invitations/accept',
+  tags: ['invitations'],
+  summary: 'Accept an invitation (public: creates the account when needed)',
+  request: { body: jsonRequestBody(invitationAcceptSchema, 'Token + credentials for new accounts') },
+  responses: {
+    200: jsonBody(invitationAcceptedSchema, 'Joined the workspace'),
+    400: errorResponses[400],
+    403: jsonBody(apiErrorSchema, 'Workspace membership is hub-managed (hub_managed, cloud edition)'),
+    404: errorResponses[404],
+    409: jsonBody(apiErrorSchema, 'Account exists — sign in to accept'),
+    410: errorResponses[410]
+  }
+});
+
+// ── CLI auth (browserless email-OTP → API key) ──────────────────────────────
+// The MINT pair is PUBLIC pre-auth like /setup: listed in PUBLIC_API_PATHS
+// (middleware/auth-context.ts) and deliberately UNLISTED in the machine
+// scope allowlist — a key/token presented there is pointless anyway (the flow
+// EXISTS to obtain a key) and 403s fail-closed. Sign-up stays closed: the
+// flow rides the emailOTP plugin's disableSignUp, so codes only sign in
+// EXISTING accounts. Both endpoints are rate-limited (request: the OTP wall
+// per IP + email; complete: the login wall per IP + email) and OTP
+// verification is better-auth's atomic, attempt-limited (3) check. On the
+// CLOUD edition both refuse outright (403 cli_otp_disabled) — hub-only login
+// (D1): CLI keys are minted via `antasphere login` + /sso/cli-connect there.
+// DELETE /cli/auth/key is the logout counterpart: an AUTHENTICATED route that
+// revokes exactly the PRESENTING key (self-revocation — possession is the
+// authority to kill itself), machine-allowed under the tool's write scope in the
+// scope allowlist, and open on BOTH editions (revocation narrows access).
+
+export const cliAuthRequestRoute = createRoute({
+  method: 'post',
+  path: '/cli/auth/request',
+  tags: ['cli-auth'],
+  summary: 'Send a sign-in code to an email (public; generic success — no account enumeration)',
+  request: { body: jsonRequestBody(cliAuthRequestSchema, 'The account email') },
+  responses: {
+    200: jsonBody(cliAuthRequestedSchema, 'Code sent if the account exists'),
+    400: jsonBody(apiErrorSchema, 'Validation error, or no email driver (otp_unavailable)'),
+    403: jsonBody(apiErrorSchema, 'cli_otp_disabled: cloud edition — sign in with `antasphere login`'),
+    429: errorResponses[429],
+    500: errorResponses[500]
+  }
+});
+
+export const cliAuthRevokeRoute = createRoute({
+  method: 'delete',
+  path: '/cli/auth/key',
+  tags: ['cli-auth'],
+  summary: 'Revoke the PRESENTING API key (CLI logout; self-revocation only)',
+  responses: {
+    200: jsonBody(cliAuthRevokedSchema, 'The presenting key is revoked'),
+    401: errorResponses[401],
+    403: jsonBody(apiErrorSchema, 'The credential is not an API key (sessions manage keys in the dashboard)')
+  }
+});
+
+// ── SSO logout (cloud edition only) ──────────────────────────────────────────
+// SESSION-ONLY by construction: deliberately UNLISTED in the machine scope
+// allowlist (middleware/scopes.ts), so API keys and OAuth bearers 403
+// fail-closed before the handler runs; the handler resolves the Better Auth
+// session route-locally (the /me zero-state pattern) so ZERO-MEMBERSHIP
+// sessions — the cloud operator pre-break-glass, a hub user whose last org
+// was removed — can still log out. The route exists ONLY on EDITION=cloud;
+// oss answers the JSON 404 terminator. Order inside the handler: resolve
+// session → build the hub end-session URL (any failure → null) → revoke the
+// local session server-side (better-auth's cookie-clearing Set-Cookie is
+// forwarded) → clear the shared hint cookie → respond. The local revoke and
+// hint clear happen even when url is null.
+
+export const ssoLogoutRoute = createRoute({
+  method: 'post',
+  path: '/sso/logout',
+  tags: ['sso'],
+  summary:
+    'Single logout (cloud edition; sessions only): revokes the local session, clears the SSO hint cookie, ' +
+    'and returns the hub end-session URL to visit (null = local signout only)',
+  responses: {
+    200: jsonBody(ssoLogoutResponseSchema, 'Local session revoked; url is the hub logout leg or null'),
+    401: errorResponses[401],
+    403: errorResponses[403]
+  }
+});
+
+// ── Break-glass (superadmin recovery, ADR 010) ──────────────────────────────
+// Session-only by construction: both paths are deliberately UNLISTED in the
+// machine scope allowlist (middleware/scopes.ts), so API keys and OAuth
+// tokens 403 fail-closed. The handlers additionally resolve the Better Auth
+// session directly and require a verified email on the SUPERADMIN_EMAILS
+// allowlist — no membership required (the recovering operator may have none).
+
+export const breakGlassClaimOwnershipRoute = createRoute({
+  method: 'post',
+  path: '/admin/break-glass/claim-ownership',
+  tags: ['admin'],
+  summary:
+    'Break-glass: make the calling superadmin (or a named existing user) an ACTIVE OWNER of a workspace (superadmin sessions only; adds an owner, never removes one; workspaceId required once the instance has several)',
+  request: {
+    body: jsonRequestBody(
+      breakGlassClaimOwnershipRequestSchema,
+      'Optional target user (default: the caller) and target workspace (required with several workspaces)'
+    )
+  },
+  responses: {
+    200: jsonBody(breakGlassClaimOwnershipSchema, 'The recovered owner membership'),
+    400: jsonBody(
+      apiErrorSchema,
+      'Validation error, or several workspaces and none named (workspace_required)'
+    ),
+    401: errorResponses[401],
+    403: errorResponses[403],
+    404: errorResponses[404],
+    409: jsonBody(apiErrorSchema, 'Instance not set up yet (not_setup)'),
+    429: errorResponses[429]
+  }
+});
+
+export const breakGlassResetTwoFactorRoute = createRoute({
+  method: 'post',
+  path: '/admin/break-glass/reset-2fa',
+  tags: ['admin'],
+  summary: "Break-glass: clear a locked-out user's 2FA (superadmin sessions only, audited)",
+  request: {
+    body: jsonRequestBody(breakGlassResetTwoFactorRequestSchema, 'The target user')
+  },
+  responses: {
+    200: jsonBody(breakGlassResetTwoFactorSchema, '2FA cleared (idempotent)'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403],
+    404: errorResponses[404],
+    429: errorResponses[429]
+  }
+});
+
+// ── Audit ────────────────────────────────────────────────────────────────────
+
+export const auditListRoute = createRoute({
+  method: 'get',
+  path: '/audit',
+  tags: ['audit'],
+  summary: 'Read the audit log (admin+, cursor-paginated, filterable)',
+  description:
+    'Every filter is optional and they combine with AND: `q` (actor email or action, case-insensitive), ' +
+    '`action` (comma-separated; an item ending in `.` matches the family), `actorVia` (comma-separated), ' +
+    '`actor` (a user id, or `system`), `resourceType`, `resourceId`, `from`/`to` (ISO 8601). ' +
+    'The cursor stays the last row id; the same filters must ride every page of one listing. ' +
+    '`total` is counted on the first page only.',
+  request: { query: auditListQuerySchema },
+  responses: {
+    200: jsonBody(auditListSchema, 'Audit entries, newest first'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: errorResponses[403]
+  }
+});
+
+// Local alias to keep the revoke route readable without a forward reference.
+function invitationSchemaRef() {
+  return invitationsListSchema.shape.invitations.element;
+}
+
+// ── Files ────────────────────────────────────────────────────────────────────
+// Every read here is per-resource authorized (ADR 013): you get the blobs you
+// uploaded plus those of the tool's resources you can read; workspace admins and
+// owners get the whole workspace. Anything outside that scope answers 404,
+// never 403 — a blob you cannot read must not be probeable.
+
+export const filesListRoute = createRoute({
+  method: 'get',
+  path: '/files',
+  tags: ['files'],
+  summary: 'List the files you can read (cursor-paginated)',
+  request: { query: cursorPageQuerySchema },
+  responses: { 200: jsonBody(filesListSchema, 'Files, newest first'), 401: errorResponses[401] }
+});
+
+export const fileGetRoute = createRoute({
+  method: 'get',
+  path: '/files/{id}',
+  tags: ['files'],
+  summary: 'File metadata (404 when you cannot read the blob)',
+  request: { params: uuidParams },
+  responses: {
+    200: jsonBody(fileSchema, 'File'),
+    401: errorResponses[401],
+    404: errorResponses[404]
+  }
+});
+
+export const fileUploadRoute = createRoute({
+  method: 'post',
+  path: '/files',
+  tags: ['files'],
+  summary: 'Upload raw bytes (streamed; content-type header = file type)',
+  request: {
+    query: fileUploadQuerySchema,
+    body: {
+      content: { 'application/octet-stream': { schema: z.any() } },
+      description: 'The file bytes'
+    }
+  },
+  responses: {
+    201: jsonBody(fileUploadedSchema, 'Stored (content-addressed, idempotent per workspace)'),
+    401: errorResponses[401],
+    403: errorResponses[403],
+    413: jsonBody(apiErrorSchema, 'Payload exceeds the instance size cap'),
+    400: errorResponses[400]
+  }
+});
+
+/**
+ * What the OpenAPI document says in the tool's own words, beyond its identity:
+ * today one sentence. Pure data, handed to `defineChassisRoutes`.
+ */
+export interface ChassisRoutesCopy {
+  /** How the document describes the 409 of `DELETE /files/{id}`: what references a blob is the tool's to name. */
+  fileInUseOpenApi: string;
+}
+
+/**
+ * The route contracts that carry something of the TOOL: every route whose
+ * request or response schema transitively holds `scopeSchema`, and the routes
+ * whose OpenAPI text names a scope or the tool's domain (the CLI key's grant,
+ * the export scope, the file-in-use refusal). Built from the contract
+ * `defineChassisContract({ scopes })` returned, from the tool's identity and
+ * from its wording of the document — no module-level state, one instantiation
+ * per tool, and no route object that no tool serves.
+ */
+export function defineChassisRoutes<TScope extends string>(
+  contract: ChassisContract<TScope>,
+  identity: Pick<ToolIdentity, 'cliKeyScopesLabel'> & { scopes: Pick<ToolIdentity['scopes'], 'dataExport'> },
+  copy: ChassisRoutesCopy
+) {
+  const {
+    meResponseSchema,
+    apiKeyCreatedSchema,
+    apiKeyCreateSchema,
+    apiKeySchema,
+    apiKeysListSchema,
+    cliAuthCompletedSchema
+  } = contract;
+
+  const meRoute = createRoute({
+    method: 'get',
+    path: '/me',
+    tags: ['auth'],
+    summary: 'Resolved identity of the calling principal',
+    responses: {
+      200: jsonBody(meResponseSchema, 'The caller identity'),
+      401: errorResponses[401]
+    }
+  });
+
+  // ── API keys ─────────────────────────────────────────────────────────────────
+
+  const apiKeysListRoute = createRoute({
+    method: 'get',
+    path: '/api-keys',
+    tags: ['api-keys'],
+    summary: 'List YOUR API keys (keys are user credentials; cursor-paginated)',
+    request: { query: cursorPageQuerySchema },
+    responses: { 200: jsonBody(apiKeysListSchema, 'Your API keys, newest first'), 401: errorResponses[401] }
+  });
+
+  const apiKeyCreateRoute = createRoute({
+    method: 'post',
+    path: '/api-keys',
+    tags: ['api-keys'],
+    summary:
+      'Mint an API key (sessions only — a key never mints a key). User-scoped by default; pass workspaceId to pin it to one workspace',
+    request: {
+      body: jsonRequestBody(apiKeyCreateSchema, 'Key name, scopes, and the optional workspace pin'),
+      headers: idempotencyHeaders
+    },
+    responses: {
+      201: jsonBody(apiKeyCreatedSchema, 'Created; the full key appears only here'),
+      400: errorResponses[400],
+      401: errorResponses[401],
+      403: jsonBody(apiErrorSchema, 'sessions_only, or no_membership for the requested pin'),
+      409: jsonBody(apiErrorSchema, 'Idempotency conflict')
+    }
+  });
+
+  const apiKeyRevokeRoute = createRoute({
+    method: 'delete',
+    path: '/api-keys/{id}',
+    tags: ['api-keys'],
+    summary: 'Revoke an API key (its creator only — keys are user credentials)',
+    request: { params: uuidParams },
+    responses: {
+      200: jsonBody(apiKeySchema, 'Revoked key'),
+      401: errorResponses[401],
+      403: errorResponses[403],
+      404: errorResponses[404]
+    }
+  });
+
+  const cliAuthCompleteRoute = createRoute({
+    method: 'post',
+    path: '/cli/auth/complete',
+    tags: ['cli-auth'],
+    summary: `Verify a sign-in code and mint an API key (shown once, ${identity.cliKeyScopesLabel})`,
+    request: { body: jsonRequestBody(cliAuthCompleteSchema, 'Email + code (+ optional key name/TTL)') },
+    responses: {
+      201: jsonBody(cliAuthCompletedSchema, 'Key minted; the full key appears only here'),
+      400: jsonBody(apiErrorSchema, 'Validation error, or no email driver (otp_unavailable)'),
+      401: jsonBody(apiErrorSchema, 'invalid_otp: wrong/expired code or no such account'),
+      403: jsonBody(
+        apiErrorSchema,
+        'two_factor_required, no active workspace membership, or cli_otp_disabled (cloud edition)'
+      ),
+      429: jsonBody(apiErrorSchema, 'Too many attempts'),
+      500: errorResponses[500]
+    }
+  });
+
+  // ── CLI cross-tool connect (cloud edition only) ─────────────────────────────
+  // PUBLIC pre-auth endpoint like /cli/auth/* (listed in PUBLIC_API_PATHS,
+  // unlisted in the machine scope allowlist): the hub-minted 120 s exchange
+  // JWT IS the credential — verified against the hub JWKS with hard iss/aud
+  // pinning, `purpose: 'sso-connect'` required, and the `jti` consumed
+  // one-time-use (a replay inside the TTL mints nothing). On success the user
+  // is JIT-provisioned through the SAME projection path as an SSO login and
+  // an ordinary API key is minted, bound to the projected workspace. The
+  // route exists ONLY on EDITION=cloud; oss answers 404. Rate-limited (the
+  // login wall, per IP).
+
+  const ssoCliConnectRoute = createRoute({
+    method: 'post',
+    path: '/sso/cli-connect',
+    tags: ['sso'],
+    summary: 'Exchange a hub-minted connect JWT for an API key (cloud edition; shown once)',
+    request: { body: jsonRequestBody(ssoCliConnectSchema, 'The hub exchange token') },
+    responses: {
+      201: jsonBody(cliAuthCompletedSchema, 'Key minted; the full key appears only here'),
+      400: jsonBody(apiErrorSchema, 'Validation error'),
+      401: jsonBody(apiErrorSchema, 'invalid_token: bad signature/iss/aud/purpose, expired, or replayed jti'),
+      403: jsonBody(
+        apiErrorSchema,
+        'Provisioning refused (identity/email conflict, link refused) or hub_grant_missing: no usable hub grant — a key is never minted born-dead'
+      ),
+      429: errorResponses[429],
+      500: errorResponses[500]
+    }
+  });
+
+  // ── Workspace ────────────────────────────────────────────────────────────────
+
+  // The export route names the scope a key needs in its summary, and that
+  // name is the tool's (`identity.scopes.dataExport`).
+  const workspaceExportRoute = createRoute({
+    method: 'get',
+    path: '/workspace/export',
+    tags: ['workspace'],
+    summary: `Full workspace export as a streamed zip (admin+; keys need ${identity.scopes.dataExport})`,
+    responses: {
+      // Deliberately NO `content` key on the 200: that is what lets the
+      // api.openapi handler legally return a plain streamed Response.
+      200: { description: 'Zip archive stream (application/zip)' },
+      401: errorResponses[401],
+      403: errorResponses[403],
+      429: errorResponses[429]
+    }
+  });
+
+  // ── Files ────────────────────────────────────────────────────────────────────
+
+  // The delete route carries the tool's wording of its 409: what references a
+  // blob is the tool's to name (`copy.fileInUseOpenApi`).
+  const fileDeleteRoute = createRoute({
+    method: 'delete',
+    path: '/files/{id}',
+    tags: ['files'],
+    summary: 'Delete a file (metadata soft-deleted, blob removed)',
+    request: { params: uuidParams },
+    responses: {
+      200: jsonBody(fileSchema, 'Deleted file'),
+      401: errorResponses[401],
+      404: errorResponses[404],
+      // ADR 011 blob-delete guard: a blob the tool still references is not
+      // deletable through the generic files surface.
+      409: jsonBody(apiErrorSchema, copy.fileInUseOpenApi)
+    }
+  });
+
+  return {
+    meRoute,
+    apiKeysListRoute,
+    apiKeyCreateRoute,
+    apiKeyRevokeRoute,
+    cliAuthCompleteRoute,
+    ssoCliConnectRoute,
+    workspaceExportRoute,
+    fileDeleteRoute
+  };
+}