@graphorin/server 0.6.1 → 0.7.0

package/src/middleware/idempotency.ts

@@ -0,0 +1,336 @@
+/**
+ * REST `Idempotency-Key` middleware per IETF
+ * draft-ietf-httpapi-idempotency-key-header-07. Layers an LRU
+ * read-cache over a durable {@link IdempotencyStore} so:
+ *
+ * - Replays of a successful request return the cached response body
+ *   AND the original status code, with a synthetic
+ *   `Idempotency-Replayed: true` header so clients can distinguish
+ *   the cached path.
+ * - Replays of a key with a different request body return `409
+ *   Conflict` and a typed error body (per ADR-036 / DEC-142).
+ * - 5xx + 408 + 429 + 503 responses are NOT cached so transient
+ *   errors do not pin the operator into a non-recoverable state.
+ *
+ * Streaming endpoints (`/v1/agents/:id/stream`,
+ * `/v1/workflows/:id/execute` when invoked with the `stream=true`
+ * query) cache only the initial 202 + `runId` envelope; the actual
+ * event stream is replayed via the WebSocket layer (Phase 14b).
+ *
+ * @packageDocumentation
+ */
+
+import type { IdempotencyRecord, IdempotencyStore } from '@graphorin/store-sqlite';
+import type { Context, MiddlewareHandler } from 'hono';
+
+import type { ServerConfigSpec } from '../config.js';
+import type { ServerVariables } from '../internal/context.js';
+import { fingerprintRequest } from '../internal/json.js';
+import { SERVER_METRIC_NAMES } from '../metrics/catalog.js';
+import type { MetricRegistry } from '../metrics/registry.js';
+
+const HEADER_NAME = 'idempotency-key';
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
+// Status codes the IETF draft + Stripe convention exclude from
+// idempotent caching (always retry-eligible).
+const NON_CACHEABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+const KEY_RE = /^[A-Za-z0-9_\-:]{8,255}$/;
+
+/**
+ * Options accepted by {@link createIdempotencyMiddleware}.
+ *
+ * @stable
+ */
+export interface IdempotencyMiddlewareOptions {
+  /**
+   * Paths whose responses are NEVER cached or replayed (IP-6) - the
+   * middleware passes straight through. Used for secret-bearing
+   * endpoints (`POST /v1/tokens` returns a raw token; caching it would
+   * persist the secret plaintext in durable SQLite for the TTL).
+   */
+  readonly excludeResponseCachePaths?: ReadonlyArray<string>;
+  readonly store: IdempotencyStore;
+  readonly config: ServerConfigSpec['server']['idempotency'];
+  /** Wall-clock provider; tests inject a deterministic generator. */
+  readonly now?: () => number;
+  /**
+   * IP-15: when supplied, the middleware publishes a live
+   * `graphorin_idempotency_cache_hit_ratio` gauge (replays / replays+executes)
+   * instead of leaving the registered metric a permanently-empty series.
+   */
+  readonly metricRegistry?: MetricRegistry;
+}
+
+interface CacheEntry {
+  readonly record: IdempotencyRecord;
+  readonly cachedAt: number;
+}
+
+/**
+ * @stable
+ */
+export function createIdempotencyMiddleware(
+  options: IdempotencyMiddlewareOptions,
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  const { store, config } = options;
+  if (!config.enabled) {
+    return async (_, next) => {
+      await next();
+    };
+  }
+  const now = options.now ?? Date.now;
+  const lru = new SimpleLru<string, CacheEntry>(config.lruCacheSize);
+
+  // periphery-08: keys whose execution is currently in flight - a
+  // concurrent duplicate is rejected (409) instead of double-executing.
+  const inFlight = new Set<string>();
+
+  const excluded = new Set(options.excludeResponseCachePaths ?? []);
+
+  // IP-15: publish the cache hit ratio as a live gauge. A "hit" is a replay
+  // served from a stored record; a "miss" is a keyed request that executed
+  // fresh. Conflicts (409) are abnormal and excluded from the ratio.
+  const registry = options.metricRegistry;
+  let hits = 0;
+  let lookups = 0;
+  const recordCacheOutcome = (hit: boolean): void => {
+    if (registry === undefined) return;
+    lookups += 1;
+    if (hit) hits += 1;
+    registry.set(SERVER_METRIC_NAMES.idempotencyCacheHitRatio, hits / lookups);
+  };
+
+  return async (c, next) => {
+    if (SAFE_METHODS.has(c.req.method.toUpperCase())) {
+      await next();
+      return;
+    }
+    // IP-6: secret-bearing endpoints opt out of response caching
+    // entirely - repeats re-execute and no body is ever persisted.
+    if (excluded.has(c.req.path)) {
+      await next();
+      return;
+    }
+    const key = c.req.header(HEADER_NAME)?.trim();
+    if (key === undefined || key.length === 0) {
+      if (config.requireKey === 'enforce') {
+        return c.json(
+          {
+            error: 'idempotency-key-required',
+            message: 'Idempotency-Key header is required for this endpoint.',
+            hint: "Set 'Idempotency-Key: <uuid>' on the request.",
+          },
+          400,
+        );
+      }
+      // 'warn' / 'off' - pass-through with a hint header.
+      if (config.requireKey === 'warn') {
+        c.header('Idempotency-Status', 'header-missing');
+      }
+      await next();
+      return;
+    }
+    if (!KEY_RE.test(key)) {
+      return c.json(
+        {
+          error: 'idempotency-key-required',
+          message: 'Idempotency-Key must be 8-255 chars of [A-Za-z0-9_:-].',
+        },
+        400,
+      );
+    }
+    c.set('state', { ...c.get('state'), idempotencyKey: key });
+    const fingerprint = await computeFingerprint(c);
+    const cached = lru.get(key);
+    let record: IdempotencyRecord | null;
+    if (cached !== undefined && now() - cached.cachedAt < 5 * 60 * 1000) {
+      record = cached.record;
+    } else {
+      record = await store.get(key);
+      if (record !== null) {
+        lru.set(key, { record, cachedAt: now() });
+      }
+    }
+    // IP-6: the verified principal the record is bound to. Replays are
+    // served only to the SAME principal that originally executed the
+    // request (who passed the route's scope checks at execute time) -
+    // a different token cannot fetch someone else's cached response,
+    // closing the scope-bypass the pre-router mount opened.
+    const auth = c.get('state').auth;
+    const principal = auth.kind === 'token' ? auth.token.tokenId : 'anonymous';
+    if (record !== null) {
+      if (record.scope !== undefined && record.scope !== principal) {
+        return c.json(
+          {
+            error: 'idempotency-conflict',
+            message: `Idempotency-Key '${key}' is bound to a different principal.`,
+          },
+          409,
+        );
+      }
+      if (config.checkBodyFingerprint && record.requestHash !== fingerprint) {
+        return c.json(
+          {
+            error: 'idempotency-conflict',
+            message: `Idempotency-Key '${key}' was previously used with a different request body.`,
+          },
+          409,
+        );
+      }
+      if (record.expiresAt > now()) {
+        c.set('state', { ...c.get('state'), idempotencyReplay: true });
+        const headers = record.responseHeaders ?? {};
+        for (const [name, value] of Object.entries(headers)) {
+          c.header(name, value);
+        }
+        c.header('Idempotency-Replayed', 'true');
+        recordCacheOutcome(true);
+        return new Response(JSON.stringify(record.response), {
+          status: record.statusCode,
+          headers: {
+            ...headers,
+            'Content-Type': 'application/json',
+            'Idempotency-Replayed': 'true',
+          },
+        });
+      }
+      // Expired - fall through to re-execute.
+      lru.delete(key);
+      await store.delete(key);
+    }
+
+    // periphery-08: the record is only written AFTER next(), so two
+    // concurrent requests with the same key would both miss the cache
+    // and both execute (a double agent run). Track in-flight keyed
+    // executions in-process (the server is single-process by design)
+    // and reject concurrent duplicates per
+    // draft-ietf-httpapi-idempotency-key-header: 409 + Retry-After.
+    // The key stays in-flight until the record is CACHED (or found
+    // uncacheable), so a duplicate never slips in between execution
+    // and the write.
+    if (inFlight.has(key)) {
+      c.header('Retry-After', '1');
+      return c.json(
+        {
+          error: 'idempotency-in-flight',
+          message: `A request with Idempotency-Key '${key}' is currently being processed.`,
+        },
+        409,
+      );
+    }
+    inFlight.add(key);
+    try {
+      // A keyed request that reaches execution is a cache miss.
+      recordCacheOutcome(false);
+      await next();
+
+      const status = c.res.status;
+      if (NON_CACHEABLE_STATUS.has(status)) {
+        // Retry-eligible - leave nothing in the cache.
+        return;
+      }
+      const responseBody = await captureJsonResponse(c);
+      if (responseBody === null) {
+        // Non-JSON or empty body - skip caching to keep the schema
+        // simple; clients that need response replay can use bodied
+        // POSTs.
+        return;
+      }
+      const responseHeaders = collectResponseHeaders(c);
+      const record_: IdempotencyRecord = {
+        key,
+        requestHash: fingerprint,
+        statusCode: status,
+        response: responseBody,
+        ...(responseHeaders !== undefined ? { responseHeaders } : {}),
+        // IP-6: bind the record to the executing principal.
+        scope: principal,
+        createdAt: now(),
+        expiresAt: now() + config.ttlSeconds * 1000,
+      };
+      try {
+        await store.put(record_);
+        lru.set(key, { record: record_, cachedAt: now() });
+      } catch {
+        // Best-effort cache. Persistence failures must not break the
+        // hot path - operators see them via the audit log + logger.
+      }
+    } finally {
+      inFlight.delete(key);
+    }
+  };
+}
+
+async function computeFingerprint(c: Context<{ Variables: ServerVariables }>): Promise<string> {
+  let body: unknown = null;
+  const ct = c.req.header('content-type');
+  if (ct?.toLowerCase().includes('application/json')) {
+    try {
+      body = await c.req.json();
+    } catch {
+      body = await c.req.text();
+    }
+  } else {
+    body = await c.req.text();
+  }
+  return fingerprintRequest(c.req.method, c.req.path, body);
+}
+
+async function captureJsonResponse(
+  c: Context<{ Variables: ServerVariables }>,
+): Promise<unknown | null> {
+  if (c.res === undefined) return null;
+  const contentType = c.res.headers.get('content-type') ?? '';
+  if (!contentType.toLowerCase().includes('application/json')) return null;
+  try {
+    const cloned = c.res.clone();
+    const text = await cloned.text();
+    if (text.length === 0) return null;
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function collectResponseHeaders(
+  c: Context<{ Variables: ServerVariables }>,
+): Readonly<Record<string, string>> | undefined {
+  if (c.res === undefined) return undefined;
+  const out: Record<string, string> = {};
+  c.res.headers.forEach((value, name) => {
+    if (name.toLowerCase() === 'content-length') return;
+    out[name] = value;
+  });
+  return Object.keys(out).length === 0 ? undefined : Object.freeze(out);
+}
+
+class SimpleLru<K, V> {
+  readonly #capacity: number;
+  readonly #map: Map<K, V> = new Map();
+
+  constructor(capacity: number) {
+    this.#capacity = Math.max(1, capacity);
+  }
+
+  get(key: K): V | undefined {
+    const value = this.#map.get(key);
+    if (value === undefined) return undefined;
+    this.#map.delete(key);
+    this.#map.set(key, value);
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    if (this.#map.has(key)) this.#map.delete(key);
+    this.#map.set(key, value);
+    while (this.#map.size > this.#capacity) {
+      const oldestKey = this.#map.keys().next().value as K | undefined;
+      if (oldestKey === undefined) break;
+      this.#map.delete(oldestKey);
+    }
+  }
+
+  delete(key: K): boolean {
+    return this.#map.delete(key);
+  }
+}

package/src/middleware/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Middleware barrel for `@graphorin/server`. Every entry is a Hono
+ * `MiddlewareHandler`; they are composed by the `createServer({...})`
+ * factory in a fixed order:
+ *
+ *   request-state -> cors -> request audit metadata -> rate-limit ->
+ *   csrf -> auth -> scope (per-route) -> idempotency (per-route) ->
+ *   audit -> handler
+ *
+ * Operators that build a custom Hono app (or wrap the framework one)
+ * can re-import these factories directly through this barrel.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  type AuditErrorSink,
+  type AuditMiddlewareOptions,
+  createAuditMiddleware,
+  HTTP_REQUEST_AUDIT_ACTION,
+} from './audit.js';
+export {
+  type AuthMiddlewareOptions,
+  createAnonymousAuthMiddleware,
+  createAuthMiddleware,
+} from './auth.js';
+export { createCorsMiddleware } from './cors.js';
+export { createCsrfMiddleware } from './csrf.js';
+export {
+  createIdempotencyMiddleware,
+  type IdempotencyMiddlewareOptions,
+} from './idempotency.js';
+export { createRateLimitMiddleware } from './rate-limit.js';
+export {
+  createRequestStateMiddleware,
+  type RequestStateMiddlewareOptions,
+} from './request-state.js';
+export { createScopeMiddleware, type ScopeRequirement } from './scope.js';

package/src/middleware/rate-limit.ts

@@ -0,0 +1,71 @@
+/**
+ * Per-IP sliding-window rate limit. Defends against brute-force
+ * authentication probes and naive DoS scenarios. The limit is
+ * deliberately conservative - operators with multi-tenant traffic
+ * should layer a dedicated reverse proxy on top.
+ *
+ * @packageDocumentation
+ */
+
+import type { MiddlewareHandler } from 'hono';
+
+import type { ServerConfigSpec } from '../config.js';
+import type { ServerVariables } from '../internal/context.js';
+
+interface Window {
+  count: number;
+  start: number;
+}
+
+/**
+ * @stable
+ */
+export function createRateLimitMiddleware(
+  config: ServerConfigSpec['server']['rateLimit'],
+  options: { readonly now?: () => number } = {},
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  if (!config.enabled) {
+    return async (_, next) => {
+      await next();
+    };
+  }
+  const windows = new Map<string, Window>();
+  const now = options.now ?? Date.now;
+  // IP-10: bound the window map - expired entries are swept once the
+  // map crosses the cap so an attacker rotating spoofed XFF values
+  // (trustProxy=true deployments) cannot grow it without bound.
+  const SWEEP_THRESHOLD = 10_000;
+  const sweep = (ts: number): void => {
+    if (windows.size < SWEEP_THRESHOLD) return;
+    for (const [key, win] of windows) {
+      if (ts - win.start >= config.windowMs) windows.delete(key);
+    }
+  };
+
+  return async (c, next) => {
+    const ip = c.get('state').clientIp ?? 'anonymous';
+    const ts = now();
+    sweep(ts);
+    const window = windows.get(ip) ?? { count: 0, start: ts };
+    if (ts - window.start >= config.windowMs) {
+      window.start = ts;
+      window.count = 0;
+    }
+    window.count += 1;
+    windows.set(ip, window);
+    const remaining = Math.max(0, config.perIpRequests - window.count);
+    c.header('X-RateLimit-Limit', config.perIpRequests.toString());
+    c.header('X-RateLimit-Remaining', remaining.toString());
+    c.header(
+      'X-RateLimit-Reset',
+      Math.max(0, Math.ceil((window.start + config.windowMs - ts) / 1000)).toString(),
+    );
+    if (window.count > config.perIpRequests) {
+      const retryAfter = Math.max(0, Math.ceil((window.start + config.windowMs - ts) / 1000));
+      return c.json({ error: 'rate-limit-exceeded', message: 'Too many requests.' }, 429, {
+        'Retry-After': retryAfter.toString(),
+      });
+    }
+    await next();
+  };
+}

package/src/middleware/request-state.ts

@@ -0,0 +1,79 @@
+/**
+ * Bootstraps the per-request `c.var.state` slot. Every server-owned
+ * middleware downstream reads from this object; defaults are kept on
+ * a single line per field so the structure is auditable at a glance.
+ *
+ * @packageDocumentation
+ */
+
+import type { MiddlewareHandler } from 'hono';
+
+import type { ServerRequestState, ServerVariables } from '../internal/context.js';
+import { newRequestId } from '../internal/ids.js';
+
+/**
+ * @stable
+ */
+export interface RequestStateMiddlewareOptions {
+  /** Override the wall clock; tests inject a fixed value. */
+  readonly now?: () => number;
+  /** Override the request id generator. */
+  readonly newRequestId?: () => string;
+  /** Trust `X-Forwarded-For`/`X-Real-IP` for the client IP. Default false. */
+  readonly trustProxy?: boolean;
+  /** Echo the request id back to the client. Default `'X-Request-Id'`. */
+  readonly responseHeader?: string | false;
+}
+
+function clientIp(
+  headerLookup: (name: string) => string | undefined,
+  trustProxy: boolean,
+): string | undefined {
+  if (trustProxy) {
+    const xff = headerLookup('x-forwarded-for');
+    if (xff !== undefined && xff.length > 0) {
+      const [first] = xff.split(',');
+      if (first !== undefined) return first.trim();
+    }
+    const xri = headerLookup('x-real-ip');
+    if (xri !== undefined && xri.length > 0) return xri.trim();
+  }
+  return undefined;
+}
+
+/**
+ * @stable
+ */
+export function createRequestStateMiddleware(
+  options: RequestStateMiddlewareOptions = {},
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  const now = options.now ?? Date.now;
+  const idFactory = options.newRequestId ?? newRequestId;
+  const trustProxy = options.trustProxy ?? false;
+  const responseHeader =
+    options.responseHeader === undefined ? 'X-Request-Id' : options.responseHeader;
+
+  return async (c, next) => {
+    const headerLookup = (name: string): string | undefined => c.req.header(name);
+    const requestId = headerLookup('x-request-id')?.trim() || idFactory();
+    // IP-10: with the default trustProxy=false the proxy headers are
+    // ignored - the client IP comes from the SOCKET, so per-IP rate
+    // limits and lockouts actually key per client instead of dumping
+    // every request into one shared 'anonymous' bucket.
+    const socketAddress = (
+      c.env as { incoming?: { socket?: { remoteAddress?: string } } } | undefined
+    )?.incoming?.socket?.remoteAddress;
+    const ip = clientIp(headerLookup, trustProxy) ?? socketAddress;
+    const state: ServerRequestState = {
+      requestId,
+      receivedAt: now(),
+      clientIp: ip,
+      auth: { kind: 'unauthenticated' },
+    };
+    c.set('state', state);
+    if (responseHeader !== false) {
+      c.header(responseHeader, requestId);
+    }
+    await next();
+  };
+}

package/src/middleware/scope.ts

@@ -0,0 +1,161 @@
+/**
+ * Per-route scope enforcement. Reads the verified token populated by
+ * the auth middleware and short-circuits with `403` when the granted
+ * set does not match the required scope.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type ParsedScope,
+  parseScope,
+  scopeMatches,
+  tryParseScope,
+} from '@graphorin/security/auth';
+import type { MiddlewareHandler } from 'hono';
+
+import type { ServerVariables } from '../internal/context.js';
+
+/**
+ * Required-scope spec accepted by {@link createScopeMiddleware}. Either
+ * a single string (`'agents:invoke'`), a parsed scope, or a function
+ * that derives the required scope from the request (e.g. to insert the
+ * `:id` segment lazily).
+ *
+ * @stable
+ */
+export type ScopeRequirement =
+  | string
+  | ParsedScope
+  | ((path: string, params: Record<string, string>) => string | ParsedScope);
+
+/**
+ * @stable
+ */
+export function createScopeMiddleware(
+  requirement: ScopeRequirement,
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  return async (c, next) => {
+    const auth = c.get('state').auth;
+    if (auth.kind === 'anonymous') {
+      // IP-13: auth is disabled server-wide (auth.kind='none'). There is no
+      // token to scope-check - the trusted-loopback operator is allowed
+      // through every gate.
+      await next();
+      return;
+    }
+    if (auth.kind === 'unauthenticated') {
+      return c.json(
+        {
+          error: 'auth-required',
+          message: 'Authentication required for this endpoint.',
+        },
+        401,
+      );
+    }
+    const required = resolveRequirement(
+      requirement,
+      c.req.path,
+      c.req.param() as Record<string, string>,
+    );
+    // W-107: a dynamic requirement built from an arbitrary URL segment
+    // may not parse (target charset/length limits). An unparseable
+    // requirement can never be granted - answer 403, never throw a 500.
+    if (required === undefined) {
+      return c.json(
+        {
+          error: 'scope-denied',
+          message: 'Token lacks the required scope (unparseable resource id).',
+        },
+        403,
+      );
+    }
+    const granted = auth.grantedScopes;
+    let allowed = false;
+    for (const scope of granted) {
+      if (scopeMatches(scope, required)) {
+        allowed = true;
+        break;
+      }
+    }
+    if (!allowed) {
+      return c.json(
+        {
+          error: 'scope-denied',
+          message: `Token lacks required scope '${required.raw}'.`,
+          hint: `Mint a token with the '${required.raw}' (or admin:*) scope.`,
+        },
+        403,
+      );
+    }
+    await next();
+  };
+}
+
+/**
+ * W-107: authentication-only gate. Lets any authenticated principal
+ * (token or the anonymous trusted-loopback operator) through and
+ * rejects only `unauthenticated` with 401. Used where possession of a
+ * valid principal is the whole requirement - e.g. the ws-ticket mint,
+ * which adds no rights of its own (the ticket carries the principal's
+ * scopes and every subscribe is per-subject gated).
+ *
+ * @stable
+ */
+export function createAuthenticatedMiddleware(): MiddlewareHandler<{
+  Variables: ServerVariables;
+}> {
+  return async (c, next) => {
+    const auth = c.get('state').auth;
+    if (auth.kind === 'unauthenticated') {
+      return c.json(
+        {
+          error: 'auth-required',
+          message: 'Authentication required for this endpoint.',
+        },
+        401,
+      );
+    }
+    await next();
+  };
+}
+
+/**
+ * W-107: imperative scope check for handlers that must resolve the
+ * resource BEFORE the requirement is known (per-resource run control:
+ * snapshot first, then require the owning agent's/workflow's scope).
+ * Mirrors the middleware exactly: anonymous allows, unauthenticated
+ * denies, an unparseable requirement denies.
+ *
+ * @stable
+ */
+export function checkScope(
+  auth: import('../internal/context.js').AuthState,
+  required: string | ParsedScope,
+): boolean {
+  if (auth.kind === 'anonymous') return true;
+  if (auth.kind === 'unauthenticated') return false;
+  const parsed = typeof required === 'string' ? tryParseScope(required) : required;
+  if (parsed === undefined) return false;
+  for (const scope of auth.grantedScopes) {
+    if (scopeMatches(scope, parsed)) return true;
+  }
+  return false;
+}
+
+function resolveRequirement(
+  requirement: ScopeRequirement,
+  path: string,
+  params: Record<string, string>,
+): ParsedScope | undefined {
+  // W-107: dynamic requirements interpolate raw URL segments - use the
+  // non-throwing parser so `GET /sessions/<junk>` yields 403, not 500.
+  if (typeof requirement === 'function') {
+    const next = requirement(path, params);
+    return typeof next === 'string' ? tryParseScope(next) : next;
+  }
+  return typeof requirement === 'string' ? tryParseScope(requirement) : requirement;
+}
+
+// `parseScope` stays imported for API parity with older call sites.
+void parseScope;