@inixiative/signet 0.2.1 → 0.3.0

package/README.md

@@ -10,22 +10,28 @@ 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`;
-  - `SignetClient`, which renews its access token and signs each `describe` / `execute` call.
+  - 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;
+  - `pairInstallation` does the whole pairing (register, request, wait on the socket, confirm the owner, collect) and `holdInstallationSignets` keeps one credential file per Signet the installation's integrations hold, enrolling later grants and dropping revoked ones;
+  - `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 call: `describe`, `execute`, task settlement, and the run actions a Foundry uses for inference (`resolveRun`, `delegateRun`, `renewRun`, `revokeRun`).
 
 ```ts
-import { collectPairing, generateClientKey, requestPairing, saveCollectedSignet, SignetClient, writePrivateJson } from '@inixiative/signet';
+import { holdInstallationSignets, InstallationSocket, pairInstallation, SignetClient } 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,
+const paired = await pairInstallation({
+  url: kingdom, root: dataDir, kind: 'archive', name: 'Laptop Archive', sourceId,
+  terms: { name: 'Laptop Archive', lifecycle: 'ongoing', resources: [], expiresAt: null, maxRequests: null, maxConcurrent: 4 },
+  onReview: ({ review }) => console.log(`Approve in Kingdom: ${review}`),
+  confirmOwner: async ({ ownerName }) => confirm(`Pair with ${ownerName}?`),
 });
-// 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!);
 
-const signet = new SignetClient(credentialFile);
-const { operations } = await signet.describe();
+new InstallationSocket({
+  url: kingdom,
+  keyFile: paired.keyFile,
+  onSnapshot: ({ signets }) => holdInstallationSignets(kingdom, paired.keyFile, paired.directory, signets),
+}).start();
+
+const signet = await SignetClient.fromFile(paired.credentialFile);
 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.3.0",
   "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.59",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/client.ts

@@ -16,6 +16,7 @@ import {
   registerInstallationResponseSchema,
   renewalCredentialPattern,
   requestRegistrationResponseSchema,
+  setInstallationCredentialResponseSchema,
   signetDescriptionSchema,
   signetKeySchema,
   signetLifecycleSchema,
@@ -346,6 +347,23 @@ export const enrollInstallationSignet = (
     options,
   );
 
+/** Give Kingdom the credential it uses to reach this installation's integration (Foundry's tunnel token). */
+export const setInstallationCredential = (
+  url: string,
+  keyFile: string,
+  integrationId: string,
+  token: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'setInstallationCredential',
+    { integrationId, token },
+    setInstallationCredentialResponseSchema,
+    options,
+  );
+
 /** Move this installation to a new key; both keys sign, the new proof bound to the current key. */
 export async function rotateInstallationKey(
   url: string,
@@ -384,13 +402,26 @@ export async function saveCollectedSignet(
   return credential;
 }
 
-export type SignetAction = 'describe' | 'execute' | 'closeTask' | 'verifyAuthority' | 'settleTask';
+export type SignetAction =
+  | 'describe'
+  | 'execute'
+  | 'closeTask'
+  | 'verifyAuthority'
+  | 'settleTask'
+  | 'resolveRun'
+  | 'delegateRun'
+  | 'renewRun'
+  | 'revokeRun';
 const signetActions: SignetAction[] = [
   'describe',
   'execute',
   'closeTask',
   'verifyAuthority',
   'settleTask',
+  'resolveRun',
+  'delegateRun',
+  'renewRun',
+  'revokeRun',
 ];
 
 /** Presents one enrolled Signet: renews its access token and signs each call with the device key. */

package/src/contracts.ts

@@ -57,7 +57,6 @@ export type SignetResource = z.infer<typeof signetResourceSchema>;
 
 export const signetEnrollmentSchema = z.strictObject({
   signetId: z.uuid(),
-  runtimeInstallationId: z.uuid().optional(),
   expectedRevision: z.number().int().min(1),
   name: z.string().trim().min(1).max(120),
   publicKey: publicClientKeySchema,
@@ -169,6 +168,8 @@ export const installationSignetsResponseSchema = z.object({
       signetId: z.uuid(),
       integrationId: z.uuid(),
       name: z.string(),
+      /** The enrollment that is current for this installation's key, if any. */
+      enrollmentId: z.uuid().nullable(),
       owner: ownerRefSchema,
     }),
   ),
@@ -230,3 +231,15 @@ 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';
+/** An installation hands Kingdom the credential Kingdom uses to reach it (a Foundry's tunnel token). */
+export const setInstallationCredentialSchema = z.strictObject({
+  integrationId: z.uuid(),
+  token: z.string().min(16).max(4096),
+});
+export const setInstallationCredentialResponseSchema = z.object({ credentialId: z.uuid() });

package/src/index.ts

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

package/src/installationPairing.ts

@@ -0,0 +1,201 @@
+import { existsSync } from 'node:fs';
+import { mkdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  collectSignet,
+  enrollInstallationSignet,
+  generateSignetKey,
+  installationInquiries,
+  kingdomUrl,
+  registerInstallation,
+  requestRegistration,
+  saveCollectedSignet,
+  signetCredentialSchema,
+} from './client';
+import type { InstallationKind, OwnerRef, RegistrationTerms } from './contracts';
+import { readPrivateJson, writePrivateJson } from './files';
+import { type InstallationSnapshot, InstallationSocket } from './installationSocket';
+
+/** Where an installation keeps what it holds for one Kingdom: its key and one file per Signet. */
+export async function installationDirectory(root: string, url: string) {
+  const directory = join(root, new URL(kingdomUrl(url)).host);
+  const keyFile = join(directory, 'installation-key.json');
+  if (!existsSync(keyFile)) await writePrivateJson(keyFile, generateSignetKey());
+  return { directory, keyFile };
+}
+
+export const signetCredentialFile = (directory: string, signetId: string) =>
+  join(directory, `signet-${signetId}.json`);
+
+export type HeldSignet = {
+  signetId: string;
+  integrationId: string;
+  owner: OwnerRef;
+  credentialFile: string;
+};
+
+const heldEnrollment = async (credentialFile: string) => {
+  if (!existsSync(credentialFile)) return null;
+  const parsed = signetCredentialSchema.safeParse(
+    await readPrivateJson(credentialFile).catch(() => null),
+  );
+  return parsed.success ? parsed.data.enrollmentId : null;
+};
+
+const lockStaleMs = 60_000;
+
+/** One holder at a time per directory, so two processes never enroll over each other. */
+async function withHoldLock<T>(directory: string, fn: () => Promise<T>): Promise<T> {
+  const lock = join(directory, '.hold-lock');
+  for (const started = Date.now(); ; ) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch {
+      const age = await stat(lock).then(
+        (info) => Date.now() - info.mtimeMs,
+        () => 0,
+      );
+      if (age > lockStaleMs) await rm(lock, { recursive: true, force: true });
+      else if (Date.now() - started > lockStaleMs) throw Error('Signet holder lock busy');
+      else await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await rm(lock, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Keeps a credential file for every Signet a snapshot lists: enrolls this installation's key when
+ * Kingdom reports no current enrollment for it, or when the file holds an enrollment Kingdom no
+ * longer reports as current (a key rotation, a revoked or expired enrollment). Files are never
+ * deleted here: a Signet missing from a snapshot (a paused integration) keeps its file.
+ */
+export async function holdInstallationSignets(
+  url: string,
+  keyFile: string,
+  directory: string,
+  signets: InstallationSnapshot['signets'],
+): Promise<HeldSignet[]> {
+  return withHoldLock(directory, async () => {
+    const held: HeldSignet[] = [];
+    for (const signet of signets) {
+      const credentialFile = signetCredentialFile(directory, signet.signetId);
+      const enrollmentId = await heldEnrollment(credentialFile);
+      if (!enrollmentId || !signet.enrollmentId || enrollmentId !== signet.enrollmentId)
+        await saveCollectedSignet(
+          credentialFile,
+          url,
+          keyFile,
+          await enrollInstallationSignet(url, keyFile, signet.signetId),
+        );
+      held.push({
+        signetId: signet.signetId,
+        integrationId: signet.integrationId,
+        owner: signet.owner,
+        credentialFile,
+      });
+    }
+    return held;
+  });
+}
+
+export type InstallationPairing = {
+  url: string;
+  root: string;
+  kind: InstallationKind;
+  name: string;
+  sourceId?: string;
+  terms: RegistrationTerms;
+  onReview: (review: { reviewCode: string; review: string; expiresAt: string }) => void;
+  confirmOwner?: (owner: { ownerName: string | null; owner: OwnerRef | null }) => Promise<boolean>;
+  /** Failures while waiting (a poll Kingdom refused, a dropped socket); waiting continues. */
+  onError?: (error: unknown) => void;
+  signal?: AbortSignal;
+  socketOptions?: { pollMs?: number; retryBaseMs?: number; authTimeoutMs?: number };
+};
+
+/**
+ * Registers this installation with Kingdom and asks to become an owner's integration. A person
+ * claims the review code in Kingdom; the installation hears the outcome over its socket (polling
+ * while the socket is down), confirms the owner, and collects its Signet.
+ */
+export async function pairInstallation(input: InstallationPairing) {
+  const url = kingdomUrl(input.url);
+  const { directory, keyFile } = await installationDirectory(input.root, url);
+  await registerInstallation(url, keyFile, {
+    kind: input.kind,
+    name: input.name,
+    ...(input.sourceId ? { sourceId: input.sourceId } : {}),
+  });
+  input.signal?.throwIfAborted();
+  const baseline = await installationInquiries(url, keyFile);
+  const earlier = new Set(baseline.inquiries.map((inquiry) => inquiry.id));
+  const pending = await requestRegistration(url, keyFile, input.terms);
+  input.onReview({
+    reviewCode: pending.reviewCode,
+    review: `${url}/dashboard?reviewSignet=${pending.reviewCode}`,
+    expiresAt: pending.expiresAt,
+  });
+  const inquiry = await new Promise<InstallationSnapshot['inquiries'][number]>(
+    (resolve, reject) => {
+      const socket = new InstallationSocket({
+        url,
+        keyFile,
+        ...input.socketOptions,
+        onError: input.onError,
+        onSnapshot: (snapshot) => {
+          const settled = settledInquiry(snapshot, earlier, baseline.declinedAt);
+          if (!settled) return;
+          socket.close();
+          if (settled instanceof Error) reject(settled);
+          else resolve(settled);
+        },
+        onRevoked: () => reject(Error('Kingdom revoked this installation')),
+      });
+      if (input.signal?.aborted) return reject(input.signal.reason);
+      input.signal?.addEventListener('abort', () => {
+        socket.close();
+        reject(input.signal!.reason);
+      });
+      socket.start();
+    },
+  );
+  if (input.confirmOwner && !(await input.confirmOwner(inquiry)))
+    throw Error('Not collected: the owner was not confirmed');
+  const collected = await collectSignet(url, keyFile, inquiry.id);
+  if (!collected) throw Error('Kingdom has not released the Signet yet; try again');
+  const credentialFile = signetCredentialFile(directory, collected.signetId);
+  await saveCollectedSignet(credentialFile, url, keyFile, collected);
+  return {
+    url,
+    keyFile,
+    directory,
+    credentialFile,
+    signetId: collected.signetId,
+    integrationId: collected.integrationId,
+    owner: collected.owner,
+    ownerName: inquiry.ownerName,
+  };
+}
+
+const settledInquiry = (
+  snapshot: InstallationSnapshot,
+  earlier: Set<string>,
+  earlierDeclinedAt: string | null,
+) => {
+  if (snapshot.declinedAt && snapshot.declinedAt !== earlierDeclinedAt)
+    return Error('The registration was declined in Kingdom');
+  const inquiry = snapshot.inquiries.find(
+    (item) => item.type === 'registerIntegration' && !earlier.has(item.id),
+  );
+  if (inquiry?.status === 'approved') return inquiry;
+  if (inquiry && inquiry.status !== 'sent')
+    return Error(`The registration was ${inquiry.status} in Kingdom`);
+  if (!inquiry && !snapshot.pending)
+    return Error('The review code expired before it was claimed; pair again');
+  return null;
+};

package/src/installationSocket.ts

@@ -0,0 +1,204 @@
+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;
+  /** A Kingdom that never answers the proof (one without Installation sockets) is treated as down. */
+  authTimeoutMs?: 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 authTimer: 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.authTimer = setTimeout(() => socket.close(), this.options.authTimeoutMs ?? 10_000);
+          this.sendOn(socket, {
+            action: 'authenticateInstallation',
+            proof: await signetProof(
+              this.options.url,
+              installationSocketAction,
+              this.options.keyFile,
+            ),
+          });
+          return;
+        case 'installation':
+          if (this.authTimer) clearTimeout(this.authTimer);
+          this.authTimer = null;
+          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.authTimer) clearTimeout(this.authTimer);
+    this.authTimer = null;
+    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.authTimer) clearTimeout(this.authTimer);
+    this.authTimer = null;
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.pingTimer = null;
+    this.retryTimer = null;
+  }
+}