@inixiative/signet 0.4.3 → 0.5.0

package/src/signetSocket.ts

@@ -0,0 +1,214 @@
+import { z } from 'zod';
+import type { SignetClient } from './client';
+import { kingdomUrl } from './client';
+import { signetPresentedFrameSchema } from './contracts';
+import { type ThreadStreamHandlers, ThreadStreams } from './threadStreams';
+
+export type SignetSocketOptions = ThreadStreamHandlers & {
+  /** The Signet this socket presents; it renews the access token the presentation rides on. */
+  client: SignetClient;
+  /** Kingdom accepted (or renewed) the presentation; it holds until `expiresAt`. */
+  onPresented?: (presentation: z.infer<typeof signetPresentedFrameSchema>) => void;
+  pingMs?: number;
+  retryBaseMs?: number;
+  retryMaxMs?: number;
+  /** A Kingdom that never answers the presentation is treated as down. */
+  authTimeoutMs?: number;
+  /** Renew this long before the access token expires (it lives five minutes). */
+  renewBeforeMs?: number;
+  WebSocket?: typeof WebSocket;
+};
+
+const frameSchema = z.object({ type: z.string() }).loose();
+/** WebSocket.OPEN, read from the spec rather than whichever WebSocket class was passed. */
+const OPEN = 1;
+
+/**
+ * Kingdom's live line to a Signet presenter: an outside agent holding a member's Signet on a host
+ * Foundry's threads (design §5.6.1). It authenticates as that Signet's presentation
+ * (`authenticateSignet`: the access token and a single-use proof bound to the Signet socket), renews
+ * the presentation before the token expires (`renewPresentation`), and holds the member's
+ * `accessThread` streams: entering a thread is opening its stream, and Kingdom closes it on leave,
+ * revocation, any revision, expiry or the host going offline. Posts are not sent here; each is its
+ * own `access/execute thread.prompt` through the `SignetClient`.
+ */
+export class SignetSocket {
+  private socket: WebSocket | null = null;
+  private stopped = false;
+  private attempts = 0;
+  private authenticated = false;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private retryTimer: ReturnType<typeof setTimeout> | null = null;
+  private authTimer: ReturnType<typeof setTimeout> | null = null;
+  private renewTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly streams: ThreadStreams;
+
+  constructor(private readonly options: SignetSocketOptions) {
+    this.streams = new ThreadStreams((frame) => this.send(frame), options, {
+      retryBaseMs: options.retryBaseMs,
+      // Kingdom closed streams because the presentation lapsed: re-present on a new connection.
+      onPresentationExpired: () => this.socket?.close(),
+    });
+  }
+
+  get connected() {
+    return this.authenticated;
+  }
+
+  start() {
+    if (this.socket || this.retryTimer) return;
+    this.stopped = false;
+    this.connect();
+  }
+
+  /** Enter a thread this Signet's lens selects: a snapshot of the member's view, then appends. */
+  open(threadId: string) {
+    this.streams.open({ signetId: this.options.client.signetId, threadId });
+  }
+
+  /** Leave a thread: Kingdom closes the stream. */
+  leave(threadId: string) {
+    this.streams.leave({ signetId: this.options.client.signetId, threadId });
+  }
+
+  /** The threads this socket holds open, or is opening. */
+  threads() {
+    return this.streams.held().map((stream) => stream.threadId);
+  }
+
+  close() {
+    this.stopped = true;
+    this.clearTimers();
+    this.socket?.close(1000, 'closed');
+    this.socket = null;
+    this.authenticated = false;
+    this.streams.down();
+  }
+
+  private connect() {
+    this.retryTimer = null;
+    if (this.stopped) return;
+    const Socket = this.options.WebSocket ?? WebSocket;
+    const socket = new Socket(kingdomUrl(this.options.client.url).replace(/^http/, 'ws'));
+    this.socket = socket;
+    socket.onmessage = (event) => void this.receive(socket, String(event.data));
+    socket.onclose = () => this.disconnected(socket);
+    socket.onerror = () => socket.close();
+  }
+
+  private async receive(socket: WebSocket, raw: string) {
+    let json: unknown;
+    try {
+      json = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (socket !== this.socket || typeof json !== 'object' || json === null) return;
+    if (this.streams.receive(json as Record<string, unknown>)) return;
+    const parsed = frameSchema.safeParse(json);
+    if (!parsed.success) return;
+    const frame = parsed.data;
+    try {
+      switch (frame.type) {
+        case 'connected': {
+          this.authTimer = setTimeout(() => socket.close(), this.options.authTimeoutMs ?? 10_000);
+          const { accessToken, proof } = await this.options.client.socketPresentation();
+          this.sendOn(socket, { action: 'authenticateSignet', accessToken, proof });
+          return;
+        }
+        case 'signet': {
+          const presented = signetPresentedFrameSchema.parse(frame);
+          if (presented.signetId !== this.options.client.signetId) {
+            this.options.onError?.(Error('Kingdom presented another Signet on this socket'));
+            socket.close();
+            return;
+          }
+          if (this.authTimer) clearTimeout(this.authTimer);
+          this.authTimer = null;
+          this.scheduleRenewal(socket, presented.expiresAt);
+          this.options.onPresented?.(presented);
+          if (this.authenticated) return;
+          this.authenticated = true;
+          this.attempts = 0;
+          this.pingTimer ??= setInterval(
+            () => this.send({ action: 'ping' }),
+            this.options.pingMs ?? 20_000,
+          );
+          this.streams.up();
+          return;
+        }
+        case 'signetRejected':
+          this.options.onError?.(Error('Kingdom refused this Signet presentation'));
+          socket.close();
+          return;
+        case 'reconnect':
+          socket.close();
+          return;
+      }
+    } catch (error) {
+      this.options.onError?.(error);
+      if (frame.type === 'connected') socket.close();
+    }
+  }
+
+  // The presentation is bounded by the access token; Kingdom closes every stream if none follows.
+  private scheduleRenewal(socket: WebSocket, expiresAt: string) {
+    if (this.renewTimer) clearTimeout(this.renewTimer);
+    const delay = Math.max(
+      0,
+      Date.parse(expiresAt) - Date.now() - (this.options.renewBeforeMs ?? 60_000),
+    );
+    this.renewTimer = setTimeout(() => void this.renew(socket, expiresAt), delay);
+  }
+
+  private async renew(socket: WebSocket, expiresAt: string) {
+    this.renewTimer = null;
+    if (socket !== this.socket) return;
+    try {
+      const { accessToken, proof } = await this.options.client.socketPresentation({ renew: true });
+      this.sendOn(socket, { action: 'renewPresentation', accessToken, proof });
+      // Kingdom answers with `signet` (which reschedules); silence means the presentation is lost.
+      this.authTimer = setTimeout(() => socket.close(), this.options.authTimeoutMs ?? 10_000);
+    } catch (error) {
+      this.options.onError?.(error);
+      if (socket !== this.socket) return;
+      // Try again while the old presentation still holds; past it, reconnect and present afresh.
+      if (Date.parse(expiresAt) > Date.now())
+        this.renewTimer = setTimeout(
+          () => void this.renew(socket, expiresAt),
+          this.options.retryBaseMs ?? 1_000,
+        );
+      else socket.close();
+    }
+  }
+
+  private send(frame: Record<string, unknown>) {
+    if (this.socket) this.sendOn(this.socket, frame);
+  }
+
+  private sendOn(socket: WebSocket, frame: Record<string, unknown>) {
+    if (socket === this.socket && socket.readyState === OPEN) socket.send(JSON.stringify(frame));
+  }
+
+  private disconnected(socket: WebSocket) {
+    if (socket !== this.socket) return;
+    this.socket = null;
+    this.authenticated = false;
+    this.clearTimers();
+    this.streams.down();
+    if (this.stopped) return;
+    const base = this.options.retryBaseMs ?? 1_000;
+    const delay = Math.min(base * 2 ** this.attempts++, this.options.retryMaxMs ?? 30_000);
+    this.retryTimer = setTimeout(() => this.connect(), delay);
+  }
+
+  private clearTimers() {
+    for (const timer of [this.authTimer, this.renewTimer, this.retryTimer])
+      if (timer) clearTimeout(timer);
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    this.authTimer = null;
+    this.renewTimer = null;
+    this.retryTimer = null;
+    this.pingTimer = null;
+  }
+}

package/src/threadStreams.ts

@@ -0,0 +1,315 @@
+import { z } from 'zod';
+import {
+  type AccessThreadCloseReason,
+  accessThreadAppendType,
+  accessThreadCloseReasonSchema,
+  accessThreadStreamName,
+  parseAccessThreadStreamName,
+  parseThreadView,
+  type ThreadEntry,
+  type ThreadViewResult,
+  threadEntrySchema,
+} from './threads';
+
+export type ThreadStreamKey = { signetId: string; threadId: string };
+
+/** What a member does with its live views. `reason` is null when Kingdom gave none. */
+export type ThreadStreamHandlers = {
+  /** A fresh view: on open, and again after every resync. Replace what was held for the thread. */
+  onSnapshot: (stream: ThreadStreamKey, view: ThreadViewResult) => void | Promise<void>;
+  onEntry: (stream: ThreadStreamKey, entry: ThreadEntry) => void | Promise<void>;
+  /** Kingdom ended the stream for good, or refused to open it (`rejected`); it is not reopened. */
+  onClosed?: (stream: ThreadStreamKey, reason: AccessThreadCloseReason | 'rejected' | null) => void;
+  /** A frame that didn't parse, or entries dropped from one (the rest are kept). */
+  onError?: (error: unknown) => void;
+};
+
+export type ThreadStreamOptions = {
+  retryBaseMs?: number;
+  /** An open Kingdom never answers is sent again after this long (a relay waits up to 15 s). */
+  openTimeoutMs?: number;
+  /** Kingdom closed a stream because the socket's presentation lapsed: re-present, then reopen. */
+  onPresentationExpired?: () => void;
+};
+
+const reasonSchema = accessThreadCloseReasonSchema.optional().catch(undefined);
+const controlFrameSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('opened'), stream: z.string() }),
+  z.object({ type: z.literal('openRejected'), stream: z.string(), reason: reasonSchema }),
+  z.object({ type: z.literal('closed'), stream: z.string(), reason: reasonSchema }),
+  z.object({ type: z.literal('resync'), stream: z.string() }),
+  z.object({
+    type: z.literal('error'),
+    action: z.string(),
+    stream: z.string(),
+    retryable: z.boolean(),
+  }),
+]);
+const dataFrameSchema = z.discriminatedUnion('action', [
+  z.object({
+    category: z.literal('data'),
+    action: z.literal('snapshot'),
+    stream: z.string(),
+    seq: z.number().int(),
+    payload: z.unknown(),
+  }),
+  z.object({
+    category: z.literal('data'),
+    action: z.literal('append'),
+    stream: z.string(),
+    seq: z.number().int(),
+    type: z.string(),
+    payload: z.unknown(),
+  }),
+]);
+
+type StreamState = {
+  key: ThreadStreamKey;
+  lastSeq: number | null;
+  attempts: number;
+  /** An open is on the wire; a resync or retry meanwhile waits for its answer, not a second open. */
+  pending: boolean;
+  /** Something asked for a fresh snapshot while an open was pending: open again once it answers. */
+  again: boolean;
+};
+
+/** Kingdom closed the stream, but the member may come back: under a new lens, or once re-presented. */
+const reopenAfter = new Set<AccessThreadCloseReason>(['revised', 'presentationExpired']);
+/** Kingdom closed the stream until the host returns: reopen with backoff. */
+const retryAfter = new Set<AccessThreadCloseReason>(['hostOffline']);
+
+/**
+ * A member's `accessThread` streams on one Kingdom socket, as Kingdom's data-stream primitive and
+ * its web client run them (Kingdom `docs/claude/WEBSOCKETS.md`, `packages/ui/src/lib/ws/
+ * createApiWebsocket.ts`, which isn't published): one open in flight per stream, a snapshot
+ * carrying `seq`, then appends; an append at or below the last seq is already in the snapshot, and a
+ * gap or `resync` re-opens for a fresh snapshot. No replay. Frames are handled one at a time, so an
+ * append never overtakes the snapshot before it. The socket that owns it sends and re-authenticates.
+ */
+export class ThreadStreams {
+  private readonly streams = new Map<string, StreamState>();
+  /** Closes this member sent and Kingdom hasn't acknowledged yet, per stream (answered in order). */
+  private readonly leaving = new Map<string, number>();
+  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private queue: Promise<void> = Promise.resolve();
+  private ready = false;
+
+  constructor(
+    private readonly send: (frame: Record<string, unknown>) => void,
+    private readonly handlers: ThreadStreamHandlers,
+    private readonly options: ThreadStreamOptions = {},
+  ) {}
+
+  /** The streams this member holds open, or is opening. */
+  held(): ThreadStreamKey[] {
+    return [...this.streams.values()].map((state) => ({ ...state.key }));
+  }
+
+  /** Enter a thread: open its stream now, or once the socket is authenticated. */
+  open(key: ThreadStreamKey) {
+    const stream = accessThreadStreamName(key);
+    if (this.streams.has(stream)) return;
+    this.streams.set(stream, {
+      key: { ...key },
+      lastSeq: null,
+      attempts: 0,
+      pending: false,
+      again: false,
+    });
+    this.sendOpen(stream);
+  }
+
+  /** Leave a thread: Kingdom closes the stream (and the host's subscription). */
+  leave(key: ThreadStreamKey) {
+    const stream = accessThreadStreamName(key);
+    if (!this.streams.delete(stream)) return;
+    this.clearTimer(stream);
+    if (!this.ready) return;
+    this.leaving.set(stream, (this.leaving.get(stream) ?? 0) + 1);
+    this.send({ action: 'close', stream });
+  }
+
+  /** The socket (re)authenticated: open every held stream for a fresh snapshot. */
+  up() {
+    this.ready = true;
+    for (const stream of this.streams.keys()) this.sendOpen(stream);
+  }
+
+  /** The socket dropped: everything held is stale until the next snapshot. */
+  down() {
+    this.ready = false;
+    this.leaving.clear();
+    for (const stream of [...this.timers.keys()]) this.clearTimer(stream);
+    for (const state of this.streams.values()) {
+      state.lastSeq = null;
+      state.pending = false;
+      state.again = false;
+    }
+  }
+
+  /** Handle a frame if it belongs to an `accessThread` stream; true when it did. */
+  receive(frame: Record<string, unknown>): boolean {
+    if (typeof frame.stream !== 'string' || !parseAccessThreadStreamName(frame.stream))
+      return false;
+    this.queue = this.queue
+      .then(() => this.handle(frame))
+      .catch(this.handlers.onError ?? (() => {}));
+    return true;
+  }
+
+  private async handle(frame: Record<string, unknown>) {
+    if (frame.category === 'data') {
+      const data = dataFrameSchema.safeParse(frame);
+      if (!data.success) return this.handlers.onError?.(data.error);
+      return this.data(data.data);
+    }
+    const control = controlFrameSchema.safeParse(frame);
+    if (!control.success) return this.handlers.onError?.(control.error);
+    this.control(control.data);
+  }
+
+  private control(frame: z.infer<typeof controlFrameSchema>) {
+    const state = this.streams.get(frame.stream);
+    switch (frame.type) {
+      case 'opened':
+        if (state) state.attempts = 0;
+        return;
+      case 'resync':
+        return this.reopen(frame.stream);
+      case 'error':
+        if (!state || frame.action !== 'open') return;
+        this.answered(state);
+        if (frame.retryable) return this.retry(frame.stream, state);
+        return this.end(frame.stream, 'rejected');
+      case 'openRejected':
+        if (state) this.answered(state);
+        return this.closedBy(frame.stream, frame.reason ?? 'rejected');
+      case 'closed':
+        // Our own close is only acknowledged (no reason, or `left`); a close with any other reason,
+        // or one we didn't ask for, is Kingdom ending the stream.
+        if ((frame.reason ?? 'left') === 'left' && this.acknowledge(frame.stream)) return;
+        return this.closedBy(frame.stream, frame.reason ?? null);
+    }
+  }
+
+  private closedBy(stream: string, reason: AccessThreadCloseReason | 'rejected' | null) {
+    const state = this.streams.get(stream);
+    if (!state) return;
+    if (reason === 'presentationExpired') {
+      // The socket re-presents; `up()` then reopens everything held.
+      state.lastSeq = null;
+      this.options.onPresentationExpired?.();
+      return;
+    }
+    if (reason && reasonIn(reopenAfter, reason)) return this.reopen(stream);
+    if (reason && reasonIn(retryAfter, reason)) return this.retry(stream, state);
+    this.end(stream, reason);
+  }
+
+  private async data(frame: z.infer<typeof dataFrameSchema>) {
+    const state = this.streams.get(frame.stream);
+    if (!state) return;
+    if (frame.action === 'snapshot') {
+      this.answered(state);
+      const view = parseThreadView(
+        z.object({ data: z.unknown() }).safeParse(frame.payload).data?.data,
+      );
+      if (!view) return this.abandon(state, Error(`${frame.stream}: unreadable snapshot`));
+      const { dropped, ...rest } = view;
+      if (dropped) this.handlers.onError?.(Error(`${frame.stream}: dropped ${dropped} entries`));
+      state.lastSeq = frame.seq;
+      await this.handlers.onSnapshot(state.key, rest);
+      if (state.again) {
+        state.again = false;
+        this.reopen(frame.stream);
+      }
+      return;
+    }
+    if (state.lastSeq === null || frame.seq <= state.lastSeq) return;
+    if (frame.seq > state.lastSeq + 1) return this.reopen(frame.stream);
+    state.lastSeq = frame.seq;
+    const entry = threadEntrySchema.safeParse(frame.payload);
+    if (frame.type !== accessThreadAppendType || !entry.success)
+      return this.handlers.onError?.(Error(`${frame.stream}: unreadable ${frame.type} append`));
+    await this.handlers.onEntry(state.key, entry.data);
+  }
+
+  private sendOpen(stream: string) {
+    const state = this.streams.get(stream);
+    if (!state || !this.ready) return;
+    if (state.pending) {
+      state.again = true;
+      return;
+    }
+    state.pending = true;
+    state.lastSeq = null;
+    this.send({ action: 'open', stream });
+    this.setTimer(stream, this.options.openTimeoutMs ?? 30_000, () => {
+      state.pending = false;
+      this.reopen(stream);
+    });
+  }
+
+  private answered(state: StreamState) {
+    state.pending = false;
+    this.clearTimer(accessThreadStreamName(state.key));
+  }
+
+  private acknowledge(stream: string) {
+    const pending = this.leaving.get(stream) ?? 0;
+    if (pending === 0) return false;
+    if (pending === 1) this.leaving.delete(stream);
+    else this.leaving.set(stream, pending - 1);
+    return true;
+  }
+
+  // Until the next snapshot, appends on the wire are already in it.
+  private reopen(stream: string) {
+    const state = this.streams.get(stream);
+    if (!state) return;
+    state.lastSeq = null;
+    this.sendOpen(stream);
+  }
+
+  private retry(stream: string, state: StreamState) {
+    const delay = Math.min((this.options.retryBaseMs ?? 1_000) * 2 ** state.attempts++, 30_000);
+    this.setTimer(stream, delay, () => this.reopen(stream));
+  }
+
+  private setTimer(stream: string, delay: number, fire: () => void) {
+    this.clearTimer(stream);
+    this.timers.set(
+      stream,
+      setTimeout(() => {
+        this.timers.delete(stream);
+        fire();
+      }, delay),
+    );
+  }
+
+  private clearTimer(stream: string) {
+    const timer = this.timers.get(stream);
+    if (timer) clearTimeout(timer);
+    this.timers.delete(stream);
+  }
+
+  // Re-opening an unreadable snapshot would read (and meter) the same thing again: leave instead.
+  private abandon(state: StreamState, error: unknown) {
+    this.handlers.onError?.(error);
+    this.leave(state.key);
+    this.handlers.onClosed?.(state.key, null);
+  }
+
+  private end(stream: string, reason: AccessThreadCloseReason | 'rejected' | null) {
+    const state = this.streams.get(stream);
+    if (!state) return;
+    this.streams.delete(stream);
+    this.clearTimer(stream);
+    this.handlers.onClosed?.(state.key, reason);
+  }
+}
+
+const reasonIn = (
+  set: Set<AccessThreadCloseReason>,
+  reason: AccessThreadCloseReason | 'rejected',
+) => reason !== 'rejected' && set.has(reason);