@graphorin/server 0.5.0

package/dist/ws/upgrade.js

@@ -0,0 +1,324 @@
+import { ClientMessageSchema, RPC_ERROR_CODES, SUBPROTOCOL_NAME, closeCodeFor, isCancelledNotification, isInitializeRequest, isPingRequest, isRunCancelRequest, isSubscribeRequest, isUnsubscribeRequest, negotiateSubprotocol, parseTicketSubprotocol } from "@graphorin/protocol";
+import { parseScope, scopeMatches } from "@graphorin/security/auth";
+
+//#region src/ws/upgrade.ts
+/**
+* Hono WebSocket upgrade handler. Wires the `@hono/node-ws` adapter
+* to the dispatcher: validates the subprotocol, runs auth (bearer
+* via `requireAuth` middleware OR ticket via the in-memory store),
+* and bridges the per-connection `WSContext` callbacks to the
+* dispatcher's RPC handler.
+*
+* ## Subprotocol + browser ticket flow
+*
+* The negotiated subprotocol is always {@link SUBPROTOCOL_NAME}
+* (`graphorin.protocol.v1`) — the canonical wire contract lives in
+* `@graphorin/protocol`'s `subprotocol.ts`. Two auth paths exist:
+*
+* - **Bearer (non-browser):** the client sends `Authorization:
+*   Bearer <token>` and a single `Sec-WebSocket-Protocol:
+*   graphorin.protocol.v1` token.
+* - **Ticket (browser):** the `WebSocket` constructor cannot set
+*   headers, so the browser client offers two subprotocol tokens —
+*   `graphorin.protocol.v1` and `ticket.<value>`. The server echoes
+*   back only the canonical name (in `app.ts`'s `handleProtocols`),
+*   and {@link resolveUpgradeAuth} extracts the ticket via
+*   `parseTicketSubprotocol` and redeems it against the single-use
+*   {@link WsTicketStore}. Tickets are short-lived and one-shot to
+*   bound replay.
+*
+* @packageDocumentation
+*/
+/**
+* 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
+*/
+async function createWsUpgradeEvents(c, options) {
+	if (negotiateSubprotocol(c.req.header("sec-websocket-protocol") ?? "") === null) return rejectImmediately(closeCodeFor("protocol.violation"), "protocol.violation");
+	const auth = await resolveUpgradeAuth(c, options);
+	if (auth.kind === "denied") return rejectImmediately(closeCodeFor(auth.reason), auth.reason);
+	const subscriberId = options.newSubscriberId?.() ?? defaultSubscriberId();
+	const newSubscriptionId = options.newSubscriptionId ?? (() => defaultSubscriptionId(subscriberId));
+	let unregister;
+	let initialized = false;
+	return {
+		onOpen: (_event, ws) => {
+			const handle = {
+				id: subscriberId,
+				tokenId: auth.tokenId,
+				grantedScopes: auth.grantedScopes,
+				send: (frame) => {
+					ws.send(JSON.stringify(frame));
+				},
+				close: (code, reason) => {
+					ws.close(code, reason);
+				},
+				bufferedAmount: () => {
+					return ws.raw?.bufferedAmount ?? 0;
+				}
+			};
+			unregister = options.dispatcher.registerSubscriber(handle).unregister;
+		},
+		onMessage: (event, ws) => {
+			const raw = typeof event.data === "string" ? event.data : "";
+			let payload;
+			try {
+				payload = JSON.parse(raw);
+			} catch {
+				sendRpcError(ws, void 0, RPC_ERROR_CODES.PARSE_ERROR, "Frame is not valid JSON.");
+				ws.close(closeCodeFor("protocol.violation"), "protocol.violation");
+				return;
+			}
+			const parsed = ClientMessageSchema.safeParse(payload);
+			if (!parsed.success) {
+				sendRpcError(ws, payload?.id, RPC_ERROR_CODES.INVALID_REQUEST, "Frame failed schema validation.");
+				ws.close(closeCodeFor("protocol.violation"), "protocol.violation");
+				return;
+			}
+			const message = parsed.data;
+			if (isCancelledNotification(message)) {
+				if (initialized && grantsInvokeScope(auth.grantedScopes)) options.runs?.abort(message.params.requestId, "mcp-cancel");
+				return;
+			}
+			if (!initialized && !isInitializeRequest(message) && !isPingRequest(message)) {
+				sendRpcError(ws, message.id, RPC_ERROR_CODES.PROTOCOL_VIOLATION, "Send `initialize` before any other RPC.");
+				return;
+			}
+			if (isInitializeRequest(message)) {
+				initialized = true;
+				sendRpcSuccess(ws, message.id, {
+					serverInfo: {
+						name: "graphorin-server",
+						version: "0.5.0"
+					},
+					capabilities: {
+						subscriptions: true,
+						replayBuffer: true,
+						sseFallback: true
+					}
+				});
+				return;
+			}
+			if (isPingRequest(message)) {
+				const nonce = message.params?.nonce;
+				ws.send(JSON.stringify({
+					v: "1",
+					kind: "pong",
+					...nonce !== void 0 ? { nonce } : {}
+				}));
+				sendRpcSuccess(ws, message.id, { ok: true });
+				return;
+			}
+			if (isSubscribeRequest(message)) {
+				const subscriptionId = newSubscriptionId();
+				const result = options.dispatcher.subscribe({
+					subscriberId,
+					subject: message.params.subject,
+					subscriptionId,
+					...message.params.sinceEventId !== void 0 ? { sinceEventId: message.params.sinceEventId } : {}
+				});
+				if (!result.ok) {
+					sendRpcError(ws, message.id, mapSubscribeErrorCode(result.reason), mapSubscribeErrorMessage(result.reason, message.params.subject));
+					return;
+				}
+				sendRpcSuccess(ws, message.id, {
+					subscriptionId,
+					subject: message.params.subject,
+					snapshotEventId: result.snapshotEventId,
+					replayedCount: result.replayedCount
+				});
+				ws.send(JSON.stringify({
+					v: "1",
+					kind: "subscribed",
+					subscriptionId,
+					subject: message.params.subject,
+					...result.snapshotEventId !== void 0 ? { snapshotEventId: result.snapshotEventId } : {}
+				}));
+				return;
+			}
+			if (isUnsubscribeRequest(message)) {
+				if (!options.dispatcher.unsubscribe(message.params.subscriptionId)) {
+					sendRpcError(ws, message.id, RPC_ERROR_CODES.SUBSCRIPTION_NOT_FOUND, `Subscription '${message.params.subscriptionId}' not active.`);
+					return;
+				}
+				sendRpcSuccess(ws, message.id, {
+					subscriptionId: message.params.subscriptionId,
+					unsubscribed: true
+				});
+				ws.send(JSON.stringify({
+					v: "1",
+					kind: "unsubscribed",
+					subscriptionId: message.params.subscriptionId
+				}));
+				return;
+			}
+			if (isRunCancelRequest(message)) {
+				if (!grantsInvokeScope(auth.grantedScopes)) {
+					sendRpcError(ws, message.id, RPC_ERROR_CODES.SCOPE_DENIED, "Token lacks required scope 'agents:invoke'.");
+					return;
+				}
+				const runId = message.params.runId;
+				if (!(options.runs?.abort(runId, message.params.reason ?? "rpc-cancel") === true)) {
+					sendRpcError(ws, message.id, RPC_ERROR_CODES.RUN_NOT_FOUND, `Run '${runId}' is not active.`);
+					return;
+				}
+				sendRpcSuccess(ws, message.id, {
+					runId,
+					cancelled: true,
+					partialStateAvailable: true
+				});
+				return;
+			}
+		},
+		onClose: () => {
+			try {
+				unregister?.();
+			} finally {
+				unregister = void 0;
+			}
+		},
+		onError: () => {
+			try {
+				unregister?.();
+			} finally {
+				unregister = void 0;
+			}
+		}
+	};
+}
+function sendRpcSuccess(ws, id, result) {
+	const frame = {
+		v: "1",
+		jsonrpc: "2.0",
+		id,
+		result
+	};
+	ws.send(JSON.stringify(frame));
+}
+function sendRpcError(ws, id, code, message) {
+	const frame = {
+		v: "1",
+		jsonrpc: "2.0",
+		id: id ?? 0,
+		error: {
+			code,
+			message
+		}
+	};
+	ws.send(JSON.stringify(frame));
+}
+function rejectImmediately(code, reason) {
+	return { onOpen: (_event, ws) => {
+		ws.close(code, reason);
+	} };
+}
+async function resolveUpgradeAuth(c, options) {
+	const state = c.var.state;
+	if (state?.auth?.kind === "token") return {
+		kind: "ok",
+		tokenId: state.auth.token.tokenId,
+		grantedScopes: state.auth.grantedScopes
+	};
+	if (options.anonymous === true) return {
+		kind: "ok",
+		tokenId: "anonymous",
+		grantedScopes: ANONYMOUS_WS_SCOPES
+	};
+	const ticketValue = parseTicketSubprotocol(c.req.header("sec-websocket-protocol") ?? "");
+	if (ticketValue !== void 0) {
+		const consumed = options.tickets.consume(ticketValue);
+		if (!consumed.ok) return {
+			kind: "denied",
+			reason: "auth.invalid"
+		};
+		return acceptTicket(consumed.ticket);
+	}
+	const header = c.req.header("authorization") ?? c.req.header("Authorization");
+	if (header?.toLowerCase().startsWith("bearer ") === true) {
+		if (options.verifier === void 0) return {
+			kind: "denied",
+			reason: "auth.required"
+		};
+		const token = header.slice(7).trim();
+		const verified = await options.verifier.verify(token);
+		if (!verified.ok) return {
+			kind: "denied",
+			reason: "auth.invalid"
+		};
+		return {
+			kind: "ok",
+			tokenId: verified.token.tokenId,
+			grantedScopes: verified.token.scopes
+		};
+	}
+	return {
+		kind: "denied",
+		reason: "auth.required"
+	};
+}
+/**
+* IP-8: the `agents:invoke` scope required to cancel a run over the WS
+* transport — the same requirement the REST `POST /runs/:runId/abort` route
+* enforces. `scopeMatches` honours wildcards (`agents:*`, `admin:*`).
+*/
+const INVOKE_SCOPE = parseScope("agents:invoke");
+/**
+* IP-13: full scope grant handed to a no-auth (`auth.kind='none'`) upgrade.
+* `admin:*` matches every required scope, including the {@link INVOKE_SCOPE}
+* gate on run cancellation.
+*/
+const ANONYMOUS_WS_SCOPES = [parseScope("admin:*")];
+function grantsInvokeScope(granted) {
+	for (const scope of granted) if (scopeMatches(scope, INVOKE_SCOPE)) return true;
+	return false;
+}
+function acceptTicket(ticket) {
+	return {
+		kind: "ok",
+		tokenId: ticket.tokenId,
+		grantedScopes: ticket.scopes
+	};
+}
+function mapSubscribeErrorCode(reason) {
+	switch (reason) {
+		case "scope-denied": return RPC_ERROR_CODES.SCOPE_DENIED;
+		case "subject-wildcard": return RPC_ERROR_CODES.INVALID_PARAMS;
+		case "subject-unknown": return RPC_ERROR_CODES.METHOD_NOT_FOUND;
+		case "subject-malformed": return RPC_ERROR_CODES.INVALID_PARAMS;
+	}
+}
+function mapSubscribeErrorMessage(reason, subject) {
+	switch (reason) {
+		case "scope-denied": return `Token lacks required scope for subject '${subject}'.`;
+		case "subject-wildcard": return `Wildcard subjects are not supported in this version. Subject: '${subject}'.`;
+		case "subject-unknown": return `Unknown subject grammar: '${subject}'.`;
+		case "subject-malformed": return `Subject '${subject}' is malformed.`;
+	}
+}
+function defaultSubscriberId() {
+	return `sub-conn-${randomToken(8)}`;
+}
+function defaultSubscriptionId(subscriberId) {
+	return `${subscriberId}-${randomToken(6)}`;
+}
+function randomToken(length) {
+	const bytes = new Uint8Array(length);
+	if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.getRandomValues === "function") globalThis.crypto.getRandomValues(bytes);
+	else for (let i = 0; i < length; i += 1) bytes[i] = Math.floor(Math.random() * 256);
+	return Buffer.from(bytes).toString("hex");
+}
+
+//#endregion
+export { createWsUpgradeEvents };
+//# sourceMappingURL=upgrade.js.map

package/dist/ws/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","names":["unregister: (() => void) | undefined","payload: unknown","frame: ServerMessage","INVOKE_SCOPE: ParsedScope","ANONYMOUS_WS_SCOPES: ReadonlyArray<ParsedScope>"],"sources":["../../src/ws/upgrade.ts"],"sourcesContent":["/**\n * Hono WebSocket upgrade handler. Wires the `@hono/node-ws` adapter\n * to the dispatcher: validates the subprotocol, runs auth (bearer\n * via `requireAuth` middleware OR ticket via the in-memory store),\n * and bridges the per-connection `WSContext` callbacks to the\n * dispatcher's RPC handler.\n *\n * ## Subprotocol + browser ticket flow\n *\n * The negotiated subprotocol is always {@link SUBPROTOCOL_NAME}\n * (`graphorin.protocol.v1`) — the canonical wire contract lives in\n * `@graphorin/protocol`'s `subprotocol.ts`. Two auth paths exist:\n *\n * - **Bearer (non-browser):** the client sends `Authorization:\n *   Bearer <token>` and a single `Sec-WebSocket-Protocol:\n *   graphorin.protocol.v1` token.\n * - **Ticket (browser):** the `WebSocket` constructor cannot set\n *   headers, so the browser client offers two subprotocol tokens —\n *   `graphorin.protocol.v1` and `ticket.<value>`. The server echoes\n *   back only the canonical name (in `app.ts`'s `handleProtocols`),\n *   and {@link resolveUpgradeAuth} extracts the ticket via\n *   `parseTicketSubprotocol` and redeems it against the single-use\n *   {@link WsTicketStore}. Tickets are short-lived and one-shot to\n *   bound replay.\n *\n * @packageDocumentation\n */\n\nimport {\n  ClientMessageSchema,\n  closeCodeFor,\n  isCancelledNotification,\n  isInitializeRequest,\n  isPingRequest,\n  isRunCancelRequest,\n  isSubscribeRequest,\n  isUnsubscribeRequest,\n  negotiateSubprotocol,\n  parseTicketSubprotocol,\n  RPC_ERROR_CODES,\n  type ServerMessage,\n  SUBPROTOCOL_NAME,\n} from '@graphorin/protocol';\nimport type { ParsedScope, TokenVerifier } from '@graphorin/security/auth';\nimport { parseScope, scopeMatches } from '@graphorin/security/auth';\nimport type { Context } from 'hono';\nimport type { WSContext, WSEvents } from 'hono/ws';\n\nimport type { ServerVariables } from '../internal/context.js';\nimport type { RunStateTracker } from '../runtime/run-state.js';\nimport type { WsDispatcher } from './dispatcher.js';\nimport type { WsTicket, WsTicketStore } from './ticket.js';\n\n/**\n * Public configuration accepted by {@link createWsUpgradeEvents}.\n *\n * @stable\n */\nexport interface WsUpgradeOptions {\n  readonly dispatcher: WsDispatcher;\n  readonly tickets: WsTicketStore;\n  /**\n   * Token verifier for bearer / ticket upgrades. Optional only in the\n   * IP-13 no-auth loopback mode (`anonymous: true`), where there is no\n   * verifier to construct and every upgrade is accepted.\n   */\n  readonly verifier?: TokenVerifier;\n  /**\n   * IP-13: authentication is disabled server-wide (`auth.kind='none'`).\n   * Accept the upgrade unconditionally with a full (`admin:*`) scope grant\n   * instead of silently refusing to mount the WS route. Trusted-loopback\n   * / single-operator mode only.\n   */\n  readonly anonymous?: boolean;\n  readonly runs?: RunStateTracker;\n  readonly now?: () => number;\n  /**\n   * Subprotocol the server advertises. Defaults to\n   * {@link SUBPROTOCOL_NAME}; tests can override to exercise the\n   * mismatch path.\n   */\n  readonly serverSubprotocol?: string;\n  readonly newSubscriptionId?: () => string;\n  readonly newSubscriberId?: () => string;\n}\n\n/**\n * Build the `WSEvents` callback bag the Hono helper consumes. The\n * function takes the request `Context` so the upgrade can read the\n * `Authorization` header / `Sec-WebSocket-Protocol` ticket directly.\n *\n * Production wiring on `@hono/node-ws`:\n *\n * ```ts\n * const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });\n * app.get('/v1/ws', upgradeWebSocket((c) => createWsUpgradeEvents(c, deps)));\n * injectWebSocket(serve(...));\n * ```\n *\n * @stable\n */\nexport async function createWsUpgradeEvents(\n  c: Context<{ Variables: ServerVariables }>,\n  options: WsUpgradeOptions,\n): Promise<WSEvents> {\n  const negotiated = negotiateSubprotocol(c.req.header('sec-websocket-protocol') ?? '');\n  if (negotiated === null) {\n    return rejectImmediately(closeCodeFor('protocol.violation'), 'protocol.violation');\n  }\n  const auth = await resolveUpgradeAuth(c, options);\n  if (auth.kind === 'denied') {\n    return rejectImmediately(closeCodeFor(auth.reason), auth.reason);\n  }\n\n  const subscriberId = options.newSubscriberId?.() ?? defaultSubscriberId();\n  const newSubscriptionId =\n    options.newSubscriptionId ?? (() => defaultSubscriptionId(subscriberId));\n\n  let unregister: (() => void) | undefined;\n  let initialized = false;\n\n  return {\n    onOpen: (_event, ws) => {\n      const handle = {\n        id: subscriberId,\n        tokenId: auth.tokenId,\n        grantedScopes: auth.grantedScopes,\n        send: (frame: ServerMessage) => {\n          ws.send(JSON.stringify(frame));\n        },\n        close: (code: number, reason: string) => {\n          ws.close(code, reason);\n        },\n        // IP-9: surface the socket's real backlog so the dispatcher's\n        // backpressure threshold measures something — the synchronous\n        // outstanding-events counter never accumulates.\n        bufferedAmount: () => {\n          const raw = (ws as { raw?: { bufferedAmount?: number } }).raw;\n          return raw?.bufferedAmount ?? 0;\n        },\n      };\n      const reg = options.dispatcher.registerSubscriber(handle);\n      unregister = reg.unregister;\n    },\n    onMessage: (event, ws) => {\n      const raw = typeof event.data === 'string' ? event.data : '';\n      let payload: unknown;\n      try {\n        payload = JSON.parse(raw);\n      } catch {\n        sendRpcError(ws, undefined, RPC_ERROR_CODES.PARSE_ERROR, 'Frame is not valid JSON.');\n        ws.close(closeCodeFor('protocol.violation'), 'protocol.violation');\n        return;\n      }\n      const parsed = ClientMessageSchema.safeParse(payload);\n      if (!parsed.success) {\n        sendRpcError(\n          ws,\n          (payload as { id?: string | number } | null)?.id,\n          RPC_ERROR_CODES.INVALID_REQUEST,\n          'Frame failed schema validation.',\n        );\n        ws.close(closeCodeFor('protocol.violation'), 'protocol.violation');\n        return;\n      }\n      const message = parsed.data;\n      if (isCancelledNotification(message)) {\n        // IP-8: only an initialized connection holding `agents:invoke` may\n        // cancel a run. A notification carries no id, so an unauthorised one\n        // is silently ignored (there is no error channel) rather than aborting\n        // an arbitrary run.\n        if (initialized && grantsInvokeScope(auth.grantedScopes)) {\n          options.runs?.abort(message.params.requestId, 'mcp-cancel');\n        }\n        return;\n      }\n      if (!initialized && !isInitializeRequest(message) && !isPingRequest(message)) {\n        // IP-21: a frame before `initialize` is a protocol-sequencing error,\n        // not an auth failure — the connection is already authenticated.\n        sendRpcError(\n          ws,\n          message.id,\n          RPC_ERROR_CODES.PROTOCOL_VIOLATION,\n          'Send `initialize` before any other RPC.',\n        );\n        return;\n      }\n      if (isInitializeRequest(message)) {\n        initialized = true;\n        sendRpcSuccess(ws, message.id, {\n          serverInfo: {\n            name: 'graphorin-server',\n            version: '0.5.0',\n          },\n          capabilities: {\n            subscriptions: true,\n            replayBuffer: true,\n            sseFallback: true,\n          },\n        });\n        return;\n      }\n      if (isPingRequest(message)) {\n        const nonce = message.params?.nonce;\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'pong',\n            ...(nonce !== undefined ? { nonce } : {}),\n          } satisfies ServerMessage),\n        );\n        sendRpcSuccess(ws, message.id, { ok: true });\n        return;\n      }\n      if (isSubscribeRequest(message)) {\n        const subscriptionId = newSubscriptionId();\n        const result = options.dispatcher.subscribe({\n          subscriberId,\n          subject: message.params.subject,\n          subscriptionId,\n          ...(message.params.sinceEventId !== undefined\n            ? { sinceEventId: message.params.sinceEventId }\n            : {}),\n        });\n        if (!result.ok) {\n          sendRpcError(\n            ws,\n            message.id,\n            mapSubscribeErrorCode(result.reason),\n            mapSubscribeErrorMessage(result.reason, message.params.subject),\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          subscriptionId,\n          subject: message.params.subject,\n          snapshotEventId: result.snapshotEventId,\n          replayedCount: result.replayedCount,\n        });\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'subscribed',\n            subscriptionId,\n            subject: message.params.subject,\n            ...(result.snapshotEventId !== undefined\n              ? { snapshotEventId: result.snapshotEventId }\n              : {}),\n          } satisfies ServerMessage),\n        );\n        return;\n      }\n      if (isUnsubscribeRequest(message)) {\n        const removed = options.dispatcher.unsubscribe(message.params.subscriptionId);\n        if (!removed) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.SUBSCRIPTION_NOT_FOUND,\n            `Subscription '${message.params.subscriptionId}' not active.`,\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          subscriptionId: message.params.subscriptionId,\n          unsubscribed: true,\n        });\n        ws.send(\n          JSON.stringify({\n            v: '1',\n            kind: 'unsubscribed',\n            subscriptionId: message.params.subscriptionId,\n          } satisfies ServerMessage),\n        );\n        return;\n      }\n      if (isRunCancelRequest(message)) {\n        // IP-8: mirror the REST `POST /runs/:runId/abort` scope gate so a\n        // bearer token cannot abort an arbitrary run without `agents:invoke`.\n        if (!grantsInvokeScope(auth.grantedScopes)) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.SCOPE_DENIED,\n            \"Token lacks required scope 'agents:invoke'.\",\n          );\n          return;\n        }\n        const runId = message.params.runId;\n        const aborted = options.runs?.abort(runId, message.params.reason ?? 'rpc-cancel') === true;\n        if (!aborted) {\n          sendRpcError(\n            ws,\n            message.id,\n            RPC_ERROR_CODES.RUN_NOT_FOUND,\n            `Run '${runId}' is not active.`,\n          );\n          return;\n        }\n        sendRpcSuccess(ws, message.id, {\n          runId,\n          cancelled: true,\n          partialStateAvailable: true,\n        });\n        return;\n      }\n    },\n    onClose: () => {\n      try {\n        unregister?.();\n      } finally {\n        unregister = undefined;\n      }\n    },\n    onError: () => {\n      try {\n        unregister?.();\n      } finally {\n        unregister = undefined;\n      }\n    },\n  };\n}\n\nfunction sendRpcSuccess(ws: WSContext, id: string | number, result: unknown): void {\n  const frame: ServerMessage = { v: '1', jsonrpc: '2.0', id, result };\n  ws.send(JSON.stringify(frame));\n}\n\nfunction sendRpcError(\n  ws: WSContext,\n  id: string | number | undefined,\n  code: number,\n  message: string,\n): void {\n  const frame: ServerMessage = {\n    v: '1',\n    jsonrpc: '2.0',\n    id: id ?? 0,\n    error: { code, message },\n  };\n  ws.send(JSON.stringify(frame));\n}\n\nfunction rejectImmediately(code: number, reason: string): WSEvents {\n  return {\n    onOpen: (_event, ws) => {\n      ws.close(code, reason);\n    },\n  };\n}\n\ninterface ResolvedUpgradeAuthOk {\n  readonly kind: 'ok';\n  readonly tokenId: string;\n  readonly grantedScopes: ReadonlyArray<ParsedScope>;\n}\n\ninterface ResolvedUpgradeAuthDenied {\n  readonly kind: 'denied';\n  readonly reason: 'auth.required' | 'auth.invalid' | 'auth.scope_denied';\n}\n\ntype ResolvedUpgradeAuth = ResolvedUpgradeAuthOk | ResolvedUpgradeAuthDenied;\n\nasync function resolveUpgradeAuth(\n  c: Context<{ Variables: ServerVariables }>,\n  options: WsUpgradeOptions,\n): Promise<ResolvedUpgradeAuth> {\n  // Phase 14a's HTTP middleware may have already verified the\n  // bearer token (`requireAuth` runs before the upgrade route on\n  // the authenticated subtree); if so, reuse the result.\n  const state = c.var.state;\n  if (state?.auth?.kind === 'token') {\n    return {\n      kind: 'ok',\n      tokenId: state.auth.token.tokenId,\n      grantedScopes: state.auth.grantedScopes,\n    };\n  }\n  // IP-13: no-auth loopback mode — accept the upgrade with a full scope grant\n  // instead of silently failing to mount. Checked before ticket/bearer so the\n  // verifier may legitimately be absent.\n  if (options.anonymous === true) {\n    return { kind: 'ok', tokenId: 'anonymous', grantedScopes: ANONYMOUS_WS_SCOPES };\n  }\n  const ticketValue = parseTicketSubprotocol(c.req.header('sec-websocket-protocol') ?? '');\n  if (ticketValue !== undefined) {\n    const consumed = options.tickets.consume(ticketValue);\n    if (!consumed.ok) {\n      return { kind: 'denied', reason: 'auth.invalid' };\n    }\n    return acceptTicket(consumed.ticket);\n  }\n  const header = c.req.header('authorization') ?? c.req.header('Authorization');\n  if (header?.toLowerCase().startsWith('bearer ') === true) {\n    if (options.verifier === undefined) return { kind: 'denied', reason: 'auth.required' };\n    const token = header.slice(7).trim();\n    const verified = await options.verifier.verify(token);\n    if (!verified.ok) return { kind: 'denied', reason: 'auth.invalid' };\n    return {\n      kind: 'ok',\n      tokenId: verified.token.tokenId,\n      grantedScopes: verified.token.scopes,\n    };\n  }\n  return { kind: 'denied', reason: 'auth.required' };\n}\n\n/**\n * IP-8: the `agents:invoke` scope required to cancel a run over the WS\n * transport — the same requirement the REST `POST /runs/:runId/abort` route\n * enforces. `scopeMatches` honours wildcards (`agents:*`, `admin:*`).\n */\nconst INVOKE_SCOPE: ParsedScope = parseScope('agents:invoke');\n\n/**\n * IP-13: full scope grant handed to a no-auth (`auth.kind='none'`) upgrade.\n * `admin:*` matches every required scope, including the {@link INVOKE_SCOPE}\n * gate on run cancellation.\n */\nconst ANONYMOUS_WS_SCOPES: ReadonlyArray<ParsedScope> = [parseScope('admin:*')];\n\nfunction grantsInvokeScope(granted: ReadonlyArray<ParsedScope>): boolean {\n  for (const scope of granted) {\n    if (scopeMatches(scope, INVOKE_SCOPE)) return true;\n  }\n  return false;\n}\n\nfunction acceptTicket(ticket: WsTicket): ResolvedUpgradeAuth {\n  return {\n    kind: 'ok',\n    tokenId: ticket.tokenId,\n    grantedScopes: ticket.scopes,\n  };\n}\n\nfunction mapSubscribeErrorCode(\n  reason: 'subject-malformed' | 'subject-unknown' | 'subject-wildcard' | 'scope-denied',\n): number {\n  switch (reason) {\n    case 'scope-denied':\n      return RPC_ERROR_CODES.SCOPE_DENIED;\n    case 'subject-wildcard':\n      return RPC_ERROR_CODES.INVALID_PARAMS;\n    case 'subject-unknown':\n      return RPC_ERROR_CODES.METHOD_NOT_FOUND;\n    case 'subject-malformed':\n      return RPC_ERROR_CODES.INVALID_PARAMS;\n  }\n}\n\nfunction mapSubscribeErrorMessage(\n  reason: 'subject-malformed' | 'subject-unknown' | 'subject-wildcard' | 'scope-denied',\n  subject: string,\n): string {\n  switch (reason) {\n    case 'scope-denied':\n      return `Token lacks required scope for subject '${subject}'.`;\n    case 'subject-wildcard':\n      return `Wildcard subjects are not supported in this version. Subject: '${subject}'.`;\n    case 'subject-unknown':\n      return `Unknown subject grammar: '${subject}'.`;\n    case 'subject-malformed':\n      return `Subject '${subject}' is malformed.`;\n  }\n}\n\nfunction defaultSubscriberId(): string {\n  return `sub-conn-${randomToken(8)}`;\n}\n\nfunction defaultSubscriptionId(subscriberId: string): string {\n  return `${subscriberId}-${randomToken(6)}`;\n}\n\nfunction randomToken(length: number): string {\n  const bytes = new Uint8Array(length);\n  if (\n    typeof globalThis.crypto !== 'undefined' &&\n    typeof globalThis.crypto.getRandomValues === 'function'\n  ) {\n    globalThis.crypto.getRandomValues(bytes);\n  } else {\n    for (let i = 0; i < length; i += 1) {\n      bytes[i] = Math.floor(Math.random() * 256);\n    }\n  }\n  return Buffer.from(bytes).toString('hex');\n}\n\nvoid SUBPROTOCOL_NAME;\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,156 @@
+{
+  "name": "@graphorin/server",
+  "version": "0.5.0",
+  "description": "Standalone server runtime for the Graphorin framework: createServer({...}) factory, Hono HTTP app, REST endpoints (agents / workflows / sessions / memory / skills / mcp / tokens / audit / health / health/secrets / metrics / triggers / runs/:runId/replay / sessions/:id/replay / audit/verify), per-request authentication + scope middleware (HMAC-SHA256 + pepper, server pepper required), brute-force lockout, IETF draft-07 Idempotency-Key middleware with SQLite backing + LRU read cache, deny-by-default CORS, double-submit CSRF for browser flows, sliding-window rate limit, audit middleware that streams every authenticated request through the tamper-evident hash chain, programmatic AgentRegistry / WorkflowRegistry, lifecycle hooks (beforeStart / onReady / beforeShutdown), pre-bind secrets resolution + storage migration runner that fails fast on missing pepper / unresolvable SecretRef / missing encryption peer, graceful SIGTERM drain with state preservation, durable triggers daemon (cron / interval / idle / event survive process restart per the catch-up policy contract), consolidator daemon lifecycle integration with hard stop timeout, per-subsystem health rollup (storage / embedder / secrets / encryption / consolidator / triggers / replay-buffer), Prometheus text exposition `/v1/metrics` with the canonical graphorin_* metric inventory, scope-enforced replay endpoints (sanitized by default, raw requires `traces:read:raw` admin scope, every invocation appended to the audit chain), and `POST /v1/audit/verify` chain integrity check. Created and maintained by Oleksiy Stepurenko.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "server",
+    "http",
+    "rest",
+    "hono",
+    "idempotency",
+    "auth",
+    "scopes",
+    "rate-limit",
+    "cors",
+    "csrf",
+    "audit",
+    "lifecycle",
+    "graceful-shutdown"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "import": "./dist/registry/index.js"
+    },
+    "./ws": {
+      "types": "./dist/ws/index.d.ts",
+      "import": "./dist/ws/index.js"
+    },
+    "./sse": {
+      "types": "./dist/sse/index.d.ts",
+      "import": "./dist/sse/index.js"
+    },
+    "./commentary": {
+      "types": "./dist/commentary/index.d.ts",
+      "import": "./dist/commentary/index.js"
+    },
+    "./triggers": {
+      "types": "./dist/triggers/index.d.ts",
+      "import": "./dist/triggers/index.js"
+    },
+    "./consolidator": {
+      "types": "./dist/consolidator/index.d.ts",
+      "import": "./dist/consolidator/index.js"
+    },
+    "./health": {
+      "types": "./dist/health/index.d.ts",
+      "import": "./dist/health/index.js"
+    },
+    "./metrics": {
+      "types": "./dist/metrics/index.d.ts",
+      "import": "./dist/metrics/index.js"
+    },
+    "./replay": {
+      "types": "./dist/replay/index.d.ts",
+      "import": "./dist/replay/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@hono/node-server": "^1.19.0",
+    "@hono/node-ws": "^1.3.0",
+    "hono": "^4.12.21",
+    "zod": "^3.25.0",
+    "@graphorin/core": "0.5.0",
+    "@graphorin/observability": "0.5.0",
+    "@graphorin/protocol": "0.5.0",
+    "@graphorin/security": "0.5.0",
+    "@graphorin/store-sqlite": "0.5.0",
+    "@graphorin/triggers": "0.5.0"
+  },
+  "peerDependencies": {
+    "@graphorin/agent": "0.5.0",
+    "@graphorin/memory": "0.5.0",
+    "@graphorin/sessions": "0.5.0",
+    "@graphorin/workflow": "0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@graphorin/agent": {
+      "optional": true
+    },
+    "@graphorin/memory": {
+      "optional": true
+    },
+    "@graphorin/sessions": {
+      "optional": true
+    },
+    "@graphorin/workflow": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/ws": "^8.18.1",
+    "better-sqlite3": "^12.9.0",
+    "ws": "^8.20.1",
+    "@graphorin/agent": "0.5.0",
+    "@graphorin/memory": "0.5.0",
+    "@graphorin/sessions": "0.5.0",
+    "@graphorin/workflow": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}