@inixiative/archive 0.6.0 → 0.8.0

package/src/client.ts

@@ -1,3 +1,4 @@
+import { kingdomUrl, SignetClient } from '@inixiative/signet';
 import {
   type ArchiveDestination,
   archiveDestinationSchema,
@@ -5,37 +6,29 @@ import {
   destinationToken,
   destinationUrl,
 } from './config';
-import type { LocalArchiveStore } from './local';
+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,49 +37,77 @@ 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: LocalArchiveStore,
+  store: ArchiveStore,
   id: string,
   input: ArchiveDestination,
   transport: typeof fetch = fetch,
 ) {
   const destination = archiveDestinationSchema.parse(input);
-  const archive = store.read(id);
-  if (!archive || archive.snapshot.projectId !== destination.projectId)
+  const archive = await store.head(id);
+  if (!archive || archive.projectId !== destination.projectId)
     throw new Error('Archive is outside destination project');
   const receiptKey = destinationIdentity(destination);
   let sent = false;
   for (let attempt = 0; attempt < 8; attempt++) {
-    const latest = store.read(id)!;
-    const previousDigest = store.receipt(id, receiptKey);
-    let pending = store.pending(id, receiptKey);
+    const latest = (await store.head(id))!;
+    const previousDigest = await store.receipt(id, receiptKey);
+    let pending = await store.pending(id, receiptKey);
     if (!pending) {
       if (previousDigest === latest.digest) return { unchanged: !sent };
-      store.enqueue(id, receiptKey, { revision: latest.revision });
-      pending = store.pending(id, receiptKey)!;
+      await store.enqueue(id, receiptKey, { revision: latest.revision });
+      pending = (await store.pending(id, receiptKey))!;
     }
-    const queued = store.read(id, pending.revision);
+    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');
-    store.delivered(id, receiptKey, queued.digest);
+    if (acknowledged?.digest !== queued.digest) throw new Error('Archive acknowledgement mismatch');
+    await store.delivered(id, receiptKey, queued.digest);
     sent = true;
   }
   throw new Error('Archive changed repeatedly during publication; retry sync');
 }
 
-export function routingPreview(store: LocalArchiveStore, destinations: ArchiveDestination[]) {
-  return store.list().map((archive) => ({
+export async function routingPreview(store: ArchiveStore, destinations: ArchiveDestination[]) {
+  return (await store.list()).map((archive) => ({
     id: archive.id,
     projectId: archive.projectId,
     tags: archive.tags,
@@ -96,14 +117,14 @@ export function routingPreview(store: LocalArchiveStore, destinations: ArchiveDe
       .map((d) => ({
         kind: d.kind,
         url: d.url,
-        ...kingdomFields(d),
+        ...(d.kind === 'kingdom' ? { integrationId: d.integrationId } : {}),
       })),
   }));
 }
 
-export async function syncArchives(store: LocalArchiveStore, destinations: ArchiveDestination[]) {
+export async function syncArchives(store: ArchiveStore, destinations: ArchiveDestination[]) {
   const results: { id: string; destination: string; status: string }[] = [];
-  for (const archive of store.list())
+  for (const archive of await store.list())
     for (const destination of destinations.filter((d) => d.projectId === archive.projectId)) {
       try {
         const result = await publishArchive(store, archive.id, destination);
@@ -112,11 +133,11 @@ export async function syncArchives(store: LocalArchiveStore, destinations: Archi
           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/collector.ts

@@ -2,7 +2,7 @@ import { closeSync, existsSync, lstatSync, openSync, readdirSync, readSync } fro
 import { isAbsolute, join, resolve } from 'node:path';
 import { importTranscriptFile } from './import-file';
 import { archiveKey } from './index';
-import type { LocalArchiveStore } from './local';
+import type { ArchiveClient } from './remote';
 import { type AtlasFileConcepts, atlasTags, provenanceReferences } from './tags';
 
 export interface CollectionSource {
@@ -100,7 +100,11 @@ export function collectionRoots(config: CollectionSource): Set<string> {
   return new Set(config.worktrees ? [...roots, ...roots.flatMap(worktreesOf)] : roots);
 }
 
-export async function collectSessions(store: LocalArchiveStore, config: CollectionSource) {
+/** Where collected sessions go: an Archive server, or a store in-process. */
+export type ArchiveWriter = Pick<ArchiveClient, 'sourceId' | 'head' | 'capture'>;
+
+export async function collectSessions(archive: ArchiveWriter, config: CollectionSource) {
+  const sourceId = await archive.sourceId();
   const roots = collectionRoots(config);
   const result = { imported: 0, unchanged: 0, skipped: 0, failed: 0 };
   // Per scan: checkouts change between scans.
@@ -117,7 +121,7 @@ export async function collectSessions(store: LocalArchiveStore, config: Collecti
       const before = lstatSync(file);
       const snapshot = importTranscriptFile(file, {
         source: config.source,
-        sourceId: store.sourceId,
+        sourceId,
         projectId: config.projectId,
       });
       const after = lstatSync(file);
@@ -125,8 +129,8 @@ export async function collectSessions(store: LocalArchiveStore, config: Collecti
         result.skipped++;
         continue;
       }
-      const old = store.read(archiveKey(snapshot));
-      if (old && old.snapshot.projectId !== config.projectId) {
+      const old = await archive.head(archiveKey(snapshot));
+      if (old && old.projectId !== config.projectId) {
         result.failed++;
         continue;
       }
@@ -135,18 +139,14 @@ export async function collectSessions(store: LocalArchiveStore, config: Collecti
       if (config.atlas && !graphs.has(cwd)) graphs.set(cwd, atlasGraph(cwd));
       const graph = graphs.get(cwd);
       snapshot.tags = [
-        ...new Set([
-          ...(old?.snapshot.tags ?? []),
-          ...(config.tags ?? []),
-          ...(graph ? atlasTags(snapshot, graph, roots) : []),
-        ]),
+        ...new Set([...(config.tags ?? []), ...(graph ? atlasTags(snapshot, graph, roots) : [])]),
       ].slice(0, 100);
       const references = provenanceReferences({
         branch: meta.branch,
         repository: meta.repository ?? repositories.get(cwd),
       });
       if (references.length) snapshot.references = references;
-      if (store.capture(snapshot).changed) result.imported++;
+      if ((await archive.capture(snapshot)).changed) result.imported++;
       else result.unchanged++;
     } catch {
       result.failed++;

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,103 @@
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  collectPairing,
+  generateSignetKey,
+  kingdomUrl,
+  requestPairing,
+  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,
+      })) ?? []
+  );
+}
+
+/**
+ * Pairs this Archive with Kingdom as a local Archive integration bound to its sourceId. The owner
+ * approves the review code in Kingdom and chooses which hosted Archives it may write to.
+ */
+export async function pairWithKingdom(input: {
+  kingdom: string;
+  name: string;
+  sourceId: string;
+  directory: string;
+  onReview: (review: { reviewCode: string; review: string; expiresAt: string }) => void;
+  sleep?: (ms: number) => Promise<unknown>;
+}) {
+  const kingdom = kingdomUrl(input.kingdom);
+  const keyFile = join(input.directory, `key-${crypto.randomUUID()}.json`);
+  await writePrivateJson(keyFile, generateSignetKey());
+  try {
+    return await awaitPairing(kingdom, keyFile, input);
+  } catch (error) {
+    await rm(keyFile, { force: true });
+    throw error;
+  }
+}
+
+async function awaitPairing(
+  kingdom: string,
+  keyFile: string,
+  input: Parameters<typeof pairWithKingdom>[0],
+) {
+  const pending = await requestPairing(kingdom, keyFile, {
+    provider: 'archive',
+    deviceId: input.sourceId,
+    name: input.name,
+    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;
+  while (Date.parse(pending.expiresAt) > Date.now()) {
+    const collected = await collectPairing(kingdom, keyFile, pending.deviceCode);
+    if (collected) {
+      const credentialFile = join(input.directory, `signet-${collected.signetId}.json`);
+      await saveCollectedSignet(credentialFile, kingdom, keyFile, collected);
+      return {
+        paired: true,
+        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',
+      };
+    }
+    await sleep(pollMs);
+  }
+  throw new Error('The review code expired before it was approved; run archive pair again');
+}
+
+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

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultHome } from './agents';
+import type { ArchiveChunk, ArchiveSnapshot } from './index';
+import { archiveKey, archiveSnapshotSchema } from './index';
+import type { ArchiveFilter, ArchiveSettings, TagDefinition } from './schemas';
+import type { ArchiveReferenceCount, TagSuggestion } from './tags';
+
+export type ArchiveListing = Omit<ArchiveSnapshot, 'entries'> & {
+  id: string;
+  revision: number;
+  digest: string;
+  entries: number;
+  models: { model: string; effort?: string; entries: number }[];
+  suggestedTags: TagSuggestion[];
+  references: ArchiveReferenceCount[];
+};
+
+export class ArchiveRequestError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * An Archive server over HTTP. Collectors, the CLI and Foundry write through this; only the
+ * server holds the database.
+ */
+export class ArchiveClient {
+  private cachedSourceId?: string;
+  constructor(private readonly options: { url: string; token: string; fetch?: typeof fetch }) {}
+  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(timeoutMs),
+        headers: {
+          authorization: `Bearer ${this.options.token}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      },
+    );
+    const payload = (await response.json().catch(() => ({}))) as { data?: T; error?: string };
+    if (!response.ok)
+      throw new ArchiveRequestError(response.status, payload.error ?? `Archive ${action} failed`);
+    return payload.data as T;
+  }
+  async sourceId() {
+    this.cachedSourceId ??= (await this.request<{ sourceId: string }>('info')).sourceId;
+    return this.cachedSourceId;
+  }
+  head(id: string) {
+    return this.request<{ id: string; digest: string; revision: number; projectId: string | null }>(
+      'head',
+      { archiveId: id },
+    ).catch((error) => {
+      if (error instanceof ArchiveRequestError && error.status === 404) return undefined;
+      throw error;
+    });
+  }
+  /** Captures a snapshot as the next revision, retrying when another writer got there first. */
+  async capture(input: unknown) {
+    const snapshot = archiveSnapshotSchema.parse(input);
+    const id = archiveKey(snapshot);
+    for (let attempt = 0; ; attempt++) {
+      const head = await this.head(id);
+      try {
+        return await this.request<{
+          id: string;
+          digest: string;
+          revision: number;
+          changed: boolean;
+        }>('ingest', { snapshot, previousDigest: head?.digest ?? null });
+      } catch (error) {
+        const conflict =
+          error instanceof ArchiveRequestError &&
+          error.status === 409 &&
+          error.message === 'Revision conflict';
+        if (!conflict || attempt >= 3) throw error;
+      }
+    }
+  }
+  read(id: string, revision?: number) {
+    return this.request<{
+      id: string;
+      revision: number;
+      digest: string;
+      snapshot: ArchiveSnapshot;
+      chunks: ArchiveChunk[];
+    }>('read', { archiveId: id, ...(revision ? { revision } : {}) }).catch((error) => {
+      if (error instanceof ArchiveRequestError && error.status === 404) return undefined;
+      throw error;
+    });
+  }
+  /** Every listing matching the filter, following cursors. */
+  async list(filter: ArchiveFilter = {}) {
+    const archives: ArchiveListing[] = [];
+    let beforeId: string | undefined;
+    do {
+      const page = await this.request<{ archives: ArchiveListing[]; nextCursor: string | null }>(
+        'list',
+        { ...filter, limit: 100, ...(beforeId ? { beforeId } : {}) },
+      );
+      archives.push(...page.archives);
+      beforeId = page.nextCursor ?? undefined;
+    } while (beforeId);
+    return archives;
+  }
+  search(
+    body: ArchiveFilter & { query?: string; budget?: number; limit?: number; beforeId?: string },
+  ) {
+    return this.request<{
+      archives: (Omit<ArchiveListing, 'id' | 'entries'> & {
+        archiveId: string;
+        chunks: ArchiveChunk[];
+        tokenCount: number;
+      })[];
+      tokenCount: number;
+      nextCursor: string | null;
+    }>('search', body);
+  }
+  tag(id: string, change: { add?: string[]; remove?: string[] }) {
+    return this.request<{ id: string; tags: string[] }>('tag', { archiveId: id, ...change });
+  }
+  delete(id: string) {
+    return this.request<{ deleted: boolean }>('delete', { archiveId: id });
+  }
+  settings() {
+    return this.request<ArchiveSettings>('settings/read');
+  }
+  updateSettings(change: Partial<ArchiveSettings>) {
+    return this.request<ArchiveSettings>('settings/update', change);
+  }
+  tagDefinitions(actorId?: string) {
+    return this.request<{ tags: (TagDefinition & { archives: number })[] }>(
+      'tags/list',
+      actorId ? { actorId } : {},
+    );
+  }
+}
+
+/** The machine's local Archive server (the `archive` block in @inixiative/config ports). */
+export const DEFAULT_URL = 'http://127.0.0.1:4700';
+
+/**
+ * A client for this machine's Archive: `ARCHIVE_URL` or the default address, with `ARCHIVE_TOKEN`
+ * or the home's `server.token`. Undefined until `archive up` (or `init`) has made a token.
+ */
+export function localArchive(options: { home?: string; url?: string; fetch?: typeof fetch } = {}) {
+  const tokenFile = join(options.home ?? defaultHome(), 'server.token');
+  const token =
+    process.env.ARCHIVE_TOKEN ??
+    (existsSync(tokenFile) ? readFileSync(tokenFile, 'utf8').trim() : undefined);
+  if (!token) return undefined;
+  return new ArchiveClient({
+    url: options.url ?? process.env.ARCHIVE_URL ?? DEFAULT_URL,
+    token,
+    fetch: options.fetch,
+  });
+}