@graphorin/server 0.5.0

package/dist/ws/subjects.js

@@ -0,0 +1,112 @@
+import { parseScope, scopeMatches } from "@graphorin/security/auth";
+
+//#region src/ws/subjects.ts
+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
+*/
+function tryParseSubject(raw) {
+	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
+*/
+function requiredScopeFor(subject) {
+	switch (subject.kind) {
+		case "session-events": return parseScope(`agents:invoke:${subject.sessionId}`);
+		case "session-run-events": return parseScope(`agents:invoke:${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
+*/
+function isSubjectAllowed(granted, subject) {
+	const required = requiredScopeFor(subject);
+	for (const scope of granted) if (scopeMatches(scope, required)) return true;
+	return false;
+}
+
+//#endregion
+export { isSubjectAllowed, requiredScopeFor, tryParseSubject };
+//# sourceMappingURL=subjects.js.map

package/dist/ws/subjects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subjects.js","names":[],"sources":["../../src/ws/subjects.ts"],"sourcesContent":["/**\n * Strict subject grammar enforced by the WS dispatcher. Subjects are\n * the multiplexing primitive over a single WS connection: every\n * subscription is keyed by a subject, every event carries the\n * subject it was emitted into, and the per-subject scope check\n * happens at subscription time.\n *\n * Wildcards are deferred to v0.2+ — the dispatcher rejects any\n * subject containing `'*'` or `'#'` so the ACL surface stays\n * tractable.\n *\n * @packageDocumentation\n */\n\nimport type { ParsedScope } from '@graphorin/security/auth';\nimport { parseScope, scopeMatches } from '@graphorin/security/auth';\n\n/**\n * Discriminated union of every recognised subject form. Surfaced on\n * audit log entries + diagnostics; the wire still carries the raw\n * string.\n *\n * @stable\n */\nexport type ParsedSubject =\n  | { readonly kind: 'session-events'; readonly sessionId: string }\n  | {\n      readonly kind: 'session-run-events';\n      readonly sessionId: string;\n      readonly runId: string;\n    }\n  | {\n      readonly kind: 'agent-run-events';\n      readonly agentId: string;\n      readonly runId: string;\n    }\n  | { readonly kind: 'workflow-events'; readonly workflowId: string }\n  | {\n      readonly kind: 'workflow-run-events';\n      readonly workflowId: string;\n      readonly runId: string;\n    }\n  | { readonly kind: 'memory-conflicts' }\n  | { readonly kind: 'audit-events' };\n\n/**\n * Result of {@link tryParseSubject}.\n *\n * @stable\n */\nexport type ParseSubjectResult =\n  | { readonly ok: true; readonly subject: ParsedSubject }\n  | {\n      readonly ok: false;\n      readonly reason: 'wildcard-not-supported' | 'unknown-subject' | 'malformed';\n    };\n\nconst SESSION_EVENTS = /^session:([A-Za-z0-9_-]+)\\/events$/;\nconst SESSION_RUN_EVENTS = /^session:([A-Za-z0-9_-]+)\\/runs\\/([A-Za-z0-9_-]+)\\/events$/;\nconst AGENT_RUN_EVENTS = /^agent:([A-Za-z0-9_-]+)\\/runs\\/([A-Za-z0-9_-]+)\\/events$/;\nconst WORKFLOW_EVENTS = /^workflow:([A-Za-z0-9_-]+)\\/events$/;\nconst WORKFLOW_RUN_EVENTS = /^workflow:([A-Za-z0-9_-]+)\\/runs\\/([A-Za-z0-9_-]+)\\/events$/;\n\n/**\n * Parse a subject string into the {@link ParsedSubject} discriminator.\n *\n * @stable\n */\nexport function tryParseSubject(raw: string): ParseSubjectResult {\n  if (typeof raw !== 'string' || raw.length === 0) {\n    return { ok: false, reason: 'malformed' };\n  }\n  if (raw.includes('*') || raw.includes('#')) {\n    return { ok: false, reason: 'wildcard-not-supported' };\n  }\n  if (raw === 'memory/conflicts') {\n    return { ok: true, subject: { kind: 'memory-conflicts' } };\n  }\n  if (raw === 'audit/events') {\n    return { ok: true, subject: { kind: 'audit-events' } };\n  }\n  let m = raw.match(SESSION_RUN_EVENTS);\n  if (m !== null) {\n    return {\n      ok: true,\n      subject: { kind: 'session-run-events', sessionId: m[1] ?? '', runId: m[2] ?? '' },\n    };\n  }\n  m = raw.match(AGENT_RUN_EVENTS);\n  if (m !== null) {\n    return {\n      ok: true,\n      subject: { kind: 'agent-run-events', agentId: m[1] ?? '', runId: m[2] ?? '' },\n    };\n  }\n  m = raw.match(SESSION_EVENTS);\n  if (m !== null) {\n    return { ok: true, subject: { kind: 'session-events', sessionId: m[1] ?? '' } };\n  }\n  m = raw.match(WORKFLOW_RUN_EVENTS);\n  if (m !== null) {\n    return {\n      ok: true,\n      subject: { kind: 'workflow-run-events', workflowId: m[1] ?? '', runId: m[2] ?? '' },\n    };\n  }\n  m = raw.match(WORKFLOW_EVENTS);\n  if (m !== null) {\n    return { ok: true, subject: { kind: 'workflow-events', workflowId: m[1] ?? '' } };\n  }\n  return { ok: false, reason: 'unknown-subject' };\n}\n\n/**\n * Required scope literal for every subject kind, expressed as a\n * `ParsedScope`. The matcher `scopeMatches(granted, required)` uses\n * the standard wildcard rules from `@graphorin/security/auth`\n * (e.g. `agents:*` matches `agents:invoke:foo`).\n *\n * @stable\n */\nexport function requiredScopeFor(subject: ParsedSubject): ParsedScope {\n  switch (subject.kind) {\n    case 'session-events':\n      return parseScope(`agents:invoke:${subject.sessionId}`);\n    case 'session-run-events':\n      return parseScope(`agents:invoke:${subject.sessionId}`);\n    case 'agent-run-events':\n      return parseScope(`agents:read:${subject.agentId}`);\n    case 'workflow-events':\n      return parseScope(`workflows:read:${subject.workflowId}`);\n    case 'workflow-run-events':\n      return parseScope(`workflows:read:${subject.workflowId}`);\n    case 'memory-conflicts':\n      return parseScope('memory:read');\n    case 'audit-events':\n      return parseScope('audit:read');\n  }\n}\n\n/**\n * Compatibility shim — re-exports `scopeMatches` so consumers don't\n * have to learn the security package's surface.\n *\n * @stable\n */\nexport function isSubjectAllowed(\n  granted: ReadonlyArray<ParsedScope>,\n  subject: ParsedSubject,\n): boolean {\n  const required = requiredScopeFor(subject);\n  for (const scope of granted) {\n    if (scopeMatches(scope, required)) return true;\n  }\n  return false;\n}\n"],"mappings":";;;AAyDA,MAAM,iBAAiB;AACvB,MAAM,qBAAqB;AAC3B,MAAM,mBAAmB;AACzB,MAAM,kBAAkB;AACxB,MAAM,sBAAsB;;;;;;AAO5B,SAAgB,gBAAgB,KAAiC;AAC/D,KAAI,OAAO,QAAQ,YAAY,IAAI,WAAW,EAC5C,QAAO;EAAE,IAAI;EAAO,QAAQ;EAAa;AAE3C,KAAI,IAAI,SAAS,IAAI,IAAI,IAAI,SAAS,IAAI,CACxC,QAAO;EAAE,IAAI;EAAO,QAAQ;EAA0B;AAExD,KAAI,QAAQ,mBACV,QAAO;EAAE,IAAI;EAAM,SAAS,EAAE,MAAM,oBAAoB;EAAE;AAE5D,KAAI,QAAQ,eACV,QAAO;EAAE,IAAI;EAAM,SAAS,EAAE,MAAM,gBAAgB;EAAE;CAExD,IAAI,IAAI,IAAI,MAAM,mBAAmB;AACrC,KAAI,MAAM,KACR,QAAO;EACL,IAAI;EACJ,SAAS;GAAE,MAAM;GAAsB,WAAW,EAAE,MAAM;GAAI,OAAO,EAAE,MAAM;GAAI;EAClF;AAEH,KAAI,IAAI,MAAM,iBAAiB;AAC/B,KAAI,MAAM,KACR,QAAO;EACL,IAAI;EACJ,SAAS;GAAE,MAAM;GAAoB,SAAS,EAAE,MAAM;GAAI,OAAO,EAAE,MAAM;GAAI;EAC9E;AAEH,KAAI,IAAI,MAAM,eAAe;AAC7B,KAAI,MAAM,KACR,QAAO;EAAE,IAAI;EAAM,SAAS;GAAE,MAAM;GAAkB,WAAW,EAAE,MAAM;GAAI;EAAE;AAEjF,KAAI,IAAI,MAAM,oBAAoB;AAClC,KAAI,MAAM,KACR,QAAO;EACL,IAAI;EACJ,SAAS;GAAE,MAAM;GAAuB,YAAY,EAAE,MAAM;GAAI,OAAO,EAAE,MAAM;GAAI;EACpF;AAEH,KAAI,IAAI,MAAM,gBAAgB;AAC9B,KAAI,MAAM,KACR,QAAO;EAAE,IAAI;EAAM,SAAS;GAAE,MAAM;GAAmB,YAAY,EAAE,MAAM;GAAI;EAAE;AAEnF,QAAO;EAAE,IAAI;EAAO,QAAQ;EAAmB;;;;;;;;;;AAWjD,SAAgB,iBAAiB,SAAqC;AACpE,SAAQ,QAAQ,MAAhB;EACE,KAAK,iBACH,QAAO,WAAW,iBAAiB,QAAQ,YAAY;EACzD,KAAK,qBACH,QAAO,WAAW,iBAAiB,QAAQ,YAAY;EACzD,KAAK,mBACH,QAAO,WAAW,eAAe,QAAQ,UAAU;EACrD,KAAK,kBACH,QAAO,WAAW,kBAAkB,QAAQ,aAAa;EAC3D,KAAK,sBACH,QAAO,WAAW,kBAAkB,QAAQ,aAAa;EAC3D,KAAK,mBACH,QAAO,WAAW,cAAc;EAClC,KAAK,eACH,QAAO,WAAW,aAAa;;;;;;;;;AAUrC,SAAgB,iBACd,SACA,SACS;CACT,MAAM,WAAW,iBAAiB,QAAQ;AAC1C,MAAK,MAAM,SAAS,QAClB,KAAI,aAAa,OAAO,SAAS,CAAE,QAAO;AAE5C,QAAO"}

package/dist/ws/ticket.d.ts

@@ -0,0 +1,74 @@
+import { ParsedScope } from "@graphorin/security/auth";
+
+//#region src/ws/ticket.d.ts
+
+/**
+ * Stable shape returned by {@link WsTicketStore.issue}.
+ *
+ * @stable
+ */
+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
+ */
+type WsTicketConsumeResult = {
+  readonly ok: true;
+  readonly ticket: WsTicket;
+} | {
+  readonly ok: false;
+  readonly reason: 'unknown' | 'consumed' | 'expired';
+};
+/**
+ * Options accepted by {@link createWsTicketStore}.
+ *
+ * @stable
+ */
+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
+ */
+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;
+}
+/**
+ * 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
+ */
+declare function createWsTicketStore(options?: WsTicketStoreOptions): WsTicketStore;
+//#endregion
+export { WsTicket, WsTicketConsumeResult, WsTicketStore, WsTicketStoreOptions, createWsTicketStore };
+//# sourceMappingURL=ticket.d.ts.map

package/dist/ws/ticket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket.d.ts","names":[],"sources":["../../src/ws/ticket.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UA2BiB,QAAA;;;;;mBAKE,cAAc;;;;;;;KAQrB,qBAAA;;mBAC8B;;;;;;;;;;UAQzB,oBAAA;;;;;;;;;;6CAU4B;;;;;;;;UAS5B,aAAA;;;;qBAE2C,cAAc;MAAiB;0BACjE;;;;;;;;;;;;;iBAmBV,mBAAA,WAA6B,uBAA4B"}

package/dist/ws/ticket.js

@@ -0,0 +1,112 @@
+import { randomBytes } from "node:crypto";
+
+//#region src/ws/ticket.ts
+/**
+* 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
+*/
+/**
+* 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
+*/
+function createWsTicketStore(options = {}) {
+	const ttlMs = options.ttlMs ?? 5 * 6e4;
+	const maxOutstanding = options.maxOutstanding ?? 1e3;
+	const now = options.now ?? Date.now;
+	const random = options.randomBytes ?? ((n) => randomBytes(n));
+	const entries = /* @__PURE__ */ new Map();
+	function evictOldest() {
+		const oldest = entries.keys().next().value;
+		if (oldest !== void 0) entries.delete(oldest);
+	}
+	function prune() {
+		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) {
+		prune();
+		while (entries.size >= maxOutstanding) evictOldest();
+		const issuedAt = now();
+		const value = encodeTicket(random(24));
+		const ticket = {
+			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) {
+		const entry = entries.get(value);
+		if (entry === void 0) {
+			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) {
+	return Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+//#endregion
+export { createWsTicketStore };
+//# sourceMappingURL=ticket.js.map

package/dist/ws/ticket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket.js","names":["ticket: WsTicket"],"sources":["../../src/ws/ticket.ts"],"sourcesContent":["/**\n * In-memory single-use ticket store for browser WebSocket clients.\n * The browser WebSocket API does not allow custom headers, so the\n * server issues a short-lived ticket via `POST /v1/session/ws-ticket`\n * (HTTP-authenticated); the client then attaches the value as a\n * second `Sec-WebSocket-Protocol` token (`ticket.<value>`) on the\n * upgrade request.\n *\n * Tickets:\n *   - default 5-minute TTL,\n *   - single-use (the first valid `consume()` call marks the ticket\n *     consumed; every subsequent attempt rejects),\n *   - in-memory only (server restart invalidates everything; CLI /\n *     SDK clients use HTTP bearer instead so the lost ticket window\n *     does not affect them).\n *\n * @packageDocumentation\n */\n\nimport { randomBytes } from 'node:crypto';\nimport type { ParsedScope } from '@graphorin/security/auth';\n\n/**\n * Stable shape returned by {@link WsTicketStore.issue}.\n *\n * @stable\n */\nexport interface WsTicket {\n  readonly value: string;\n  readonly expiresAt: number;\n  readonly issuedAt: number;\n  readonly tokenId: string;\n  readonly scopes: ReadonlyArray<ParsedScope>;\n}\n\n/**\n * Stable result of {@link WsTicketStore.consume}.\n *\n * @stable\n */\nexport type WsTicketConsumeResult =\n  | { readonly ok: true; readonly ticket: WsTicket }\n  | { readonly ok: false; readonly reason: 'unknown' | 'consumed' | 'expired' };\n\n/**\n * Options accepted by {@link createWsTicketStore}.\n *\n * @stable\n */\nexport interface WsTicketStoreOptions {\n  /** Default `300_000` (5 min). */\n  readonly ttlMs?: number;\n  /** Cap on the number of unconsumed tickets retained. Default `1_000`. */\n  readonly maxOutstanding?: number;\n  readonly now?: () => number;\n  /**\n   * Random-bytes generator. Tests pass a deterministic source so\n   * ticket values are reproducible.\n   */\n  readonly randomBytes?: (length: number) => Uint8Array;\n}\n\n/**\n * Pluggable in-memory ticket store used by the WS upgrade handler +\n * the `POST /v1/session/ws-ticket` route.\n *\n * @stable\n */\nexport interface WsTicketStore {\n  readonly ttlMs: number;\n  issue(input: { readonly tokenId: string; readonly scopes: ReadonlyArray<ParsedScope> }): WsTicket;\n  consume(value: string): WsTicketConsumeResult;\n  /** Drop expired entries; called on every `consume()`. */\n  prune(): number;\n  size(): number;\n}\n\ninterface InternalEntry {\n  readonly ticket: WsTicket;\n  consumed: boolean;\n}\n\n/**\n * Build the default in-memory ticket store. Production deployments\n * use exactly one store per process (multiple processes would each\n * issue their own tickets — there is no shared state because the\n * single-user-per-process default applies).\n *\n * @stable\n */\nexport function createWsTicketStore(options: WsTicketStoreOptions = {}): WsTicketStore {\n  const ttlMs = options.ttlMs ?? 5 * 60_000;\n  const maxOutstanding = options.maxOutstanding ?? 1_000;\n  const now = options.now ?? Date.now;\n  const random = options.randomBytes ?? ((n: number) => randomBytes(n));\n  const entries = new Map<string, InternalEntry>();\n\n  function evictOldest(): void {\n    const oldest = entries.keys().next().value;\n    if (oldest !== undefined) entries.delete(oldest);\n  }\n\n  function prune(): number {\n    const cutoff = now();\n    let removed = 0;\n    for (const [value, entry] of entries) {\n      if (entry.ticket.expiresAt <= cutoff) {\n        entries.delete(value);\n        removed += 1;\n      }\n    }\n    return removed;\n  }\n\n  function issue(input: {\n    readonly tokenId: string;\n    readonly scopes: ReadonlyArray<ParsedScope>;\n  }): WsTicket {\n    prune();\n    while (entries.size >= maxOutstanding) {\n      evictOldest();\n    }\n    const issuedAt = now();\n    const value = encodeTicket(random(24));\n    const ticket: WsTicket = {\n      value,\n      issuedAt,\n      expiresAt: issuedAt + ttlMs,\n      tokenId: input.tokenId,\n      scopes: Object.freeze(input.scopes.slice()),\n    };\n    entries.set(value, { ticket, consumed: false });\n    return ticket;\n  }\n\n  function consume(value: string): WsTicketConsumeResult {\n    const entry = entries.get(value);\n    if (entry === undefined) {\n      prune();\n      return { ok: false, reason: 'unknown' };\n    }\n    if (entry.ticket.expiresAt <= now()) {\n      entries.delete(value);\n      prune();\n      return { ok: false, reason: 'expired' };\n    }\n    if (entry.consumed) {\n      prune();\n      return { ok: false, reason: 'consumed' };\n    }\n    entry.consumed = true;\n    prune();\n    return { ok: true, ticket: entry.ticket };\n  }\n\n  return Object.freeze({\n    ttlMs,\n    issue,\n    consume,\n    prune,\n    size: () => entries.size,\n  });\n}\n\nfunction encodeTicket(bytes: Uint8Array): string {\n  // URL-safe base64 — Buffer.from is available in every supported\n  // Node runtime; the implementation never touches the value once\n  // encoded so the choice is purely cosmetic.\n  return Buffer.from(bytes)\n    .toString('base64')\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n    .replace(/=+$/g, '');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,SAAgB,oBAAoB,UAAgC,EAAE,EAAiB;CACrF,MAAM,QAAQ,QAAQ,SAAS,IAAI;CACnC,MAAM,iBAAiB,QAAQ,kBAAkB;CACjD,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,SAAS,QAAQ,iBAAiB,MAAc,YAAY,EAAE;CACpE,MAAM,0BAAU,IAAI,KAA4B;CAEhD,SAAS,cAAoB;EAC3B,MAAM,SAAS,QAAQ,MAAM,CAAC,MAAM,CAAC;AACrC,MAAI,WAAW,OAAW,SAAQ,OAAO,OAAO;;CAGlD,SAAS,QAAgB;EACvB,MAAM,SAAS,KAAK;EACpB,IAAI,UAAU;AACd,OAAK,MAAM,CAAC,OAAO,UAAU,QAC3B,KAAI,MAAM,OAAO,aAAa,QAAQ;AACpC,WAAQ,OAAO,MAAM;AACrB,cAAW;;AAGf,SAAO;;CAGT,SAAS,MAAM,OAGF;AACX,SAAO;AACP,SAAO,QAAQ,QAAQ,eACrB,cAAa;EAEf,MAAM,WAAW,KAAK;EACtB,MAAM,QAAQ,aAAa,OAAO,GAAG,CAAC;EACtC,MAAMA,SAAmB;GACvB;GACA;GACA,WAAW,WAAW;GACtB,SAAS,MAAM;GACf,QAAQ,OAAO,OAAO,MAAM,OAAO,OAAO,CAAC;GAC5C;AACD,UAAQ,IAAI,OAAO;GAAE;GAAQ,UAAU;GAAO,CAAC;AAC/C,SAAO;;CAGT,SAAS,QAAQ,OAAsC;EACrD,MAAM,QAAQ,QAAQ,IAAI,MAAM;AAChC,MAAI,UAAU,QAAW;AACvB,UAAO;AACP,UAAO;IAAE,IAAI;IAAO,QAAQ;IAAW;;AAEzC,MAAI,MAAM,OAAO,aAAa,KAAK,EAAE;AACnC,WAAQ,OAAO,MAAM;AACrB,UAAO;AACP,UAAO;IAAE,IAAI;IAAO,QAAQ;IAAW;;AAEzC,MAAI,MAAM,UAAU;AAClB,UAAO;AACP,UAAO;IAAE,IAAI;IAAO,QAAQ;IAAY;;AAE1C,QAAM,WAAW;AACjB,SAAO;AACP,SAAO;GAAE,IAAI;GAAM,QAAQ,MAAM;GAAQ;;AAG3C,QAAO,OAAO,OAAO;EACnB;EACA;EACA;EACA;EACA,YAAY,QAAQ;EACrB,CAAC;;AAGJ,SAAS,aAAa,OAA2B;AAI/C,QAAO,OAAO,KAAK,MAAM,CACtB,SAAS,SAAS,CAClB,QAAQ,OAAO,IAAI,CACnB,QAAQ,OAAO,IAAI,CACnB,QAAQ,QAAQ,GAAG"}

package/dist/ws/upgrade.d.ts

@@ -0,0 +1,63 @@
+import { ServerVariables } from "../internal/context.js";
+import { WsDispatcher } from "./dispatcher.js";
+import { RunStateTracker } from "../runtime/run-state.js";
+import { WsTicketStore } from "./ticket.js";
+import { Context } from "hono";
+import { TokenVerifier } from "@graphorin/security/auth";
+import { WSEvents } from "hono/ws";
+
+//#region src/ws/upgrade.d.ts
+
+/**
+ * Public configuration accepted by {@link createWsUpgradeEvents}.
+ *
+ * @stable
+ */
+interface WsUpgradeOptions {
+  readonly dispatcher: WsDispatcher;
+  readonly tickets: WsTicketStore;
+  /**
+   * Token verifier for bearer / ticket upgrades. Optional only in the
+   * IP-13 no-auth loopback mode (`anonymous: true`), where there is no
+   * verifier to construct and every upgrade is accepted.
+   */
+  readonly verifier?: TokenVerifier;
+  /**
+   * IP-13: authentication is disabled server-wide (`auth.kind='none'`).
+   * Accept the upgrade unconditionally with a full (`admin:*`) scope grant
+   * instead of silently refusing to mount the WS route. Trusted-loopback
+   * / single-operator mode only.
+   */
+  readonly anonymous?: boolean;
+  readonly runs?: RunStateTracker;
+  readonly now?: () => number;
+  /**
+   * Subprotocol the server advertises. Defaults to
+   * {@link SUBPROTOCOL_NAME}; tests can override to exercise the
+   * mismatch path.
+   */
+  readonly serverSubprotocol?: string;
+  readonly newSubscriptionId?: () => string;
+  readonly newSubscriberId?: () => string;
+}
+/**
+ * Build the `WSEvents` callback bag the Hono helper consumes. The
+ * function takes the request `Context` so the upgrade can read the
+ * `Authorization` header / `Sec-WebSocket-Protocol` ticket directly.
+ *
+ * Production wiring on `@hono/node-ws`:
+ *
+ * ```ts
+ * const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });
+ * app.get('/v1/ws', upgradeWebSocket((c) => createWsUpgradeEvents(c, deps)));
+ * injectWebSocket(serve(...));
+ * ```
+ *
+ * @stable
+ */
+declare function createWsUpgradeEvents(c: Context<{
+  Variables: ServerVariables;
+}>, options: WsUpgradeOptions): Promise<WSEvents>;
+//#endregion
+export { WsUpgradeOptions, createWsUpgradeEvents };
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/ws/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","names":[],"sources":["../../src/ws/upgrade.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;UA0DiB,gBAAA;uBACM;oBACH;;;;;;sBAME;;;;;;;;kBAQJ;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BI,qBAAA,IACjB;aAAqB;aACf,mBACR,QAAQ"}