@ixo/oracle-runtime-workers 0.2.0

package/src/realtime/session-socket-hub.ts

@@ -0,0 +1,249 @@
+/**
+ * The realtime clients of one user object: every accepted WebSocket, the
+ * session it subscribed to, and its handshake state. This is the Workers
+ * counterpart of the Node runtime's `WsService` (`sessionConnections`) plus
+ * the socket.io room `server.to(sessionId)` that `BaseEvent` fans out to.
+ *
+ * Sockets are Hibernatable WebSockets: everything the hub knows about a
+ * socket — identity, handshake state AND the heartbeat bookkeeping (last
+ * ping sent, last pong seen) — lives in the per-socket attachment
+ * (`serializeAttachment`), so the set is rebuilt losslessly from
+ * `ctx.getWebSockets()` whenever the object wakes from hibernation or
+ * restarts. Nothing here is kept only in memory.
+ */
+import { ENGINE_PING, encodeEvent } from './socket-io-codec';
+
+export interface SocketAttachment {
+  /** engine.io session id (the `sid` from the OPEN handshake). */
+  sid: string;
+  /** Oracle session the socket subscribed to (`?sessionId=`). */
+  sessionId: string;
+  /** User DID the shell routed the socket for (`?userDid=`). */
+  routedUserDid: string;
+  /** Set once the CONNECT packet's UCAN auth validated. */
+  userDid?: string;
+  openedAt: number;
+  /** Last engine.io pong (`3`) seen — at open, "now". */
+  lastPongAt: number;
+  /** Last engine.io ping (`2`) sent; unset until the first heartbeat round. */
+  lastPingAt?: number;
+}
+
+/** The subset of the Workers `WebSocket` the hub needs (tests use fakes). */
+export interface HubSocket {
+  send(message: string): void;
+  close(code?: number, reason?: string): void;
+  serializeAttachment(value: unknown): void;
+  deserializeAttachment(): unknown;
+}
+
+export interface SessionSocketHubOptions {
+  logger?: { warn: (message: string) => void };
+  now?: () => number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isAttachment(value: unknown): value is SocketAttachment {
+  if (!isRecord(value)) return false;
+  const record = value;
+  return (
+    typeof record.sid === 'string' &&
+    typeof record.sessionId === 'string' &&
+    typeof record.routedUserDid === 'string' &&
+    typeof record.openedAt === 'number'
+  );
+}
+
+/** Attachments written before the heartbeat fields existed get them on restore. */
+function withHeartbeat(
+  attachment: SocketAttachment,
+  now: number,
+): SocketAttachment {
+  return typeof attachment.lastPongAt === 'number'
+    ? attachment
+    : { ...attachment, lastPongAt: now };
+}
+
+export class SessionSocketHub<S extends HubSocket = HubSocket> {
+  private readonly sockets = new Map<S, SocketAttachment>();
+
+  private readonly logger: { warn: (message: string) => void };
+
+  private readonly now: () => number;
+
+  constructor(options: SessionSocketHubOptions = {}) {
+    this.logger = options.logger ?? { warn: () => undefined };
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  /** Register a freshly accepted socket and persist its identity on it. */
+  add(socket: S, attachment: SocketAttachment): void {
+    socket.serializeAttachment(attachment);
+    this.sockets.set(socket, attachment);
+  }
+
+  /**
+   * Rebuild the set from the hibernated sockets (object wake or restart).
+   * The heartbeat bookkeeping comes back from the attachment untouched, so a
+   * socket that stopped answering before the object slept is still caught.
+   */
+  restore(sockets: readonly S[]): number {
+    let restored = 0;
+    const now = this.now();
+    for (const socket of sockets) {
+      const attachment = socket.deserializeAttachment();
+      if (!isAttachment(attachment)) {
+        // Not one of ours (or a pre-handshake socket whose attachment was
+        // never written): nothing to route to, close it.
+        socket.close(1011, 'unknown socket');
+        continue;
+      }
+      this.sockets.set(socket, withHeartbeat(attachment, now));
+      restored += 1;
+    }
+    return restored;
+  }
+
+  get(socket: S): SocketAttachment | undefined {
+    return this.sockets.get(socket);
+  }
+
+  /** Update the persisted attachment (e.g. after the CONNECT auth validated). */
+  update(
+    socket: S,
+    patch: Partial<SocketAttachment>,
+  ): SocketAttachment | undefined {
+    const current = this.sockets.get(socket);
+    if (!current) return undefined;
+    const next = { ...current, ...patch };
+    socket.serializeAttachment(next);
+    this.sockets.set(socket, next);
+    return next;
+  }
+
+  remove(socket: S): void {
+    this.sockets.delete(socket);
+  }
+
+  /** A pong arrived: persist the time (the object may sleep right after). */
+  notePong(socket: S): void {
+    if (this.sockets.has(socket))
+      this.update(socket, { lastPongAt: this.now() });
+  }
+
+  /** Every socket with its heartbeat bookkeeping (diagnostics). */
+  entries(): Array<{ socket: S; attachment: SocketAttachment }> {
+    return [...this.sockets].map(([socket, attachment]) => ({
+      socket,
+      attachment,
+    }));
+  }
+
+  /** Authenticated sockets subscribed to `sessionId`. */
+  forSession(sessionId: string): S[] {
+    const out: S[] = [];
+    for (const [socket, meta] of this.sockets) {
+      if (meta.userDid && meta.sessionId === sessionId) out.push(socket);
+    }
+    return out;
+  }
+
+  hasSession(sessionId: string): boolean {
+    return this.forSession(sessionId).length > 0;
+  }
+
+  /** Fan an event out to every authenticated socket of the session. */
+  emitToSession(
+    sessionId: string,
+    eventName: string,
+    payload: unknown,
+  ): number {
+    const frame = encodeEvent(eventName, payload);
+    let sent = 0;
+    for (const socket of this.forSession(sessionId)) {
+      if (this.trySend(socket, frame)) sent += 1;
+    }
+    return sent;
+  }
+
+  send(socket: S, frame: string): boolean {
+    return this.trySend(socket, frame);
+  }
+
+  /**
+   * One heartbeat round (run from the object's alarm, never from a timer):
+   * close every socket whose last pong is older than
+   * `pingIntervalMs + pingTimeoutMs` — the same rule the client applies in
+   * the other direction — and ping the rest, recording the ping time on the
+   * socket. Returns the sockets closed.
+   */
+  heartbeat(pingIntervalMs: number, pingTimeoutMs: number): S[] {
+    const now = this.now();
+    const closed: S[] = [];
+    for (const [socket, meta] of [...this.sockets]) {
+      if (now - meta.lastPongAt > pingIntervalMs + pingTimeoutMs) {
+        this.remove(socket);
+        try {
+          socket.close(4408, 'ping timeout');
+        } catch {
+          // already gone
+        }
+        closed.push(socket);
+        continue;
+      }
+      if (this.trySend(socket, ENGINE_PING))
+        this.update(socket, { lastPingAt: now });
+    }
+    return closed;
+  }
+
+  /**
+   * When the next heartbeat round is due: `pingIntervalMs` after the most
+   * overdue socket's last ping (its open time before the first round), or
+   * null with no sockets attached.
+   */
+  nextPingAt(pingIntervalMs: number): number | null {
+    let next: number | null = null;
+    for (const meta of this.sockets.values()) {
+      const due = (meta.lastPingAt ?? meta.openedAt) + pingIntervalMs;
+      if (next === null || due < next) next = due;
+    }
+    return next;
+  }
+
+  get size(): number {
+    return this.sockets.size;
+  }
+
+  /** Distinct sessions with at least one authenticated socket. */
+  sessionCount(): number {
+    const ids = new Set<string>();
+    for (const meta of this.sockets.values()) {
+      if (meta.userDid) ids.add(meta.sessionId);
+    }
+    return ids.size;
+  }
+
+  /** Authenticated socket count (Node's `totalConnections`). */
+  connectionCount(): number {
+    let n = 0;
+    for (const meta of this.sockets.values()) if (meta.userDid) n += 1;
+    return n;
+  }
+
+  private trySend(socket: S, frame: string): boolean {
+    try {
+      socket.send(frame);
+      return true;
+    } catch (err) {
+      this.logger.warn(
+        `socket send failed, dropping socket: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      this.remove(socket);
+      return false;
+    }
+  }
+}

package/src/realtime/socket-io-codec.ts

@@ -0,0 +1,187 @@
+/**
+ * Wire codec for the socket.io v4 protocol over a raw WebSocket — the
+ * server half only, enough to speak to `socket.io-client` (the client SDK's
+ * `use-websocket-events` hook connects with `transports: ['websocket']`).
+ *
+ * Two layers, both text frames:
+ *
+ *   engine.io v4 — one leading digit: `0` open, `1` close, `2` ping,
+ *     `3` pong, `4` message, `5` upgrade, `6` noop. The server initiates
+ *     pings; the client answers with `3`.
+ *   socket.io v4 (inside a `4` message) — type digit, optional binary
+ *     attachment count (`n-`), optional namespace (`/nsp,`), optional ack id
+ *     (digits), then a JSON payload. Only the default namespace is served.
+ *
+ * Examples on the wire:
+ *   server → `0{"sid":"…","upgrades":[],"pingInterval":25000,…}`
+ *   client → `40{"invocation":"…"}`            CONNECT with the auth object
+ *   server → `40{"sid":"…"}`                   CONNECT acknowledged
+ *   server → `44{"message":"Unauthorized"}`   CONNECT_ERROR
+ *   either → `42["tool_result",{…}]`          EVENT
+ *   client → `4212["ev",{}]` / server → `4312[]`   EVENT with ack id 12 / ACK
+ *
+ * Binary events (types 5/6) are not supported: nothing this runtime emits is
+ * binary, and the client SDK never sends any.
+ */
+
+export const ENGINE_OPEN = '0';
+export const ENGINE_CLOSE = '1';
+export const ENGINE_PING = '2';
+export const ENGINE_PONG = '3';
+export const ENGINE_MESSAGE = '4';
+
+const SIO_CONNECT = 0;
+const SIO_DISCONNECT = 1;
+const SIO_EVENT = 2;
+const SIO_ACK = 3;
+const SIO_CONNECT_ERROR = 4;
+
+export interface OpenHandshake {
+  sid: string;
+  pingIntervalMs: number;
+  pingTimeoutMs: number;
+  maxPayloadBytes: number;
+}
+
+export type ClientFrame =
+  | { kind: 'ping' }
+  | { kind: 'pong' }
+  | { kind: 'close' }
+  | { kind: 'connect'; auth: unknown }
+  | { kind: 'disconnect' }
+  | { kind: 'event'; name: string; args: unknown[]; ackId?: number }
+  | { kind: 'ack'; id: number; args: unknown[] }
+  | { kind: 'unsupported'; reason: string; raw: string };
+
+export function encodeOpen(handshake: OpenHandshake): string {
+  return (
+    ENGINE_OPEN +
+    JSON.stringify({
+      sid: handshake.sid,
+      upgrades: [],
+      pingInterval: handshake.pingIntervalMs,
+      pingTimeout: handshake.pingTimeoutMs,
+      maxPayload: handshake.maxPayloadBytes,
+    })
+  );
+}
+
+export function encodeConnectAck(sid: string): string {
+  return `${ENGINE_MESSAGE}${SIO_CONNECT}${JSON.stringify({ sid })}`;
+}
+
+export function encodeConnectError(message: string, data?: unknown): string {
+  return `${ENGINE_MESSAGE}${SIO_CONNECT_ERROR}${JSON.stringify(
+    data === undefined ? { message } : { message, data },
+  )}`;
+}
+
+export function encodeEvent(name: string, ...args: unknown[]): string {
+  return `${ENGINE_MESSAGE}${SIO_EVENT}${JSON.stringify([name, ...args])}`;
+}
+
+export function encodeAck(id: number, args: unknown[] = []): string {
+  return `${ENGINE_MESSAGE}${SIO_ACK}${id}${JSON.stringify(args)}`;
+}
+
+export function encodeDisconnect(): string {
+  return `${ENGINE_MESSAGE}${SIO_DISCONNECT}`;
+}
+
+function unsupported(reason: string, raw: string): ClientFrame {
+  return { kind: 'unsupported', reason, raw };
+}
+
+function parseJson(text: string): { ok: true; value: unknown } | { ok: false } {
+  if (text.length === 0) return { ok: true, value: undefined };
+  try {
+    return { ok: true, value: JSON.parse(text) as unknown };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Decode one text frame from the client. Never throws: anything outside the
+ * supported protocol subset comes back as `unsupported` with a reason, so
+ * the caller can log it and decide whether to close.
+ */
+export function decodeClientFrame(raw: string): ClientFrame {
+  if (raw.length === 0) return unsupported('empty frame', raw);
+  const engineType = raw.charAt(0);
+  switch (engineType) {
+    case ENGINE_PING:
+      return { kind: 'ping' };
+    case ENGINE_PONG:
+      return { kind: 'pong' };
+    case ENGINE_CLOSE:
+      return { kind: 'close' };
+    case ENGINE_MESSAGE:
+      return decodeSocketIoPacket(raw.slice(1), raw);
+    default:
+      return unsupported(`engine.io packet type ${engineType}`, raw);
+  }
+}
+
+function decodeSocketIoPacket(packet: string, raw: string): ClientFrame {
+  if (packet.length === 0) return unsupported('empty socket.io packet', raw);
+  const type = Number(packet.charAt(0));
+  if (!Number.isInteger(type) || type < 0 || type > 6) {
+    return unsupported(`socket.io packet type ${packet.charAt(0)}`, raw);
+  }
+  if (type === 5 || type === 6) {
+    return unsupported('binary socket.io packets are not supported', raw);
+  }
+  let i = 1;
+  // Namespace: only the default one is served.
+  if (packet.charAt(i) === '/') {
+    const end = packet.indexOf(',', i);
+    const nsp = end === -1 ? packet.slice(i) : packet.slice(i, end);
+    if (nsp !== '/') return unsupported(`namespace ${nsp} is not served`, raw);
+    i = end === -1 ? packet.length : end + 1;
+  }
+  // Optional ack id: consecutive digits before the payload.
+  let idText = '';
+  while (
+    i < packet.length &&
+    packet.charAt(i) >= '0' &&
+    packet.charAt(i) <= '9'
+  ) {
+    idText += packet.charAt(i);
+    i += 1;
+  }
+  const ackId = idText.length > 0 ? Number(idText) : undefined;
+  const payload = parseJson(packet.slice(i));
+  if (!payload.ok) return unsupported('malformed JSON payload', raw);
+
+  switch (type) {
+    case SIO_CONNECT:
+      return { kind: 'connect', auth: payload.value };
+    case SIO_DISCONNECT:
+      return { kind: 'disconnect' };
+    case SIO_EVENT: {
+      const value = payload.value;
+      if (!Array.isArray(value) || typeof value[0] !== 'string') {
+        return unsupported('event payload must be [name, ...args]', raw);
+      }
+      return {
+        kind: 'event',
+        name: value[0],
+        args: value.slice(1),
+        ...(ackId !== undefined ? { ackId } : {}),
+      };
+    }
+    case SIO_ACK: {
+      if (ackId === undefined) return unsupported('ack without id', raw);
+      const value = payload.value;
+      return {
+        kind: 'ack',
+        id: ackId,
+        args: Array.isArray(value) ? value : [],
+      };
+    }
+    default:
+      // CONNECT_ERROR is server → client only.
+      return unsupported(`unexpected socket.io packet type ${type}`, raw);
+  }
+}

package/src/secrets/jwe.ts

@@ -0,0 +1,74 @@
+/**
+ * Compact-JWE primitives for per-room secrets — a byte-for-byte port of
+ * `@ixo/oracles-chain-client`'s `matrix-bot/jwe-utils.ts` (the scheme the
+ * portal uses when a user deposits a room secret for an oracle):
+ *
+ *   - key agreement: `ECDH-ES+A256KW` over a P-256 keypair
+ *   - content encryption: `A256GCM`
+ *   - serialization: compact JWE
+ *
+ * Pure `jose` over WebCrypto, so it runs identically on Workers and Node —
+ * a secret written by the portal (or the Node runtime) decrypts here and
+ * vice versa.
+ */
+import { CompactEncrypt, compactDecrypt, importJWK, type JWK } from 'jose';
+
+export type { JWK };
+
+const JWE_ALG = 'ECDH-ES+A256KW';
+const JWE_ENC = 'A256GCM';
+
+/** Decrypt a compact JWE with the oracle's P-256 private JWK → UTF-8 plaintext. */
+export async function decryptJwe(
+  compact: string,
+  privateJwk: JWK,
+): Promise<string> {
+  const key = await importJWK(privateJwk, JWE_ALG);
+  const { plaintext } = await compactDecrypt(compact, key);
+  return new TextDecoder().decode(plaintext);
+}
+
+/**
+ * Compact-JWE encrypt to a P-256 public key (`ECDH-ES+A256KW` / `A256GCM`).
+ * Accepts a private JWK too: `d` is stripped so callers holding only the
+ * oracle's own keypair can encrypt to themselves (e.g. writing back a
+ * refreshed OAuth token) — same contract as the chain-client's `encryptJWE`.
+ */
+export async function encryptJwe(plaintext: string, jwk: JWK): Promise<string> {
+  const { d: _d, ...publicJwk } = jwk;
+  const key = await importJWK(publicJwk, JWE_ALG);
+  return new CompactEncrypt(new TextEncoder().encode(plaintext))
+    .setProtectedHeader({ alg: JWE_ALG, enc: JWE_ENC })
+    .encrypt(key);
+}
+
+/**
+ * Parse a JSON-encoded EC JWK (as returned by the gateway's
+ * `getOracleSecretsKey` — the oracle key is always P-256). Returns `null` on
+ * anything malformed so a corrupted key degrades to "no key seated" instead
+ * of throwing on the boot path. Unknown fields are dropped.
+ */
+export function parseJwk(json: string): JWK | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+  const { kty, crv, x, y, d, kid } = parsed as Record<string, unknown>;
+  if (kty !== 'EC') return null;
+  if (
+    typeof crv !== 'string' ||
+    typeof x !== 'string' ||
+    typeof y !== 'string'
+  ) {
+    return null;
+  }
+  const jwk: JWK = { kty: 'EC', crv, x, y };
+  if (typeof d === 'string') jwk.d = d;
+  if (typeof kid === 'string') jwk.kid = kid;
+  return jwk;
+}

package/src/secrets/pin-cipher.ts

@@ -0,0 +1,43 @@
+/**
+ * AES-256-CBC PIN cipher — the scheme the CLI uses when publishing the
+ * oracle's P-256 private JWK into the Matrix account room, ported from the
+ * chain-client's `decrypt()` (`setup-claim-signing-mnemonics.ts`):
+ *
+ *   - ciphertext format: `ivHex:cipherHex`
+ *   - key: the UTF-8 bytes of `pin.padEnd(32)` (no KDF — parity, not choice)
+ *   - padding: PKCS#7 (Node's `createDecipheriv` default; WebCrypto's
+ *     AES-CBC removes it identically, so ciphertexts are interchangeable)
+ *
+ * Bare WebCrypto — runs on Workers and Node alike. Throws on a key that is
+ * not exactly 32 bytes, mirroring Node's "Invalid key length" for over-long
+ * or multi-byte PINs.
+ */
+import { hexToBytes } from '@noble/hashes/utils';
+
+export async function decryptWithPin(
+  text: string,
+  pin: string,
+): Promise<string> {
+  const [ivHex, encryptedHex] = text.split(':');
+  const iv = hexToBytes(ivHex ?? '');
+  const encrypted = hexToBytes(encryptedHex ?? '');
+  const keyBytes = new TextEncoder().encode(pin.padEnd(32));
+  if (keyBytes.length !== 32) {
+    throw new Error(
+      `decryptWithPin: invalid key length ${keyBytes.length} (the PIN must be at most 32 single-byte characters)`,
+    );
+  }
+  const key = await crypto.subtle.importKey(
+    'raw',
+    keyBytes,
+    { name: 'AES-CBC' },
+    false,
+    ['decrypt'],
+  );
+  const plain = await crypto.subtle.decrypt(
+    { name: 'AES-CBC', iv },
+    key,
+    encrypted,
+  );
+  return new TextDecoder().decode(plain);
+}