@inixiative/archive 0.9.0 → 0.11.0

package/README.md

@@ -21,7 +21,7 @@ archive up      # creates ~/.local/share/archive/server.token, then docker compo
 archive down
 ```
 
-`up` runs the `compose.yaml` that ships in the package (project `archive`) with `ARCHIVE_DATA_DIR` set to the archive home and the server token from its `server.token`. Postgres data lives in `$ARCHIVE_DATA_DIR/postgres` and the server's destinations in `$ARCHIVE_DATA_DIR/config`, so both survive rebuilds and volume prunes. Pin a version with `ARCHIVE_VERSION`; build from a checkout with `docker compose -f compose.yaml -f compose.build.yaml up -d --build`.
+`up` runs the `compose.yaml` that ships in the package (project `archive`) with `ARCHIVE_DATA_DIR` set to the archive home and the server token from its `server.token`. Postgres data lives in `$ARCHIVE_DATA_DIR/postgres` and the server's configuration (`destinations.json`, destination token files, the Kingdom pairing) in `$ARCHIVE_DATA_DIR/config`, so both survive rebuilds and volume prunes. Compose mounts the config directory at the same absolute path, so the CLI and the server read one `destinations.json` and every path in it resolves for both. Running Compose directly requires an absolute `ARCHIVE_DATA_DIR`. Pin a version with `ARCHIVE_VERSION`; build from a checkout with `docker compose -f compose.yaml -f compose.build.yaml up -d --build`.
 
 The server applies its schema migrations on start and requires bearer authentication for data endpoints; `/health` has no session data. Every other command talks to it over HTTP at `--url` (default `http://127.0.0.1:4700`) with the token in `--token-file` (default `~/.local/share/archive/server.token`) or `ARCHIVE_TOKEN`:
 
@@ -44,11 +44,11 @@ Every deployment runs the published image `ghcr.io/inixiative/archive` (tags: ve
 The local Archive publishes onward to destinations. Place the destination's token in a private file under the server's config directory (`chmod 600`, owned by you) or an environment variable, then run:
 
 ```sh
-archive connect --home ~/.local/share/archive/config --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/config/credentials/inixiative.token
-archive search --remote --home ~/.local/share/archive/config --query 'migration'
+archive connect --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/config/credentials/inixiative.token
+archive search --remote --query 'migration'
 ```
 
-`setup` is an alias for `connect`. Setup verifies access before saving `destinations.json` and does not upload; the Compose server (`serve --sync`) reads it and publishes every 30 seconds. `sync` and `routes` run the same publication, or preview it, once against `DATABASE_URL`. The URL locates the server; the token grants access. Configuration stores only the token file path (`tokenFile`) or environment variable name (`--token-env`, `tokenEnv`), never the token. A token file is read on every request, so rotating it needs no restart; symlinks and files readable by group or others are refused. Redirects are refused; only HTTPS or loopback HTTP is allowed.
+`setup` is an alias for `connect`. Setup verifies access before saving `<home>/config/destinations.json` and does not upload; the Compose server (`serve --sync`) reads it and publishes every 30 seconds. `sync` and `routes` run the same publication, or preview it, once against `DATABASE_URL`. The URL locates the server; the token grants access. Configuration stores only the token file path (`tokenFile`) or environment variable name (`--token-env`, `tokenEnv`), never the token. A token file is read on every request, so rotating it needs no restart; symlinks and files readable by group or others are refused. Redirects are refused; only HTTPS or loopback HTTP is allowed.
 
 ## Always-on local archiving
 
@@ -76,14 +76,14 @@ First, pair this Archive with Kingdom:
 bun run archive pair --kingdom https://api.your-kingdom.example --name "Work laptop"
 ```
 
-`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.
+`pair` registers this Archive with Kingdom as an **Installation**, named by a key kept in `<home>/config/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://api.your-kingdom.example --credential-file ~/.archive/kingdom/signet-SIGNET.json --integration-id HOSTED_ARCHIVE_INTEGRATION --resource-id LIBRARY --project-id inixiative
+bun run archive connect --kind kingdom --url https://api.your-kingdom.example --credential-file ~/.local/share/archive/config/kingdom/KINGDOM_HOST/signet-SIGNET.json --integration-id HOSTED_ARCHIVE_INTEGRATION --resource-id LIBRARY --project-id inixiative
 ```
 
 `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).
@@ -104,6 +104,17 @@ Foundry writes its captures to the local Archive server through `@inixiative/arc
 
 Only explicit `projectId` matches authorize publication. An archive with no matching destination stays local. Multiple matches create deliberate separate copies. `routes` previews these destinations before upload. Tags, references and actors never change ownership or routing.
 
+The server manages routes over HTTP too, so Foundry can read and set them. Only Kingdom destinations are set this way, through the Signets `pair` collected; direct token destinations stay CLI-only.
+
+| Action | Body | Returns |
+|---|---|---|
+| `destinations/list` | `projectId?` | `destinations`: each as `connect` reports it, with `delivered` (archives acknowledged at their latest digest) and `pending` |
+| `destinations/libraries` | none | `paired`, and the `libraries` (`integrationId`, `resourceId`, `name`) the held Signets may write to |
+| `destinations/connect` | `projectId`, `integrationId`, `resourceId` | the saved destination, after Kingdom confirms `sessions.write` on the library (403 otherwise) |
+| `destinations/remove` | `projectId`, `integrationId`, `resourceId` | `removed` |
+
+`@inixiative/archive/remote`'s `ArchiveClient` wraps these as `destinations()`, `libraries()`, `connectDestination()` and `removeDestination()`. The sync loop picks up changes within 30 seconds.
+
 ## Tags, references, actors and retention
 
 The archive owns its tag system. It keeps two different things apart:
@@ -133,6 +144,7 @@ All data endpoints are `POST /api/v1/archive/<action>` with a JSON body and `Aut
 | `delete` | `archiveId` | deleted |
 | `settings/read`, `settings/update` | `integrations?`, `retentionDays?` | settings |
 | `tags/list`, `tags/define`, `tags/remove` | `tag`, `actorId?`, `description?` | offered tags with usage counts |
+| `destinations/list`, `destinations/libraries`, `destinations/connect`, `destinations/remove` | see [Routing](#routing) | routes |
 
 Filters are `projectId`, `source`, `tag`, `actorId`, `model`, `effort` and `reference` (`{integration, ref}`). Jev integration is not enabled. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
 

package/compose.yaml

@@ -1,4 +1,6 @@
 # Ports are the archive block of @inixiative/config ports: HTTP 4700, Postgres 6132.
+# ARCHIVE_DATA_DIR is the absolute archive home (`archive up` sets it). Its config directory is
+# mounted at the same path, so destinations.json and the files it names resolve for the CLI too.
 services:
   postgres:
     image: pgvector/pgvector:pg17
@@ -9,7 +11,7 @@ services:
     ports:
       - "127.0.0.1:${ARCHIVE_POSTGRES_PORT:-6132}:5432"
     volumes:
-      - ${ARCHIVE_DATA_DIR:-./data}/postgres:/var/lib/postgresql/data
+      - ${ARCHIVE_DATA_DIR:?Set ARCHIVE_DATA_DIR to the absolute archive home}/postgres:/var/lib/postgresql/data
     restart: unless-stopped
     healthcheck:
       test: ["CMD", "pg_isready", "-U", "archive"]
@@ -18,7 +20,7 @@ services:
       retries: 20
   archive:
     image: ghcr.io/inixiative/archive:${ARCHIVE_VERSION:-latest}
-    command: ["bun", "run", "src/cli.ts", "serve", "--home", "/data", "--hostname", "0.0.0.0", "--sync"]
+    command: ["bun", "run", "src/cli.ts", "serve", "--home", "${ARCHIVE_DATA_DIR}", "--hostname", "0.0.0.0", "--sync"]
     depends_on:
       postgres:
         condition: service_healthy
@@ -28,7 +30,7 @@ services:
       ARCHIVE_SERVER_TOKEN: ${ARCHIVE_SERVER_TOKEN:?Set a unique random token of at least 32 characters}
       DATABASE_URL: postgresql://archive:${ARCHIVE_POSTGRES_PASSWORD:-archive}@postgres:5432/archive
     volumes:
-      - ${ARCHIVE_DATA_DIR:-./data}/config:/data
+      - ${ARCHIVE_DATA_DIR}/config:${ARCHIVE_DATA_DIR}/config
     restart: unless-stopped
     healthcheck:
       test: ["CMD", "bun", "-e", "fetch('http://127.0.0.1:4700/health').then(r=>{if(!r.ok)process.exit(1)})"]

package/package.json

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

package/src/cli.ts

@@ -18,7 +18,13 @@ import {
 import { importChatGPTThread } from './chatgpt';
 import { archiveRequest, routingPreview, searchRemotes, syncArchives } from './client';
 import { collectSessions } from './collector';
-import { archiveDestinationSchema, connectDestination, readDestinations } from './config';
+import {
+  archiveDestinationSchema,
+  connectDestination,
+  destinationsFile,
+  kingdomDirectory,
+  readDestinations,
+} from './config';
 import { importTranscriptFile } from './import-file';
 import { pairWithKingdom, verifyKingdomDestination } from './kingdom';
 import { previewImports } from './preview';
@@ -76,7 +82,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
     },
   });
   const home = resolve(v.home!),
-    config = v.config ?? join(home, 'destinations.json'),
+    config = v.config ?? destinationsFile(home),
     tokenFile = v['token-file'] ? resolve(v['token-file']) : join(home, 'server.token');
   const output = (value: unknown) => console.log(JSON.stringify(value, null, 2));
   const command = positionals[0];
@@ -153,6 +159,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
       token: process.env.ARCHIVE_SERVER_TOKEN ?? readToken() ?? '',
       port: Number(v.port ?? process.env.PORT ?? 4700),
       hostname: v.hostname,
+      config: { destinationsFile: config, kingdomDirectory: kingdomDirectory(home) },
     });
     output({ listening: instance.server.url.href, sync: v.sync });
     let stopped = false;
@@ -190,8 +197,10 @@ export async function runCli(args = Bun.argv.slice(2)) {
         kingdom: v.kingdom,
         name: v.name ?? `${hostname()} Archive`,
         sourceId: await local.sourceId(),
-        directory: join(home, 'kingdom'),
+        directory: kingdomDirectory(home),
         onReview: (review) => console.error(JSON.stringify(review)),
+        onError: (error) =>
+          console.error(`Still waiting: ${error instanceof Error ? error.message : String(error)}`),
         confirmOwner: async ({ ownerName }) => {
           if (v.yes) return true;
           if (!process.stdin.isTTY)

package/src/config.ts

@@ -11,7 +11,7 @@ import {
   renameSync,
   writeFileSync,
 } from 'node:fs';
-import { dirname, isAbsolute } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { z } from 'zod';
 
 const projectId = z.string().min(1).max(256);
@@ -35,7 +35,7 @@ const archiveDestination = z
  * 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({
+export const kingdomDestinationSchema = z.strictObject({
   kind: z.literal('kingdom'),
   projectId,
   url: z.url(),
@@ -43,7 +43,7 @@ const kingdomDestination = z.strictObject({
   integrationId: z.uuid(),
   resourceId: z.uuid(),
 });
-export const archiveDestinationSchema = z.union([archiveDestination, kingdomDestination]);
+export const archiveDestinationSchema = z.union([archiveDestination, kingdomDestinationSchema]);
 export type ArchiveDestination = z.infer<typeof archiveDestinationSchema>;
 
 /** Private regular file owned by this user; a symlink or group/world access is refused. */
@@ -94,30 +94,56 @@ export function destinationIdentity(destination: ArchiveDestination) {
       : ['kingdom', destination.integrationId, destination.resourceId],
   ]);
 }
+/**
+ * The server's configuration: destinations and the Kingdom pairing. Compose mounts it at the same
+ * absolute path, so the CLI and the server read one file and the paths in it resolve for both.
+ */
+export const configDirectory = (home: string) => join(home, 'config');
+export const destinationsFile = (home: string) => join(configDirectory(home), 'destinations.json');
+export const kingdomDirectory = (home: string) => join(configDirectory(home), 'kingdom');
+
+/** A destination as reported: never a token, and no credential file for Kingdom entries. */
+export const describeDestination = (destination: ArchiveDestination) => ({
+  configured: true as const,
+  kind: destination.kind,
+  projectId: destination.projectId,
+  url: destination.url,
+  ...(destination.kind === 'kingdom'
+    ? { integrationId: destination.integrationId, resourceId: destination.resourceId }
+    : destination.tokenFile
+      ? { tokenFile: destination.tokenFile }
+      : { tokenEnv: destination.tokenEnv }),
+});
+export type DescribedDestination = ReturnType<typeof describeDestination>;
+
+function writeDestinations(file: string, destinations: ArchiveDestination[]) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(destinations, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  renameSync(temp, file);
+  chmodSync(file, 0o600);
+}
+
+const sameRoute = (a: ArchiveDestination, projectId: string, identity: string) =>
+  a.projectId === projectId && destinationIdentity(a) === identity;
+
 export function connectDestination(file: string, input: unknown) {
   const destination = archiveDestinationSchema.parse(input);
   destination.url = destinationUrl(destination.url).href;
   const destinations = readDestinations(file);
   const identity = destinationIdentity(destination);
-  const index = destinations.findIndex(
-    (item) => item.projectId === destination.projectId && destinationIdentity(item) === identity,
-  );
+  const index = destinations.findIndex((item) => sameRoute(item, destination.projectId, identity));
   if (index < 0) destinations.push(destination);
   else destinations[index] = destination;
-  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
-  const temp = `${file}.${randomUUID()}.tmp`;
-  writeFileSync(temp, JSON.stringify(destinations, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
-  renameSync(temp, file);
-  chmodSync(file, 0o600);
-  return {
-    configured: true,
-    kind: destination.kind,
-    projectId: destination.projectId,
-    url: destination.url,
-    ...(destination.kind === 'kingdom'
-      ? { integrationId: destination.integrationId, resourceId: destination.resourceId }
-      : destination.tokenFile
-        ? { tokenFile: destination.tokenFile }
-        : { tokenEnv: destination.tokenEnv }),
-  };
+  writeDestinations(file, destinations);
+  return describeDestination(destination);
+}
+
+/** Stops routing a project to a destination (by `destinationIdentity`); its receipts remain. */
+export function removeDestination(file: string, route: { projectId: string; identity: string }) {
+  const destinations = readDestinations(file);
+  const kept = destinations.filter((item) => !sameRoute(item, route.projectId, route.identity));
+  if (kept.length === destinations.length) return false;
+  writeDestinations(file, kept);
+  return true;
 }

package/src/kingdom.ts

@@ -1,19 +1,17 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import {
-  collectSignet,
-  generateSignetKey,
-  installationInquiries,
-  kingdomUrl,
-  registerInstallation,
-  requestRegistration,
-  SignetClient,
-  saveCollectedSignet,
-  writePrivateJson,
-} from '@inixiative/signet';
+import { pairInstallation, SignetClient } from '@inixiative/signet';
 import type { ArchiveDestination } from './config';
 
-const pollMs = 3000;
+type KingdomDestination = Extract<ArchiveDestination, { kind: 'kingdom' }>;
+type Library = { integrationId: string; resourceId: string; name: string };
+
+/** The Signet does not grant sessions.write on the library. */
+export class KingdomGrantMissing extends Error {
+  constructor() {
+    super("This Archive's Signet does not grant sessions.write on that library");
+  }
+}
 
 /** Libraries this Archive's Signet may write to, as Kingdom describes them. */
 export async function writableLibraries(credentialFile: string) {
@@ -36,79 +34,45 @@ type Pairing = {
   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>;
+  onError?: (error: unknown) => void;
+  socketOptions?: { pollMs?: number; retryBaseMs?: number; authTimeoutMs?: number };
 };
 
-/** 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.
+ * Pairs this Archive with Kingdom as an Installation: a person claims the review code, the Archive
+ * confirms the owner locally, then collects the Signet for its local Archive integration.
  */
 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, {
+  const paired = await pairInstallation({
+    url: input.kingdom,
+    root: input.directory,
     kind: 'archive',
     name: input.name,
     sourceId: input.sourceId,
+    terms: {
+      name: input.name,
+      lifecycle: 'ongoing',
+      resources: [],
+      expiresAt: null,
+      maxRequests: null,
+      maxConcurrent: 4,
+    },
+    onReview: input.onReview,
+    confirmOwner: input.confirmOwner,
+    onError: input.onError,
+    socketOptions: input.socketOptions,
   });
-  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);
-  }
+  return {
+    paired: true,
+    owner: paired.ownerName,
+    integrationId: paired.integrationId,
+    credentialFile: paired.credentialFile,
+    libraries: await writableLibraries(paired.credentialFile),
+    next: 'archive connect --kind kingdom --url KINGDOM --credential-file FILE --integration-id ID --resource-id ID --project-id PROJECT',
+  };
 }
 
-export async function verifyKingdomDestination(
-  destination: Extract<ArchiveDestination, { kind: 'kingdom' }>,
-) {
+export async function verifyKingdomDestination(destination: KingdomDestination) {
   const libraries = await writableLibraries(destination.credentialFile);
   if (
     !libraries.some(
@@ -117,5 +81,50 @@ export async function verifyKingdomDestination(
         library.resourceId === destination.resourceId,
     )
   )
-    throw new Error("This Archive's Signet does not grant sessions.write on that library");
+    throw new KingdomGrantMissing();
+}
+
+/** Credential files of the Signets `pair` collected into the directory, one per owner. */
+export function heldSignets(directory: string) {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .flatMap((kingdom) =>
+      readdirSync(join(directory, kingdom.name))
+        .filter((name) => /^signet-[^/]+\.json$/.test(name))
+        .map((name) => join(directory, kingdom.name, name)),
+    )
+    .sort();
+}
+
+/** Every library the held Signets may write to; `paired` is false until `pair` collected one. */
+export async function pairedLibraries(directory: string) {
+  const credentialFiles = heldSignets(directory);
+  const libraries = new Map<string, Library>();
+  for (const credentialFile of credentialFiles)
+    for (const library of await writableLibraries(credentialFile))
+      libraries.set(JSON.stringify([library.integrationId, library.resourceId]), library);
+  return { paired: credentialFiles.length > 0, libraries: [...libraries.values()] };
+}
+
+/** The Kingdom destination for a library, through whichever held Signet grants writing to it. */
+export async function pairedDestination(
+  directory: string,
+  route: { projectId: string; integrationId: string; resourceId: string },
+): Promise<KingdomDestination> {
+  for (const credentialFile of heldSignets(directory)) {
+    const destination: KingdomDestination = {
+      kind: 'kingdom',
+      ...route,
+      url: (await SignetClient.fromFile(credentialFile)).url,
+      credentialFile,
+    };
+    try {
+      await verifyKingdomDestination(destination);
+      return destination;
+    } catch (error) {
+      if (!(error instanceof KingdomGrantMissing)) throw error;
+    }
+  }
+  throw new KingdomGrantMissing();
 }

package/src/remote.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { defaultHome } from './agents';
+import type { DescribedDestination } from './config';
 import type { ArchiveChunk, ArchiveSnapshot } from './index';
 import { archiveKey, archiveSnapshotSchema } from './index';
 import type { ArchiveFilter, ArchiveSettings, TagDefinition } from './schemas';
@@ -16,6 +17,14 @@ export type ArchiveListing = Omit<ArchiveSnapshot, 'entries'> & {
   references: ArchiveReferenceCount[];
 };
 
+/** A configured destination and how many of its project's archives it holds at their latest. */
+export type DestinationStatus = DescribedDestination & { delivered: number; pending: number };
+/** A hosted Archive library a held Signet may write to. */
+export type ArchiveLibrary = { integrationId: string; resourceId: string; name: string };
+export type ArchiveLibraries = { paired: boolean; libraries: ArchiveLibrary[] };
+/** A project routed to a hosted Archive library through Kingdom. */
+export type KingdomRoute = { projectId: string; integrationId: string; resourceId: string };
+
 export class ArchiveRequestError extends Error {
   constructor(
     readonly status: number,
@@ -147,6 +156,19 @@ export class ArchiveClient {
       actorId ? { actorId } : {},
     );
   }
+  destinations(filter: { projectId?: string } = {}) {
+    return this.request<{ destinations: DestinationStatus[] }>('destinations/list', filter);
+  }
+  libraries() {
+    return this.request<ArchiveLibraries>('destinations/libraries');
+  }
+  /** Routes a project to a library; the server verifies its Signet grants sessions.write first. */
+  connectDestination(route: KingdomRoute) {
+    return this.request<DescribedDestination>('destinations/connect', route);
+  }
+  removeDestination(route: KingdomRoute) {
+    return this.request<{ removed: boolean }>('destinations/remove', route);
+  }
 }
 
 /** The machine's local Archive server (the `archive` block in @inixiative/config ports). */

package/src/server.ts

@@ -1,6 +1,15 @@
 import { timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
+import {
+  connectDestination,
+  describeDestination,
+  destinationIdentity,
+  kingdomDestinationSchema,
+  readDestinations,
+  removeDestination,
+} from './config';
 import { archiveReferenceSchema, archiveSnapshotSchema, selectChunks } from './index';
+import { KingdomGrantMissing, pairedDestination, pairedLibraries } from './kingdom';
 import { ArchiveConflict, ArchiveStore, archiveSettingsSchema, tagDefinitionSchema } from './store';
 
 const ingestSchema = z.strictObject({
@@ -36,9 +45,22 @@ const tagSchema = z.strictObject({
 });
 const tagListSchema = z.strictObject({ actorId: z.string().min(1).max(256).optional() });
 const tagRemoveSchema = tagDefinitionSchema.pick({ tag: true, actorId: true });
+const destinationListSchema = z.strictObject({ projectId: filterFields.projectId });
+const kingdomRouteSchema = kingdomDestinationSchema.pick({
+  projectId: true,
+  integrationId: true,
+  resourceId: true,
+});
+
+/** Where the server finds its destinations and the Signets `pair` collected. */
+export type ArchiveServerConfig = { destinationsFile: string; kingdomDirectory: string };
 
 /** One deployment, one ownership boundary. No shared cross-tenant database or admin API. */
-export function createArchiveHandler(store: ArchiveStore, token: string) {
+export function createArchiveHandler(
+  store: ArchiveStore,
+  token: string,
+  config?: ArchiveServerConfig,
+) {
   if (token.length < 32)
     throw new Error('ARCHIVE_SERVER_TOKEN must contain at least 32 characters');
   const expected = Buffer.from(`Bearer ${token}`);
@@ -162,9 +184,50 @@ export function createArchiveHandler(store: ArchiveStore, token: string) {
         return json({ data: await store.defineTag(tagDefinitionSchema.parse(body)) });
       if (path === '/api/v1/archive/tags/remove')
         return json({ data: { removed: await store.undefineTag(tagRemoveSchema.parse(body)) } });
+      if (config && path === '/api/v1/archive/destinations/list') {
+        const { projectId } = destinationListSchema.parse(body);
+        const destinations = [];
+        for (const destination of readDestinations(config.destinationsFile))
+          if (!projectId || destination.projectId === projectId)
+            destinations.push({
+              ...describeDestination(destination),
+              ...(await store.delivery(destination.projectId, destinationIdentity(destination))),
+            });
+        return json({ data: { destinations } });
+      }
+      if (config && path === '/api/v1/archive/destinations/libraries') {
+        z.strictObject({}).parse(body);
+        return json({ data: await pairedLibraries(config.kingdomDirectory) });
+      }
+      if (config && path === '/api/v1/archive/destinations/connect') {
+        const route = kingdomRouteSchema.parse(body);
+        const destination = await pairedDestination(config.kingdomDirectory, route);
+        return json({ data: connectDestination(config.destinationsFile, destination) });
+      }
+      if (config && path === '/api/v1/archive/destinations/remove') {
+        const route = kingdomRouteSchema.parse(body);
+        const configured = readDestinations(config.destinationsFile).find(
+          (d) =>
+            d.kind === 'kingdom' &&
+            d.projectId === route.projectId &&
+            d.integrationId === route.integrationId &&
+            d.resourceId === route.resourceId,
+        );
+        return json({
+          data: {
+            removed: configured
+              ? removeDestination(config.destinationsFile, {
+                  projectId: route.projectId,
+                  identity: destinationIdentity(configured),
+                })
+              : false,
+          },
+        });
+      }
       return json({ error: 'Not found' }, 404);
     } catch (error) {
       if (error instanceof ArchiveConflict) return json({ error: error.message }, 409);
+      if (error instanceof KingdomGrantMissing) return json({ error: error.message }, 403);
       if (error instanceof z.ZodError || error instanceof SyntaxError)
         return json({ error: 'Invalid archive request' }, 400);
       return json({ error: 'Archive operation failed' }, 500);
@@ -177,6 +240,7 @@ export async function startArchiveServer(options: {
   token: string;
   port?: number;
   hostname?: string;
+  config?: ArchiveServerConfig;
 }) {
   const store = new ArchiveStore(options.databaseUrl);
   try {
@@ -188,7 +252,7 @@ export async function startArchiveServer(options: {
       port: options.port ?? 4700,
       hostname: options.hostname ?? '127.0.0.1',
       maxRequestBodySize: 65_000_000,
-      fetch: createArchiveHandler(store, options.token),
+      fetch: createArchiveHandler(store, options.token, options.config),
     });
     return {
       server,

package/src/store.ts

@@ -429,6 +429,15 @@ export class ArchiveStore {
       this.db.outbox.deleteMany({ where: { archiveId: id, destination } }),
     ]);
   }
+  /** A project's archives at one destination: delivered at their latest digest, or pending. */
+  async delivery(projectId: string, destination: string) {
+    const archives = await this.db.archive.findMany({
+      where: { projectId },
+      select: { digest: true, receipts: { where: { destination }, select: { digest: true } } },
+    });
+    const delivered = archives.filter((a) => a.receipts[0]?.digest === a.digest).length;
+    return { delivered, pending: archives.length - delivered };
+  }
   async close() {
     await this.db.$disconnect();
   }