@graphorin/server 0.6.0 → 0.7.0

package/src/app-middleware.ts

@@ -0,0 +1,149 @@
+/**
+ * Middleware wiring for `createServer({...})`.
+ *
+ * Two attachment points, called in this order by the composition:
+ *
+ * 1. {@link attachGlobalMiddleware} - request-state / CORS / CSRF /
+ *    rate-limit, mounted on `*` at app construction time.
+ * 2. {@link attachProtectedMiddleware} - auth + audit + idempotency
+ *    for the authenticated subtree, mounted by `mountRoutes` after
+ *    the unauthenticated health / metrics endpoints.
+ *
+ * The relative order of these layers is part of the documented
+ * contract - do not reorder.
+ *
+ * @packageDocumentation
+ */
+
+import type { TokenVerifier } from '@graphorin/security';
+import type { AuditDb } from '@graphorin/security/audit';
+import type { GraphorinSqliteStore } from '@graphorin/store-sqlite';
+import type { Hono } from 'hono';
+import type { ServerConfigSpec } from './config.js';
+import type { ServerVariables } from './internal/context.js';
+import type { MetricRegistry } from './metrics/registry.js';
+import {
+  createAnonymousAuthMiddleware,
+  createAuditMiddleware,
+  createAuthMiddleware,
+  createCorsMiddleware,
+  createCsrfMiddleware,
+  createIdempotencyMiddleware,
+  createRateLimitMiddleware,
+  createRequestStateMiddleware,
+} from './middleware/index.js';
+
+/**
+ * Global middleware in the documented order. Per-route scope +
+ * idempotency layers are mounted by the route factories so the
+ * composition stays declarative + auditable.
+ */
+export function attachGlobalMiddleware(
+  app: Hono<{ Variables: ServerVariables }>,
+  config: ServerConfigSpec,
+  now: () => number,
+): void {
+  app.use(
+    '*',
+    createRequestStateMiddleware({
+      now,
+      ...(config.server.trustProxy ? { trustProxy: true } : {}),
+    }),
+  );
+  app.use('*', createCorsMiddleware(config.server.cors));
+  app.use('*', createCsrfMiddleware(config.server.csrf));
+  app.use('*', createRateLimitMiddleware(config.server.rateLimit, { now }));
+}
+
+/** Dependencies consumed by {@link attachProtectedMiddleware}. */
+export interface ProtectedMiddlewareContext {
+  readonly now: () => number;
+  readonly store: GraphorinSqliteStore;
+  readonly metricRegistry: MetricRegistry;
+  readonly verifier?: TokenVerifier | undefined;
+  readonly auditDb?: AuditDb | undefined;
+}
+
+/**
+ * Authenticated subtree begins here. The health endpoint above is
+ * intentionally outside the auth boundary so liveness probes work
+ * before the token verifier is wired. The WebSocket upgrade path is
+ * also exempt: the upgrade handler in `ws/upgrade.ts` performs its
+ * own bearer + ticket validation inline (the HTTP auth middleware
+ * would otherwise short-circuit the upgrade with a 401 response
+ * before the handler can negotiate the subprotocol).
+ */
+export function attachProtectedMiddleware(
+  app: Hono<{ Variables: ServerVariables }>,
+  config: ServerConfigSpec,
+  ctx: ProtectedMiddlewareContext,
+): { readonly anonymousAuth: boolean } {
+  const base = config.server.basePath;
+  const wsUpgradePath = config.server.ws.enabled ? `${base}${config.server.ws.path}` : undefined;
+  const metricsPath =
+    config.metrics.enabled && !config.metrics.requireAuth
+      ? `${base}${config.metrics.path}`
+      : undefined;
+  function shouldSkipAuth(path: string): boolean {
+    if (path === `${base}/health` || path === `${base}/health/`) return true;
+    if (wsUpgradePath !== undefined) {
+      if (path === wsUpgradePath || path === `${wsUpgradePath}/`) return true;
+    }
+    if (metricsPath !== undefined) {
+      if (path === metricsPath || path === `${metricsPath}/`) return true;
+    }
+    return false;
+  }
+  // IP-13: in the no-auth loopback mode (`auth.kind='none'`) there is no
+  // verifier, but the authenticated subtree must still be reachable - install
+  // an anonymous middleware that stamps a fully-authorized principal so the
+  // domain routes serve instead of every one of them returning 401.
+  const anonymousAuth = ctx.verifier === undefined && config.auth.kind === 'none';
+  if (ctx.verifier !== undefined || anonymousAuth) {
+    const authMw =
+      ctx.verifier !== undefined
+        ? createAuthMiddleware({ verifier: ctx.verifier })
+        : createAnonymousAuthMiddleware();
+    app.use(`${base}/*`, async (c, next) => {
+      if (shouldSkipAuth(c.req.path)) {
+        await next();
+        return;
+      }
+      return authMw(c, next);
+    });
+    if (ctx.auditDb !== undefined) {
+      const auditMw = createAuditMiddleware({ auditDb: ctx.auditDb, now: ctx.now });
+      app.use(`${base}/*`, async (c, next) => {
+        if (shouldSkipAuth(c.req.path)) {
+          await next();
+          return;
+        }
+        return auditMw(c, next);
+      });
+    }
+  }
+
+  // Idempotency middleware - applied to side-effecting endpoints. We
+  // mount it once on the authenticated subtree so handlers don't have
+  // to duplicate the configuration per-route.
+  if (config.server.idempotency.enabled) {
+    const idempotencyMw = createIdempotencyMiddleware({
+      store: ctx.store.idempotency,
+      config: config.server.idempotency,
+      now: ctx.now,
+      // IP-6: token minting returns a raw secret - never cache it.
+      excludeResponseCachePaths: [`${base}/tokens`],
+      // IP-15: publish the live cache hit ratio gauge.
+      metricRegistry: ctx.metricRegistry,
+    });
+    app.use(`${base}/*`, async (c, next) => {
+      if (shouldSkipAuth(c.req.path)) {
+        await next();
+        return;
+      }
+      return idempotencyMw(c, next);
+    });
+  }
+
+  return { anonymousAuth };
+}

package/src/app-routes.ts

@@ -0,0 +1,305 @@
+/**
+ * HTTP route mounting for `createServer({...})` - health, metrics,
+ * the authenticated middleware boundary, every REST domain surface,
+ * the WebSocket upgrade, and SSE. Mount order is part of the
+ * documented contract (unauthenticated health/metrics first, then the
+ * auth boundary, then the domain routes) - do not reorder.
+ *
+ * @packageDocumentation
+ */
+
+import type { TokenVerifier } from '@graphorin/security';
+import type { AuditDb } from '@graphorin/security/audit';
+import type { GraphorinSqliteStore } from '@graphorin/store-sqlite';
+import type { createNodeWebSocket } from '@hono/node-ws';
+import type { Hono } from 'hono';
+import { refreshLiveMetrics } from './app-metrics.js';
+import { attachProtectedMiddleware } from './app-middleware.js';
+import type { ServerConfigSpec } from './config.js';
+import type { ConsolidatorDaemon } from './consolidator/daemon.js';
+import {
+  createExtendedHealthRoutes,
+  createMetricsRoutes,
+  createSecretsHealthRoutes,
+  type HealthCheckOptions,
+} from './health/index.js';
+import type { ServerVariables } from './internal/context.js';
+import type { MetricRegistry } from './metrics/registry.js';
+import type { AgentRegistry, WorkflowRegistry } from './registry/index.js';
+import { createReplayRoutes, type ReplayApi } from './replay/index.js';
+import {
+  type AuditApi,
+  createAgentRoutes,
+  createAuditRoutes,
+  createAuthRoutes,
+  createMcpRoutes,
+  createMemoryRoutes,
+  createRunRoutes,
+  createSessionRoutes,
+  createSkillsRoutes,
+  createTokensRoutes,
+  createWorkflowRoutes,
+  type McpApi,
+  type MemoryApi,
+  type SessionApi,
+  type SkillsApi,
+} from './routes/index.js';
+import type { RunStateTracker } from './runtime/run-state.js';
+import { createSseRoutes } from './sse/index.js';
+import type { TriggersDaemon } from './triggers/daemon.js';
+import { createTriggersRoutes } from './triggers/routes.js';
+import type { WorkflowTimerDaemon } from './workflows/timer-daemon.js';
+import type { WsDispatcher, WsTicketStore } from './ws/index.js';
+import { createWsUpgradeEvents } from './ws/upgrade.js';
+
+export interface MountRoutesContext {
+  readonly version: string;
+  readonly startedAt: number;
+  readonly now: () => number;
+  readonly agents: AgentRegistry;
+  readonly workflows: WorkflowRegistry;
+  readonly runs: RunStateTracker;
+  readonly store: GraphorinSqliteStore;
+  readonly metricRegistry: MetricRegistry;
+  readonly sessions?: SessionApi;
+  readonly memory?: MemoryApi;
+  readonly skills?: SkillsApi;
+  readonly mcp?: McpApi;
+  readonly audit?: AuditApi;
+  readonly replay?: ReplayApi;
+  readonly healthProbes?: () => HealthCheckOptions | Promise<HealthCheckOptions>;
+  readonly verifier?: TokenVerifier;
+  readonly auditDb?: AuditDb;
+  readonly pepper?: import('@graphorin/security').SecretValue;
+  readonly wsDispatcher?: WsDispatcher;
+  readonly wsTickets?: WsTicketStore;
+  readonly wsAdapter?: ReturnType<typeof createNodeWebSocket>;
+  readonly triggersDaemon?: TriggersDaemon;
+  readonly consolidatorDaemon?: ConsolidatorDaemon;
+  readonly workflowTimerDaemon?: WorkflowTimerDaemon;
+}
+
+/** IP-23: is `host` a loopback interface (so an open /metrics is not exposed)? */
+function isLoopbackHost(host: string): boolean {
+  const h = host.trim().toLowerCase();
+  return h === '127.0.0.1' || h === '::1' || h === '[::1]' || h === 'localhost';
+}
+
+export function mountRoutes(
+  app: Hono<{ Variables: ServerVariables }>,
+  config: ServerConfigSpec,
+  ctx: MountRoutesContext,
+): void {
+  const base = config.server.basePath;
+  const probes =
+    ctx.healthProbes ??
+    (() =>
+      buildDefaultHealthProbes(
+        ctx.store,
+        ctx.triggersDaemon,
+        ctx.consolidatorDaemon,
+        ctx.wsDispatcher,
+        config,
+        ctx.workflowTimerDaemon,
+      ));
+  const health = createExtendedHealthRoutes({
+    version: ctx.version,
+    startedAt: ctx.startedAt,
+    now: ctx.now,
+    probes,
+  });
+  app.route(`${base}/health`, health);
+
+  // IP-13: `auth.kind='none'` disables authentication on every route. It is the
+  // documented trusted-loopback / single-operator mode, but binding a
+  // non-loopback host with auth off exposes full admin access (including the WS
+  // stream) to anyone who can reach it - warn loudly rather than silently.
+  if (config.auth.kind === 'none' && !isLoopbackHost(config.server.host)) {
+    console.warn(
+      `[graphorin/server] WARN: auth.kind='none' disables authentication on every endpoint, ` +
+        `but the server binds the non-loopback host '${config.server.host}'. Anyone who can reach ` +
+        `it has full admin access - use auth.kind='token' for non-loopback deployments or bind a ` +
+        `loopback host.`,
+    );
+  }
+
+  if (config.metrics.enabled) {
+    // IP-23: an unauthenticated /metrics endpoint leaks operational intel
+    // (trigger ids in labels, consolidator budgets). It is fine on a loopback
+    // host, but binding a non-loopback host with auth off silently exposes it.
+    if (!config.metrics.requireAuth && !isLoopbackHost(config.server.host)) {
+      console.warn(
+        `[graphorin/server] WARN: /metrics is unauthenticated (metrics.requireAuth=false) and ` +
+          `the server binds the non-loopback host '${config.server.host}'. The exposition leaks ` +
+          `operational detail to anyone who can reach it - set metrics.requireAuth=true or bind a ` +
+          `loopback host.`,
+      );
+    }
+    const metricsRoute = createMetricsRoutes({
+      registry: ctx.metricRegistry,
+      requireAuth: config.metrics.requireAuth,
+      refresh: () =>
+        refreshLiveMetrics({
+          registry: ctx.metricRegistry,
+          store: ctx.store,
+          runs: ctx.runs,
+          startedAt: ctx.startedAt,
+          now: ctx.now,
+          ...(ctx.triggersDaemon !== undefined ? { triggersDaemon: ctx.triggersDaemon } : {}),
+          ...(ctx.consolidatorDaemon !== undefined
+            ? { consolidatorDaemon: ctx.consolidatorDaemon }
+            : {}),
+          ...(ctx.wsDispatcher !== undefined ? { wsDispatcher: ctx.wsDispatcher } : {}),
+        }),
+    });
+    app.route(`${base}${config.metrics.path}`, metricsRoute);
+  }
+
+  // Auth + audit + idempotency for everything below this line - see
+  // `app-middleware.ts` for the boundary semantics and skip list.
+  const { anonymousAuth } = attachProtectedMiddleware(app, config, ctx);
+
+  // Mounted AFTER the auth middleware so the scope check has a
+  // verified token to inspect; the unauthenticated `/v1/health` GET
+  // continues to serve the rollup.
+  app.route(`${base}/health/secrets`, createSecretsHealthRoutes());
+
+  app.route(
+    `${base}/agents`,
+    createAgentRoutes({
+      agents: ctx.agents,
+      runs: ctx.runs,
+      // IP-2: the streaming dispatcher reaches the route layer.
+      ...(ctx.wsDispatcher !== undefined ? { dispatcher: ctx.wsDispatcher } : {}),
+    }),
+  );
+  app.route(`${base}/runs`, createRunRoutes({ agents: ctx.agents, runs: ctx.runs }));
+  app.route(
+    `${base}/workflows`,
+    createWorkflowRoutes({
+      workflows: ctx.workflows,
+      runs: ctx.runs,
+      ...(ctx.wsDispatcher !== undefined ? { dispatcher: ctx.wsDispatcher } : {}),
+    }),
+  );
+  if (ctx.sessions !== undefined) {
+    app.route(`${base}/sessions`, createSessionRoutes({ sessions: ctx.sessions }));
+  }
+  if (ctx.memory !== undefined) {
+    app.route(`${base}/memory`, createMemoryRoutes({ memory: ctx.memory }));
+  }
+  if (ctx.skills !== undefined) {
+    app.route(`${base}/skills`, createSkillsRoutes({ skills: ctx.skills }));
+  }
+  if (ctx.mcp !== undefined) {
+    app.route(`${base}/mcp`, createMcpRoutes({ mcp: ctx.mcp }));
+  }
+  if (ctx.audit !== undefined) {
+    app.route(`${base}/audit`, createAuditRoutes({ audit: ctx.audit }));
+  }
+  if (ctx.triggersDaemon !== undefined) {
+    app.route(`${base}/triggers`, createTriggersRoutes({ daemon: ctx.triggersDaemon }));
+  }
+  if (ctx.replay !== undefined) {
+    app.route(
+      `${base}`,
+      createReplayRoutes({
+        replay: ctx.replay,
+        ...(ctx.auditDb !== undefined ? { auditDb: ctx.auditDb } : {}),
+        now: ctx.now,
+      }),
+    );
+  }
+  if (config.auth.kind === 'token' && ctx.pepper !== undefined) {
+    app.route(
+      `${base}/tokens`,
+      createTokensRoutes({
+        tokenStore: ctx.store.authTokens,
+        pepper: ctx.pepper,
+        defaultEnv: 'live',
+        allowedEnvs: config.auth.tokenEnvironments,
+      }),
+    );
+  }
+  if (ctx.wsTickets !== undefined) {
+    app.route(`${base}`, createAuthRoutes({ tickets: ctx.wsTickets }));
+  }
+  // IP-13: mount the WS upgrade when a verifier is wired OR auth is disabled
+  // (`auth.kind='none'`). The old condition required a verifier, so
+  // `ws.enabled: true` under no-auth was silently ignored - the route never
+  // mounted and clients got a bare 404 with no explanation.
+  if (
+    ctx.wsDispatcher !== undefined &&
+    ctx.wsTickets !== undefined &&
+    ctx.wsAdapter !== undefined &&
+    (ctx.verifier !== undefined || anonymousAuth) &&
+    config.server.ws.enabled
+  ) {
+    const dispatcher = ctx.wsDispatcher;
+    const tickets = ctx.wsTickets;
+    const verifier = ctx.verifier;
+    const runs = ctx.runs;
+    app.get(
+      `${base}${config.server.ws.path}`,
+      ctx.wsAdapter.upgradeWebSocket((c) =>
+        createWsUpgradeEvents(c, {
+          dispatcher,
+          tickets,
+          ...(verifier !== undefined ? { verifier } : {}),
+          anonymous: anonymousAuth,
+          runs,
+          now: ctx.now,
+        }),
+      ),
+    );
+  }
+  if (ctx.wsDispatcher !== undefined && config.server.sse.enabled) {
+    app.route(
+      `${base}${config.server.sse.path}`,
+      createSseRoutes({
+        dispatcher: ctx.wsDispatcher,
+        keepAliveMs: config.server.sse.keepAliveMs,
+        // IP-9: bound the per-connection delivery queue.
+        perConnectionQueueLimit: config.server.stream.perConnectionQueueLimit,
+        now: ctx.now,
+      }),
+    );
+  }
+}
+
+function buildDefaultHealthProbes(
+  store: GraphorinSqliteStore,
+  triggersDaemon: TriggersDaemon | undefined,
+  consolidatorDaemon: ConsolidatorDaemon | undefined,
+  dispatcher: WsDispatcher | undefined,
+  config: ServerConfigSpec,
+  workflowTimerDaemon?: WorkflowTimerDaemon,
+): HealthCheckOptions {
+  const out: {
+    -readonly [K in keyof HealthCheckOptions]?: HealthCheckOptions[K];
+  } = {
+    store,
+    walWarnThresholdBytes: config.health.walWarnThresholdBytes,
+    encryptionEnabled: config.storage.encryption.enabled,
+    // IP-1: when this process built the encrypted store itself, the
+    // keyed open at boot proved the cipher peer - report the fact.
+    ...(config.storage.encryption.enabled ? { cipherPeerInstalled: true } : {}),
+  };
+  if (triggersDaemon !== undefined) out.triggers = triggersDaemon;
+  if (consolidatorDaemon !== undefined) out.consolidator = consolidatorDaemon;
+  if (workflowTimerDaemon !== undefined) out.workflowTimers = workflowTimerDaemon;
+  if (dispatcher !== undefined) {
+    const sizes = dispatcher.size();
+    // The dispatcher only exposes (subscribers, subscriptions); the
+    // per-subject replay-buffer occupancy is owned by each
+    // subscription, not the dispatcher itself. Surface the active
+    // subscription count as a usable proxy + the raw subscriber count
+    // so operators can correlate.
+    out.replayBuffer = {
+      eventsBuffered: sizes.subscriptions,
+      subscribers: sizes.subscribers,
+      subscriptions: sizes.subscriptions,
+    };
+  }
+  return Object.freeze(out as HealthCheckOptions);
+}

package/src/app-ws.ts

@@ -0,0 +1,111 @@
+/**
+ * WebSocket layer construction for `createServer({...})` - dispatcher,
+ * single-use ticket store, the `@hono/node-ws` adapter, and the
+ * Graphorin-aware subprotocol negotiation policy. Built before the
+ * listener starts; the upgrade route itself is mounted in
+ * `app-routes.ts` and the adapter is injected into the Node server in
+ * `app-lifecycle.ts`.
+ *
+ * @packageDocumentation
+ */
+
+import { negotiateSubprotocol, SUBPROTOCOL_NAME } from '@graphorin/protocol';
+import { createNodeWebSocket } from '@hono/node-ws';
+import type { Hono } from 'hono';
+import { createLateBoundCommentarySink, type LateBoundCommentarySink } from './commentary/index.js';
+import type { ServerConfigSpec } from './config.js';
+import type { ServerVariables } from './internal/context.js';
+import {
+  createWsDispatcher,
+  createWsTicketStore,
+  type WsDispatcher,
+  type WsTicketStore,
+} from './ws/index.js';
+
+/**
+ * Everything the WebSocket layer contributes to the composed server.
+ * Every member is `undefined` when `server.ws.enabled` is false.
+ */
+export interface WsLayer {
+  readonly dispatcher: WsDispatcher | undefined;
+  readonly tickets: WsTicketStore | undefined;
+  readonly wsAdapter: ReturnType<typeof createNodeWebSocket> | undefined;
+  readonly commentaryAuditSink: LateBoundCommentarySink | undefined;
+}
+
+/**
+ * Build the WS dispatcher + ticket store + node-ws adapter when
+ * `server.ws.enabled` is true.
+ */
+export function buildWsLayer(
+  app: Hono<{ Variables: ServerVariables }>,
+  config: ServerConfigSpec,
+  now: () => number,
+): WsLayer {
+  let dispatcher: WsDispatcher | undefined;
+  let tickets: WsTicketStore | undefined;
+  let wsAdapter: ReturnType<typeof createNodeWebSocket> | undefined;
+  // IP-21: the dispatcher is built here, before the audit DB opens in start().
+  // Hand it a late-bound commentary sink now and install the audit-writing
+  // target once the DB exists - otherwise the sanitizer's documented decisions
+  // (wrapped/stripped frames with before/after digests) are dropped.
+  let commentaryAuditSink: LateBoundCommentarySink | undefined;
+  if (config.server.ws.enabled) {
+    commentaryAuditSink = createLateBoundCommentarySink();
+    dispatcher = createWsDispatcher({
+      commentary: {
+        policy: config.server.ws.commentarySanitization.policy,
+        applyToEvents: config.server.ws.commentarySanitization.applyToEvents,
+        sink: commentaryAuditSink,
+      },
+      replayBuffer: {
+        maxEvents: config.server.stream.replayBuffer.maxEvents,
+        ttlMs: config.server.stream.replayBuffer.ttlSeconds * 1000,
+      },
+      perConnectionQueueLimit: config.server.stream.perConnectionQueueLimit,
+      now,
+    });
+    tickets = createWsTicketStore({
+      ttlMs: config.server.ws.ticketTtlMs,
+      now,
+    });
+    wsAdapter = createNodeWebSocket({ app });
+    // The WS server inside @hono/node-ws is created without any
+    // subprotocol-negotiation policy; without one, the `ws` library
+    // never echoes back `Sec-WebSocket-Protocol` and clients that
+    // advertised a subprotocol close the connection immediately.
+    // Mutate the options to install a Graphorin-aware policy that
+    // selects `graphorin.protocol.v1` when the client offered it.
+    const wssOptions = (
+      wsAdapter.wss as unknown as {
+        options: {
+          handleProtocols?: (
+            protocols: Set<string>,
+            request: import('node:http').IncomingMessage,
+          ) => string | false;
+        };
+      }
+    ).options;
+    wssOptions.handleProtocols = (protocols) => {
+      const negotiated = negotiateSubprotocol(Array.from(protocols));
+      if (negotiated !== null) return negotiated;
+      // Browser ticket flow: the `WebSocket` constructor cannot set an
+      // `Authorization` header, so the browser client offers two
+      // subprotocol tokens - the canonical `graphorin.protocol.v1`
+      // name plus a `ticket.<value>` token (see the wire contract in
+      // `@graphorin/protocol`'s `subprotocol.ts`:
+      // `SUBPROTOCOL_NAME` / `TICKET_SUBPROTOCOL_PREFIX` /
+      // `parseTicketSubprotocol`). The server MUST echo back exactly
+      // the canonical name (never the `ticket.*` token) so the
+      // handshake's `Sec-WebSocket-Protocol` response stays valid; the
+      // ticket value is consumed separately by `createWsUpgradeEvents`
+      // via `parseTicketSubprotocol` and exchanged through the
+      // single-use `WsTicketStore`.
+      for (const candidate of protocols) {
+        if (candidate === SUBPROTOCOL_NAME) return SUBPROTOCOL_NAME;
+      }
+      return false;
+    };
+  }
+  return { dispatcher, tickets, wsAdapter, commentaryAuditSink };
+}