@graphorin/server 0.6.1 → 0.7.0

package/src/ws/replay-buffer.ts

@@ -0,0 +1,209 @@
+/**
+ * Per-subscription replay buffer used by the dispatcher to support
+ * short-disconnect resume. When a client reconnects with a
+ * `lastEventId`, the dispatcher walks the buffer from the matching
+ * cursor and re-emits every event the client missed.
+ *
+ * Defaults (configurable per-server):
+ *  - `maxEvents`: 1000 (per subscription)
+ *  - `ttlMs`: 5 minutes
+ *
+ * @packageDocumentation
+ */
+
+import type { ServerEventFrame } from '@graphorin/protocol';
+
+/**
+ * Public configuration accepted by {@link createReplayBuffer}.
+ *
+ * @stable
+ */
+export interface ReplayBufferOptions {
+  readonly maxEvents?: number;
+  readonly ttlMs?: number;
+  readonly now?: () => number;
+}
+
+/**
+ * Snapshot returned by {@link ReplayBuffer.replay}.
+ *
+ * @stable
+ */
+export interface ReplayBufferSlice {
+  readonly events: ReadonlyArray<ServerEventFrame>;
+  readonly droppedCount: number;
+  readonly nextEventIdHint: string | undefined;
+}
+
+/**
+ * Occupancy snapshot returned by {@link ReplayBuffer.stats}.
+ *
+ * @stable
+ */
+export interface ReplayBufferStats {
+  /** Number of subjects currently holding at least one buffered event. */
+  readonly subjects: number;
+  /** Total buffered events across all subjects. */
+  readonly events: number;
+}
+
+/**
+ * Per-subject replay buffer. Stores up to `maxEvents` per subject
+ * with a TTL; thread-safe under the single-writer Node event loop
+ * model.
+ *
+ * @stable
+ */
+export interface ReplayBuffer {
+  push(subject: string, event: ServerEventFrame): void;
+  replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice;
+  size(subject: string): number;
+  forget(subject: string): void;
+  prune(): void;
+  /**
+   * Occupancy snapshot (W-028). OPTIONAL so external implementations
+   * of this `@stable` interface keep compiling; `createReplayBuffer`
+   * always provides it. When absent, the `/v1/metrics` replay-buffer
+   * gauge degrades to `0`.
+   */
+  stats?(): ReplayBufferStats;
+}
+
+interface BufferedEvent {
+  readonly event: ServerEventFrame;
+  readonly bufferedAt: number;
+}
+
+/**
+ * Build an in-memory replay buffer.
+ *
+ * @stable
+ */
+export function createReplayBuffer(options: ReplayBufferOptions = {}): ReplayBuffer {
+  const maxEvents = options.maxEvents ?? 1_000;
+  const ttlMs = options.ttlMs ?? 5 * 60_000;
+  const now = options.now ?? Date.now;
+  const buffers = new Map<string, BufferedEvent[]>();
+  const dropped = new Map<string, number>();
+
+  function pruneSubject(subject: string): void {
+    const list = buffers.get(subject);
+    if (list === undefined || list.length === 0) return;
+    const cutoff = now() - ttlMs;
+    let cutoffIndex = 0;
+    while (cutoffIndex < list.length) {
+      const entry = list[cutoffIndex];
+      if (entry === undefined || entry.bufferedAt >= cutoff) break;
+      cutoffIndex += 1;
+    }
+    if (cutoffIndex > 0) {
+      list.splice(0, cutoffIndex);
+      dropped.set(subject, (dropped.get(subject) ?? 0) + cutoffIndex);
+    }
+    if (list.length === 0) {
+      // W-028: release the whole subject, including its dropped-count
+      // entry - otherwise every finished run leaves a Map entry behind
+      // forever. A resume with a stale cursor still signals the gap:
+      // `replay()` floors droppedCount at 1 when the cursor misses.
+      buffers.delete(subject);
+      dropped.delete(subject);
+    }
+  }
+
+  function push(subject: string, event: ServerEventFrame): void {
+    pruneSubject(subject);
+    let list = buffers.get(subject);
+    if (list === undefined) {
+      list = [];
+      buffers.set(subject, list);
+    }
+    list.push({ event, bufferedAt: now() });
+    if (list.length > maxEvents) {
+      const overflow = list.length - maxEvents;
+      list.splice(0, overflow);
+      dropped.set(subject, (dropped.get(subject) ?? 0) + overflow);
+    }
+  }
+
+  function replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice {
+    pruneSubject(subject);
+    const list = buffers.get(subject) ?? [];
+    const droppedCount = dropped.get(subject) ?? 0;
+    const last = list.at(-1);
+    if (sinceEventId === undefined) {
+      const slice: ReplayBufferSlice = {
+        events: list.map((entry) => entry.event),
+        droppedCount,
+        nextEventIdHint: last?.event.eventId,
+      };
+      return slice;
+    }
+    const startIndex = list.findIndex((entry) => entry.event.eventId === sinceEventId);
+    if (startIndex < 0) {
+      // Cursor predates the buffer; return everything we still have +
+      // signal the gap via `droppedCount`. The miss itself PROVES at
+      // least one event was dropped, so floor the count at 1 even
+      // after the dropped-map entry was released by pruning (W-028) -
+      // the dispatcher must still send the replay-marker.
+      return {
+        events: list.map((entry) => entry.event),
+        droppedCount: Math.max(droppedCount, 1),
+        nextEventIdHint: last?.event.eventId,
+      };
+    }
+    const replayed = list.slice(startIndex + 1).map((entry) => entry.event);
+    return {
+      events: replayed,
+      droppedCount: 0,
+      nextEventIdHint: replayed.at(-1)?.eventId,
+    };
+  }
+
+  return Object.freeze({
+    push,
+    replay,
+    size(subject: string): number {
+      pruneSubject(subject);
+      return buffers.get(subject)?.length ?? 0;
+    },
+    forget(subject: string): void {
+      buffers.delete(subject);
+      dropped.delete(subject);
+    },
+    prune(): void {
+      for (const subject of [...buffers.keys()]) pruneSubject(subject);
+    },
+    stats(): ReplayBufferStats {
+      let events = 0;
+      for (const list of buffers.values()) events += list.length;
+      return { subjects: buffers.size, events };
+    },
+  });
+}
+
+/**
+ * W-028: schedule a periodic {@link ReplayBuffer.prune} sweep. Without
+ * it TTL expiry only ran lazily inside `push`/`replay`/`size` FOR THE
+ * SAME SUBJECT, so every finished run-subject (a fresh runId per run)
+ * retained up to `maxEvents` full payloads forever on a long-living
+ * server. Mirrors `scheduleRunPruning` (IP-16): `unref`-ed timer,
+ * returns a stop function. The sweep applies only the already
+ * documented TTL - replay semantics inside the TTL window are
+ * unchanged (an immediate `forget` on run completion would break
+ * short-disconnect resume of terminal events).
+ *
+ * @stable
+ */
+export function scheduleReplayBufferPruning(
+  buffer: ReplayBuffer,
+  opts: { readonly intervalMs?: number } = {},
+): () => void {
+  const intervalMs = opts.intervalMs ?? 60_000;
+  const timer = setInterval(() => {
+    buffer.prune();
+  }, intervalMs);
+  if (typeof (timer as { unref?: () => void }).unref === 'function') {
+    (timer as { unref: () => void }).unref();
+  }
+  return () => clearInterval(timer);
+}

package/src/ws/subjects.ts

@@ -0,0 +1,162 @@
+/**
+ * Strict subject grammar enforced by the WS dispatcher. Subjects are
+ * the multiplexing primitive over a single WS connection: every
+ * subscription is keyed by a subject, every event carries the
+ * subject it was emitted into, and the per-subject scope check
+ * happens at subscription time.
+ *
+ * Wildcards are deferred to v0.2+ - the dispatcher rejects any
+ * subject containing `'*'` or `'#'` so the ACL surface stays
+ * tractable.
+ *
+ * @packageDocumentation
+ */
+
+import type { ParsedScope } from '@graphorin/security/auth';
+import { parseScope, scopeMatches } from '@graphorin/security/auth';
+
+/**
+ * Discriminated union of every recognised subject form. Surfaced on
+ * audit log entries + diagnostics; the wire still carries the raw
+ * string.
+ *
+ * @stable
+ */
+export type ParsedSubject =
+  | { readonly kind: 'session-events'; readonly sessionId: string }
+  | {
+      readonly kind: 'session-run-events';
+      readonly sessionId: string;
+      readonly runId: string;
+    }
+  | {
+      readonly kind: 'agent-run-events';
+      readonly agentId: string;
+      readonly runId: string;
+    }
+  | { readonly kind: 'workflow-events'; readonly workflowId: string }
+  | {
+      readonly kind: 'workflow-run-events';
+      readonly workflowId: string;
+      readonly runId: string;
+    }
+  | { readonly kind: 'memory-conflicts' }
+  | { readonly kind: 'audit-events' };
+
+/**
+ * Result of {@link tryParseSubject}.
+ *
+ * @stable
+ */
+export type ParseSubjectResult =
+  | { readonly ok: true; readonly subject: ParsedSubject }
+  | {
+      readonly ok: false;
+      readonly reason: 'wildcard-not-supported' | 'unknown-subject' | 'malformed';
+    };
+
+const SESSION_EVENTS = /^session:([A-Za-z0-9_-]+)\/events$/;
+const SESSION_RUN_EVENTS = /^session:([A-Za-z0-9_-]+)\/runs\/([A-Za-z0-9_-]+)\/events$/;
+const AGENT_RUN_EVENTS = /^agent:([A-Za-z0-9_-]+)\/runs\/([A-Za-z0-9_-]+)\/events$/;
+const WORKFLOW_EVENTS = /^workflow:([A-Za-z0-9_-]+)\/events$/;
+const WORKFLOW_RUN_EVENTS = /^workflow:([A-Za-z0-9_-]+)\/runs\/([A-Za-z0-9_-]+)\/events$/;
+
+/**
+ * Parse a subject string into the {@link ParsedSubject} discriminator.
+ *
+ * @stable
+ */
+export function tryParseSubject(raw: string): ParseSubjectResult {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return { ok: false, reason: 'malformed' };
+  }
+  if (raw.includes('*') || raw.includes('#')) {
+    return { ok: false, reason: 'wildcard-not-supported' };
+  }
+  if (raw === 'memory/conflicts') {
+    return { ok: true, subject: { kind: 'memory-conflicts' } };
+  }
+  if (raw === 'audit/events') {
+    return { ok: true, subject: { kind: 'audit-events' } };
+  }
+  let m = raw.match(SESSION_RUN_EVENTS);
+  if (m !== null) {
+    return {
+      ok: true,
+      subject: { kind: 'session-run-events', sessionId: m[1] ?? '', runId: m[2] ?? '' },
+    };
+  }
+  m = raw.match(AGENT_RUN_EVENTS);
+  if (m !== null) {
+    return {
+      ok: true,
+      subject: { kind: 'agent-run-events', agentId: m[1] ?? '', runId: m[2] ?? '' },
+    };
+  }
+  m = raw.match(SESSION_EVENTS);
+  if (m !== null) {
+    return { ok: true, subject: { kind: 'session-events', sessionId: m[1] ?? '' } };
+  }
+  m = raw.match(WORKFLOW_RUN_EVENTS);
+  if (m !== null) {
+    return {
+      ok: true,
+      subject: { kind: 'workflow-run-events', workflowId: m[1] ?? '', runId: m[2] ?? '' },
+    };
+  }
+  m = raw.match(WORKFLOW_EVENTS);
+  if (m !== null) {
+    return { ok: true, subject: { kind: 'workflow-events', workflowId: m[1] ?? '' } };
+  }
+  return { ok: false, reason: 'unknown-subject' };
+}
+
+/**
+ * Required scope literal for every subject kind, expressed as a
+ * `ParsedScope`. The matcher `scopeMatches(granted, required)` uses
+ * the standard wildcard rules from `@graphorin/security/auth`
+ * (e.g. `agents:*` matches `agents:invoke:foo`).
+ *
+ * @stable
+ */
+export function requiredScopeFor(subject: ParsedSubject): ParsedScope {
+  switch (subject.kind) {
+    // periphery-10: session streams are READ-ONLY, so they gate on
+    // `sessions:read:<sessionId>` - consistent with the SSE route's
+    // `sessions:read` requirement (which the old `agents:invoke:<x>`
+    // requirement silently stacked on top of), and the resource slot
+    // is a sessionId under the sessions family instead of overloading
+    // `agents:invoke` (whose slot is an agentId everywhere else).
+    case 'session-events':
+      return parseScope(`sessions:read:${subject.sessionId}`);
+    case 'session-run-events':
+      return parseScope(`sessions:read:${subject.sessionId}`);
+    case 'agent-run-events':
+      return parseScope(`agents:read:${subject.agentId}`);
+    case 'workflow-events':
+      return parseScope(`workflows:read:${subject.workflowId}`);
+    case 'workflow-run-events':
+      return parseScope(`workflows:read:${subject.workflowId}`);
+    case 'memory-conflicts':
+      return parseScope('memory:read');
+    case 'audit-events':
+      return parseScope('audit:read');
+  }
+}
+
+/**
+ * Compatibility shim - re-exports `scopeMatches` so consumers don't
+ * have to learn the security package's surface.
+ *
+ * @stable
+ */
+export function isSubjectAllowed(
+  granted: ReadonlyArray<ParsedScope>,
+  subject: ParsedSubject,
+): boolean {
+  const required = requiredScopeFor(subject);
+  for (const scope of granted) {
+    if (scopeMatches(scope, required)) return true;
+  }
+  return false;
+}

package/src/ws/ticket.ts

@@ -0,0 +1,174 @@
+/**
+ * In-memory single-use ticket store for browser WebSocket clients.
+ * The browser WebSocket API does not allow custom headers, so the
+ * server issues a short-lived ticket via `POST /v1/session/ws-ticket`
+ * (HTTP-authenticated); the client then attaches the value as a
+ * second `Sec-WebSocket-Protocol` token (`ticket.<value>`) on the
+ * upgrade request.
+ *
+ * Tickets:
+ *   - default 5-minute TTL,
+ *   - single-use (the first valid `consume()` call marks the ticket
+ *     consumed; every subsequent attempt rejects),
+ *   - in-memory only (server restart invalidates everything; CLI /
+ *     SDK clients use HTTP bearer instead so the lost ticket window
+ *     does not affect them).
+ *
+ * @packageDocumentation
+ */
+
+import { randomBytes } from 'node:crypto';
+import type { ParsedScope } from '@graphorin/security/auth';
+
+/**
+ * Stable shape returned by {@link WsTicketStore.issue}.
+ *
+ * @stable
+ */
+export interface WsTicket {
+  readonly value: string;
+  readonly expiresAt: number;
+  readonly issuedAt: number;
+  readonly tokenId: string;
+  readonly scopes: ReadonlyArray<ParsedScope>;
+}
+
+/**
+ * Stable result of {@link WsTicketStore.consume}.
+ *
+ * @stable
+ */
+export type WsTicketConsumeResult =
+  | { readonly ok: true; readonly ticket: WsTicket }
+  | { readonly ok: false; readonly reason: 'unknown' | 'consumed' | 'expired' };
+
+/**
+ * Options accepted by {@link createWsTicketStore}.
+ *
+ * @stable
+ */
+export interface WsTicketStoreOptions {
+  /** Default `300_000` (5 min). */
+  readonly ttlMs?: number;
+  /** Cap on the number of unconsumed tickets retained. Default `1_000`. */
+  readonly maxOutstanding?: number;
+  readonly now?: () => number;
+  /**
+   * Random-bytes generator. Tests pass a deterministic source so
+   * ticket values are reproducible.
+   */
+  readonly randomBytes?: (length: number) => Uint8Array;
+}
+
+/**
+ * Pluggable in-memory ticket store used by the WS upgrade handler +
+ * the `POST /v1/session/ws-ticket` route.
+ *
+ * @stable
+ */
+export interface WsTicketStore {
+  readonly ttlMs: number;
+  issue(input: { readonly tokenId: string; readonly scopes: ReadonlyArray<ParsedScope> }): WsTicket;
+  consume(value: string): WsTicketConsumeResult;
+  /** Drop expired entries; called on every `consume()`. */
+  prune(): number;
+  size(): number;
+}
+
+interface InternalEntry {
+  readonly ticket: WsTicket;
+  consumed: boolean;
+}
+
+/**
+ * Build the default in-memory ticket store. Production deployments
+ * use exactly one store per process (multiple processes would each
+ * issue their own tickets - there is no shared state because the
+ * single-user-per-process default applies).
+ *
+ * @stable
+ */
+export function createWsTicketStore(options: WsTicketStoreOptions = {}): WsTicketStore {
+  const ttlMs = options.ttlMs ?? 5 * 60_000;
+  const maxOutstanding = options.maxOutstanding ?? 1_000;
+  const now = options.now ?? Date.now;
+  const random = options.randomBytes ?? ((n: number) => randomBytes(n));
+  const entries = new Map<string, InternalEntry>();
+
+  function evictOldest(): void {
+    const oldest = entries.keys().next().value;
+    if (oldest !== undefined) entries.delete(oldest);
+  }
+
+  function prune(): number {
+    const cutoff = now();
+    let removed = 0;
+    for (const [value, entry] of entries) {
+      if (entry.ticket.expiresAt <= cutoff) {
+        entries.delete(value);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+
+  function issue(input: {
+    readonly tokenId: string;
+    readonly scopes: ReadonlyArray<ParsedScope>;
+  }): WsTicket {
+    prune();
+    while (entries.size >= maxOutstanding) {
+      evictOldest();
+    }
+    const issuedAt = now();
+    const value = encodeTicket(random(24));
+    const ticket: WsTicket = {
+      value,
+      issuedAt,
+      expiresAt: issuedAt + ttlMs,
+      tokenId: input.tokenId,
+      scopes: Object.freeze(input.scopes.slice()),
+    };
+    entries.set(value, { ticket, consumed: false });
+    return ticket;
+  }
+
+  function consume(value: string): WsTicketConsumeResult {
+    const entry = entries.get(value);
+    if (entry === undefined) {
+      prune();
+      return { ok: false, reason: 'unknown' };
+    }
+    if (entry.ticket.expiresAt <= now()) {
+      entries.delete(value);
+      prune();
+      return { ok: false, reason: 'expired' };
+    }
+    if (entry.consumed) {
+      prune();
+      return { ok: false, reason: 'consumed' };
+    }
+    entry.consumed = true;
+    prune();
+    return { ok: true, ticket: entry.ticket };
+  }
+
+  return Object.freeze({
+    ttlMs,
+    issue,
+    consume,
+    prune,
+    size: () => entries.size,
+  });
+}
+
+function encodeTicket(bytes: Uint8Array): string {
+  // URL-safe base64 - Buffer.from is available in every supported
+  // Node runtime; the implementation never touches the value once
+  // encoded so the choice is purely cosmetic.
+  return Buffer.from(bytes)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}