@insiderfinance/totalfinance 0.1.0

package/modules/http/src/bin.ts

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * `totalfinance-http` — the loopback, read-only local HTTP server over the operation registry (Stage 7A
+ * Decision 7). Machine-first: the bound address is printed as one JSON line on stdout; logs on stderr.
+ */
+
+import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { OPERATION_BUDGETS } from '@totalfinance/workflows';
+import {
+  REGISTRY_PROFILES,
+  createFileArtifactStore,
+  createFileAuthorizationStore,
+  createFileExecutionJournalStore,
+  createLocalJobRunner,
+  registryForProfile,
+  type RegistryProfile,
+} from '@totalfinance/workflows/local';
+import { createLocalHttpServer } from './server.js';
+
+const HELP = `totalfinance-http — TotalFinance local HTTP server (loopback, read-only by default)
+
+Usage
+  totalfinance-http [--port 8787] [--host 127.0.0.1] [--openapi]
+                [--profile default|options|research|full] [--packs a,b]
+                [--store <dir>] [--max-input-bytes <n>] [--seed <int>] [--deadline-ms <n>]
+                [--allow-non-loopback]
+                [--capability <name>] [--token-file <path>]
+  totalfinance-http --help | --version
+
+  --openapi          print the OpenAPI 3.1 document to stdout and exit (no server)
+  --store <dir>      the artifact/job store directory (default ~/.totalfinance/store); attaches handles, jobs, authorizations, and journals
+  --capability <n>   enable a server capability (repeatable); writes require a bearer token
+  --token-file <path>  read the bearer token from a protected file (overrides TOTALFINANCE_HTTP_TOKEN)
+  TOTALFINANCE_HTTP_TOKEN  alternative environment variable; never put a secret in CLI arguments
+  --allow-non-loopback  bind a non-loopback host; public reads remain; bring your own network/TLS boundary
+
+Writes (including trade:approve) require a server-owned token of at least 32 random characters.
+Generate one with node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))'
+and store it in a file readable only by your user (mode 0600), or a protected environment.
+Send Authorization: Bearer <token> for writes and POST /jobs or /jobs/{id}/cancel.
+Without a token, job creation/cancellation are disabled; read-only inline analytics remain public.
+JSON POST requests require Content-Type: application/json. Host and any Origin must name this
+server and its bound port; null/foreign origins are refused. No credential appears in discovery or logs.
+
+Routes: GET /openapi.json · GET /capabilities · GET /operations · GET /operations/{id} ·
+POST /operations/{id}/run · POST /jobs · GET /jobs/{id} · POST /jobs/{id}/cancel · GET /jobs/{id}/result ·
+GET /artifacts/{uri}
+`;
+
+function integerFlag(name: string, value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (!/^-?\d+$/.test(value)) {
+    process.stderr.write(
+      `totalfinance-http: --${name} must be an integer, received ${JSON.stringify(value)}\n`,
+    );
+    process.exit(2);
+  }
+  return Number(value);
+}
+
+async function main(): Promise<void> {
+  let values: ReturnType<typeof parse>['values'];
+  try {
+    values = parse().values;
+  } catch {
+    // Unknown arguments may contain an accidentally supplied secret; never repeat argv.
+    process.stderr.write(`totalfinance-http: invalid command-line options.\n${HELP}`);
+    process.exit(2);
+  }
+  if (values.help) {
+    process.stderr.write(HELP);
+    return;
+  }
+  if (values.version) {
+    const { WORKFLOWS_VERSION } = await import('@totalfinance/workflows');
+    process.stdout.write(
+      `${JSON.stringify({ 'totalfinance-http': WORKFLOWS_VERSION, node: process.version })}\n`,
+    );
+    return;
+  }
+  const profile = (values.profile ?? 'default') as RegistryProfile;
+  if (!REGISTRY_PROFILES.includes(profile)) {
+    process.stderr.write(
+      `totalfinance-http: --profile must be one of ${REGISTRY_PROFILES.join(', ')}\n`,
+    );
+    process.exit(2);
+  }
+  const packs =
+    values.packs === undefined
+      ? undefined
+      : values.packs
+          .split(',')
+          .map((p) => p.trim())
+          .filter(Boolean);
+  const registry = registryForProfile({ profile, ...(packs ? { packs } : {}) });
+  const storeFlag = values.store ?? join(homedir(), '.totalfinance', 'store');
+  const directory = isAbsolute(storeFlag) ? storeFlag : resolve(storeFlag);
+  const host = values.host ?? '127.0.0.1';
+  const port = integerFlag('port', values.port) ?? 8787;
+  const clock = () => new Date().toISOString();
+  const maxInputBytes = integerFlag('max-input-bytes', values['max-input-bytes']);
+  const defaultSeed = integerFlag('seed', values.seed);
+  const deadlineMs = integerFlag('deadline-ms', values['deadline-ms']);
+  const capabilities = values.capability === undefined ? undefined : [...values.capability];
+  let authenticationToken = process.env['TOTALFINANCE_HTTP_TOKEN'];
+  if (values['token-file'] !== undefined) {
+    try {
+      // A single trailing line ending is convenient for a protected text file; do not trim secrets.
+      authenticationToken = readFileSync(values['token-file'], 'utf8').replace(/\r?\n$/, '');
+    } catch {
+      throw new Error('Unable to read --token-file; supply a readable protected token file.');
+    }
+  }
+  const local = createLocalHttpServer({
+    registry,
+    artifacts: createFileArtifactStore({ directory }),
+    stores: {
+      authorization: createFileAuthorizationStore({ directory }),
+      journal: createFileExecutionJournalStore({ directory }),
+    },
+    ...(capabilities !== undefined ? { capabilities } : {}),
+    ...(authenticationToken !== undefined ? { authenticationToken } : {}),
+    jobs: createLocalJobRunner({
+      registry,
+      directory,
+      profile,
+      ...(packs ? { packs } : {}),
+      clock,
+    }),
+    host,
+    port,
+    ...(values['allow-non-loopback'] ? { allowNonLoopback: true } : {}),
+    budgets: {
+      maxInputBytes: maxInputBytes ?? OPERATION_BUDGETS.maxInputBytes.transportDefault,
+      ...(defaultSeed !== undefined ? { defaultSeed } : {}),
+      ...(deadlineMs !== undefined ? { deadlineMs } : {}),
+    },
+    clock,
+  });
+  if (values.openapi) {
+    process.stdout.write(`${JSON.stringify(local.document, null, 2)}\n`);
+    return;
+  }
+  const bound = await local.start();
+  process.stdout.write(
+    `${JSON.stringify({ listening: bound.url, host: bound.host, port: bound.port, profile, store: directory, operations: registry.size })}\n`,
+  );
+  process.stderr.write(
+    `totalfinance-http listening on ${bound.url} (profile ${profile}, ${registry.size} operations, store ${directory}); GET ${bound.url}/openapi.json\n`,
+  );
+  const shutdown = () => {
+    void local.stop().then(() => process.exit(0));
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+}
+
+function parse() {
+  return parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: false,
+    strict: true,
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+      port: { type: 'string' },
+      host: { type: 'string' },
+      openapi: { type: 'boolean' },
+      profile: { type: 'string' },
+      packs: { type: 'string' },
+      store: { type: 'string' },
+      'max-input-bytes': { type: 'string' },
+      seed: { type: 'string' },
+      'deadline-ms': { type: 'string' },
+      'allow-non-loopback': { type: 'boolean' },
+      capability: { type: 'string', multiple: true },
+      'token-file': { type: 'string' },
+    },
+  });
+}
+
+main().catch((error: unknown) => {
+  process.stderr.write(
+    `totalfinance-http: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
+  );
+  process.exit(70);
+});

package/modules/http/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * `@insiderfinance/totalfinance/http` — the local HTTP transport over the TotalFinance operation registry (Stage 7A):
+ * the OpenAPI 3.1 document generated from the registry, and the loopback read-only server behind
+ * the `totalfinance-http` binary. It owns no schema and no compute.
+ */
+
+export { openApiDocument } from './openapi.js';
+export type { OpenApiDocument, OpenApiDocumentInput } from './openapi.js';
+export { createLocalHttpServer, statusForError } from './server.js';
+export type { LocalHttpServer, LocalHttpServerBudgets, LocalHttpServerInput } from './server.js';

package/modules/http/src/openapi.ts

@@ -0,0 +1,488 @@
+/**
+ * OpenAPI 3.1 for the local HTTP server (Stage 7A Decision 7): generated from the registry — the
+ * operations' JSON Schemas verbatim (components keyed by id), one error schema (`OperationError`),
+ * and the `x-totalfinance` vendor extension carrying each operation's effect metadata and annotations.
+ * Deterministic (ids sorted) so the committed document diffs cleanly.
+ */
+
+import { ErrorCode, InputError } from '@totalfinance/core';
+import type { JSONSchema } from '@totalfinance/core/schema';
+import {
+  OPERATION_BUDGETS,
+  RESOURCE_HANDLE_SCHEMA,
+  WORKFLOWS_VERSION,
+  type OperationDescription,
+  type OperationRegistry,
+  operationResultSchema as sharedOperationResultSchema,
+} from '@totalfinance/workflows';
+import { operationWrites } from './security.js';
+
+export interface OpenApiDocumentInput {
+  registry: OperationRegistry;
+  /** The server url advertised in `servers` (default `http://127.0.0.1:8787`). */
+  serverUrl?: string;
+}
+
+/** The subset of OpenAPI 3.1 this document uses — enough to be typed, validated, and diffed. */
+export interface OpenApiDocument {
+  openapi: '3.1.0';
+  info: { title: string; version: string; description: string };
+  servers: { url: string; description: string }[];
+  paths: Record<string, Record<string, unknown>>;
+  components: {
+    schemas: Record<string, JSONSchema>;
+    securitySchemes: Record<string, { type: 'http'; scheme: 'bearer'; description: string }>;
+  };
+}
+
+const OPERATION_ERROR: JSONSchema = {
+  type: 'object',
+  description: 'Every non-2xx body: the same document the CLI prints and the MCP server returns.',
+  properties: {
+    code: {
+      type: 'string',
+      description: 'A registered TotalFinance error code (input.*, operation.*, …)',
+    },
+    message: { type: 'string' },
+    context: { type: 'object' },
+    operation: {
+      type: 'object',
+      properties: { id: { type: 'string' }, version: { type: 'string' } },
+      required: ['id', 'version'],
+    },
+  },
+  required: ['code', 'message', 'context', 'operation'],
+};
+
+const RESOURCE_HANDLE: JSONSchema = RESOURCE_HANDLE_SCHEMA;
+
+const JOB_RECORD: JSONSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    operation: {
+      type: 'object',
+      properties: { id: { type: 'string' }, version: { type: 'string' } },
+      required: ['id', 'version'],
+    },
+    state: {
+      type: 'string',
+      enum: ['accepted', 'queued', 'running', 'completed', 'failed', 'cancelled'],
+    },
+    progress: {
+      type: ['object', 'null'],
+      properties: { stage: { type: 'string' }, fraction: { type: ['number', 'null'] } },
+    },
+    inputsHash: { type: 'string' },
+    seed: { type: ['integer', 'null'] },
+    submittedAt: { type: 'string' },
+    startedAt: { type: ['string', 'null'] },
+    finishedAt: { type: ['string', 'null'] },
+    result: { oneOf: [{ $ref: '#/components/schemas/ResourceHandle' }, { type: 'null' }] },
+    error: { oneOf: [{ $ref: '#/components/schemas/OperationError' }, { type: 'null' }] },
+    usage: { type: 'object', properties: { elapsedMs: { type: ['number', 'null'] } } },
+  },
+  required: [
+    'id',
+    'operation',
+    'state',
+    'progress',
+    'inputsHash',
+    'seed',
+    'submittedAt',
+    'startedAt',
+    'finishedAt',
+    'result',
+    'error',
+    'usage',
+  ],
+};
+
+const OPERATION_DESCRIPTION: JSONSchema = {
+  type: 'object',
+  description: 'describeOperation(...) — the transport-neutral description every adapter renders.',
+  properties: {
+    id: { type: 'string' },
+    version: { type: 'string' },
+    title: { type: 'string' },
+    description: { type: 'string' },
+    inputSchema: { type: 'object' },
+    outputSchema: { type: ['object', 'null'] },
+    sideEffect: { type: 'string', enum: ['none', 'portfolio-state', 'external-order'] },
+    authorization: { type: 'string', enum: ['none', 'policy', 'human'] },
+    idempotency: { type: 'string', enum: ['not-applicable', 'optional', 'required'] },
+    deterministic: { type: 'boolean' },
+    stochastic: { oneOf: [{ type: 'boolean' }, { type: 'string', enum: ['per-call'] }] },
+    costClass: { type: 'string', enum: ['small', 'medium', 'large', 'job'] },
+    requiredCapabilities: { type: 'array', items: { type: 'string' } },
+    supportsCancellation: { type: 'boolean' },
+    handleFields: { type: 'array', items: { type: 'string' } },
+    annotations: {
+      type: 'object',
+      properties: {
+        readOnlyHint: { type: 'boolean' },
+        destructiveHint: { type: 'boolean' },
+        idempotentHint: { type: 'boolean' },
+        openWorldHint: { type: 'boolean' },
+      },
+      required: ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'],
+    },
+  },
+  required: [
+    'id',
+    'version',
+    'title',
+    'description',
+    'inputSchema',
+    'outputSchema',
+    'sideEffect',
+    'authorization',
+    'idempotency',
+    'deterministic',
+    'stochastic',
+    'costClass',
+    'requiredCapabilities',
+    'supportsCancellation',
+    'handleFields',
+    'annotations',
+  ],
+};
+
+function operationResultSchema(outputRef: string | null): JSONSchema {
+  // One envelope definition for every transport (workflows/envelope-schema): the HTTP document
+  // refers to the shared handle and per-operation output components by `$ref`.
+  return sharedOperationResultSchema({
+    ...(outputRef === null ? {} : { structured: { $ref: outputRef } }),
+    handle: { $ref: '#/components/schemas/ResourceHandle' },
+  });
+}
+
+const errorResponse = (description: string) => ({
+  description,
+  content: { 'application/json': { schema: { $ref: '#/components/schemas/OperationError' } } },
+});
+
+const ERROR_RESPONSES = {
+  '400': errorResponse('The input was refused (an input.* code).'),
+  '401': errorResponse('Missing or invalid bearer credential (operation.capability_missing).'),
+  '403': errorResponse(
+    'Untrusted Host/Origin, missing server capability, or mutations disabled without a credential.',
+  ),
+  '404': errorResponse('Unknown operation, job, or handle.'),
+  '413': errorResponse('The input exceeds the wire byte budget (operation.input_too_large).'),
+  '415': errorResponse(
+    'JSON POST requests require Content-Type: application/json (input.wrong_shape).',
+  ),
+  '422': errorResponse('The operation failed (any other operation error).'),
+  '500': errorResponse('Internal error (operation.internal).'),
+};
+
+function vendorExtension(description: OperationDescription): Record<string, unknown> {
+  return {
+    'x-totalfinance': {
+      sideEffect: description.sideEffect,
+      authorization: description.authorization,
+      idempotency: description.idempotency,
+      deterministic: description.deterministic,
+      stochastic: description.stochastic,
+      costClass: description.costClass,
+      supportsCancellation: description.supportsCancellation,
+      handleFields: description.handleFields,
+      annotations: description.annotations,
+    },
+  };
+}
+
+/** Generate the OpenAPI 3.1 document for a registry. */
+export function openApiDocument(input: OpenApiDocumentInput): OpenApiDocument {
+  const functionName = 'openApiDocument';
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new InputError(`${functionName}: input must be an object ({ registry, serverUrl? }).`, {
+      code: ErrorCode.InputWrongType,
+      context: { function: functionName, field: 'input' },
+    });
+  }
+  for (const key of Object.keys(input)) {
+    if (key !== 'registry' && key !== 'serverUrl') {
+      throw new InputError(
+        `${functionName}: unknown field "${key}" in input. Allowed fields: registry, serverUrl.`,
+        {
+          code: ErrorCode.InputUnknownField,
+          context: { function: functionName, field: 'input', key },
+        },
+      );
+    }
+  }
+  const registry = input.registry as unknown as Record<string, unknown> | null;
+  if (
+    registry === null ||
+    typeof registry !== 'object' ||
+    ['list', 'get', 'require', 'describe', 'run', 'packs'].some(
+      (member) => typeof registry[member] !== 'function',
+    ) ||
+    !Number.isSafeInteger(registry['size']) ||
+    (registry['size'] as number) < 0
+  ) {
+    throw new InputError(`${functionName}: input.registry must be an OperationRegistry.`, {
+      code: ErrorCode.InputWrongType,
+      context: { function: functionName, field: 'input.registry' },
+    });
+  }
+  if (
+    input.serverUrl !== undefined &&
+    (typeof input.serverUrl !== 'string' || !/^https?:\/\//.test(input.serverUrl))
+  ) {
+    throw new InputError(`${functionName}: input.serverUrl must be an http(s) url when present.`, {
+      code:
+        typeof input.serverUrl === 'string' ? ErrorCode.InputWrongShape : ErrorCode.InputWrongType,
+      context: { function: functionName, field: 'input.serverUrl' },
+    });
+  }
+  const descriptions = [...input.registry.list()].sort((a, b) =>
+    a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
+  );
+  const schemas: Record<string, JSONSchema> = {
+    OperationError: OPERATION_ERROR,
+    ResourceHandle: RESOURCE_HANDLE,
+    JobRecord: JOB_RECORD,
+    OperationDescription: OPERATION_DESCRIPTION,
+    OperationResult: operationResultSchema(null),
+  };
+  const paths: Record<string, Record<string, unknown>> = {
+    '/operations': {
+      get: {
+        operationId: 'listOperations',
+        summary: 'Every registered operation, described',
+        responses: {
+          '200': {
+            description: 'The descriptions, in registry order.',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: { $ref: '#/components/schemas/OperationDescription' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    '/operations/{id}': {
+      get: {
+        operationId: 'describeOperation',
+        summary: 'One operation, described',
+        parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+        responses: {
+          '200': {
+            description: 'The description.',
+            content: {
+              'application/json': { schema: { $ref: '#/components/schemas/OperationDescription' } },
+            },
+          },
+          '404': ERROR_RESPONSES['404'],
+        },
+      },
+    },
+  };
+  for (const description of descriptions) {
+    const inputName = `${description.id}.input`;
+    const outputName = `${description.id}.output`;
+    schemas[inputName] = description.inputSchema;
+    if (description.outputSchema !== null) schemas[outputName] = description.outputSchema;
+    const resultName = `${description.id}.result`;
+    schemas[resultName] = operationResultSchema(
+      description.outputSchema !== null ? `#/components/schemas/${outputName}` : null,
+    );
+    paths[`/operations/${description.id}/run`] = {
+      post: {
+        operationId: `run.${description.id}`,
+        security: operationWrites(description) ? [{ localBearer: [] }] : [],
+        summary: description.title,
+        description: description.description,
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': { schema: { $ref: `#/components/schemas/${inputName}` } },
+          },
+        },
+        responses: {
+          '200': {
+            description: 'The OperationResult.',
+            content: {
+              'application/json': { schema: { $ref: `#/components/schemas/${resultName}` } },
+            },
+          },
+          ...ERROR_RESPONSES,
+        },
+        ...vendorExtension(description),
+      },
+    };
+  }
+  paths['/jobs'] = {
+    post: {
+      operationId: 'submitJob',
+      security: [{ localBearer: [] }],
+      description:
+        'Job creation persists state even for analytics and always requires the server-owned bearer token. Without a configured token, submission is disabled; inline read-only /run calls remain public.',
+      summary:
+        'Submit an operation as a job (a job-class operation runs in a worker; others inline)',
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                id: { type: 'string' },
+                input: { type: 'object' },
+                seed: { type: 'integer' },
+              },
+              required: ['id', 'input'],
+              additionalProperties: false,
+            },
+          },
+        },
+      },
+      responses: {
+        '202': {
+          description: 'The accepted (or, inline, terminal) record.',
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/JobRecord' } } },
+        },
+        ...ERROR_RESPONSES,
+      },
+    },
+  };
+  paths['/jobs/{id}'] = {
+    get: {
+      operationId: 'getJob',
+      summary: 'The job record',
+      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+      responses: {
+        '200': {
+          description: 'The record.',
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/JobRecord' } } },
+        },
+        '404': ERROR_RESPONSES['404'],
+      },
+    },
+  };
+  paths['/jobs/{id}/cancel'] = {
+    post: {
+      operationId: 'cancelJob',
+      security: [{ localBearer: [] }],
+      description:
+        'Cancellation mutates persisted job state and always requires the server-owned bearer token. No JSON body is required.',
+      summary: 'Cancel a job — the worker is terminated; the record moves to cancelled',
+      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+      responses: {
+        '200': {
+          description: 'The cancelled (or already terminal) record.',
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/JobRecord' } } },
+        },
+        ...ERROR_RESPONSES,
+      },
+    },
+  };
+  paths['/jobs/{id}/result'] = {
+    get: {
+      operationId: 'getJobResult',
+      summary: 'The stored OperationResult of a completed job',
+      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+      responses: {
+        '200': {
+          description: 'The OperationResult.',
+          content: {
+            'application/json': { schema: { $ref: '#/components/schemas/OperationResult' } },
+          },
+        },
+        '404': ERROR_RESPONSES['404'],
+        '409': errorResponse('The job was cancelled (operation.cancelled) or has not finished.'),
+        '422': ERROR_RESPONSES['422'],
+      },
+    },
+  };
+  paths['/artifacts/{uri}'] = {
+    get: {
+      operationId: 'getArtifact',
+      summary: 'A stored value by handle uri (url-encoded)',
+      parameters: [{ name: 'uri', in: 'path', required: true, schema: { type: 'string' } }],
+      responses: {
+        '200': {
+          description: 'The handle and the stored value.',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  handle: { $ref: '#/components/schemas/ResourceHandle' },
+                  value: { type: 'object' },
+                },
+                required: ['handle', 'value'],
+              },
+            },
+          },
+        },
+        '404': ERROR_RESPONSES['404'],
+      },
+    },
+  };
+  paths['/capabilities'] = {
+    get: {
+      operationId: 'capabilities',
+      summary: 'Packs, budgets, the seed policy, and which stores are attached',
+      responses: {
+        '200': {
+          description: 'The capabilities.',
+          content: { 'application/json': { schema: { type: 'object' } } },
+        },
+      },
+    },
+  };
+  paths['/openapi.json'] = {
+    get: {
+      operationId: 'openapi',
+      summary: 'This document',
+      responses: {
+        '200': {
+          description: 'The OpenAPI 3.1 document.',
+          content: { 'application/json': { schema: { type: 'object' } } },
+        },
+      },
+    },
+  };
+  // Host/Origin and malformed-target checks also protect all discovery and read routes.
+  for (const methods of Object.values(paths)) {
+    for (const operation of Object.values(methods)) {
+      const route = operation as { responses: Record<string, unknown> };
+      route.responses['400'] ??= ERROR_RESPONSES['400'];
+      route.responses['403'] ??= ERROR_RESPONSES['403'];
+    }
+  }
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'TotalFinance local operations',
+      version: WORKFLOWS_VERSION,
+      description:
+        `The local, read-only-by-default, loopback HTTP transport over the TotalFinance operation registry (${descriptions.length} operations across ${input.registry.packs().length} packs). ` +
+        `Host and any Origin must match this server's host and bound port; null/foreign origins are refused. JSON POSTs require application/json. ` +
+        `Enabled writes (including trade:approve) and job creation/cancellation require a server-owned bearer credential; read-only analytics and discovery remain unauthenticated. A credential does not grant capabilities. ` +
+        `Every request body is the operation's own input schema; every error body is one OperationError. ` +
+        `Wire byte budget default ${OPERATION_BUDGETS.maxInputBytes.transportDefault}.`,
+    },
+    servers: [{ url: input.serverUrl ?? 'http://127.0.0.1:8787', description: 'loopback' }],
+    paths,
+    components: {
+      schemas,
+      securitySchemes: {
+        localBearer: {
+          type: 'http',
+          scheme: 'bearer',
+          description:
+            'Server-owned authenticationToken, at least 32 cryptographically random characters. Configure via --token-file or TOTALFINANCE_HTTP_TOKEN; send Authorization: Bearer <token>. Required for enabled writes (including approval), job creation and cancellation. Absent configuration disables job mutations. Read-only analytics remain public. No token is published in this document.',
+        },
+      },
+    },
+  };
+}