@inixiative/signet 0.1.0 → 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.1.0",
+  "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.49",
+    "@inixiative/config": "^0.5.58",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/client.ts

@@ -6,18 +6,22 @@ import {
   accessResultSchema,
   accessTokenPattern,
   collectedSignetSchema,
-  type IntegrationPairingProposal,
+  type InstallationKind,
+  installationInquiriesResponseSchema,
+  installationSignetsResponseSchema,
   nonceSchema,
   ownerRefSchema,
   publicClientKeySchema,
+  type RegistrationTerms,
+  registerInstallationResponseSchema,
   renewalCredentialPattern,
+  requestRegistrationResponseSchema,
   signetDescriptionSchema,
   signetKeySchema,
   signetLifecycleSchema,
-  signetRequestResponseSchema,
 } from './contracts';
 import { readPrivateJson, writePrivateJson } from './files';
-import { createSignetProof } from './proof';
+import { createSignetProof, keyThumbprint } from './proof';
 
 /** A Kingdom API origin: HTTPS, or HTTP on loopback, with no path or credentials. */
 export const kingdomUrl = (value: string) => {
@@ -201,48 +205,109 @@ export async function signetProof(
   });
 }
 
-export type PairingTerms = Omit<IntegrationPairingProposal, 'lifecycle' | 'taskId'>;
-
-/** Ask Kingdom to pair this device as an integration; the owner approves the review code. */
-export async function requestPairing(
+/** A call an Installation makes as itself: no access token, a DPoP proof by its key. */
+async function installationPost<T>(
   url: string,
   keyFile: string,
-  terms: PairingTerms,
+  action: string,
+  body: unknown,
+  schema: z.ZodType<T>,
   options: SignetRequestOptions = {},
-) {
-  const publicKey = signetPublicKey(await readPrivateJson(keyFile));
-  return signetRequestResponseSchema.parse(
+): Promise<T> {
+  return schema.parse(
     await signetPost(
       url,
-      'requestSignet',
-      { ...terms, lifecycle: 'ongoing', publicKey },
-      { DPoP: await signetProof(url, 'requestSignet', keyFile, undefined, options) },
+      action,
+      body,
+      { DPoP: await signetProof(url, action, keyFile, undefined, options) },
       undefined,
       options,
     ),
   );
 }
 
+/** Make this installation known to Kingdom. Idempotent for the same key. */
+export const registerInstallation = (
+  url: string,
+  keyFile: string,
+  installation: { kind: InstallationKind; name: string; sourceId?: string },
+  options: SignetRequestOptions = {},
+) =>
+  readPrivateJson(keyFile).then((key) =>
+    installationPost(
+      url,
+      keyFile,
+      'registerInstallation',
+      { ...installation, publicKey: signetPublicKey(key) },
+      registerInstallationResponseSchema,
+      options,
+    ),
+  );
+
+/** Ask to be registered as an integration; a person claims the review code in Kingdom. */
+export const requestRegistration = (
+  url: string,
+  keyFile: string,
+  terms: RegistrationTerms,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'requestRegistration',
+    { terms },
+    requestRegistrationResponseSchema,
+    options,
+  );
+
+/** This installation's pending request and its inquiries. */
+export const installationInquiries = (
+  url: string,
+  keyFile: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'installationInquiries',
+    {},
+    installationInquiriesResponseSchema,
+    options,
+  );
+
+export const cancelInstallationInquiry = (
+  url: string,
+  keyFile: string,
+  inquiryId: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'cancelInstallationInquiry',
+    { inquiryId },
+    z.object({ id: z.uuid() }),
+    options,
+  );
+
 /**
- * Collect an approved pairing. Returns null while it awaits review (Kingdom answers 409; stop
- * polling at the request's expiresAt) and throws once it is denied (403).
+ * Collect the Signet an approved inquiry minted. Returns null while it awaits review (Kingdom
+ * answers 409) and throws once it is declined, denied or past its delivery deadline (403).
  */
-export async function collectPairing(
+export async function collectSignet(
   url: string,
   keyFile: string,
-  deviceCode: string,
+  inquiryId: string,
   options: SignetRequestOptions = {},
 ) {
   try {
-    return collectedSignetSchema.parse(
-      await signetPost(
-        url,
-        'collectSignet',
-        { deviceCode },
-        { DPoP: await signetProof(url, 'collectSignet', keyFile, undefined, options) },
-        undefined,
-        options,
-      ),
+    return await installationPost(
+      url,
+      keyFile,
+      'collectSignet',
+      { inquiryId },
+      collectedSignetSchema,
+      options,
     );
   } catch (error) {
     if (error instanceof SignetHttpError && error.status === 409) return null;
@@ -250,7 +315,64 @@ export async function collectPairing(
   }
 }
 
-/** Write a collected pairing next to its key; the file is what a SignetClient presents. */
+/** The Signets held by this installation's integrations. */
+export const installationSignets = (
+  url: string,
+  keyFile: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'installationSignets',
+    {},
+    installationSignetsResponseSchema,
+    options,
+  );
+
+/** Enroll this installation's key on a Signet one of its integrations holds. */
+export const enrollInstallationSignet = (
+  url: string,
+  keyFile: string,
+  signetId: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'enrollInstallationSignet',
+    { signetId },
+    collectedSignetSchema,
+    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,
+  keyFile: string,
+  newKeyFile: string,
+  options: SignetRequestOptions = {},
+) {
+  const publicKey = signetPublicKey(await readPrivateJson(newKeyFile));
+  const currentThumbprint = await keyThumbprint(signetPublicKey(await readPrivateJson(keyFile)));
+  const proof = await signetProof(
+    url,
+    'rotateInstallationKey',
+    newKeyFile,
+    currentThumbprint,
+    options,
+  );
+  return installationPost(
+    url,
+    keyFile,
+    'rotateInstallationKey',
+    { publicKey, proof },
+    registerInstallationResponseSchema,
+    options,
+  );
+}
+
+/** Write a collected Signet next to its key; the file is what a SignetClient presents. */
 export async function saveCollectedSignet(
   credentialFile: string,
   url: string,

package/src/contracts.ts

@@ -5,7 +5,6 @@ const token43 = /^[A-Za-z0-9_-]{43}$/;
 export const accessTokenPattern = /^kingdom_[A-Za-z0-9_-]{43}$/;
 export const renewalCredentialPattern = /^signet_renew_[A-Za-z0-9_-]{43}$/;
 export const nonceSchema = z.string().regex(token43);
-export const deviceCodeSchema = z.string().regex(token43);
 
 export const archiveDocumentIdSchema = z.string().regex(/^[a-f0-9]{64}$/);
 export const archiveFieldSchema = z.enum(['id', 'title', 'content', 'tags', 'createdAt']);
@@ -94,58 +93,93 @@ const signetTerms = {
   maxRequests: z.number().int().min(1).max(100000).nullable(),
   maxConcurrent: z.number().int().min(1).max(20),
 };
-/** Kinds of integration a device can pair as; approval creates one and issues it a Signet. */
-export const pairableProviderSchema = z.enum(['foundry', 'archive']);
-export type PairableProvider = z.infer<typeof pairableProviderSchema>;
+/** A local Foundry, Archive or Oracle known to Kingdom by its key. */
+export const installationKindSchema = z.enum(['foundry', 'archive', 'oracle']);
+export type InstallationKind = z.infer<typeof installationKindSchema>;
 export const signetProposalSchema = z.strictObject({
   ...signetTerms,
   integrationId: z.uuid(),
   resources: z.array(signetResourceSchema).min(1).max(100),
 });
-/** A local Archive names its sourceId; Kingdom binds every write through its Signets to it. */
-const deviceIdentity = (value: { provider?: PairableProvider; deviceId?: string }) =>
-  value.provider !== 'archive' || z.uuid().safeParse(value.deviceId).success;
-const deviceIdentityMessage = { message: 'A local Archive pairs with its sourceId as deviceId' };
-export const integrationPairingProposalSchema = z
-  .strictObject({
-    ...signetTerms,
-    provider: pairableProviderSchema,
-    deviceId: z.string().min(1).max(256).optional(),
-    resources: z.array(signetResourceSchema).max(100),
-    lifecycle: z.literal('ongoing'),
-  })
-  .refine(deviceIdentity, deviceIdentityMessage);
-export const signetRequestSchema = z
-  .strictObject({
-    ...signetTerms,
-    integrationId: z.uuid().optional(),
-    provider: pairableProviderSchema.optional(),
-    deviceId: z.string().min(1).max(256).optional(),
-    resources: z.array(signetResourceSchema).max(100),
-    publicKey: publicClientKeySchema,
-  })
-  .refine((value) => Boolean(value.integrationId) !== Boolean(value.provider), {
-    message: 'Name the host integration, or the kind of integration to pair',
-  })
-  .refine((value) => Boolean(value.provider) || !value.deviceId, {
-    message: 'Only integration pairing names a device',
-  })
-  .refine(deviceIdentity, deviceIdentityMessage);
+export const signetReviewProposalSchema = z.strictObject({
+  ...signetTerms,
+  resources: z.array(signetResourceSchema).max(100),
+});
+/** What an Installation asks for when it asks to be registered as an owner's integration. */
+export const registrationTermsSchema = z.strictObject({
+  ...signetTerms,
+  lifecycle: z.literal('ongoing'),
+  resources: z.array(signetResourceSchema).max(100),
+});
+/** A person asks for a Signet on an integration, to be presented with `publicKey`. */
+export const signetRequestSchema = z.strictObject({
+  ...signetTerms,
+  integrationId: z.uuid(),
+  resources: z.array(signetResourceSchema).min(1).max(100),
+  publicKey: publicClientKeySchema,
+});
 export const signetRequestResponseSchema = z.object({
   requestId: z.uuid(),
   reviewCode: z.string(),
-  deviceCode: deviceCodeSchema,
   expiresAt: z.iso.datetime(),
 });
-export const signetReviewProposalSchema = z.strictObject({
-  ...signetTerms,
-  resources: z.array(signetResourceSchema).max(100),
-});
 export type SignetProposal = z.infer<typeof signetProposalSchema>;
-export type IntegrationPairingProposal = z.infer<typeof integrationPairingProposalSchema>;
+export type RegistrationTerms = z.infer<typeof registrationTermsSchema>;
 export type SignetRequest = z.infer<typeof signetRequestSchema>;
 export type SignetRequestResponse = z.infer<typeof signetRequestResponseSchema>;
 
+/** A local Archive names its sourceId; Kingdom binds every write through its Signets to it. */
+export const registerInstallationSchema = z
+  .strictObject({
+    kind: installationKindSchema,
+    name: z.string().trim().min(1).max(120),
+    sourceId: z.uuid().optional(),
+    publicKey: publicClientKeySchema,
+  })
+  .refine((value) => value.kind !== 'archive' || Boolean(value.sourceId), {
+    message: 'A local Archive registers with its sourceId',
+  });
+export const registerInstallationResponseSchema = z.object({ installationId: z.uuid() });
+export const requestRegistrationSchema = z.strictObject({ terms: registrationTermsSchema });
+export const requestRegistrationResponseSchema = z.object({
+  reviewCode: z.string(),
+  expiresAt: z.iso.datetime(),
+});
+export const installationInquirySchema = z.object({
+  id: z.uuid(),
+  type: z.string(),
+  status: z.enum(['draft', 'sent', 'changesRequested', 'approved', 'denied', 'canceled']),
+  createdAt: z.iso.datetime(),
+  expiresAt: z.iso.datetime().nullable(),
+  owner: ownerRefSchema.nullable(),
+  ownerName: z.string().nullable(),
+  integrationId: z.uuid().nullable(),
+  signetId: z.uuid().nullable(),
+  deliverBefore: z.iso.datetime().nullable(),
+});
+export const installationInquiriesResponseSchema = z.object({
+  pending: z.object({ reviewCode: z.string(), expiresAt: z.iso.datetime() }).nullable(),
+  declinedAt: z.iso.datetime().nullable(),
+  inquiries: z.array(installationInquirySchema),
+});
+export const inquiryReferenceSchema = z.strictObject({ inquiryId: z.uuid() });
+export const installationSignetsResponseSchema = z.object({
+  signets: z.array(
+    z.object({
+      signetId: z.uuid(),
+      integrationId: z.uuid(),
+      name: z.string(),
+      owner: ownerRefSchema,
+    }),
+  ),
+});
+export const enrollInstallationSignetSchema = z.strictObject({ signetId: z.uuid() });
+export const rotateInstallationKeySchema = z.strictObject({
+  publicKey: publicClientKeySchema,
+  proof: z.string().max(8192),
+});
+export type InstallationInquiry = z.infer<typeof installationInquirySchema>;
+
 export const signetDescriptionSchema = z.object({
   signetId: z.uuid(),
   integrationId: z.uuid(),
@@ -196,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;
+  }
+}