@inixiative/signet 0.4.3 → 0.5.0

package/src/installationPairing.ts

@@ -9,12 +9,18 @@ import {
   kingdomUrl,
   registerInstallation,
   requestRegistration,
+  SignetHttpError,
   saveCollectedSignet,
   signetCredentialSchema,
 } from './client';
-import type { InstallationKind, OwnerRef, RegistrationRequest } from './contracts';
+import type {
+  InstallationKind,
+  InstallationSnapshot,
+  OwnerRef,
+  RegistrationRequest,
+} from './contracts';
 import { readPrivateJson, writePrivateJson } from './files';
-import { type InstallationSnapshot, InstallationSocket } from './installationSocket';
+import { 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) {
@@ -78,7 +84,10 @@ export async function holdInstallationSignets(
   url: string,
   keyFile: string,
   directory: string,
-  signets: InstallationSnapshot['signets'],
+  signets: Pick<
+    InstallationSnapshot['signets'][number],
+    'signetId' | 'integrationId' | 'owner' | 'enrollmentId'
+  >[],
 ): Promise<HeldSignet[]> {
   return withHoldLock(directory, async () => {
     const held: HeldSignet[] = [];
@@ -112,7 +121,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 +149,106 @@ 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 unread = snapshot.dropped.filter((drop) => drop.list === 'inquiries');
+        if (unread.length)
+          input.onError?.(Error(`Could not read ${unread.length} inquiries from Kingdom`));
+        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 +270,43 @@ 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' | 'dropped'>;
+
+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');
+  // An inquiry this package couldn't read is not a withdrawn or expired one: keep waiting.
+  if (!inquiry && snapshot.dropped.some((drop) => drop.list === 'inquiries')) return null;
+  // 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;
 };