@graphorin/server 0.6.0 → 0.7.0

package/src/metrics/tools-bridge.ts

@@ -0,0 +1,124 @@
+/**
+ * W-051: bridge the `@graphorin/tools` module-level counter registry
+ * (which `@graphorin/mcp` also writes) into the server's
+ * {@link MetricRegistry}, so `tool.*` / `mcp.*` telemetry - including
+ * the shadow-mode `tool.dataflow.*` counters - shows up on
+ * `/v1/metrics` without hand-wiring.
+ *
+ * Called from `refreshLiveMetrics` on every scrape. Counters are
+ * delta-synced (the tools registry is cumulative per process; the
+ * Prometheus registry increments by the positive difference, so
+ * repeated scrapes never double-count); gauges are set absolutely -
+ * the `kinds` field on the snapshot (added for exactly this bridge)
+ * tells the two apart. Histograms are deliberately NOT bridged yet:
+ * summary bridging needs per-key consumed-observation offsets, and the
+ * raw observation lists stay available through `snapshotCounters()`
+ * for library users (documented in the observability guide).
+ *
+ * Naming: `tool.executor.retry.total{toolName=x}` becomes
+ * `graphorin_tool_executor_retry_total{toolName="x"}` - `[.-]` map to
+ * `_` (the Prometheus name grammar forbids dots), label values pass
+ * through the same sanitizer as trigger ids.
+ *
+ * @packageDocumentation
+ */
+
+import { type CounterSnapshot, snapshotCounters } from '@graphorin/tools/audit';
+import type { MetricRegistry } from './registry.js';
+
+const BRIDGED_PREFIXES = ['tool.', 'mcp.'] as const;
+const PROM_LABEL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/**
+ * Sync the tools-package counter snapshot into `registry`. Idempotent
+ * per value: scraping twice without new increments changes nothing.
+ *
+ * @stable
+ */
+export function syncToolCounters(
+  registry: MetricRegistry,
+  snapshot: CounterSnapshot = snapshotCounters(),
+): void {
+  for (const [key, value] of Object.entries(snapshot.counters)) {
+    const parsed = parseCounterKey(key);
+    if (parsed === undefined) continue;
+    if (!BRIDGED_PREFIXES.some((prefix) => parsed.name.startsWith(prefix))) continue;
+    const kind = snapshot.kinds[key] ?? 'counter';
+    const metricName = toPrometheusName(parsed.name);
+    try {
+      if (kind === 'gauge') {
+        registry.registerGauge(metricName, `Bridged from tools counter '${parsed.name}'.`);
+        registry.set(metricName, value, parsed.labels);
+      } else {
+        registry.registerCounter(metricName, `Bridged from tools counter '${parsed.name}'.`);
+        const current = readBridgedValue(registry, metricName, parsed.labels);
+        const delta = value - current;
+        if (delta > 0) registry.inc(metricName, parsed.labels, delta);
+      }
+    } catch {
+      // Best-effort: one malformed key (or a name registered by other
+      // code with a conflicting kind) must never fail the scrape.
+    }
+  }
+}
+
+/** Parsed `name{k=v,...}` key in the tools `buildKey` format. */
+interface ParsedCounterKey {
+  readonly name: string;
+  readonly labels: Record<string, string>;
+}
+
+function parseCounterKey(key: string): ParsedCounterKey | undefined {
+  const brace = key.indexOf('{');
+  if (brace === -1) return { name: key, labels: {} };
+  if (!key.endsWith('}')) return undefined;
+  const name = key.slice(0, brace);
+  const body = key.slice(brace + 1, -1);
+  const labels: Record<string, string> = {};
+  for (const pair of body.split(',')) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) return undefined;
+    const labelName = pair.slice(0, eq);
+    if (!PROM_LABEL_NAME_RE.test(labelName)) return undefined;
+    labels[labelName] = sanitizeLabelValue(pair.slice(eq + 1));
+  }
+  return { name, labels };
+}
+
+function toPrometheusName(name: string): string {
+  return `graphorin_${name.replace(/[.-]/g, '_')}`;
+}
+
+/**
+ * Same policy as the trigger-id sanitizer in `app-metrics.ts`: bound
+ * the character set and the length so server identities / tool names
+ * cannot explode label cardinality with UTF-8 sequences.
+ */
+function sanitizeLabelValue(value: string): string {
+  return value.replace(/[^A-Za-z0-9_:.\-/]/g, '_').slice(0, 200);
+}
+
+function readBridgedValue(
+  registry: MetricRegistry,
+  name: string,
+  labels: Record<string, string>,
+): number {
+  const entries = registry.snapshot().counters[name] ?? [];
+  for (const entry of entries) {
+    if (labelsEqual(entry.labels, labels)) return entry.value;
+  }
+  return 0;
+}
+
+function labelsEqual(
+  a: Record<string, string | number | boolean>,
+  b: Record<string, string>,
+): boolean {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of bKeys) {
+    if (String(a[k]) !== b[k]) return false;
+  }
+  return true;
+}

package/src/middleware/audit.ts

@@ -0,0 +1,114 @@
+/**
+ * Audit middleware. Forwards every authenticated request through
+ * `appendAudit` (`@graphorin/security/audit`) so the operator gets a
+ * tamper-evident chain of every state-changing call. Append failures
+ * never break the request hot path; they are recorded on a best-
+ * effort error sink.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type AuditDb,
+  type AuditDecision,
+  type AuditEntryInput,
+  appendAudit,
+} from '@graphorin/security/audit';
+import type { MiddlewareHandler } from 'hono';
+
+import type { ServerVariables } from '../internal/context.js';
+
+/**
+ * Canonical action discriminator emitted on every authenticated REST
+ * request per the Phase 14a spec (`§ Audit middleware`). Exposed as
+ * a constant so consumers (downstream filters, dashboards) can grep
+ * for it without restating the literal everywhere.
+ *
+ * @stable
+ */
+export const HTTP_REQUEST_AUDIT_ACTION = 'http:request' as const;
+
+/**
+ * Optional telemetry sink. The default ignores errors; production
+ * deployments wire this into their structured logger.
+ *
+ * @stable
+ */
+export type AuditErrorSink = (err: unknown, entry: Omit<AuditEntryInput, 'ts'>) => void;
+
+/**
+ * @stable
+ */
+export interface AuditMiddlewareOptions {
+  readonly auditDb: AuditDb;
+  /** Optional override for the time source. */
+  readonly now?: () => number;
+  /** Optional error sink. Defaults to swallow. */
+  readonly onError?: AuditErrorSink;
+  /**
+   * When `true` (the default), include the path + method + status on
+   * the audit entry's metadata. Disable for compliance-strict
+   * deployments that already log the request envelope elsewhere.
+   */
+  readonly recordMetadata?: boolean;
+}
+
+function decisionForStatus(status: number): AuditDecision {
+  if (status >= 500) return 'error';
+  if (status === 404) return 'not-found';
+  if (status >= 400) return 'denied';
+  return 'success';
+}
+
+/**
+ * @stable
+ */
+export function createAuditMiddleware(
+  options: AuditMiddlewareOptions,
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  const now = options.now ?? Date.now;
+  const onError = options.onError ?? (() => {});
+  const recordMetadata = options.recordMetadata ?? true;
+
+  return async (c, next) => {
+    const start = now();
+    await next();
+    const status = c.res?.status ?? 0;
+    const auth = c.get('state').auth;
+    if (auth.kind !== 'token') {
+      // Anonymous calls (health, etc.) are not audited.
+      return;
+    }
+    const token = auth.token;
+    const entry: AuditEntryInput = {
+      ts: now(),
+      actor: {
+        kind: 'token',
+        id: token.tokenId,
+        ...(token.label !== undefined ? { label: token.label } : {}),
+      },
+      action: HTTP_REQUEST_AUDIT_ACTION,
+      target: c.req.path,
+      decision: decisionForStatus(status),
+      ...(recordMetadata
+        ? {
+            metadata: {
+              method: c.req.method,
+              status,
+              durationMs: now() - start,
+              requestId: c.get('state').requestId,
+              ...(c.get('state').idempotencyKey !== undefined
+                ? { idempotencyKey: c.get('state').idempotencyKey }
+                : {}),
+              ...(c.get('state').idempotencyReplay === true ? { idempotencyReplayed: true } : {}),
+            },
+          }
+        : {}),
+    };
+    try {
+      await appendAudit(options.auditDb, entry);
+    } catch (err) {
+      onError(err, entry);
+    }
+  };
+}

package/src/middleware/auth.ts

@@ -0,0 +1,195 @@
+/**
+ * Bearer-token authentication middleware. Wraps the
+ * `@graphorin/security` token verifier so handlers see
+ * a stable {@link import('../internal/context.js').AuthState}
+ * structure on `c.var.state.auth`.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type ParsedScope,
+  parseScope,
+  type TokenVerifier,
+  tryParseScope,
+} from '@graphorin/security/auth';
+import type { Context, MiddlewareHandler, Next } from 'hono';
+
+import type { ServerVariables } from '../internal/context.js';
+
+/**
+ * IP-13: the scope set granted to every request when `auth.kind = 'none'`.
+ * `admin:*` matches every required scope (see `@graphorin/security/auth`
+ * `scopeMatches`), so the trusted-loopback operator is uniformly authorized
+ * without special-casing each route.
+ */
+const ANONYMOUS_GRANTED_SCOPES: ReadonlyArray<ParsedScope> = Object.freeze([parseScope('admin:*')]);
+
+/**
+ * Build the no-auth middleware mounted when `auth.kind = 'none'`. It stamps
+ * `state.auth = { kind: 'anonymous', grantedScopes: [admin:*] }` so the
+ * scope middleware, SSE handler and replay routes all treat the request as a
+ * fully-authorized principal. This is the documented trusted-loopback /
+ * single-operator mode - never mount it on a non-loopback deployment without
+ * understanding that every endpoint becomes open.
+ *
+ * @stable
+ */
+export function createAnonymousAuthMiddleware(): MiddlewareHandler<{
+  Variables: ServerVariables;
+}> {
+  return async (c, next: Next) => {
+    c.set('state', {
+      ...c.get('state'),
+      auth: { kind: 'anonymous' as const, grantedScopes: ANONYMOUS_GRANTED_SCOPES },
+    });
+    await next();
+  };
+}
+
+/**
+ * Options accepted by {@link createAuthMiddleware}. Tests inject a
+ * stub verifier; production wiring uses the verifier built during the
+ * server's pre-bind step.
+ *
+ * @stable
+ */
+export interface AuthMiddlewareOptions {
+  readonly verifier: TokenVerifier;
+  /**
+   * Whether to allow unauthenticated requests through. Used by
+   * `health` and (when explicitly opted-in) by the public read
+   * endpoints. When `false` (the default), missing / malformed /
+   * invalid tokens short-circuit the request with `401`.
+   */
+  readonly allowAnonymous?: boolean;
+}
+
+const HEADER_NAME = 'authorization';
+const BEARER_PREFIX = 'bearer ';
+
+function extractBearer(c: Context): string | undefined {
+  const raw = c.req.header(HEADER_NAME);
+  if (raw === undefined || raw === null) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length < BEARER_PREFIX.length) return undefined;
+  if (trimmed.slice(0, BEARER_PREFIX.length).toLowerCase() !== BEARER_PREFIX) return undefined;
+  return trimmed.slice(BEARER_PREFIX.length).trim();
+}
+
+function reasonToStatus(reason: string): {
+  status: number;
+  body: { error: string; message: string; hint?: string };
+} {
+  switch (reason) {
+    case 'malformed':
+      return { status: 401, body: { error: 'auth-invalid', message: 'Malformed bearer token.' } };
+    case 'unknown-token':
+      return { status: 401, body: { error: 'auth-invalid', message: 'Unknown bearer token.' } };
+    case 'revoked':
+      return {
+        status: 401,
+        body: { error: 'auth-revoked', message: 'Bearer token has been revoked.' },
+      };
+    case 'expired':
+      return { status: 401, body: { error: 'auth-expired', message: 'Bearer token has expired.' } };
+    case 'ip-locked-out':
+      return {
+        status: 429,
+        body: {
+          error: 'auth-locked-out',
+          message: 'Too many failed authentications from this address.',
+          hint: 'Wait for the lockout window to elapse before retrying.',
+        },
+      };
+    case 'token-locked-out':
+      return {
+        status: 429,
+        body: {
+          error: 'auth-locked-out',
+          message: 'Bearer token is locked out after repeated failures.',
+          hint: 'Operator must rotate the token.',
+        },
+      };
+    default:
+      return {
+        status: 401,
+        body: { error: 'auth-invalid', message: `Authentication failed: ${reason}.` },
+      };
+  }
+}
+
+/**
+ * Build the bearer-token middleware. The middleware always sets
+ * `c.var.state.auth`, even on the unauthenticated branch, so
+ * downstream code can pattern-match the discriminated union without
+ * a separate "is anonymous?" check.
+ *
+ * @stable
+ */
+export function createAuthMiddleware(
+  options: AuthMiddlewareOptions,
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  const allowAnonymous = options.allowAnonymous ?? false;
+  return async (c, next: Next) => {
+    const token = extractBearer(c);
+    // IP-11: the request-state middleware is the ONLY IP authority -
+    // it resolves the client IP per the configured trustProxy policy
+    // (proxy headers when trusted, else the socket address). The old
+    // fallback read attacker-controlled X-Real-IP unconditionally,
+    // letting header rotation evade per-IP lockout and a spoofed
+    // victim IP trigger a lockout against them.
+    const ip = c.get('state').clientIp;
+    if (token === undefined) {
+      if (allowAnonymous) {
+        c.set('state', { ...c.get('state'), auth: { kind: 'unauthenticated' as const } });
+        await next();
+        return;
+      }
+      return c.json(
+        {
+          error: 'auth-required',
+          message: 'Bearer token required.',
+          hint: "Set 'Authorization: Bearer <token>'.",
+        },
+        401,
+      );
+    }
+    const result = await options.verifier.verify(token, ip !== undefined ? { ip } : {});
+    if (!result.ok) {
+      const mapped = reasonToStatus(result.reason);
+      const headers: Record<string, string> = {};
+      if (result.retryAfterMs !== undefined) {
+        headers['Retry-After'] = Math.ceil(result.retryAfterMs / 1000).toString();
+      }
+      return c.json(mapped.body, mapped.status as 401 | 429, headers);
+    }
+    const grantedScopes: ParsedScope[] = [];
+    for (const scope of result.token.scopes) {
+      grantedScopes.push(scope);
+    }
+    // Defensive: any string scopes coming from the store also parse here
+    // even though the verifier itself parses them - see scope.ts.
+    void tryParseScope;
+    c.set('state', {
+      ...c.get('state'),
+      auth: {
+        kind: 'token' as const,
+        token: result.token,
+        grantedScopes: Object.freeze(grantedScopes),
+      },
+    });
+    // Mirror the verified token onto the documented `c.var.token`
+    // slot so route handlers can read it without unwrapping the auth
+    // discriminator. The shape is the one called out in the Phase
+    // 14a spec: { id, label, scopes, env, expiresAt? }.
+    c.set('token', {
+      id: result.token.tokenId,
+      label: result.token.label,
+      scopes: Object.freeze(grantedScopes.slice()),
+      env: result.token.env,
+      expiresAt: result.token.expiresAt,
+    });
+    await next();
+  };
+}

package/src/middleware/cors.ts

@@ -0,0 +1,72 @@
+/**
+ * Deny-by-default CORS middleware. The framework refuses to echo back
+ * arbitrary origins; allowlist semantics match the threat-model
+ * checklist in the runtime architecture.
+ *
+ * @packageDocumentation
+ */
+
+import type { MiddlewareHandler } from 'hono';
+
+import type { ServerConfigSpec } from '../config.js';
+import type { ServerVariables } from '../internal/context.js';
+
+/**
+ * @stable
+ */
+export function createCorsMiddleware(
+  config: ServerConfigSpec['server']['cors'],
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  const allowSet = new Set(config.allowOrigins);
+  const allowAny = allowSet.has('*');
+  const allowMethods = config.allowMethods.join(', ');
+  const allowHeaders = config.allowHeaders.join(', ');
+  const maxAge = config.maxAgeSeconds.toString();
+
+  return async (c, next) => {
+    const origin = c.req.header('origin');
+    const isPreflight =
+      c.req.method === 'OPTIONS' && c.req.header('access-control-request-method') !== undefined;
+    if (origin === undefined) {
+      // Same-origin request - proceed without CORS headers.
+      if (isPreflight) {
+        return c.body(null, 204);
+      }
+      await next();
+      return;
+    }
+    const allowed = allowAny || allowSet.has(origin);
+    if (!allowed) {
+      if (isPreflight) {
+        return c.body(null, 204);
+      }
+      // Pass the request through but withhold the CORS allow header so
+      // the browser blocks it; do NOT short-circuit the request - the
+      // server-to-server flow must still receive a normal response.
+      await next();
+      return;
+    }
+
+    if (allowAny && config.allowCredentials) {
+      // Specs forbid `Access-Control-Allow-Origin: *` with credentials;
+      // mirror the request origin instead.
+      c.header('Access-Control-Allow-Origin', origin);
+      c.header('Vary', 'Origin');
+    } else if (allowAny) {
+      c.header('Access-Control-Allow-Origin', '*');
+    } else {
+      c.header('Access-Control-Allow-Origin', origin);
+      c.header('Vary', 'Origin');
+    }
+    if (config.allowCredentials) {
+      c.header('Access-Control-Allow-Credentials', 'true');
+    }
+    if (isPreflight) {
+      c.header('Access-Control-Allow-Methods', allowMethods);
+      c.header('Access-Control-Allow-Headers', allowHeaders);
+      c.header('Access-Control-Max-Age', maxAge);
+      return c.body(null, 204);
+    }
+    await next();
+  };
+}

package/src/middleware/csrf.ts

@@ -0,0 +1,98 @@
+/**
+ * Double-submit CSRF middleware. Targets browser flows: when a
+ * request carries a session-cookie style credential we require the
+ * client to echo the value of the `graphorin_csrf` cookie back in
+ * the `X-CSRF-Token` header. Bearer-token (Authorization header)
+ * requests are exempt because they are not vulnerable to the
+ * confused-deputy attack the cookie pattern guards against.
+ *
+ * @packageDocumentation
+ */
+
+import { Buffer } from 'node:buffer';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+import type { MiddlewareHandler } from 'hono';
+
+import type { ServerConfigSpec } from '../config.js';
+import type { ServerVariables } from '../internal/context.js';
+
+/**
+ * @stable
+ */
+export function createCsrfMiddleware(
+  config: ServerConfigSpec['server']['csrf'],
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  if (!config.enabled) {
+    return async (_, next) => {
+      await next();
+    };
+  }
+  const safeMethods = new Set(config.safeMethods.map((m) => m.toUpperCase()));
+
+  return async (c, next) => {
+    const method = c.req.method.toUpperCase();
+    const cookieHeader = c.req.header('cookie');
+    const cookies = parseCookies(cookieHeader);
+    const cookieValue = cookies.get(config.cookieName);
+    const authHeader = c.req.header('authorization');
+    const isBearer = authHeader !== undefined && /^bearer\s+/i.test(authHeader);
+
+    if (safeMethods.has(method) || isBearer) {
+      // Always issue a fresh CSRF cookie on browser flows so SPAs
+      // can read it on first load. Skip the cookie issuance for
+      // bearer-only callers - they don't need it.
+      if (!isBearer && cookieValue === undefined) {
+        const token = randomBytes(24).toString('base64url');
+        // IP-12: the CSRF token must be readable by the SPA for the
+        // double-submit echo, so the cookie carries NO HttpOnly attribute -
+        // RFC 6265 enables HttpOnly on its mere presence, even `HttpOnly=false`.
+        c.header('Set-Cookie', `${config.cookieName}=${token}; Path=/; SameSite=Strict; Secure`);
+      }
+      await next();
+      return;
+    }
+
+    if (cookieValue === undefined) {
+      return c.json(
+        { error: 'csrf-denied', message: 'CSRF cookie missing on state-changing request.' },
+        403,
+      );
+    }
+    const headerValue = c.req.header(config.headerName);
+    if (headerValue === undefined) {
+      return c.json(
+        { error: 'csrf-denied', message: `CSRF header '${config.headerName}' missing.` },
+        403,
+      );
+    }
+    if (!constantTimeEqual(cookieValue, headerValue)) {
+      return c.json({ error: 'csrf-denied', message: 'CSRF token mismatch.' }, 403);
+    }
+    await next();
+  };
+}
+
+function parseCookies(header: string | undefined): Map<string, string> {
+  const out = new Map<string, string>();
+  if (header === undefined) return out;
+  const parts = header.split(';');
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed.length === 0) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 0) continue;
+    const name = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    out.set(name, value);
+  }
+  return out;
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  const aBuf = Buffer.from(a, 'utf8');
+  const bBuf = Buffer.from(b, 'utf8');
+  if (aBuf.length !== bBuf.length) return false;
+  return timingSafeEqual(aBuf, bBuf);
+}