@graphorin/server 0.6.0 → 0.7.0

package/src/app.ts

@@ -0,0 +1,317 @@
+/**
+ * `createServer({...})` - the single programmatic entry point.
+ *
+ * The factory returns a {@link GraphorinServer} handle the operator
+ * controls via `start()` / `stop()`. The same handle is consumed by
+ * the `graphorin start` CLI binary in `@graphorin/cli`.
+ *
+ * Phase 14a covers the full HTTP surface, the lifecycle plumbing,
+ * the Hono app composition, and the auth / scope / idempotency /
+ * audit middleware stack. Phase 14b/c attach the WebSocket layer +
+ * triggers daemon + observability endpoints to the same handle.
+ *
+ * This file is the composition root: the cohesive builders live in
+ * focused sibling modules - `app-audit-binding.ts` (default audit-db
+ * binding), `app-middleware.ts` (global + authenticated-subtree
+ * middleware), `app-ws.ts` (WebSocket layer), `app-daemons.ts`
+ * (triggers / consolidator daemon construction), `app-routes.ts`
+ * (route mounting), `app-metrics.ts` (live scrape refresh), and
+ * `app-lifecycle.ts` (`start()` / `stop()` sequencing).
+ *
+ * @packageDocumentation
+ */
+
+import process from 'node:process';
+import { createSqliteStore, type GraphorinSqliteStore } from '@graphorin/store-sqlite';
+import { Hono } from 'hono';
+import { buildDaemons, type TriggersDaemonInput, type WorkflowTimersInput } from './app-daemons.js';
+import { createLifecycle } from './app-lifecycle.js';
+import { attachGlobalMiddleware } from './app-middleware.js';
+import { buildWsLayer } from './app-ws.js';
+import { parseServerConfig, type ServerConfigInput, type ServerConfigSpec } from './config.js';
+import type { ConsolidatorDaemon, ConsolidatorLike } from './consolidator/daemon.js';
+import { ConfigInvalidError } from './errors/index.js';
+import type { HealthCheckOptions } from './health/index.js';
+import type { ServerVariables } from './internal/context.js';
+import type { LifecycleHooks } from './lifecycle/index.js';
+import { createServerMetricRegistry, SERVER_METRIC_NAMES } from './metrics/catalog.js';
+import type { MetricRegistry } from './metrics/registry.js';
+import { AgentRegistry, WorkflowRegistry } from './registry/index.js';
+import type { ReplayApi } from './replay/index.js';
+import type { AuditApi, McpApi, MemoryApi, SessionApi, SkillsApi } from './routes/index.js';
+import { RunStateTracker } from './runtime/run-state.js';
+import type { TriggersDaemon } from './triggers/daemon.js';
+import type { WorkflowTimerDaemon } from './workflows/timer-daemon.js';
+import type { WsDispatcher, WsTicketStore } from './ws/index.js';
+
+// Stable re-exports - both were born in this module and stay
+// importable from `./app.js` (and the package barrel) unchanged.
+export { ensureStoreAuditBinding } from './app-audit-binding.js';
+export type { TriggersDaemonInput, WorkflowTimersInput } from './app-daemons.js';
+
+/**
+ * Public surface returned by {@link createServer}.
+ *
+ * @stable
+ */
+export interface GraphorinServer {
+  readonly version: string;
+  readonly config: ServerConfigSpec;
+  readonly app: Hono<{ Variables: ServerVariables }>;
+  readonly agents: AgentRegistry;
+  readonly workflows: WorkflowRegistry;
+  readonly runs: RunStateTracker;
+  readonly listeningOn: { readonly host: string; readonly port: number } | undefined;
+  /**
+   * Optional WebSocket dispatcher exposed when `server.ws.enabled =
+   * true`. Route handlers + the agent / workflow runtimes call
+   * `dispatcher.emit(subject, event)` to fan out events to subscribed
+   * clients. Returns `undefined` when WS is disabled.
+   */
+  readonly wsDispatcher: WsDispatcher | undefined;
+  /**
+   * Optional WebSocket ticket store exposed when `server.ws.enabled
+   * = true`. Surfaced primarily for tests; the
+   * `POST /v1/session/ws-ticket` route uses it transparently.
+   */
+  readonly wsTickets: WsTicketStore | undefined;
+  /**
+   * Optional triggers daemon - populated when the operator wired a
+   * scheduler (or an in-process trigger surface) at construction
+   * time. Phase 14c integration.
+   */
+  readonly triggers: TriggersDaemon | undefined;
+  /**
+   * Optional consolidator daemon - populated when the operator
+   * supplied a `Consolidator` instance via `createServer({
+   * consolidator })`. Phase 14c integration.
+   */
+  readonly consolidator: ConsolidatorDaemon | undefined;
+  /**
+   * W-032: optional workflow durable-timer daemon - populated when the
+   * operator wired a `createTimerDriver(...)` at construction time.
+   */
+  readonly workflowTimers: WorkflowTimerDaemon | undefined;
+  /**
+   * Phase 14c Prometheus registry. Always present; sample updates
+   * are observable via `metrics.snapshot()`.
+   */
+  readonly metrics: MetricRegistry;
+  start(): Promise<{ readonly host: string; readonly port: number }>;
+  stop(options?: { readonly force?: boolean }): Promise<void>;
+}
+
+/**
+ * @stable
+ */
+export interface CreateServerOptions {
+  /** Loaded `graphorin.config.ts` payload - see `defineConfig({...})`. */
+  readonly config?: ServerConfigInput;
+  /**
+   * Optional pre-validated config. When supplied, `config` is ignored
+   * and the schema validation step is skipped. Useful for tests + the
+   * `graphorin migrate` CLI command which bypasses the listener.
+   */
+  readonly validatedConfig?: ServerConfigSpec;
+  /** Pre-built SQLite store. Tests inject an in-memory store. */
+  readonly store?: GraphorinSqliteStore;
+  /** Optional pre-built tracker. Tests inject deterministic timing. */
+  readonly runs?: RunStateTracker;
+  /** Optional pre-built registries. */
+  readonly agents?: AgentRegistry;
+  readonly workflows?: WorkflowRegistry;
+  /** Optional in-process domain adapters wired into REST routes. */
+  readonly sessions?: SessionApi;
+  readonly memory?: MemoryApi;
+  readonly skills?: SkillsApi;
+  readonly mcp?: McpApi;
+  readonly audit?: AuditApi;
+  /**
+   * Optional consolidator surface (`@graphorin/memory`). Phase 14c
+   * starts/stops the runtime alongside the server lifecycle and
+   * surfaces its status through `/v1/health`.
+   */
+  readonly consolidator?: ConsolidatorLike;
+  /**
+   * Optional triggers daemon - pass an existing one (e.g. built
+   * from `createScheduler`) or a triggers configuration the server
+   * should wrap with the daemon adapter.
+   */
+  readonly triggers?: TriggersDaemonInput;
+  /**
+   * W-032: optional workflow durable-timer surface - pass a
+   * `createTimerDriver(...)` built over your workflows + checkpoint
+   * stores (`{ driver }`), or a pre-built daemon. The server starts
+   * and stops it with the lifecycle and reports it on `/v1/health`.
+   */
+  readonly workflowTimers?: WorkflowTimersInput;
+  /**
+   * Optional replay API consumed by the scope-enforced replay
+   * endpoints. Phase 14c.
+   */
+  readonly replay?: ReplayApi;
+  /**
+   * Optional probes that augment `/v1/health`. Provided by consumer
+   * code (e.g. `embedder` provides `embedderLoaded`).
+   */
+  readonly healthProbes?: () => HealthCheckOptions | Promise<HealthCheckOptions>;
+  /**
+   * Optional Prometheus metric registry override. When omitted, the
+   * server constructs the canonical registry from
+   * {@link createServerMetricRegistry}.
+   */
+  readonly metricRegistry?: MetricRegistry;
+  /** Lifecycle hook overrides. */
+  readonly hooks?: LifecycleHooks;
+  /** Wall-clock provider for tests. */
+  readonly now?: () => number;
+  /** Override the cipher peer probe. Tests inject a stub. */
+  readonly probeCipherPeer?: () => Promise<void>;
+  /** Override the package version reported on `/v1/health`. */
+  readonly version?: string;
+  /** Skip `applyProcessHardening` (tests). */
+  readonly skipHardening?: boolean;
+  /** Skip starting the actual listener (tests). */
+  readonly skipListen?: boolean;
+}
+
+/**
+ * @stable
+ */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+/**
+ * Build a fully-wired Graphorin server. The returned handle is
+ * inert until `start()` is awaited.
+ *
+ * @stable
+ */
+export async function createServer(options: CreateServerOptions = {}): Promise<GraphorinServer> {
+  const config: ServerConfigSpec =
+    options.validatedConfig ?? parseServerConfig(options.config ?? {});
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  const version = options.version ?? VERSION;
+
+  // IP-1: when encryption is configured, resolve the passphrase ref
+  // BEFORE constructing the store and thread the encryption config
+  // through - `graphorin init --encrypted` produced a config nothing
+  // honoured, and a database encrypted via `storage encrypt` could not
+  // be opened by the server at all.
+  let storeEncryption:
+    | { enabled: true; cipher?: never; passphraseResolver: () => Promise<string> }
+    | undefined;
+  if (options.store === undefined && config.storage.encryption.enabled) {
+    if (config.storage.encryption.passphraseRef === undefined) {
+      throw new Error(
+        '[graphorin/server] storage.encryption.enabled is true but no passphraseRef is configured.',
+      );
+    }
+    const { resolveSecret } = await import('@graphorin/security/secrets');
+    const passphrase = await resolveSecret(config.storage.encryption.passphraseRef);
+    storeEncryption = {
+      enabled: true,
+      passphraseResolver: async () => passphrase.use((v) => v),
+    } as never;
+  }
+  const store =
+    options.store ??
+    (await createSqliteStore({
+      path: config.storage.path,
+      mode: config.storage.mode,
+      ...(storeEncryption !== undefined
+        ? {
+            encryption: {
+              enabled: true,
+              ...(config.storage.encryption.cipher !== undefined
+                ? { cipher: config.storage.encryption.cipher as never }
+                : {}),
+              passphraseResolver: storeEncryption.passphraseResolver,
+            },
+          }
+        : {}),
+    }));
+
+  const metricRegistry = options.metricRegistry ?? createServerMetricRegistry();
+  metricRegistry.set(SERVER_METRIC_NAMES.buildInfo, 1, { version });
+
+  // IP-15: agent / workflow run completions move graphorin_agent_runs_total +
+  // graphorin_agent_run_duration_seconds. The tracker stays metric-agnostic -
+  // it fires a terminal callback the server turns into samples.
+  const runs =
+    options.runs ??
+    new RunStateTracker({
+      now,
+      onTerminal: (info) => {
+        metricRegistry.inc(SERVER_METRIC_NAMES.agentRunsTotal, { status: info.status });
+        if (info.durationMs !== undefined) {
+          metricRegistry.observe(SERVER_METRIC_NAMES.agentRunDuration, info.durationMs / 1000);
+        }
+      },
+    });
+  const agents = options.agents ?? new AgentRegistry();
+  const workflows = options.workflows ?? new WorkflowRegistry();
+
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  // Request-state / CORS / CSRF / rate-limit - see `app-middleware.ts`.
+  attachGlobalMiddleware(app, config, now);
+
+  const { triggersDaemon, consolidatorDaemon, workflowTimerDaemon } = buildDaemons(options);
+
+  const ws = buildWsLayer(app, config, now);
+
+  const lifecycle = createLifecycle({
+    options,
+    config,
+    store,
+    app,
+    metricRegistry,
+    runs,
+    agents,
+    workflows,
+    version,
+    startedAt,
+    now,
+    ws,
+    triggersDaemon,
+    consolidatorDaemon,
+    workflowTimerDaemon,
+  });
+
+  const handle: GraphorinServer = {
+    version,
+    config,
+    app,
+    agents,
+    workflows,
+    runs,
+    metrics: metricRegistry,
+    get wsDispatcher() {
+      return lifecycle.wsDispatcher;
+    },
+    get wsTickets() {
+      return lifecycle.wsTickets;
+    },
+    get triggers() {
+      return triggersDaemon;
+    },
+    get consolidator() {
+      return consolidatorDaemon;
+    },
+    get workflowTimers() {
+      return workflowTimerDaemon;
+    },
+    get listeningOn() {
+      return lifecycle.listeningOn;
+    },
+    start: lifecycle.start,
+    stop: lifecycle.stop,
+  };
+  return handle;
+}
+
+void process;
+void ConfigInvalidError;

package/src/commentary/audit-bridge.ts

@@ -0,0 +1,135 @@
+/**
+ * IP-21: bridge the delivery-commentary sanitizer's audit decisions into the
+ * tamper-evident audit log. `createWsDispatcher` ran the sanitizer without a
+ * `sink`, so every documented sanitization decision - what was wrapped or
+ * stripped on the wire, with before/after digests and the matched-pattern
+ * bucket - was silently dropped instead of landing in the audit chain.
+ *
+ * The WS dispatcher is constructed before the audit DB is unsealed (the DB
+ * opens during `start()`), so the server hands the dispatcher a
+ * {@link LateBoundCommentarySink} and installs the real audit-writing target
+ * via {@link bridgeCommentaryToAudit} once the DB exists. Mirrors the
+ * `bridgeAuthToAudit` / `bridgeSecretsToAudit` pattern in `@graphorin/security`.
+ *
+ * @packageDocumentation
+ */
+
+import { type AuditDb, type AuditEntryInput, appendAudit } from '@graphorin/security/audit';
+
+import type { DeliveryCommentaryDecision, DeliveryCommentarySink } from './types.js';
+
+/**
+ * Audit action recorded for a delivery-commentary sanitization decision.
+ *
+ * @stable
+ */
+export const COMMENTARY_AUDIT_ACTION = 'delivery:commentary:sanitized';
+
+/**
+ * Translate a sanitizer decision into an audit entry. The digests + matched
+ * pattern bucket land in `metadata`; raw payloads never do (the sanitizer only
+ * ever exposes SHA-256s of the before/after bodies).
+ */
+export function commentaryDecisionToAuditInput(
+  decision: DeliveryCommentaryDecision,
+): AuditEntryInput {
+  return {
+    actor: { kind: 'system', id: 'graphorin/server' },
+    action: COMMENTARY_AUDIT_ACTION,
+    target: `${decision.transport}:${decision.eventType}`,
+    decision: 'success',
+    metadata: {
+      policy: decision.policy,
+      applied: decision.applied,
+      boundary: decision.boundary,
+      reasons: decision.reasons,
+      ...(decision.matchedPattern !== undefined ? { matchedPattern: decision.matchedPattern } : {}),
+      sha256OfBefore: decision.sha256OfBefore,
+      sha256OfAfter: decision.sha256OfAfter,
+    },
+  };
+}
+
+/**
+ * A commentary sink that also exposes a `drain()` so callers (and tests) can
+ * await any in-flight audit writes.
+ *
+ * @stable
+ */
+export interface CommentaryAuditSink extends DeliveryCommentarySink {
+  /** Resolve once every queued audit write has settled. */
+  readonly drain: () => Promise<void>;
+}
+
+/**
+ * Build a commentary sink that appends each sanitization decision to the audit
+ * log. Writes serialise through `appendAudit` so concurrent decisions never
+ * race on `seq`; a failed write is isolated from the wire - `onWriteError`
+ * (default: a console warning) runs instead of throwing.
+ *
+ * @stable
+ */
+export function bridgeCommentaryToAudit(
+  db: AuditDb,
+  onWriteError: (
+    decision: DeliveryCommentaryDecision,
+    error: unknown,
+  ) => void = defaultOnWriteError,
+): CommentaryAuditSink {
+  let tail: Promise<unknown> = Promise.resolve();
+  return {
+    onDecision(decision) {
+      const input = commentaryDecisionToAuditInput(decision);
+      tail = tail
+        .then(() => appendAudit(db, input))
+        .catch((error) => onWriteError(decision, error));
+    },
+    drain: async () => {
+      await tail;
+    },
+  };
+}
+
+function defaultOnWriteError(_decision: DeliveryCommentaryDecision, error: unknown): void {
+  console.warn(
+    `[graphorin/server] WARN: failed to write a delivery-commentary audit entry: ${
+      error instanceof Error ? error.message : String(error)
+    }`,
+  );
+}
+
+/**
+ * A {@link DeliveryCommentarySink} whose real target is installed later. The WS
+ * dispatcher is created before the audit DB opens (IP-21); the server hands it
+ * this forwarding sink and calls {@link LateBoundCommentarySink.bind} once the
+ * audit-writing sink exists. Decisions emitted before binding are dropped - the
+ * dispatcher only sanitizes once it is live (after `start()`, by which point
+ * the audit DB, if configured, has opened and bound).
+ *
+ * @stable
+ */
+export interface LateBoundCommentarySink extends DeliveryCommentarySink {
+  /** Install the real sink. Replaces any previously-bound target. */
+  bind(target: DeliveryCommentarySink): void;
+}
+
+/**
+ * @stable
+ */
+export function createLateBoundCommentarySink(): LateBoundCommentarySink {
+  let target: DeliveryCommentarySink | undefined;
+  return {
+    bind(next) {
+      target = next;
+    },
+    onDecision(decision) {
+      // Contract: a sink never throws into the wire. The sanitizer also guards,
+      // but be defensive in case a bound target misbehaves.
+      try {
+        target?.onDecision(decision);
+      } catch {
+        // swallow
+      }
+    },
+  };
+}

package/src/commentary/built-in-patterns.ts

@@ -0,0 +1,79 @@
+/**
+ * Default pattern catalogue for the delivery-layer commentary-phase
+ * trace sanitization applied by the WebSocket dispatcher (`@graphorin/server/ws`)
+ * and the SSE event-emission boundary (`@graphorin/server/sse`).
+ *
+ * The catalogue is structurally identical to the session-output
+ * sanitization catalogue exposed by `@graphorin/sessions/commentary`;
+ * they live in two packages so the server's delivery layer does not
+ * pull a hard dependency on the session module while still providing
+ * defense-in-depth across the storage-write boundary (Phase 11) and
+ * the wire-emission boundary (this module). Deployments that want a
+ * single source of truth across both layers can pass the sessions
+ * catalogue through {@link import('./types.js').DeliveryCommentaryConfig}.patterns.
+ *
+ * @packageDocumentation
+ */
+
+import type { DeliveryCommentaryPattern } from './types.js';
+
+/**
+ * The framework-shipped catalogue. Snapshot bytes-equal across the
+ * `ws` / `sse` / `rest` transports; idempotent on a single payload
+ * (the wrap envelope itself is not matched by any pattern, so a
+ * second pass over a previously-sanitized payload is a no-op).
+ *
+ * @stable
+ */
+export const DEFAULT_DELIVERY_COMMENTARY_PATTERNS: ReadonlyArray<DeliveryCommentaryPattern> =
+  Object.freeze([
+    Object.freeze({
+      reason: 'tool.call.start-payload-signature',
+      regex: /\{\s*"type"\s*:\s*"tool\.call\.start"[\s\S]*?"toolName"\s*:\s*"[^"]+"[\s\S]*?\}/g,
+      description:
+        'JSON-encoded `tool.call.start` event with a `toolName` field - leaks the internal tool dispatch.',
+    }),
+    Object.freeze({
+      reason: 'tool.call.delta-payload-signature',
+      regex: /\{\s*"type"\s*:\s*"tool\.call\.delta"[\s\S]*?"argsDelta"[\s\S]*?\}/g,
+      description: 'JSON-encoded `tool.call.delta` event with streaming `argsDelta`.',
+    }),
+    Object.freeze({
+      reason: 'tool.call.end-payload-signature',
+      regex: /\{\s*"type"\s*:\s*"tool\.call\.end"[\s\S]*?"finalArgs"[\s\S]*?\}/g,
+      description: 'JSON-encoded `tool.call.end` event carrying the final args payload.',
+    }),
+    Object.freeze({
+      reason: 'tool.execute.end-payload-signature',
+      regex: /\{\s*"type"\s*:\s*"tool\.execute\.end"[\s\S]*?"result"\s*:\s*[\s\S]*?\}/g,
+      description: 'JSON-encoded `tool.execute.end` event with the raw `result` payload.',
+    }),
+    Object.freeze({
+      reason: 'agent.fanout-event-signature',
+      regex: /\{\s*"type"\s*:\s*"agent\.fanout\.(?:spawned|merged)"[\s\S]*?\}/g,
+      description: 'JSON-encoded `agent.fanout.spawned` / `agent.fanout.merged` event.',
+    }),
+    Object.freeze({
+      reason: 'context.compacted-event-signature',
+      regex: /\{\s*"type"\s*:\s*"context\.compacted"[\s\S]*?"originalTokens"[\s\S]*?\}/g,
+      description: 'JSON-encoded `context.compacted` event with token deltas.',
+    }),
+    Object.freeze({
+      reason: 'agent.model.fellback-event-signature',
+      regex: /\{\s*"type"\s*:\s*"agent\.model\.fellback"[\s\S]*?"fromModel"[\s\S]*?\}/g,
+      description: 'JSON-encoded `agent.model.fellback` event with fallback chain detail.',
+    }),
+  ]);
+
+/**
+ * Default whitelist of `event.type` strings the dispatcher walks
+ * through the sanitizer. Extension is opt-in via
+ * `DeliveryCommentaryConfig.applyToEvents`.
+ *
+ * @stable
+ */
+export const DEFAULT_APPLY_TO_EVENTS: ReadonlyArray<string> = Object.freeze([
+  'tool.execute.end',
+  'tool.execute.error',
+  'text.delta',
+]);

package/src/commentary/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Delivery-layer commentary-phase trace sanitization for
+ * `@graphorin/server`.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  bridgeCommentaryToAudit,
+  COMMENTARY_AUDIT_ACTION,
+  type CommentaryAuditSink,
+  commentaryDecisionToAuditInput,
+  createLateBoundCommentarySink,
+  type LateBoundCommentarySink,
+} from './audit-bridge.js';
+export {
+  DEFAULT_APPLY_TO_EVENTS,
+  DEFAULT_DELIVERY_COMMENTARY_PATTERNS,
+} from './built-in-patterns.js';
+export {
+  createDeliveryCommentarySanitizer,
+  type DeliveryCommentarySanitizer,
+} from './sanitizer.js';
+export type {
+  DeliveryCommentaryConfig,
+  DeliveryCommentaryDecision,
+  DeliveryCommentaryPattern,
+  DeliveryCommentaryPolicy,
+  DeliveryCommentaryReason,
+  DeliveryCommentarySink,
+  DeliveryCommentaryTransport,
+} from './types.js';