@inixiative/signet 0.2.2 → 0.3.0

package/README.md

@@ -11,33 +11,27 @@ This package is the one implementation of that protocol, shared by Kingdom (whic
 - `files`: private 0600 JSON files for keys and credentials.
 - `client`:
   - 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 `describe` / `execute` call.
+  - `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 {
-  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,
+import { holdInstallationSignets, InstallationSocket, pairInstallation, SignetClient } from '@inixiative/signet';
+
+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 reviewCode; someone claims it in Kingdom. The socket tells you when the inquiry resolves.
-const socket = new InstallationSocket({
+
+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);
-  },
-});
-socket.start();
+  keyFile: paired.keyFile,
+  onSnapshot: ({ signets }) => holdInstallationSignets(kingdom, paired.keyFile, paired.directory, signets),
+}).start();
 
-const signet = new SignetClient(kingdom, credentialFile, signetId);
+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.2",
+  "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.58",
+    "@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,
     }),
   ),
@@ -236,3 +237,9 @@ export const installationSnapshotSchema = installationInquiriesResponseSchema.ex
 );
 /** 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,5 +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

@@ -19,6 +19,8 @@ export type InstallationSocketOptions = {
   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;
 };
 
@@ -36,6 +38,7 @@ export class InstallationSocket {
   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;
@@ -97,7 +100,8 @@ export class InstallationSocket {
     try {
       switch (frame.type) {
         case 'connected':
-          this.send({
+          this.authTimer = setTimeout(() => socket.close(), this.options.authTimeoutMs ?? 10_000);
+          this.sendOn(socket, {
             action: 'authenticateInstallation',
             proof: await signetProof(
               this.options.url,
@@ -107,6 +111,8 @@ export class InstallationSocket {
           });
           return;
         case 'installation':
+          if (this.authTimer) clearTimeout(this.authTimer);
+          this.authTimer = null;
           this.authenticated = true;
           this.attempts = 0;
           this.stopPolling();
@@ -152,6 +158,8 @@ export class InstallationSocket {
     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;
@@ -186,6 +194,8 @@ export class InstallationSocket {
 
   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;