@graphorin/server 0.6.1 → 0.7.0

package/dist/ws/upgrade.js.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.js","names":["unregister: (() => void) | undefined","payload: unknown","pkg.version","frame: ServerMessage","INVOKE_SCOPE: ParsedScope","ANONYMOUS_WS_SCOPES: ReadonlyArray<ParsedScope>"],"sources":["../../src/ws/upgrade.ts"],"sourcesContent":["import pkg from '../../package.json' with { type: 'json' };\n/**\n * Hono WebSocket upgrade handler. Wires the `@hono/node-ws` adapter\n * to the dispatcher: validates the subprotocol, runs auth (bearer\n * via `requireAuth` middleware OR ticket via the in-memory store),\n * and bridges the per-connection `WSContext` callbacks to the\n * dispatcher's RPC handler.\n *\n * ## Subprotocol + browser ticket flow\n *\n * The negotiated subprotocol is always {@link SUBPROTOCOL_NAME}\n * (`graphorin.protocol.v1`) - the canonical wire contract lives in\n * `@graphorin/protocol`'s `subprotocol.ts`. Two auth paths exist:\n *\n * - **Bearer (non-browser):** the client sends `Authorization:\n *   Bearer <token>` and a single `Sec-WebSocket-Protocol:\n *   graphorin.protocol.v1` token.\n * - **Ticket (browser):** the `WebSocket` constructor cannot set\n *   headers, so the browser client offers two subprotocol tokens -\n *   `graphorin.protocol.v1` and `ticket.<value>`. The server echoes\n *   back only the canonical name (in `app.ts`'s `handleProtocols`),\n *   and {@link resolveUpgradeAuth} extracts the ticket via\n *   `parseTicketSubprotocol` and redeems it against the single-use\n *   {@link WsTicketStore}. Tickets are short-lived and one-shot to\n *   bound replay.\n *\n * @packageDocumentation\n */\n\nimport {\n  ClientMessageSchema,\n  closeCodeFor,\n  isCancelledNotification,\n  isInitializeRequest,\n  isPingRequest,\n  isRunCancelRequest,\n  isSubscribeRequest,\n  isUnsubscribeRequest,\n  negotiateSubprotocol,\n  parseTicketSubprotocol,\n  RPC_ERROR_CODES,\n  type ServerMessage,\n  SUBPROTOCOL_NAME,\n} from '@graphorin/protocol';\nimport type { ParsedScope, TokenVerifier } from '@graphorin/security/auth';\nimport { parseScope, scopeMatches } from '@graphorin/security/auth';\nimport type { Context } from 'hono';\nimport type { WSContext, WSEvents } from 'hono/ws';\n\nimport type { ServerVariables } from '../internal/context.js';\nimport type { RunStateTracker } from '../runtime/run-state.js';\nimport type { WsDispatcher } from './dispatcher.js';\nimport type { WsTicket, WsTicketStore } from './ticket.js';\n\n/**\n * Public configuration accepted by {@link createWsUpgradeEvents}.\n *\n * @stable\n */\nexport interface WsUpgradeOptions {\n  readonly dispatcher: WsDispatcher;\n  readonly tickets: WsTicketStore;\n  /**\n   * Token verifier for bearer / ticket upgrades. Optional only in the\n   * IP-13 no-auth loopback mode (`anonymous: true`), where there is no\n   * verifier to construct and every upgrade is accepted.\n   */\n  readonly verifier?: TokenVerifier;\n  /**\n   * IP-13: authentication is disabled server-wide (`auth.kind='none'`).\n   * Accept the upgrade unconditionally with a full (`admin:*`) scope grant\n   * instead of silently refusing to mount the WS route. Trusted-loopback\n   * / single-operator mode only.\n   */\n  readonly anonymous?: boolean;\n  readonly runs?: RunStateTracker;\n  readonly now?: () => number;\n  /**\n   * Subprotocol the server advertises. Defaults to\n   * {@link SUBPROTOCOL_NAME}; tests can override to exercise the\n   * mismatch path.\n   */\n  readonly serverSubprotocol?: string;\n  readonly newSubscriptionId?: () => string;\n  readonly newSubscriberId?: () => string;\n}\n\n/**\n * Build the `WSEvents` callback bag the Hono helper consumes. The\n * function takes the request `Context` so the upgrade can read the\n * `Authorization` header / `Sec-WebSocket-Protocol` ticket directly.\n *\n * Production wiring on `@hono/node-ws`:\n *\n * ```ts\n * const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });\n * app.get('/v1/ws', upgradeWebSocket((c) => createWsUpgradeEvents(c, deps)));\n * injectWebSocket(serve(...));\n * ```\n *\n * @stable\n */\nexport async function createWsUpgradeEvents(\n  c: Context<{ Variables: ServerVariables }>,\n  options: WsUpgradeOptions,\n): Promise<WSEvents> {\n  const negotiated = negotiateSubprotocol(c.req.header('sec-websocket-protocol') ?? '');\n  if (negotiated === null) {\n    return rejectImmediately(closeCodeFor('protocol.violation'), 'protocol.violation');\n  }\n  const auth = await resolveUpgradeAuth(c, options);\n  if (auth.kind === 'denied') {\n    return rejectImmediately(closeCodeFor(auth.reason), auth.reason);\n  }\n\n  const subscriberId = options.newSubscriberId?.() ?? defaultSubscriberId();\n  const newSubscriptionId =\n    options.newSubscriptionId ?? (() => defaultSubscriptionId(subscriberId));\n\n  let unregister: (() => void) | undefined;\n  let initialized = false;\n\n  return {\n    onOpen: (_event, ws) => {\n      const handle = {\n        id: subscriberId,\n        tokenId: auth.tokenId,\n        grantedScopes: auth.grantedScopes,\n        send: (frame: ServerMessage) => {\n          ws.send(JSON.stringify(frame));\n        },\n        close: (code: number, reason: string) => {\n          ws.close(code, reason);\n        },\n        // IP-9: surface the socket's real backlog so the dispatcher's\n        // backpressure threshold measures something - the synchronous\n        // outstanding-events counter never accumulates.\n        bufferedAmount: () => {\n          const raw = (ws as { raw?: { bufferedAmount?: number } }).raw;\n          return raw?.bufferedAmount ?? 0;\n        },\n      };\n      const reg = options.dispatcher.registerSubscriber(handle);\n      unregister = reg.unregister;\n    },\n    onMessage: (event, ws) => {\n      const raw = typeof event.data === 'string' ? event.data : '';\n      let payload: unknown;\n      try {\n        payload = JSON.parse(raw);\n      } catch {\n        sendRpcError(ws, undefined, RPC_ERROR_CODES.PARSE_ERROR, 'Frame is not valid JSON.');\n        ws.close(closeCodeFor('protocol.violation'), 'protocol.violation');\n        return;\n      }\n      const parsed = ClientMessageSchema.safeParse(payload);\n      if (!parsed.success) {\n        sendRpcError(\n          ws,\n          (payload as { id?: string | number } | null)?.id,\n          RPC_ERROR_CODES.INVALID_REQUEST,\n          'Frame failed schema validation.',\n        );\n        ws.close(closeCodeFor('protocol.violation'), 'protocol.violation');\n        return;\n      }\n      const message = parsed.data;\n      if (isCancelledNotification(message)) {\n        // IP-8: only an initialized connection holding `agents:invoke` may\n        // cancel a run. A notification carries no id, so an unauthorised one\n        // is silently ignored (there is no error channel) rather than aborting\n        // an arbitrary run.\n        if (initialized && grantsInvokeScope(auth.grantedScopes)) {\n          options.runs?.abort(message.params.requestId, 'mcp-cancel');\n        }\n        return;\n      }\n      if (!initialized && !isInitializeRequest(message) && !isPingRequest(message)) {\n        // IP-21: a frame before `initialize` is a protocol-sequencing error,\n        // not an auth failure - the connection is already authenticated.\n        sendRpcError(\n          ws,\n          message.id,\n          RPC_ERROR_CODES.PROTOCOL_VIOLATION,\n          'Send `initialize` before any other RPC.',\n        );\n        return;\n      }\n      if (isInitializeRequest(message)) {\n        initialized = true;\n        sendRpcSuccess(ws, message.id, {\n          serverInfo: {\n            name: 'graphorin-server',\n            version: pkg.version,\n          },\n          capabilities: {\n            subscriptions: true,\n            replayBuffer: true,\n            sseFallback: true,\n          },\n        });\n        return;\n      }\n      if (isPingRequest(message)) {\n        const nonce = message.params?.nonce;\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'pong',\n            ...(nonce !== undefined ? { nonce } : {}),\n          } satisfies ServerMessage),\n        );\n        sendRpcSuccess(ws, message.id, { ok: true });\n        return;\n      }\n      if (isSubscribeRequest(message)) {\n        const subscriptionId = newSubscriptionId();\n        const result = options.dispatcher.subscribe({\n          subscriberId,\n          subject: message.params.subject,\n          subscriptionId,\n          ...(message.params.sinceEventId !== undefined\n            ? { sinceEventId: message.params.sinceEventId }\n            : {}),\n        });\n        if (!result.ok) {\n          sendRpcError(\n            ws,\n            message.id,\n            mapSubscribeErrorCode(result.reason),\n            mapSubscribeErrorMessage(result.reason, message.params.subject),\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          subscriptionId,\n          subject: message.params.subject,\n          snapshotEventId: result.snapshotEventId,\n          replayedCount: result.replayedCount,\n        });\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'subscribed',\n            subscriptionId,\n            subject: message.params.subject,\n            ...(result.snapshotEventId !== undefined\n              ? { snapshotEventId: result.snapshotEventId }\n              : {}),\n          } satisfies ServerMessage),\n        );\n        return;\n      }\n      if (isUnsubscribeRequest(message)) {\n        const removed = options.dispatcher.unsubscribe(message.params.subscriptionId);\n        if (!removed) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.SUBSCRIPTION_NOT_FOUND,\n            `Subscription '${message.params.subscriptionId}' not active.`,\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          subscriptionId: message.params.subscriptionId,\n          unsubscribed: true,\n        });\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'unsubscribed',\n            subscriptionId: message.params.subscriptionId,\n          } satisfies ServerMessage),\n        );\n        return;\n      }\n      if (isRunCancelRequest(message)) {\n        // IP-8: mirror the REST `POST /runs/:runId/abort` scope gate so a\n        // bearer token cannot abort an arbitrary run without `agents:invoke`.\n        if (!grantsInvokeScope(auth.grantedScopes)) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.SCOPE_DENIED,\n            \"Token lacks required scope 'agents:invoke'.\",\n          );\n          return;\n        }\n        const runId = message.params.runId;\n        const aborted = options.runs?.abort(runId, message.params.reason ?? 'rpc-cancel') === true;\n        if (!aborted) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.RUN_NOT_FOUND,\n            `Run '${runId}' is not active.`,\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          runId,\n          cancelled: true,\n          partialStateAvailable: true,\n        });\n        return;\n      }\n    },\n    onClose: () => {\n      try {\n        unregister?.();\n      } finally {\n        unregister = undefined;\n      }\n    },\n    onError: () => {\n      try {\n        unregister?.();\n      } finally {\n        unregister = undefined;\n      }\n    },\n  };\n}\n\nfunction sendRpcSuccess(ws: WSContext, id: string | number, result: unknown): void {\n  const frame: ServerMessage = { v: '1', jsonrpc: '2.0', id, result };\n  ws.send(JSON.stringify(frame));\n}\n\nfunction sendRpcError(\n  ws: WSContext,\n  id: string | number | undefined,\n  code: number,\n  message: string,\n): void {\n  const frame: ServerMessage = {\n    v: '1',\n    jsonrpc: '2.0',\n    id: id ?? 0,\n    error: { code, message },\n  };\n  ws.send(JSON.stringify(frame));\n}\n\nfunction rejectImmediately(code: number, reason: string): WSEvents {\n  return {\n    onOpen: (_event, ws) => {\n      ws.close(code, reason);\n    },\n  };\n}\n\ninterface ResolvedUpgradeAuthOk {\n  readonly kind: 'ok';\n  readonly tokenId: string;\n  readonly grantedScopes: ReadonlyArray<ParsedScope>;\n}\n\ninterface ResolvedUpgradeAuthDenied {\n  readonly kind: 'denied';\n  readonly reason: 'auth.required' | 'auth.invalid' | 'auth.scope_denied';\n}\n\ntype ResolvedUpgradeAuth = ResolvedUpgradeAuthOk | ResolvedUpgradeAuthDenied;\n\nasync function resolveUpgradeAuth(\n  c: Context<{ Variables: ServerVariables }>,\n  options: WsUpgradeOptions,\n): Promise<ResolvedUpgradeAuth> {\n  // Phase 14a's HTTP middleware may have already verified the\n  // bearer token (`requireAuth` runs before the upgrade route on\n  // the authenticated subtree); if so, reuse the result.\n  const state = c.var.state;\n  if (state?.auth?.kind === 'token') {\n    return {\n      kind: 'ok',\n      tokenId: state.auth.token.tokenId,\n      grantedScopes: state.auth.grantedScopes,\n    };\n  }\n  // IP-13: no-auth loopback mode - accept the upgrade with a full scope grant\n  // instead of silently failing to mount. Checked before ticket/bearer so the\n  // verifier may legitimately be absent.\n  if (options.anonymous === true) {\n    return { kind: 'ok', tokenId: 'anonymous', grantedScopes: ANONYMOUS_WS_SCOPES };\n  }\n  const ticketValue = parseTicketSubprotocol(c.req.header('sec-websocket-protocol') ?? '');\n  if (ticketValue !== undefined) {\n    const consumed = options.tickets.consume(ticketValue);\n    if (!consumed.ok) {\n      return { kind: 'denied', reason: 'auth.invalid' };\n    }\n    return acceptTicket(consumed.ticket);\n  }\n  const header = c.req.header('authorization') ?? c.req.header('Authorization');\n  if (header?.toLowerCase().startsWith('bearer ') === true) {\n    if (options.verifier === undefined) return { kind: 'denied', reason: 'auth.required' };\n    const token = header.slice(7).trim();\n    // P-05: pass the client IP like the HTTP auth middleware does, so\n    // the verifier's per-IP failure threshold / lockout engages for\n    // upgrade attempts too - without it `GET /v1/ws` was a\n    // lockout-free brute-force surface.\n    const ip = c.get('state')?.clientIp;\n    const verified = await options.verifier.verify(token, ip !== undefined ? { ip } : {});\n    if (!verified.ok) return { kind: 'denied', reason: 'auth.invalid' };\n    return {\n      kind: 'ok',\n      tokenId: verified.token.tokenId,\n      grantedScopes: verified.token.scopes,\n    };\n  }\n  return { kind: 'denied', reason: 'auth.required' };\n}\n\n/**\n * IP-8: the `agents:invoke` scope required to cancel a run over the WS\n * transport - the same requirement the REST `POST /runs/:runId/abort` route\n * enforces. `scopeMatches` honours wildcards (`agents:*`, `admin:*`).\n */\nconst INVOKE_SCOPE: ParsedScope = parseScope('agents:invoke');\n\n/**\n * IP-13: full scope grant handed to a no-auth (`auth.kind='none'`) upgrade.\n * `admin:*` matches every required scope, including the {@link INVOKE_SCOPE}\n * gate on run cancellation.\n */\nconst ANONYMOUS_WS_SCOPES: ReadonlyArray<ParsedScope> = [parseScope('admin:*')];\n\nfunction grantsInvokeScope(granted: ReadonlyArray<ParsedScope>): boolean {\n  for (const scope of granted) {\n    if (scopeMatches(scope, INVOKE_SCOPE)) return true;\n  }\n  return false;\n}\n\nfunction acceptTicket(ticket: WsTicket): ResolvedUpgradeAuth {\n  return {\n    kind: 'ok',\n    tokenId: ticket.tokenId,\n    grantedScopes: ticket.scopes,\n  };\n}\n\nfunction mapSubscribeErrorCode(\n  reason: 'subject-malformed' | 'subject-unknown' | 'subject-wildcard' | 'scope-denied',\n): number {\n  switch (reason) {\n    case 'scope-denied':\n      return RPC_ERROR_CODES.SCOPE_DENIED;\n    case 'subject-wildcard':\n      return RPC_ERROR_CODES.INVALID_PARAMS;\n    case 'subject-unknown':\n      return RPC_ERROR_CODES.METHOD_NOT_FOUND;\n    case 'subject-malformed':\n      return RPC_ERROR_CODES.INVALID_PARAMS;\n  }\n}\n\nfunction mapSubscribeErrorMessage(\n  reason: 'subject-malformed' | 'subject-unknown' | 'subject-wildcard' | 'scope-denied',\n  subject: string,\n): string {\n  switch (reason) {\n    case 'scope-denied':\n      return `Token lacks required scope for subject '${subject}'.`;\n    case 'subject-wildcard':\n      return `Wildcard subjects are not supported in this version. Subject: '${subject}'.`;\n    case 'subject-unknown':\n      return `Unknown subject grammar: '${subject}'.`;\n    case 'subject-malformed':\n      return `Subject '${subject}' is malformed.`;\n  }\n}\n\nfunction defaultSubscriberId(): string {\n  return `sub-conn-${randomToken(8)}`;\n}\n\nfunction defaultSubscriptionId(subscriberId: string): string {\n  return `${subscriberId}-${randomToken(6)}`;\n}\n\nfunction randomToken(length: number): string {\n  const bytes = new Uint8Array(length);\n  if (\n    typeof globalThis.crypto !== 'undefined' &&\n    typeof globalThis.crypto.getRandomValues === 'function'\n  ) {\n    globalThis.crypto.getRandomValues(bytes);\n  } else {\n    for (let i = 0; i < length; i += 1) {\n      bytes[i] = Math.floor(Math.random() * 256);\n    }\n  }\n  return Buffer.from(bytes).toString('hex');\n}\n\nvoid SUBPROTOCOL_NAME;\n"],"mappings":"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"}
+{"version":3,"file":"upgrade.js","names":["unregister: (() => void) | undefined","payload: unknown","pkg.version","frame: ServerMessage","ANONYMOUS_WS_SCOPES: ReadonlyArray<ParsedScope>"],"sources":["../../src/ws/upgrade.ts"],"sourcesContent":["import pkg from '../../package.json' with { type: 'json' };\n/**\n * Hono WebSocket upgrade handler. Wires the `@hono/node-ws` adapter\n * to the dispatcher: validates the subprotocol, runs auth (bearer\n * via `requireAuth` middleware OR ticket via the in-memory store),\n * and bridges the per-connection `WSContext` callbacks to the\n * dispatcher's RPC handler.\n *\n * ## Subprotocol + browser ticket flow\n *\n * The negotiated subprotocol is always {@link SUBPROTOCOL_NAME}\n * (`graphorin.protocol.v1`) - the canonical wire contract lives in\n * `@graphorin/protocol`'s `subprotocol.ts`. Two auth paths exist:\n *\n * - **Bearer (non-browser):** the client sends `Authorization:\n *   Bearer <token>` and a single `Sec-WebSocket-Protocol:\n *   graphorin.protocol.v1` token.\n * - **Ticket (browser):** the `WebSocket` constructor cannot set\n *   headers, so the browser client offers two subprotocol tokens -\n *   `graphorin.protocol.v1` and `ticket.<value>`. The server echoes\n *   back only the canonical name (in `app.ts`'s `handleProtocols`),\n *   and {@link resolveUpgradeAuth} extracts the ticket via\n *   `parseTicketSubprotocol` and redeems it against the single-use\n *   {@link WsTicketStore}. Tickets are short-lived and one-shot to\n *   bound replay.\n *\n * @packageDocumentation\n */\n\nimport {\n  ClientMessageSchema,\n  closeCodeFor,\n  isCancelledNotification,\n  isInitializeRequest,\n  isPingRequest,\n  isRunCancelRequest,\n  isSubscribeRequest,\n  isUnsubscribeRequest,\n  negotiateSubprotocol,\n  parseTicketSubprotocol,\n  RPC_ERROR_CODES,\n  type ServerMessage,\n  SUBPROTOCOL_NAME,\n} from '@graphorin/protocol';\nimport type { ParsedScope, TokenVerifier } from '@graphorin/security/auth';\nimport { parseScope } from '@graphorin/security/auth';\nimport type { Context } from 'hono';\nimport type { WSContext, WSEvents } from 'hono/ws';\n\nimport type { ServerVariables } from '../internal/context.js';\nimport { checkScope } from '../middleware/scope.js';\nimport { type RunStateTracker, requiredRunScope } from '../runtime/run-state.js';\nimport type { WsDispatcher } from './dispatcher.js';\nimport type { WsTicket, WsTicketStore } from './ticket.js';\n\n/**\n * Public configuration accepted by {@link createWsUpgradeEvents}.\n *\n * @stable\n */\nexport interface WsUpgradeOptions {\n  readonly dispatcher: WsDispatcher;\n  readonly tickets: WsTicketStore;\n  /**\n   * Token verifier for bearer / ticket upgrades. Optional only in the\n   * IP-13 no-auth loopback mode (`anonymous: true`), where there is no\n   * verifier to construct and every upgrade is accepted.\n   */\n  readonly verifier?: TokenVerifier;\n  /**\n   * IP-13: authentication is disabled server-wide (`auth.kind='none'`).\n   * Accept the upgrade unconditionally with a full (`admin:*`) scope grant\n   * instead of silently refusing to mount the WS route. Trusted-loopback\n   * / single-operator mode only.\n   */\n  readonly anonymous?: boolean;\n  readonly runs?: RunStateTracker;\n  readonly now?: () => number;\n  /**\n   * Subprotocol the server advertises. Defaults to\n   * {@link SUBPROTOCOL_NAME}; tests can override to exercise the\n   * mismatch path.\n   */\n  readonly serverSubprotocol?: string;\n  readonly newSubscriptionId?: () => string;\n  readonly newSubscriberId?: () => string;\n}\n\n/**\n * Build the `WSEvents` callback bag the Hono helper consumes. The\n * function takes the request `Context` so the upgrade can read the\n * `Authorization` header / `Sec-WebSocket-Protocol` ticket directly.\n *\n * Production wiring on `@hono/node-ws`:\n *\n * ```ts\n * const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });\n * app.get('/v1/ws', upgradeWebSocket((c) => createWsUpgradeEvents(c, deps)));\n * injectWebSocket(serve(...));\n * ```\n *\n * @stable\n */\nexport async function createWsUpgradeEvents(\n  c: Context<{ Variables: ServerVariables }>,\n  options: WsUpgradeOptions,\n): Promise<WSEvents> {\n  const negotiated = negotiateSubprotocol(c.req.header('sec-websocket-protocol') ?? '');\n  if (negotiated === null) {\n    return rejectImmediately(closeCodeFor('protocol.violation'), 'protocol.violation');\n  }\n  const auth = await resolveUpgradeAuth(c, options);\n  if (auth.kind === 'denied') {\n    return rejectImmediately(closeCodeFor(auth.reason), auth.reason);\n  }\n\n  const subscriberId = options.newSubscriberId?.() ?? defaultSubscriberId();\n  const newSubscriptionId =\n    options.newSubscriptionId ?? (() => defaultSubscriptionId(subscriberId));\n\n  let unregister: (() => void) | undefined;\n  let initialized = false;\n\n  return {\n    onOpen: (_event, ws) => {\n      const handle = {\n        id: subscriberId,\n        tokenId: auth.tokenId,\n        grantedScopes: auth.grantedScopes,\n        send: (frame: ServerMessage) => {\n          ws.send(JSON.stringify(frame));\n        },\n        close: (code: number, reason: string) => {\n          ws.close(code, reason);\n        },\n        // IP-9: surface the socket's real backlog so the dispatcher's\n        // backpressure threshold measures something - the synchronous\n        // outstanding-events counter never accumulates.\n        bufferedAmount: () => {\n          const raw = (ws as { raw?: { bufferedAmount?: number } }).raw;\n          return raw?.bufferedAmount ?? 0;\n        },\n      };\n      const reg = options.dispatcher.registerSubscriber(handle);\n      unregister = reg.unregister;\n    },\n    onMessage: (event, ws) => {\n      const raw = typeof event.data === 'string' ? event.data : '';\n      let payload: unknown;\n      try {\n        payload = JSON.parse(raw);\n      } catch {\n        sendRpcError(ws, undefined, RPC_ERROR_CODES.PARSE_ERROR, 'Frame is not valid JSON.');\n        ws.close(closeCodeFor('protocol.violation'), 'protocol.violation');\n        return;\n      }\n      const parsed = ClientMessageSchema.safeParse(payload);\n      if (!parsed.success) {\n        sendRpcError(\n          ws,\n          (payload as { id?: string | number } | null)?.id,\n          RPC_ERROR_CODES.INVALID_REQUEST,\n          'Frame failed schema validation.',\n        );\n        ws.close(closeCodeFor('protocol.violation'), 'protocol.violation');\n        return;\n      }\n      const message = parsed.data;\n      if (isCancelledNotification(message)) {\n        // IP-8 / W-107: only an initialized connection whose grant covers\n        // the run's OWNING resource may cancel it. A notification carries\n        // no id, so an unauthorised one is silently ignored (there is no\n        // error channel) rather than aborting an arbitrary run.\n        if (initialized) {\n          const snapshot = options.runs?.snapshot(message.params.requestId);\n          if (\n            snapshot !== undefined &&\n            checkScope(\n              { kind: 'token', grantedScopes: auth.grantedScopes } as never,\n              requiredRunScope(snapshot, 'control'),\n            )\n          ) {\n            options.runs?.abort(message.params.requestId, 'mcp-cancel');\n          }\n        }\n        return;\n      }\n      if (!initialized && !isInitializeRequest(message) && !isPingRequest(message)) {\n        // IP-21: a frame before `initialize` is a protocol-sequencing error,\n        // not an auth failure - the connection is already authenticated.\n        sendRpcError(\n          ws,\n          message.id,\n          RPC_ERROR_CODES.PROTOCOL_VIOLATION,\n          'Send `initialize` before any other RPC.',\n        );\n        return;\n      }\n      if (isInitializeRequest(message)) {\n        initialized = true;\n        sendRpcSuccess(ws, message.id, {\n          serverInfo: {\n            name: 'graphorin-server',\n            version: pkg.version,\n          },\n          capabilities: {\n            subscriptions: true,\n            replayBuffer: true,\n            sseFallback: true,\n          },\n        });\n        return;\n      }\n      if (isPingRequest(message)) {\n        const nonce = message.params?.nonce;\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'pong',\n            ...(nonce !== undefined ? { nonce } : {}),\n          } satisfies ServerMessage),\n        );\n        sendRpcSuccess(ws, message.id, { ok: true });\n        return;\n      }\n      if (isSubscribeRequest(message)) {\n        const subscriptionId = newSubscriptionId();\n        const result = options.dispatcher.subscribe({\n          subscriberId,\n          subject: message.params.subject,\n          subscriptionId,\n          ...(message.params.sinceEventId !== undefined\n            ? { sinceEventId: message.params.sinceEventId }\n            : {}),\n        });\n        if (!result.ok) {\n          sendRpcError(\n            ws,\n            message.id,\n            mapSubscribeErrorCode(result.reason),\n            mapSubscribeErrorMessage(result.reason, message.params.subject),\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          subscriptionId,\n          subject: message.params.subject,\n          snapshotEventId: result.snapshotEventId,\n          replayedCount: result.replayedCount,\n        });\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'subscribed',\n            subscriptionId,\n            subject: message.params.subject,\n            ...(result.snapshotEventId !== undefined\n              ? { snapshotEventId: result.snapshotEventId }\n              : {}),\n          } satisfies ServerMessage),\n        );\n        return;\n      }\n      if (isUnsubscribeRequest(message)) {\n        const removed = options.dispatcher.unsubscribe(message.params.subscriptionId);\n        if (!removed) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.SUBSCRIPTION_NOT_FOUND,\n            `Subscription '${message.params.subscriptionId}' not active.`,\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          subscriptionId: message.params.subscriptionId,\n          unsubscribed: true,\n        });\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'unsubscribed',\n            subscriptionId: message.params.subscriptionId,\n          } satisfies ServerMessage),\n        );\n        return;\n      }\n      if (isRunCancelRequest(message)) {\n        // IP-8 / W-107: mirror the REST `POST /runs/:runId/abort` gate at\n        // the same per-resource granularity - snapshot first (unknown run\n        // answers RUN_NOT_FOUND, matching REST's 404-before-403 order),\n        // then require the OWNING agent's/workflow's control scope.\n        const runId = message.params.runId;\n        const snapshot = options.runs?.snapshot(runId);\n        if (snapshot === undefined) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.RUN_NOT_FOUND,\n            `Run '${runId}' is not active.`,\n          );\n          return;\n        }\n        const required = requiredRunScope(snapshot, 'control');\n        if (!checkScope({ kind: 'token', grantedScopes: auth.grantedScopes } as never, required)) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.SCOPE_DENIED,\n            `Token lacks required scope '${required}'.`,\n          );\n          return;\n        }\n        const aborted = options.runs?.abort(runId, message.params.reason ?? 'rpc-cancel') === true;\n        if (!aborted) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.RUN_NOT_FOUND,\n            `Run '${runId}' is not active.`,\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          runId,\n          cancelled: true,\n          partialStateAvailable: true,\n        });\n        return;\n      }\n    },\n    onClose: () => {\n      try {\n        unregister?.();\n      } finally {\n        unregister = undefined;\n      }\n    },\n    onError: () => {\n      try {\n        unregister?.();\n      } finally {\n        unregister = undefined;\n      }\n    },\n  };\n}\n\nfunction sendRpcSuccess(ws: WSContext, id: string | number, result: unknown): void {\n  const frame: ServerMessage = { v: '1', jsonrpc: '2.0', id, result };\n  ws.send(JSON.stringify(frame));\n}\n\nfunction sendRpcError(\n  ws: WSContext,\n  id: string | number | undefined,\n  code: number,\n  message: string,\n): void {\n  const frame: ServerMessage = {\n    v: '1',\n    jsonrpc: '2.0',\n    id: id ?? 0,\n    error: { code, message },\n  };\n  ws.send(JSON.stringify(frame));\n}\n\nfunction rejectImmediately(code: number, reason: string): WSEvents {\n  return {\n    onOpen: (_event, ws) => {\n      ws.close(code, reason);\n    },\n  };\n}\n\ninterface ResolvedUpgradeAuthOk {\n  readonly kind: 'ok';\n  readonly tokenId: string;\n  readonly grantedScopes: ReadonlyArray<ParsedScope>;\n}\n\ninterface ResolvedUpgradeAuthDenied {\n  readonly kind: 'denied';\n  readonly reason: 'auth.required' | 'auth.invalid' | 'auth.scope_denied';\n}\n\ntype ResolvedUpgradeAuth = ResolvedUpgradeAuthOk | ResolvedUpgradeAuthDenied;\n\nasync function resolveUpgradeAuth(\n  c: Context<{ Variables: ServerVariables }>,\n  options: WsUpgradeOptions,\n): Promise<ResolvedUpgradeAuth> {\n  // Phase 14a's HTTP middleware may have already verified the\n  // bearer token (`requireAuth` runs before the upgrade route on\n  // the authenticated subtree); if so, reuse the result.\n  const state = c.var.state;\n  if (state?.auth?.kind === 'token') {\n    return {\n      kind: 'ok',\n      tokenId: state.auth.token.tokenId,\n      grantedScopes: state.auth.grantedScopes,\n    };\n  }\n  // IP-13: no-auth loopback mode - accept the upgrade with a full scope grant\n  // instead of silently failing to mount. Checked before ticket/bearer so the\n  // verifier may legitimately be absent.\n  if (options.anonymous === true) {\n    return { kind: 'ok', tokenId: 'anonymous', grantedScopes: ANONYMOUS_WS_SCOPES };\n  }\n  const ticketValue = parseTicketSubprotocol(c.req.header('sec-websocket-protocol') ?? '');\n  if (ticketValue !== undefined) {\n    const consumed = options.tickets.consume(ticketValue);\n    if (!consumed.ok) {\n      return { kind: 'denied', reason: 'auth.invalid' };\n    }\n    return acceptTicket(consumed.ticket);\n  }\n  const header = c.req.header('authorization') ?? c.req.header('Authorization');\n  if (header?.toLowerCase().startsWith('bearer ') === true) {\n    if (options.verifier === undefined) return { kind: 'denied', reason: 'auth.required' };\n    const token = header.slice(7).trim();\n    // P-05: pass the client IP like the HTTP auth middleware does, so\n    // the verifier's per-IP failure threshold / lockout engages for\n    // upgrade attempts too - without it `GET /v1/ws` was a\n    // lockout-free brute-force surface.\n    const ip = c.get('state')?.clientIp;\n    const verified = await options.verifier.verify(token, ip !== undefined ? { ip } : {});\n    if (!verified.ok) return { kind: 'denied', reason: 'auth.invalid' };\n    return {\n      kind: 'ok',\n      tokenId: verified.token.tokenId,\n      grantedScopes: verified.token.scopes,\n    };\n  }\n  return { kind: 'denied', reason: 'auth.required' };\n}\n\n/**\n * IP-13: the anonymous trusted-loopback principal (auth disabled) holds\n * `admin:*` so every per-subject and per-run check passes uniformly.\n */\nconst ANONYMOUS_WS_SCOPES: ReadonlyArray<ParsedScope> = [parseScope('admin:*')];\n\nfunction acceptTicket(ticket: WsTicket): ResolvedUpgradeAuth {\n  return {\n    kind: 'ok',\n    tokenId: ticket.tokenId,\n    grantedScopes: ticket.scopes,\n  };\n}\n\nfunction mapSubscribeErrorCode(\n  reason: 'subject-malformed' | 'subject-unknown' | 'subject-wildcard' | 'scope-denied',\n): number {\n  switch (reason) {\n    case 'scope-denied':\n      return RPC_ERROR_CODES.SCOPE_DENIED;\n    case 'subject-wildcard':\n      return RPC_ERROR_CODES.INVALID_PARAMS;\n    case 'subject-unknown':\n      return RPC_ERROR_CODES.METHOD_NOT_FOUND;\n    case 'subject-malformed':\n      return RPC_ERROR_CODES.INVALID_PARAMS;\n  }\n}\n\nfunction mapSubscribeErrorMessage(\n  reason: 'subject-malformed' | 'subject-unknown' | 'subject-wildcard' | 'scope-denied',\n  subject: string,\n): string {\n  switch (reason) {\n    case 'scope-denied':\n      return `Token lacks required scope for subject '${subject}'.`;\n    case 'subject-wildcard':\n      return `Wildcard subjects are not supported in this version. Subject: '${subject}'.`;\n    case 'subject-unknown':\n      return `Unknown subject grammar: '${subject}'.`;\n    case 'subject-malformed':\n      return `Subject '${subject}' is malformed.`;\n  }\n}\n\nfunction defaultSubscriberId(): string {\n  return `sub-conn-${randomToken(8)}`;\n}\n\nfunction defaultSubscriptionId(subscriberId: string): string {\n  return `${subscriberId}-${randomToken(6)}`;\n}\n\nfunction randomToken(length: number): string {\n  const bytes = new Uint8Array(length);\n  if (\n    typeof globalThis.crypto !== 'undefined' &&\n    typeof globalThis.crypto.getRandomValues === 'function'\n  ) {\n    globalThis.crypto.getRandomValues(bytes);\n  } else {\n    for (let i = 0; i < length; i += 1) {\n      bytes[i] = Math.floor(Math.random() * 256);\n    }\n  }\n  return Buffer.from(bytes).toString('hex');\n}\n\nvoid SUBPROTOCOL_NAME;\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/server",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Standalone server runtime for the Graphorin framework: createServer({...}) factory, Hono HTTP app, REST endpoints (agents / workflows / sessions / memory / skills / mcp / tokens / audit / health / health/secrets / metrics / triggers / runs/:runId/replay / sessions/:id/replay / audit/verify), per-request authentication + scope middleware (HMAC-SHA256 + pepper, server pepper required), brute-force lockout, IETF draft-07 Idempotency-Key middleware with SQLite backing + LRU read cache, deny-by-default CORS, double-submit CSRF for browser flows, sliding-window rate limit, audit middleware that streams every authenticated request through the tamper-evident hash chain, programmatic AgentRegistry / WorkflowRegistry, lifecycle hooks (beforeStart / onReady / beforeShutdown), pre-bind secrets resolution + storage migration runner that fails fast on missing pepper / unresolvable SecretRef / missing encryption peer, graceful SIGTERM drain with state preservation, durable triggers daemon (cron / interval / idle / event survive process restart per the catch-up policy contract), consolidator daemon lifecycle integration with hard stop timeout, per-subsystem health rollup (storage / embedder / secrets / encryption / consolidator / triggers / replay-buffer), Prometheus text exposition `/v1/metrics` with the canonical graphorin_* metric inventory, scope-enforced replay endpoints (sanitized by default, raw requires `traces:read:raw` admin scope, every invocation appended to the audit chain), and `POST /v1/audit/verify` chain integrity check. Created and maintained by Oleksiy Stepurenko.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -33,8 +33,9 @@
     "graceful-shutdown"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -42,60 +43,61 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./config": {
       "types": "./dist/config.d.ts",
-      "import": "./dist/config.js"
+      "default": "./dist/config.js"
     },
     "./middleware": {
       "types": "./dist/middleware/index.d.ts",
-      "import": "./dist/middleware/index.js"
+      "default": "./dist/middleware/index.js"
     },
     "./errors": {
       "types": "./dist/errors/index.d.ts",
-      "import": "./dist/errors/index.js"
+      "default": "./dist/errors/index.js"
     },
     "./registry": {
       "types": "./dist/registry/index.d.ts",
-      "import": "./dist/registry/index.js"
+      "default": "./dist/registry/index.js"
     },
     "./ws": {
       "types": "./dist/ws/index.d.ts",
-      "import": "./dist/ws/index.js"
+      "default": "./dist/ws/index.js"
     },
     "./sse": {
       "types": "./dist/sse/index.d.ts",
-      "import": "./dist/sse/index.js"
+      "default": "./dist/sse/index.js"
     },
     "./commentary": {
       "types": "./dist/commentary/index.d.ts",
-      "import": "./dist/commentary/index.js"
+      "default": "./dist/commentary/index.js"
     },
     "./triggers": {
       "types": "./dist/triggers/index.d.ts",
-      "import": "./dist/triggers/index.js"
+      "default": "./dist/triggers/index.js"
     },
     "./consolidator": {
       "types": "./dist/consolidator/index.d.ts",
-      "import": "./dist/consolidator/index.js"
+      "default": "./dist/consolidator/index.js"
     },
     "./health": {
       "types": "./dist/health/index.d.ts",
-      "import": "./dist/health/index.js"
+      "default": "./dist/health/index.js"
     },
     "./metrics": {
       "types": "./dist/metrics/index.d.ts",
-      "import": "./dist/metrics/index.js"
+      "default": "./dist/metrics/index.js"
     },
     "./replay": {
       "types": "./dist/replay/index.d.ts",
-      "import": "./dist/replay/index.js"
+      "default": "./dist/replay/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -105,18 +107,18 @@
     "@hono/node-ws": "^1.3.0",
     "hono": "^4.12.25",
     "zod": "^3.25.0",
-    "@graphorin/core": "0.6.1",
-    "@graphorin/observability": "0.6.1",
-    "@graphorin/protocol": "0.6.1",
-    "@graphorin/security": "0.6.1",
-    "@graphorin/store-sqlite": "0.6.1",
-    "@graphorin/triggers": "0.6.1"
+    "@graphorin/core": "0.7.0",
+    "@graphorin/protocol": "0.7.0",
+    "@graphorin/security": "0.7.0",
+    "@graphorin/store-sqlite": "0.7.0",
+    "@graphorin/tools": "0.7.0",
+    "@graphorin/triggers": "0.7.0"
   },
   "peerDependencies": {
-    "@graphorin/agent": ">=0.5.0 <1.0.0",
-    "@graphorin/memory": ">=0.5.0 <1.0.0",
-    "@graphorin/sessions": ">=0.5.0 <1.0.0",
-    "@graphorin/workflow": ">=0.5.0 <1.0.0"
+    "@graphorin/agent": ">=0.7.0 <1.0.0",
+    "@graphorin/memory": ">=0.7.0 <1.0.0",
+    "@graphorin/sessions": ">=0.7.0 <1.0.0",
+    "@graphorin/workflow": ">=0.7.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@graphorin/agent": {
@@ -141,10 +143,9 @@
     "@types/ws": "^8.18.1",
     "better-sqlite3": "^12.9.0",
     "ws": "^8.20.1",
-    "@graphorin/agent": "0.6.1",
-    "@graphorin/memory": "0.6.1",
-    "@graphorin/sessions": "0.6.1",
-    "@graphorin/workflow": "0.6.1"
+    "@graphorin/agent": "0.7.0",
+    "@graphorin/sessions": "0.7.0",
+    "@graphorin/workflow": "0.7.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/app-audit-binding.ts

@@ -0,0 +1,227 @@
+/**
+ * Default audit-db binding registration for `createServer({...})`.
+ *
+ * Extracted from `app.ts` so the binding (and its SQLite row mapping)
+ * lives next to nothing but itself; the server lifecycle and the CLI
+ * both call {@link ensureStoreAuditBinding} before opening the audit
+ * chain.
+ *
+ * @packageDocumentation
+ */
+
+import { registerAuditDbBinding } from '@graphorin/security/audit';
+import {
+  cipherSelectionPragmas,
+  type EncryptionCipher,
+  loadCipherDriver,
+} from '@graphorin/store-sqlite';
+
+/** The ciphers sqlite3mc supports - mirrors `EncryptionCipher`. */
+const KNOWN_CIPHERS: ReadonlySet<string> = new Set([
+  'sqlcipher',
+  'chacha20',
+  'aes256cbc',
+  'aes128cbc',
+  'rc4',
+]);
+
+/**
+ * Pre-built audit-db binding shipped from `@graphorin/store-sqlite`.
+ * Registered exactly once per process so {@link openAuditDb} can find
+ * a default binding without forcing operators to wire it manually.
+ *
+ * Exported as {@link ensureStoreAuditBinding} so the CLI (Phase 15
+ * `graphorin audit verify | prune | export`) can reach into the same
+ * binding without booting the HTTP listener.
+ *
+ * @stable
+ */
+let storeAuditBindingRegistered = false;
+export function ensureStoreAuditBinding(): void {
+  if (storeAuditBindingRegistered) return;
+  registerAuditDbBinding(
+    {
+      id: 'better-sqlite3-multiple-ciphers',
+      description: 'Default audit-db binding shipped by @graphorin/store-sqlite.',
+      open: async (opts) => {
+        const driver = await loadCipherDriver();
+        const passphrase = await opts.passphrase.use((value) => value);
+        const Db = driver as unknown as new (
+          path: string,
+        ) => {
+          pragma(s: string): unknown;
+          prepare(sql: string): {
+            run(...args: unknown[]): unknown;
+            get(...args: unknown[]): unknown;
+            all(...args: unknown[]): unknown;
+            iterate(...args: unknown[]): IterableIterator<unknown>;
+          };
+          exec(sql: string): unknown;
+          close(): void;
+          open: boolean;
+        };
+        // W-110 / CS-7: pin the cipher BEFORE PRAGMA key - `opts.cipher`
+        // (config.audit.cipher) was previously ignored, so every audit.db
+        // silently came out as sqlite3mc's default. Default 'chacha20':
+        // pre-fix files were created without cipher pragmas (= chacha20
+        // format), so this pin is byte-compatible with every existing
+        // audit.db, while 'sqlcipher' (the MAIN store's ADR-030 default)
+        // would brick them. Unknown values fail fast.
+        const cipher = opts.cipher ?? 'chacha20';
+        if (!KNOWN_CIPHERS.has(cipher)) {
+          throw new Error(
+            `[graphorin/server] unknown audit.cipher '${cipher}'. Supported: ${[...KNOWN_CIPHERS].join(', ')}.`,
+          );
+        }
+        const db = new Db(opts.path);
+        for (const pragma of cipherSelectionPragmas(cipher as EncryptionCipher)) {
+          db.pragma(pragma);
+        }
+        db.pragma(`key = '${passphrase.replace(/'/g, "''")}'`);
+        db.pragma('journal_mode = WAL');
+        db.pragma('synchronous = NORMAL');
+        db.pragma('busy_timeout = 5000');
+        db.pragma('foreign_keys = ON');
+        db.exec(
+          `CREATE TABLE IF NOT EXISTS audit_log (
+            seq INTEGER PRIMARY KEY,
+            ts INTEGER NOT NULL,
+            actor_json TEXT NOT NULL,
+            action TEXT NOT NULL,
+            target TEXT NOT NULL,
+            decision TEXT NOT NULL,
+            context_json TEXT,
+            metadata_json TEXT,
+            prev_hash TEXT NOT NULL,
+            hash TEXT NOT NULL UNIQUE
+          ) WITHOUT ROWID;`,
+        );
+        return {
+          binding: 'better-sqlite3-multiple-ciphers',
+          path: opts.path,
+          async insert(entry) {
+            db.prepare(
+              `INSERT INTO audit_log (
+                 seq, ts, actor_json, action, target, decision,
+                 context_json, metadata_json, prev_hash, hash
+               ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            ).run(
+              entry.seq,
+              entry.ts,
+              JSON.stringify(entry.actor),
+              entry.action,
+              entry.target,
+              entry.decision,
+              entry.context !== undefined ? JSON.stringify(entry.context) : null,
+              entry.metadata !== undefined ? JSON.stringify(entry.metadata) : null,
+              entry.prevHash,
+              entry.hash,
+            );
+            return entry;
+          },
+          async latest() {
+            const row = db.prepare('SELECT * FROM audit_log ORDER BY seq DESC LIMIT 1').get() as
+              | undefined
+              | {
+                  seq: number;
+                  ts: number;
+                  actor_json: string;
+                  action: string;
+                  target: string;
+                  decision: string;
+                  context_json: string | null;
+                  metadata_json: string | null;
+                  prev_hash: string;
+                  hash: string;
+                };
+            if (row === undefined) return undefined;
+            return rowToEntry(row);
+          },
+          async *iterate(bounds) {
+            const lo = bounds?.fromSeq ?? 1;
+            const hi = bounds?.toSeq ?? Number.MAX_SAFE_INTEGER;
+            const iter = db
+              .prepare('SELECT * FROM audit_log WHERE seq BETWEEN ? AND ? ORDER BY seq ASC')
+              .iterate(lo, hi);
+            for (const row of iter) yield rowToEntry(row as Parameters<typeof rowToEntry>[0]);
+          },
+          async count() {
+            const row = db.prepare('SELECT COUNT(*) AS n FROM audit_log').get() as { n: number };
+            return row.n;
+          },
+          async deleteUpTo(threshold) {
+            const before = db
+              .prepare('SELECT COUNT(*) AS n FROM audit_log WHERE seq <= ?')
+              .get(threshold) as { n: number };
+            db.prepare('DELETE FROM audit_log WHERE seq <= ?').run(threshold);
+            return before.n;
+          },
+          async replaceEntry(entry) {
+            db.prepare(`UPDATE audit_log SET prev_hash = ?, hash = ? WHERE seq = ?`).run(
+              entry.prevHash,
+              entry.hash,
+              entry.seq,
+            );
+          },
+          // W-011: cross-process fence. Raw BEGIN IMMEDIATE (not
+          // better-sqlite3's .transaction() - that helper rejects async
+          // functions, while this binding's methods are async-shaped
+          // with synchronous bodies; the in-process WRITE_CHAINS
+          // serialisation guarantees no foreign statement interleaves
+          // inside the transaction). ROLLBACK strictly in finally so an
+          // exception can never leave the handle wedged inside an open
+          // transaction.
+          async transact(fn) {
+            db.exec('BEGIN IMMEDIATE');
+            let committed = false;
+            try {
+              const result = await fn();
+              db.exec('COMMIT');
+              committed = true;
+              return result;
+            } finally {
+              if (!committed) {
+                try {
+                  db.exec('ROLLBACK');
+                } catch {
+                  // Already rolled back / connection unusable - nothing to release.
+                }
+              }
+            }
+          },
+          async close() {
+            if (db.open) db.close();
+          },
+        };
+      },
+    },
+    { setAsDefault: true },
+  );
+  storeAuditBindingRegistered = true;
+}
+
+function rowToEntry(row: {
+  seq: number;
+  ts: number;
+  actor_json: string;
+  action: string;
+  target: string;
+  decision: string;
+  context_json: string | null;
+  metadata_json: string | null;
+  prev_hash: string;
+  hash: string;
+}) {
+  return {
+    seq: row.seq,
+    ts: row.ts,
+    actor: JSON.parse(row.actor_json),
+    action: row.action,
+    target: row.target,
+    decision: row.decision as 'success' | 'denied' | 'error' | 'not-found',
+    ...(row.context_json !== null ? { context: JSON.parse(row.context_json) } : {}),
+    ...(row.metadata_json !== null ? { metadata: JSON.parse(row.metadata_json) } : {}),
+    prevHash: row.prev_hash,
+    hash: row.hash,
+  };
+}

package/src/app-daemons.ts

@@ -0,0 +1,73 @@
+/**
+ * Daemon construction for `createServer({...})` - wraps the caller's
+ * triggers scheduler / consolidator surfaces in their daemon adapters.
+ * Start/stop sequencing stays in `app-lifecycle.ts` because the order
+ * relative to the listener is part of the lifecycle contract.
+ *
+ * @packageDocumentation
+ */
+
+import type { ConsolidatorDaemon, ConsolidatorLike } from './consolidator/daemon.js';
+import { createConsolidatorDaemon } from './consolidator/daemon.js';
+import type { TriggersDaemon } from './triggers/daemon.js';
+import { createTriggersDaemon } from './triggers/daemon.js';
+import type { WorkflowTimerDaemon, WorkflowTimerDriverLike } from './workflows/timer-daemon.js';
+import { createWorkflowTimerDaemon } from './workflows/timer-daemon.js';
+
+/**
+ * Discriminated union accepted by `CreateServerOptions.triggers`. A
+ * caller may either supply a fully-built daemon (e.g. constructed
+ * around a custom `Scheduler`) or just the underlying scheduler - the
+ * server wraps it with {@link createTriggersDaemon} automatically.
+ *
+ * @stable
+ */
+export type TriggersDaemonInput =
+  | { readonly daemon: TriggersDaemon }
+  | { readonly scheduler: import('@graphorin/triggers').Scheduler };
+
+/** W-032: accepted forms for `createServer({ workflowTimers })`. */
+export type WorkflowTimersInput =
+  | { readonly daemon: WorkflowTimerDaemon }
+  | { readonly driver: WorkflowTimerDriverLike };
+
+/** Subset of `CreateServerOptions` consumed by {@link buildDaemons}. */
+export interface BuildDaemonsOptions {
+  readonly triggers?: TriggersDaemonInput | undefined;
+  readonly consolidator?: ConsolidatorLike | undefined;
+  readonly workflowTimers?: WorkflowTimersInput | undefined;
+}
+
+/** Daemon handles constructed (or adopted) by {@link buildDaemons}. */
+export interface BuiltDaemons {
+  readonly triggersDaemon: TriggersDaemon | undefined;
+  readonly consolidatorDaemon: ConsolidatorDaemon | undefined;
+  readonly workflowTimerDaemon: WorkflowTimerDaemon | undefined;
+}
+
+/**
+ * Wrap the operator-supplied triggers / consolidator surfaces in their
+ * daemon adapters. Pure construction - nothing is started here.
+ */
+export function buildDaemons(options: BuildDaemonsOptions): BuiltDaemons {
+  let triggersDaemon: TriggersDaemon | undefined;
+  if (options.triggers !== undefined) {
+    if ('daemon' in options.triggers) {
+      triggersDaemon = options.triggers.daemon;
+    } else {
+      triggersDaemon = createTriggersDaemon({ scheduler: options.triggers.scheduler });
+    }
+  }
+  let consolidatorDaemon: ConsolidatorDaemon | undefined;
+  if (options.consolidator !== undefined) {
+    consolidatorDaemon = createConsolidatorDaemon({ consolidator: options.consolidator });
+  }
+  let workflowTimerDaemon: WorkflowTimerDaemon | undefined;
+  if (options.workflowTimers !== undefined) {
+    workflowTimerDaemon =
+      'daemon' in options.workflowTimers
+        ? options.workflowTimers.daemon
+        : createWorkflowTimerDaemon({ driver: options.workflowTimers.driver });
+  }
+  return { triggersDaemon, consolidatorDaemon, workflowTimerDaemon };
+}