@inixiative/signet 0.4.2 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.4.2",
+  "version": "0.4.6",
   "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.90",
+    "@inixiative/config": "^0.5.105",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/client.ts

@@ -126,7 +126,8 @@ const errorDetail = async (response: Response) => {
   try {
     const body = JSON.parse(text) as { message?: unknown; error?: unknown };
     const error = body.error as { message?: unknown } | string | undefined;
-    const message = typeof error === 'string' ? error : (error?.message ?? body.message);
+    const errorMessage = typeof error === 'string' ? error : error?.message;
+    const message = typeof body.message === 'string' ? body.message : errorMessage;
     if (typeof message === 'string') return message.slice(0, 500);
   } catch {}
   return text.replace(/\s+/g, ' ').slice(0, 500) || undefined;

package/src/contracts.ts

@@ -164,9 +164,13 @@ export const registerInstallationSchema = z
   });
 export const registerInstallationResponseSchema = z.object({ installationId: z.uuid() });
 export const requestRegistrationSchema = z.strictObject({ terms: registrationRequestSchema });
+/** A link into Kingdom's web app that callers open, so http(s) only. */
+const kingdomLinkSchema = z.url({ protocol: /^https?$/ });
 export const requestRegistrationResponseSchema = z.object({
   reviewCode: z.string(),
   expiresAt: z.iso.datetime(),
+  /** Where a person reviews the registration in Kingdom's web app. */
+  reviewUrl: kingdomLinkSchema,
 });
 export const installationInquirySchema = z.object({
   id: z.uuid(),
@@ -227,6 +231,30 @@ export const signetDescriptionSchema = z.object({
 });
 export type SignetDescription = z.infer<typeof signetDescriptionSchema>;
 
+const holderPersonSchema = z.object({
+  id: z.uuid(),
+  name: z.string().nullable(),
+  email: z.string(),
+});
+/**
+ * `access/describe`'s `holder` for an Integration-held Signet (an Installation such as a Foundry):
+ * the integration, its owner, who issued the Signet, and where to manage it in Kingdom.
+ */
+export const signetHolderSchema = z.object({
+  integration: z.object({ id: z.uuid(), name: z.string(), provider: z.string().nullable() }),
+  owner: z.object({
+    ownerModel: ownerModelSchema,
+    name: z.string().nullable(),
+    organization: z.object({ id: z.uuid(), name: z.string(), slug: z.string() }).nullable(),
+    space: z.object({ id: z.uuid(), name: z.string() }).nullable(),
+    user: holderPersonSchema.nullable(),
+  }),
+  issuedBy: holderPersonSchema.nullable(),
+  webUrl: kingdomLinkSchema,
+  manageUrl: kingdomLinkSchema,
+});
+export type SignetHolder = z.infer<typeof signetHolderSchema>;
+
 /** Operation-specific fields; Kingdom validates each against the operation it names. */
 export const accessInputSchema = z.strictObject({
   resourceId: z.uuid(),

package/src/installationPairing.ts

@@ -9,6 +9,7 @@ import {
   kingdomUrl,
   registerInstallation,
   requestRegistration,
+  SignetHttpError,
   saveCollectedSignet,
   signetCredentialSchema,
 } from './client';
@@ -112,7 +113,10 @@ export type InstallationPairing = {
   terms: RegistrationRequest;
   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. */
+  /**
+   * Failures while waiting (a poll Kingdom refused, a dropped socket); waiting continues, except
+   * at the deadline, where repeated failures end it.
+   */
   onError?: (error: unknown) => void;
   signal?: AbortSignal;
   socketOptions?: { pollMs?: number; retryBaseMs?: number; authTimeoutMs?: number };
@@ -137,30 +141,103 @@ export async function pairInstallation(input: InstallationPairing) {
   const pending = await requestRegistration(url, keyFile, input.terms);
   input.onReview({
     reviewCode: pending.reviewCode,
-    review: `${url}/dashboard?reviewSignet=${pending.reviewCode}`,
+    review: pending.reviewUrl,
     expiresAt: pending.expiresAt,
   });
+  const retryBaseMs = input.socketOptions?.retryBaseMs ?? 1_000;
   const inquiry = await new Promise<InstallationSnapshot['inquiries'][number]>(
     (resolve, reject) => {
+      let deadline: ReturnType<typeof setTimeout> | undefined;
+      let retry: ReturnType<typeof setTimeout> | undefined;
+      let done = false;
+      let claimed = false;
+      // Refusals that count toward revocation, each at least a backoff step after the last.
+      const refusals: number[] = [];
+      // The review code's expiry until a claim creates the inquiry; then the inquiry's own.
+      let waitUntil: string | null = pending.expiresAt;
+      const onAbort = () => {
+        stop();
+        reject(input.signal?.reason);
+      };
+      const stop = () => {
+        done = true;
+        clearTimeout(deadline);
+        clearTimeout(retry);
+        input.signal?.removeEventListener('abort', onAbort);
+        socket.close();
+      };
+      const finish = (settled: ReturnType<typeof settledInquiry>) => {
+        if (!settled || done) return;
+        stop();
+        if (settled instanceof Error) reject(settled);
+        else resolve(settled);
+      };
+      const arm = (until: string | null) => {
+        clearTimeout(deadline);
+        waitUntil = until;
+        if (!until || done) return;
+        const delay = Math.max(0, Date.parse(until) + expiryGraceMs - Date.now());
+        deadline =
+          delay > maxTimerMs
+            ? setTimeout(() => arm(until), maxTimerMs)
+            : setTimeout(() => void check(until), delay);
+      };
+      const follow = (snapshot: Snapshot) => {
+        refusals.length = 0;
+        const settled = settledInquiry(snapshot, earlier, baseline.declinedAt, claimed);
+        if (settled) return finish(settled);
+        const inquiry = newInquiry(snapshot, earlier);
+        if (!inquiry) return;
+        claimed = true;
+        if (inquiry.expiresAt !== waitUntil) arm(inquiry.expiresAt);
+      };
+      // Kingdom refuses a revoked installation's key (the revoke frame only reaches a live socket),
+      // but a 401 can also be a passing failure; only a refusal that persists ends the wait.
+      const refused = (error: unknown) => {
+        const refusal =
+          error instanceof SignetHttpError && (error.status === 401 || error.status === 403);
+        const last = refusals.at(-1);
+        if (
+          refusal &&
+          (last === undefined || Date.now() - last >= retryBaseMs * 2 ** refusals.length)
+        )
+          refusals.push(Date.now());
+        if (refusal && refusals.length >= refusalsToRevoke) return finish(revoked());
+        input.onError?.(error);
+      };
+      const check = async (until: string) => {
+        let last: Snapshot | null = null;
+        for (let attempt = 0; !last && attempt < 3; attempt++) {
+          if (attempt)
+            await new Promise((wake) => {
+              retry = setTimeout(wake, retryBaseMs * 2 ** attempt);
+            });
+          if (done) return;
+          last = await installationInquiries(url, keyFile).catch((error) => {
+            refused(error);
+            return null;
+          });
+        }
+        if (done || waitUntil !== until) return;
+        if (!last) return finish(unconfirmed());
+        follow(last);
+        if (done || waitUntil !== until) return;
+        finish(newInquiry(last, earlier) ? unapproved() : expired());
+      };
       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);
+        onError: refused,
+        onSnapshot: follow,
+        onRevoked: () => finish(revoked()),
       });
+      if (input.signal?.aborted) {
+        stop();
+        return reject(input.signal.reason);
+      }
+      input.signal?.addEventListener('abort', onAbort, { once: true });
+      arm(waitUntil);
       socket.start();
     },
   );
@@ -182,20 +259,41 @@ export async function pairInstallation(input: InstallationPairing) {
   };
 }
 
+/** setTimeout fires at once past this delay (~24.8 days). */
+const maxTimerMs = 2 ** 31 - 1;
+/** Slack past an expiry (clock skew, a claim in its last second) before giving up. */
+const expiryGraceMs = 5_000;
+/** Consecutive refusals of this installation's key, a backoff step apart, that mean revoked. */
+const refusalsToRevoke = 3;
+/** Kingdom can still approve these. */
+const openStatuses = new Set(['sent', 'changesRequested']);
+
+type Snapshot = Pick<InstallationSnapshot, 'pending' | 'declinedAt' | 'inquiries'>;
+
+const expired = () => Error('The review code expired before it was claimed; pair again');
+const revoked = () => Error('Kingdom revoked this installation');
+const withdrawn = () => Error('The registration was withdrawn in Kingdom');
+const unapproved = () => Error('The registration expired in Kingdom before it was approved');
+const unconfirmed = () =>
+  Error('Could not reach Kingdom to confirm the registration; check Kingdom before pairing again');
+
+const newInquiry = (snapshot: Snapshot, earlier: Set<string>) =>
+  snapshot.inquiries.find((item) => item.type === 'registerIntegration' && !earlier.has(item.id));
+
 const settledInquiry = (
-  snapshot: InstallationSnapshot,
+  snapshot: Snapshot,
   earlier: Set<string>,
   earlierDeclinedAt: string | null,
+  claimed: boolean,
 ) => {
   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),
-  );
+  const inquiry = newInquiry(snapshot, earlier);
   if (inquiry?.status === 'approved') return inquiry;
-  if (inquiry && inquiry.status !== 'sent')
+  if (inquiry && !openStatuses.has(inquiry.status))
     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');
+  // A canceled inquiry is soft-deleted, so it drops out of the snapshot.
+  if (!inquiry && claimed) return withdrawn();
+  if (!inquiry && !snapshot.pending) return expired();
   return null;
 };