@inixiative/signet 0.2.1 → 0.2.2

package/README.md

@@ -10,22 +10,34 @@ This package is the one implementation of that protocol, shared by Kingdom (whic
 - `proof`: create and verify DPoP proofs (ES256, nonce-bound, access-token-bound).
 - `files`: private 0600 JSON files for keys and credentials.
 - `client`:
-  - device pairing: `requestPairing`, then the owner approves the review code in Kingdom, then `collectPairing` and `saveCollectedSignet`;
+  - an **Installation** (a local Foundry, Archive or Oracle) is an actor known to Kingdom by its key: `registerInstallation`, then `requestRegistration` returns a review code a person claims in Kingdom (a `registerIntegration` Inquiry), then `collectSignet` and `saveCollectedSignet`. `installationInquiries`, `installationSignets`, `cancelInstallationInquiry`, `enrollInstallationSignet` and `rotateInstallationKey` act as the installation;
+  - `InstallationSocket`, Kingdom's live line to an installation: it proves the key, receives a snapshot of the installation's inquiries and Signets on connect and on every change, keeps the installation's integrations marked online, advertises its viewer URL, and polls the same reads while the socket is down;
   - `SignetClient`, which renews its access token and signs each `describe` / `execute` call.
 
 ```ts
-import { collectPairing, generateClientKey, requestPairing, saveCollectedSignet, SignetClient, writePrivateJson } from '@inixiative/signet';
-
-await writePrivateJson(keyFile, generateClientKey());
-const pending = await requestPairing(kingdom, keyFile, {
-  provider: 'archive', name: 'Laptop Archive', resources: [], expiresAt: null, maxRequests: null, maxConcurrent: 4,
+import {
+  collectSignet, generateSignetKey, InstallationSocket, registerInstallation, requestRegistration,
+  saveCollectedSignet, SignetClient, writePrivateJson,
+} from '@inixiative/signet';
+
+await writePrivateJson(keyFile, generateSignetKey());
+await registerInstallation(kingdom, keyFile, { kind: 'archive', name: 'Laptop Archive', sourceId });
+const { reviewCode } = await requestRegistration(kingdom, keyFile, {
+  name: 'Laptop Archive', lifecycle: 'ongoing', resources: [], expiresAt: null, maxRequests: null, maxConcurrent: 4,
+});
+// Show reviewCode; someone claims it in Kingdom. The socket tells you when the inquiry resolves.
+const socket = new InstallationSocket({
+  url: kingdom,
+  keyFile,
+  onSnapshot: async ({ inquiries }) => {
+    const approved = inquiries.find((inquiry) => inquiry.status === 'approved' && inquiry.signetId);
+    const collected = approved && (await collectSignet(kingdom, keyFile, approved.id));
+    if (collected) await saveCollectedSignet(credentialFile, kingdom, keyFile, collected);
+  },
 });
-// Show pending.reviewCode; poll until approved (null while pending, until pending.expiresAt).
-const collected = await collectPairing(kingdom, keyFile, pending.deviceCode);
-await saveCollectedSignet(credentialFile, kingdom, keyFile, collected!);
+socket.start();
 
-const signet = new SignetClient(credentialFile);
-const { operations } = await signet.describe();
+const signet = new SignetClient(kingdom, credentialFile, signetId);
 await signet.execute({ integrationId, operation: 'sessions.write', input: { resourceId, snapshot, previousDigest: null } });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Present Kingdom Signets: the wire contracts, DPoP proofs, device pairing and a renewing client shared by Kingdom, Archive, Foundry and Oracle.",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.55",
+    "@inixiative/config": "^0.5.58",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/contracts.ts

@@ -230,3 +230,9 @@ export const accessRequestSchema = z.strictObject({
 });
 export type AccessRequest = z.infer<typeof accessRequestSchema>;
 export const accessResultSchema = z.object({ executionId: z.uuid(), result: z.unknown() });
+/** What Kingdom pushes over the Installation socket, and what a poll of both reads assembles. */
+export const installationSnapshotSchema = installationInquiriesResponseSchema.extend(
+  installationSignetsResponseSchema.shape,
+);
+/** The path a socket proof is bound to (POST), though the socket itself opens at the API origin. */
+export const installationSocketAction = 'installationSocket';

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './client';
 export * from './contracts';
 export * from './files';
+export * from './installationSocket';
 export * from './proof';

package/src/installationSocket.ts

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { installationInquiries, installationSignets, kingdomUrl, signetProof } from './client';
+import { installationSnapshotSchema, installationSocketAction } from './contracts';
+
+export type InstallationSnapshot = z.infer<typeof installationSnapshotSchema>;
+
+export type InstallationSocketOptions = {
+  url: string;
+  keyFile: string;
+  onSnapshot: (snapshot: InstallationSnapshot) => void | Promise<void>;
+  /** Kingdom revoked this installation; the socket has stopped for good. */
+  onRevoked?: () => void;
+  onError?: (error: unknown) => void;
+  /** Where Kingdom can reach this installation's viewer (Foundry's tunnel); re-advertised on every connect. */
+  viewerUrl?: string | null;
+  /** Reported on every ping so Kingdom can show how busy this installation is. */
+  sessionCount?: () => number;
+  pingMs?: number;
+  pollMs?: number;
+  retryBaseMs?: number;
+  retryMaxMs?: number;
+  WebSocket?: typeof WebSocket;
+};
+
+const frameSchema = z.object({ type: z.string() }).loose();
+
+/**
+ * Kingdom's live line to an Installation. It proves the installation's key, then receives a
+ * snapshot of its inquiries and Signets on connect and again whenever one changes. While the
+ * socket is down it polls the same reads, so nothing waits on the socket coming back.
+ */
+export class InstallationSocket {
+  private socket: WebSocket | null = null;
+  private stopped = false;
+  private attempts = 0;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private pollTimer: ReturnType<typeof setTimeout> | null = null;
+  private retryTimer: ReturnType<typeof setTimeout> | null = null;
+  private authenticated = false;
+  private polling = false;
+  private pollGeneration = 0;
+  private viewerUrl: string | null;
+
+  constructor(private readonly options: InstallationSocketOptions) {
+    this.viewerUrl = options.viewerUrl ?? null;
+  }
+
+  get connected() {
+    return this.authenticated;
+  }
+
+  start() {
+    if (this.socket || this.retryTimer) return;
+    this.stopped = false;
+    this.connect();
+  }
+
+  /** Tell Kingdom this installation is restarting (presence shows it as such), then close. */
+  restarting() {
+    this.send({ action: 'restarting' });
+    this.close();
+  }
+
+  advertise(viewerUrl: string | null) {
+    this.viewerUrl = viewerUrl;
+    if (this.authenticated) this.send({ action: 'advertise', viewerUrl });
+  }
+
+  close() {
+    this.stopped = true;
+    this.clearTimers();
+    this.socket?.close(1000, 'closed');
+    this.socket = null;
+    this.authenticated = false;
+  }
+
+  private connect() {
+    this.retryTimer = null;
+    if (this.stopped) return;
+    const Socket = this.options.WebSocket ?? WebSocket;
+    const socket = new Socket(kingdomUrl(this.options.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 parsed: ReturnType<typeof frameSchema.safeParse>;
+    try {
+      parsed = frameSchema.safeParse(JSON.parse(raw));
+    } catch {
+      return;
+    }
+    if (!parsed.success || socket !== this.socket) return;
+    const frame = parsed.data;
+    try {
+      switch (frame.type) {
+        case 'connected':
+          this.send({
+            action: 'authenticateInstallation',
+            proof: await signetProof(
+              this.options.url,
+              installationSocketAction,
+              this.options.keyFile,
+            ),
+          });
+          return;
+        case 'installation':
+          this.authenticated = true;
+          this.attempts = 0;
+          this.stopPolling();
+          this.pingTimer ??= setInterval(
+            () => this.send({ action: 'ping', sessionCount: this.options.sessionCount?.() }),
+            this.options.pingMs ?? 20_000,
+          );
+          if (this.viewerUrl) this.send({ action: 'advertise', viewerUrl: this.viewerUrl });
+          return;
+        case 'installation.snapshot':
+          await this.options.onSnapshot(installationSnapshotSchema.parse(frame));
+          return;
+        case 'installationRejected':
+          socket.close();
+          return;
+        case 'installationRevoked':
+          this.close();
+          this.options.onRevoked?.();
+          return;
+        case 'reconnect':
+          socket.close();
+          return;
+        case 'advertiseRejected':
+          this.options.onError?.(Error(`Kingdom refused viewer URL ${this.viewerUrl}`));
+          return;
+      }
+    } catch (error) {
+      this.options.onError?.(error);
+      if (frame.type === 'connected') 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 === WebSocket.OPEN)
+      socket.send(JSON.stringify(frame));
+  }
+
+  private disconnected(socket: WebSocket) {
+    if (socket !== this.socket) return;
+    this.socket = null;
+    this.authenticated = false;
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    this.pingTimer = null;
+    if (this.stopped) return;
+    if (!this.polling) void this.poll();
+    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 async poll(generation = ++this.pollGeneration) {
+    if (this.stopped || this.authenticated || generation !== this.pollGeneration) return;
+    this.polling = true;
+    try {
+      const [inquiries, signets] = await Promise.all([
+        installationInquiries(this.options.url, this.options.keyFile),
+        installationSignets(this.options.url, this.options.keyFile),
+      ]);
+      if (!this.authenticated) await this.options.onSnapshot({ ...inquiries, ...signets });
+    } catch (error) {
+      this.options.onError?.(error);
+    }
+    if (this.stopped || this.authenticated || generation !== this.pollGeneration) return;
+    this.pollTimer = setTimeout(() => void this.poll(generation), this.options.pollMs ?? 60_000);
+  }
+
+  private stopPolling() {
+    if (this.pollTimer) clearTimeout(this.pollTimer);
+    this.pollTimer = null;
+    this.polling = false;
+    this.pollGeneration++;
+  }
+
+  private clearTimers() {
+    this.stopPolling();
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.pingTimer = null;
+    this.retryTimer = null;
+  }
+}