@inixiative/archive 0.7.0 → 0.9.0

package/README.md

@@ -68,19 +68,35 @@ archive agents status
 
 ## Connect through Kingdom
 
-Pair a runtime with Kingdom (Foundry: Settings → Kingdom) and expose its `kingdom_runtime_` credential in an environment variable, then either let Kingdom store the archives:
+Kingdom is the permission hub. Your machine's Archive talks directly only to local pieces, such as your local Foundry. It reaches a hosted Archive through Kingdom, by presenting a Signet.
+
+First, pair this Archive with Kingdom:
 
 ```sh
-bun run archive connect --kind kingdom --url https://your-kingdom.example --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+bun run archive pair --kingdom https://api.your-kingdom.example --name "Work laptop"
 ```
 
-or forward them through Kingdom to a hosted Archive it has bound for that project:
+`pair` registers this Archive with Kingdom as an **Installation**, named by a key kept in `<home>/kingdom/<kingdom host>/`. The same key is reused for every owner it registers with. It then asks to be registered as an integration and prints a review code with a link.
+
+Open the link, choose the owner and the hosted Archives this machine may write to, and approve. The command waits for approval, then shows which owner it was registered with and asks you to accept. Pass `--yes` to accept without the prompt; without a terminal, `--yes` is required. Only then does it collect the Signet (0600) and list the libraries it may write to. Confirming the owner protects you if someone else claimed your code into their own owner.
+
+Next, route a project to one of those libraries:
 
 ```sh
-bun run archive connect --kind kingdom --url https://your-kingdom.example --connection-id inixiative --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+bun run archive connect --kind kingdom --url https://api.your-kingdom.example --credential-file ~/.archive/kingdom/signet-SIGNET.json --integration-id HOSTED_ARCHIVE_INTEGRATION --resource-id LIBRARY --project-id inixiative
 ```
 
-Kingdom takes the owner from the runtime credential; `--owner-model`, `--organization-id` and `--space-id` narrow it to an organization or space that owner manages. A forwarding connection accepts only its bound `projectId`, and the hosted Archive's own token stays in Kingdom's server environment. A Kingdom runtime credential is distinct from a standalone Archive token. Kingdom retains responsibility for memberships, shares, revocation and hosted browsing.
+`connect` checks that the Signet grants `sessions.write` on that library before it saves anything. `serve --sync` then sends each changed session through `POST /api/v1/access/execute`. Every call carries the Signet's access token and a fresh DPoP proof (`@inixiative/signet` renews the token).
+
+Kingdom enforces the grant on every write:
+
+- It accepts only snapshots whose `sourceId` is this Archive's.
+- It records the paired integration on the session's actor.
+- It resolves a revision conflict from this source by writing over the hosted head. Older captures are still refused.
+
+Each write is usage on the Signet. Revoke the Signet, or pause the local Archive integration in Kingdom, to stop it. `search --remote` uses `documents.search` when the Signet grants it.
+
+Kingdom keeps no archive store. It forwards each write to the hosted Archive server, whose own token stays in Kingdom as an encrypted credential.
 
 Foundry writes its captures to the local Archive server through `@inixiative/archive/remote`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/archive",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -32,9 +32,10 @@
     "check": "bun run typecheck && bun run lint && bun run test",
     "prepublishOnly": "bun run check",
     "lint": "biome check .",
-    "prepare": "lefthook install && prisma generate"
+    "prepare": "if git rev-parse --git-dir >/dev/null 2>&1; then lefthook install; fi && prisma generate"
   },
   "dependencies": {
+    "@inixiative/signet": "^0.2.1",
     "@prisma/client": "^6.6.0",
     "js-tiktoken": "1.0.21",
     "prisma": "^6.6.0",
@@ -42,7 +43,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.44",
+    "@inixiative/config": "^0.5.55",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
@@ -15,16 +16,11 @@ import {
   writeAgents,
 } from './agents';
 import { importChatGPTThread } from './chatgpt';
-import {
-  archiveRequest,
-  kingdomFields,
-  routingPreview,
-  searchRemotes,
-  syncArchives,
-} from './client';
+import { archiveRequest, routingPreview, searchRemotes, syncArchives } from './client';
 import { collectSessions } from './collector';
 import { archiveDestinationSchema, connectDestination, readDestinations } from './config';
 import { importTranscriptFile } from './import-file';
+import { pairWithKingdom, verifyKingdomDestination } from './kingdom';
 import { previewImports } from './preview';
 import { ArchiveClient, DEFAULT_URL } from './remote';
 import { startArchiveServer } from './server';
@@ -50,10 +46,10 @@ export async function runCli(args = Bun.argv.slice(2)) {
       url: { type: 'string' },
       kind: { type: 'string', default: 'archive' },
       'project-id': { type: 'string' },
-      'connection-id': { type: 'string' },
-      'owner-model': { type: 'string' },
-      'organization-id': { type: 'string' },
-      'space-id': { type: 'string' },
+      'integration-id': { type: 'string' },
+      'resource-id': { type: 'string' },
+      'credential-file': { type: 'string' },
+      kingdom: { type: 'string' },
       'token-env': { type: 'string' },
       'token-file': { type: 'string' },
       file: { type: 'string' },
@@ -75,6 +71,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
       watch: { type: 'boolean', default: false },
       sync: { type: 'boolean', default: false },
       remote: { type: 'boolean', default: false },
+      yes: { type: 'boolean', default: false },
       help: { type: 'boolean' },
     },
   });
@@ -91,7 +88,9 @@ export async function runCli(args = Bun.argv.slice(2)) {
         'import --file PATH --source codex|claude-code|chatgpt --project-id ID [--tag TAG]\n' +
         'collect --directory HISTORY --source codex|claude-code --project-root EXACT_CWD [--project-root ...] [--worktrees] [--atlas] --project-id ID [--watch]\n' +
         'list | export --id ID | tag --id ID [--tag TAG ...] [--untag TAG ...] | search --query TEXT [--remote]\n' +
-        'connect --url HTTPS_URL --project-id ID (--token-env ENV | --token-file PATH) [--kind kingdom ...]   (destinations for serve --sync)\n' +
+        'pair --kingdom KINGDOM_API_URL [--name NAME] [--yes]   (register this Archive with Kingdom; claim the review code there, then confirm the owner)\n' +
+        'connect --url HTTPS_URL --project-id ID (--token-env ENV | --token-file PATH)   (a remote Archive, for serve --sync)\n' +
+        'connect --kind kingdom --url KINGDOM_API_URL --credential-file PATH --integration-id UUID --resource-id UUID --project-id ID   (a hosted Archive through Kingdom)\n' +
         'sync | routes   (DATABASE_URL: publish to, or preview, destinations once)\n' +
         'agents add-collector --name N --source codex|claude-code --project-id ID --project-root DIR [--project-root ...] [--directory HISTORY] [--worktrees] [--atlas]\n' +
         'agents remove-collector --name N | server --url URL | install | uninstall | status\n' +
@@ -162,8 +161,8 @@ export async function runCli(args = Bun.argv.slice(2)) {
       while (v.sync && !stopped) {
         try {
           const results = await syncArchives(instance.store, readDestinations(config));
-          const failed = results.filter((r) => r.status.startsWith('failed')).length;
-          if (failed) console.error(JSON.stringify({ sync: 'failed', archives: failed }));
+          const failed = results.filter((r) => r.status.startsWith('failed'));
+          if (failed.length) console.error(JSON.stringify({ sync: 'failed', archives: failed }));
         } catch {
           console.error(JSON.stringify({ sync: 'unavailable' }));
         }
@@ -180,34 +179,61 @@ export async function runCli(args = Bun.argv.slice(2)) {
     process.once('SIGINT', stop);
     return;
   }
+  if (command === 'pair') {
+    if (!v.kingdom) throw new Error('pair requires --kingdom KINGDOM_API_URL');
+    const local = new ArchiveClient({
+      url: v.url ?? DEFAULT_URL,
+      token: process.env.ARCHIVE_TOKEN ?? readToken() ?? '',
+    });
+    output(
+      await pairWithKingdom({
+        kingdom: v.kingdom,
+        name: v.name ?? `${hostname()} Archive`,
+        sourceId: await local.sourceId(),
+        directory: join(home, 'kingdom'),
+        onReview: (review) => console.error(JSON.stringify(review)),
+        confirmOwner: async ({ ownerName }) => {
+          if (v.yes) return true;
+          if (!process.stdin.isTTY)
+            throw new Error(`Registered with ${ownerName}; rerun with --yes to accept it`);
+          const answer = prompt(`Kingdom registered this Archive with ${ownerName}. Accept? [y/N]`);
+          return /^y(es)?$/i.test(answer?.trim() ?? '');
+        },
+      }),
+    );
+    return;
+  }
   if (command === 'connect' || command === 'setup') {
-    const destinationTokenFile = v['token-file'] && resolve(v['token-file']);
-    const destination = archiveDestinationSchema.parse({
-      projectId: v['project-id'],
-      url: v.url,
-      tokenEnv: v['token-env'] ?? (destinationTokenFile ? undefined : 'ARCHIVE_TOKEN'),
-      tokenFile: destinationTokenFile,
-      kind: v.kind,
-      ...(v.kind === 'kingdom'
+    const destination = archiveDestinationSchema.parse(
+      v.kind === 'kingdom'
         ? {
-            connectionId: v['connection-id'],
-            ownerModel: v['owner-model'],
-            organizationId: v['organization-id'],
-            spaceId: v['space-id'],
+            kind: 'kingdom',
+            projectId: v['project-id'],
+            url: v.url,
+            credentialFile: v['credential-file'] && resolve(v['credential-file']),
+            integrationId: v['integration-id'],
+            resourceId: v['resource-id'],
           }
-        : {}),
-    });
+        : {
+            kind: 'archive',
+            projectId: v['project-id'],
+            url: v.url,
+            tokenEnv: v['token-env'] ?? (v['token-file'] ? undefined : 'ARCHIVE_TOKEN'),
+            tokenFile: v['token-file'] && resolve(v['token-file']),
+          },
+    );
     // Verify credentials and protocol before saving; no records uploaded by setup.
-    const probe = await archiveRequest(destination, 'search', {
-      query: '',
-      budget: 16,
-      limit: 1,
-      ...(destination.kind === 'archive'
-        ? { projectId: destination.projectId }
-        : kingdomFields(destination)),
-    });
-    if (!Array.isArray(probe.data?.archives))
-      throw new Error('Destination is not an Archive-compatible endpoint');
+    if (destination.kind === 'kingdom') await verifyKingdomDestination(destination);
+    else {
+      const probe = await archiveRequest(destination, 'search', {
+        query: '',
+        budget: 16,
+        limit: 1,
+        projectId: destination.projectId,
+      });
+      if (!Array.isArray(probe.data?.archives))
+        throw new Error('Destination is not an Archive-compatible endpoint');
+    }
     output(connectDestination(config, destination));
     return;
   }

package/src/client.ts

@@ -1,3 +1,4 @@
+import { kingdomUrl, SignetClient } from '@inixiative/signet';
 import {
   type ArchiveDestination,
   archiveDestinationSchema,
@@ -9,33 +10,25 @@ import type { ArchiveStore } from './store';
 
 export { type ArchiveDestination, archiveDestinationSchema } from './config';
 
-/** Identifies the Kingdom owner and forwarding connection; standalone Archive needs neither. */
-export function kingdomFields(destination: ArchiveDestination) {
-  if (destination.kind === 'archive') return {};
-  const { ownerModel, organizationId, spaceId, connectionId } = destination;
-  return Object.fromEntries(
-    Object.entries({ ownerModel, organizationId, spaceId, connectionId }).filter(
-      ([, value]) => value !== undefined,
-    ),
-  );
-}
+type DirectDestination = Extract<ArchiveDestination, { kind: 'archive' }>;
+type KingdomDestination = Extract<ArchiveDestination, { kind: 'kingdom' }>;
+type Ingested = { id: string; digest: string; revision: number; changed: boolean };
+
+const sessionWriteTimeoutMs = 300_000;
 
 export async function archiveRequest(
-  destination: ArchiveDestination,
+  destination: DirectDestination,
   action: string,
   body: unknown,
   transport: typeof fetch = fetch,
 ) {
   const url = destinationUrl(destination.url);
   const token = destinationToken(destination);
-  if (!token || (destination.kind === 'kingdom' && !token.startsWith('kingdom_runtime_')))
-    throw new Error('Archive runtime credential unavailable');
-  const path =
-    destination.kind === 'kingdom' && destination.connectionId ? `remote/${action}` : action;
-  const response = await transport(new URL(`api/v1/archive/${path}`, url), {
+  if (!token) throw new Error('Archive server token unavailable');
+  const response = await transport(new URL(`api/v1/archive/${action}`, url), {
     method: 'POST',
     redirect: 'error',
-    signal: AbortSignal.timeout(30_000),
+    signal: AbortSignal.timeout(action === 'ingest' ? sessionWriteTimeoutMs : 30_000),
     headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
     body: JSON.stringify(body),
   });
@@ -44,6 +37,39 @@ export async function archiveRequest(
   return response.json() as Promise<{ data: any }>;
 }
 
+const kingdomSignet = async (destination: KingdomDestination) => {
+  const signet = await SignetClient.fromFile(destination.credentialFile);
+  if (signet.url !== kingdomUrl(destination.url))
+    throw new Error('The Signet credential belongs to a different Kingdom');
+  return signet;
+};
+
+/** Runs one Archive operation on the destination's library through the paired Signet. */
+export async function kingdomArchiveOperation(
+  destination: KingdomDestination,
+  operation: 'sessions.write' | 'documents.search',
+  input: Record<string, unknown>,
+) {
+  const { result } = await (await kingdomSignet(destination)).execute(
+    {
+      integrationId: destination.integrationId,
+      operation,
+      input: { resourceId: destination.resourceId, limit: 20, ...input },
+    },
+    { timeoutMs: operation === 'sessions.write' ? sessionWriteTimeoutMs : 30_000 },
+  );
+  return result;
+}
+
+const ingest = async (
+  destination: ArchiveDestination,
+  body: { snapshot: unknown; previousDigest: string | null },
+  transport: typeof fetch,
+) =>
+  (destination.kind === 'archive'
+    ? (await archiveRequest(destination, 'ingest', body, transport)).data
+    : await kingdomArchiveOperation(destination, 'sessions.write', body)) as Ingested | undefined;
+
 export async function publishArchive(
   store: ArchiveStore,
   id: string,
@@ -68,17 +94,12 @@ export async function publishArchive(
     const queued = await store.read(id, pending.revision);
     if (!queued || queued.snapshot.projectId !== destination.projectId)
       throw new Error('Pending archive is outside destination project');
-    const body = await archiveRequest(
+    const acknowledged = await ingest(
       destination,
-      'ingest',
-      {
-        ...kingdomFields(destination),
-        previousDigest,
-        snapshot: queued.snapshot,
-      },
+      { previousDigest, snapshot: queued.snapshot },
       transport,
     );
-    if (body.data?.digest !== queued.digest) throw new Error('Archive acknowledgement mismatch');
+    if (acknowledged?.digest !== queued.digest) throw new Error('Archive acknowledgement mismatch');
     await store.delivered(id, receiptKey, queued.digest);
     sent = true;
   }
@@ -96,7 +117,7 @@ export async function routingPreview(store: ArchiveStore, destinations: ArchiveD
       .map((d) => ({
         kind: d.kind,
         url: d.url,
-        ...kingdomFields(d),
+        ...(d.kind === 'kingdom' ? { integrationId: d.integrationId } : {}),
       })),
   }));
 }
@@ -112,11 +133,11 @@ export async function syncArchives(store: ArchiveStore, destinations: ArchiveDes
           destination: destination.url,
           status: result.unchanged ? 'unchanged' : 'published',
         });
-      } catch {
+      } catch (error) {
         results.push({
           id: archive.id,
           destination: destination.url,
-          status: 'failed; local revision retained',
+          status: `failed; local revision retained: ${error instanceof Error ? error.message : String(error)}`,
         });
       }
     }
@@ -131,17 +152,24 @@ export async function searchRemotes(
   return Promise.all(
     destinations.map(async (destination) => {
       try {
-        const result = await archiveRequest(destination, 'search', {
-          query,
-          budget,
-          ...(destination.kind === 'archive'
-            ? { projectId: destination.projectId }
-            : kingdomFields(destination)),
-        });
+        const data =
+          destination.kind === 'archive'
+            ? (
+                await archiveRequest(destination, 'search', {
+                  query,
+                  budget,
+                  projectId: destination.projectId,
+                })
+              ).data
+            : await kingdomArchiveOperation(destination, 'documents.search', {
+                query,
+                budget,
+                projectId: destination.projectId,
+              });
         return {
           destination: destination.url,
           projectId: destination.projectId,
-          data: result.data,
+          data,
         };
       } catch {
         return {

package/src/config.ts

@@ -14,43 +14,36 @@ import {
 import { dirname, isAbsolute } from 'node:path';
 import { z } from 'zod';
 
-const common = {
-  projectId: z.string().min(1).max(256),
-  url: z.url(),
-  tokenEnv: z
-    .string()
-    .regex(/^[A-Z][A-Z0-9_]+$/)
-    .optional(),
-  tokenFile: z.string().max(4096).refine(isAbsolute, 'tokenFile must be absolute').optional(),
-};
-/** Kingdom derives the owner from the runtime credential; these narrow it to a space or organization it manages. */
-export const kingdomOwnerFields = {
-  ownerModel: z.enum(['User', 'OrganizationUser', 'Organization', 'Space', 'SpaceUser']).optional(),
-  organizationId: z.uuid().optional(),
-  spaceId: z.uuid().optional(),
-};
-export const archiveDestinationSchema = z
-  .union([
-    z.strictObject({
-      ...common,
-      kind: z.literal('archive'),
-    }),
-    z.strictObject({
-      ...common,
-      kind: z.literal('kingdom'),
-      /** A hosted Archive that Kingdom forwards to; omitted, Kingdom stores the archive itself. */
-      connectionId: z
-        .string()
-        .regex(/^[a-z0-9-]+$/)
-        .max(120)
-        .optional(),
-      ...kingdomOwnerFields,
-    }),
-  ])
+const projectId = z.string().min(1).max(256);
+/** A remote Archive this one syncs to directly with its server token. */
+const archiveDestination = z
+  .strictObject({
+    kind: z.literal('archive'),
+    projectId,
+    url: z.url(),
+    tokenEnv: z
+      .string()
+      .regex(/^[A-Z][A-Z0-9_]+$/)
+      .optional(),
+    tokenFile: z.string().max(4096).refine(isAbsolute, 'tokenFile must be absolute').optional(),
+  })
   .refine(
     (d) => Boolean(d.tokenEnv) !== Boolean(d.tokenFile),
     'Set exactly one of tokenEnv or tokenFile',
   );
+/**
+ * A hosted Archive reached through Kingdom: this Archive presents the Signet it was paired with,
+ * granting sessions.write on that Archive's library.
+ */
+const kingdomDestination = z.strictObject({
+  kind: z.literal('kingdom'),
+  projectId,
+  url: z.url(),
+  credentialFile: z.string().max(4096).refine(isAbsolute, 'credentialFile must be absolute'),
+  integrationId: z.uuid(),
+  resourceId: z.uuid(),
+});
+export const archiveDestinationSchema = z.union([archiveDestination, kingdomDestination]);
 export type ArchiveDestination = z.infer<typeof archiveDestinationSchema>;
 
 /** Private regular file owned by this user; a symlink or group/world access is refused. */
@@ -65,7 +58,7 @@ export function readTokenFile(path: string) {
     closeSync(fd);
   }
 }
-export const destinationToken = (destination: ArchiveDestination) =>
+export const destinationToken = (destination: z.infer<typeof archiveDestination>) =>
   destination.tokenFile ? readTokenFile(destination.tokenFile) : process.env[destination.tokenEnv!];
 
 export function destinationUrl(input: string) {
@@ -93,18 +86,12 @@ export function readDestinations(file: string): ArchiveDestination[] {
 }
 export function destinationIdentity(destination: ArchiveDestination) {
   const url = destinationUrl(destination.url);
-  // Preserve existing Foundry/Kingdom upload receipt identities.
   return JSON.stringify([
     url.origin,
     new URL(destination.url).pathname,
     destination.kind === 'archive'
       ? 'standalone'
-      : [
-          destination.connectionId ?? 'kingdom',
-          destination.ownerModel ?? null,
-          destination.organizationId ?? null,
-          destination.spaceId ?? null,
-        ],
+      : ['kingdom', destination.integrationId, destination.resourceId],
   ]);
 }
 export function connectDestination(file: string, input: unknown) {
@@ -127,8 +114,10 @@ export function connectDestination(file: string, input: unknown) {
     kind: destination.kind,
     projectId: destination.projectId,
     url: destination.url,
-    ...(destination.tokenFile
-      ? { tokenFile: destination.tokenFile }
-      : { tokenEnv: destination.tokenEnv }),
+    ...(destination.kind === 'kingdom'
+      ? { integrationId: destination.integrationId, resourceId: destination.resourceId }
+      : destination.tokenFile
+        ? { tokenFile: destination.tokenFile }
+        : { tokenEnv: destination.tokenEnv }),
   };
 }

package/src/kingdom.ts

@@ -0,0 +1,121 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  collectSignet,
+  generateSignetKey,
+  installationInquiries,
+  kingdomUrl,
+  registerInstallation,
+  requestRegistration,
+  SignetClient,
+  saveCollectedSignet,
+  writePrivateJson,
+} from '@inixiative/signet';
+import type { ArchiveDestination } from './config';
+
+const pollMs = 3000;
+
+/** Libraries this Archive's Signet may write to, as Kingdom describes them. */
+export async function writableLibraries(credentialFile: string) {
+  const description = await (await SignetClient.fromFile(credentialFile)).describe();
+  return (
+    description.operations
+      .find((operation) => operation.key === 'sessions.write')
+      ?.resources.map((resource) => ({
+        integrationId: resource.integrationId,
+        resourceId: resource.id,
+        name: resource.name,
+      })) ?? []
+  );
+}
+
+type Pairing = {
+  kingdom: string;
+  name: string;
+  sourceId: string;
+  directory: string;
+  onReview: (review: { reviewCode: string; review: string; expiresAt: string }) => void;
+  confirmOwner: (owner: { ownerName: string | null; owner: unknown }) => Promise<boolean>;
+  sleep?: (ms: number) => Promise<unknown>;
+};
+
+/** The key that names this Archive to one Kingdom; reused for every owner it registers with. */
+async function installationKey(directory: string) {
+  const keyFile = join(directory, 'installation-key.json');
+  if (!existsSync(keyFile)) await writePrivateJson(keyFile, generateSignetKey());
+  return keyFile;
+}
+
+/**
+ * Registers this Archive with Kingdom as an Installation and asks to become an owner's local
+ * Archive integration. A person claims the review code in Kingdom; once approved, the Archive
+ * confirms the owner locally before collecting its Signet.
+ */
+export async function pairWithKingdom(input: Pairing) {
+  const kingdom = kingdomUrl(input.kingdom);
+  const directory = join(input.directory, new URL(kingdom).host);
+  const keyFile = await installationKey(directory);
+  await registerInstallation(kingdom, keyFile, {
+    kind: 'archive',
+    name: input.name,
+    sourceId: input.sourceId,
+  });
+  const askedAt = Date.now();
+  const pending = await requestRegistration(kingdom, keyFile, {
+    name: input.name,
+    lifecycle: 'ongoing',
+    resources: [],
+    expiresAt: null,
+    maxRequests: null,
+    maxConcurrent: 4,
+  });
+  input.onReview({
+    reviewCode: pending.reviewCode,
+    review: `${kingdom}/dashboard?reviewSignet=${pending.reviewCode}`,
+    expiresAt: pending.expiresAt,
+  });
+  const sleep = input.sleep ?? Bun.sleep;
+  for (;;) {
+    const state = await installationInquiries(kingdom, keyFile);
+    if (state.declinedAt && Date.parse(state.declinedAt) >= askedAt)
+      throw new Error('The registration was declined in Kingdom');
+    const inquiry = state.inquiries.find(
+      (item) => item.type === 'registerIntegration' && Date.parse(item.createdAt) >= askedAt,
+    );
+    if (inquiry?.status === 'approved') {
+      if (!(await input.confirmOwner({ ownerName: inquiry.ownerName, owner: inquiry.owner })))
+        throw new Error('Not collected: the owner was not confirmed');
+      const collected = await collectSignet(kingdom, keyFile, inquiry.id);
+      if (!collected) throw new Error('Kingdom has not released the Signet yet; try again');
+      const credentialFile = join(directory, `signet-${collected.signetId}.json`);
+      await saveCollectedSignet(credentialFile, kingdom, keyFile, collected);
+      return {
+        paired: true,
+        owner: inquiry.ownerName,
+        integrationId: collected.integrationId,
+        credentialFile,
+        libraries: await writableLibraries(credentialFile),
+        next: 'archive connect --kind kingdom --url KINGDOM --credential-file FILE --integration-id ID --resource-id ID --project-id PROJECT',
+      };
+    }
+    if (inquiry && inquiry.status !== 'sent')
+      throw new Error(`The registration was ${inquiry.status} in Kingdom`);
+    if (!inquiry && !state.pending)
+      throw new Error('The review code expired before it was claimed; run archive pair again');
+    await sleep(pollMs);
+  }
+}
+
+export async function verifyKingdomDestination(
+  destination: Extract<ArchiveDestination, { kind: 'kingdom' }>,
+) {
+  const libraries = await writableLibraries(destination.credentialFile);
+  if (
+    !libraries.some(
+      (library) =>
+        library.integrationId === destination.integrationId &&
+        library.resourceId === destination.resourceId,
+    )
+  )
+    throw new Error("This Archive's Signet does not grant sessions.write on that library");
+}

package/src/remote.ts

@@ -32,13 +32,17 @@ export class ArchiveRequestError extends Error {
 export class ArchiveClient {
   private cachedSourceId?: string;
   constructor(private readonly options: { url: string; token: string; fetch?: typeof fetch }) {}
-  async request<T>(action: string, body: unknown = {}): Promise<T> {
+  async request<T>(
+    action: string,
+    body: unknown = {},
+    { timeoutMs = 30_000 }: { timeoutMs?: number } = {},
+  ): Promise<T> {
     const response = await (this.options.fetch ?? fetch)(
       new URL(`api/v1/archive/${action}`, this.options.url),
       {
         method: 'POST',
         redirect: 'error',
-        signal: AbortSignal.timeout(30_000),
+        signal: AbortSignal.timeout(timeoutMs),
         headers: {
           authorization: `Bearer ${this.options.token}`,
           'content-type': 'application/json',