@inixiative/signet 0.7.0 → 0.9.0

package/README.md

@@ -14,6 +14,8 @@ This package is the one implementation of that protocol, shared by Kingdom (whic
   - `pairInstallation` does the whole pairing (register, request, wait on the socket, confirm the owner, collect) and `holdInstallationSignets` keeps one credential file per Signet the installation's integrations hold, enrolling later grants and dropping revoked ones;
   - `InstallationSocket`, Kingdom's live line to an installation: it proves the key, receives a snapshot of the installation's inquiries and Signets on connect and on every change, keeps the installation's integrations marked online, advertises its viewer URL, and polls the same reads while the socket is down;
   - a **person or their agent** acts as themselves with a Kingdom API token plus a proof from its key: `requestSignet` asks for a Signet on an integration (a `signetRequest` Inquiry, approved at once when the caller manages the integration), `awaitSignet` polls `collectSignet` until it is approved, and `enrollSignet` enrolls the key on a Signet an owner granted directly (`owner/grant`). `saveCollectedSignet` writes either result next to the key;
+  - `installation`: the layout every installation shares, under one root per product (a Foundry's `kingdom/`, `~/.kcp`): one directory per Kingdom host with its key and one file per Signet (`installationPaths`, `installationDirectory`, `signetCredentialFile`, `heldCredentials`), `privateDirectory`, and `defaultInstallationName(product)`. `listedSignets`, `heldSignetFile` and `withdrawRegistration` read and act on it. `holdPersonSignets` enrolls the key on Signets issued to a person, under the same per-directory `withHoldLock` as `holdInstallationSignets`, so a person login and an installation sync never enroll over each other;
+  - `SignetHolders`, a cache of each held Signet's `access/describe` (with its `holder`), keyed by credential file or by the caller's own `keyOf`, refreshed after `stale()`;
   - `SignetClient`, which renews its access token and signs each call: `describe`, `execute`, task settlement, and the run actions a Foundry uses for inference (`resolveRun`, `delegateRun`, `renewRun`, `revokeRun`), and for a subscription run `releaseSubscription` and `reportSubscriptionLimits`.
 
 ```ts
@@ -59,7 +61,7 @@ await signet.describe();
 
 ## Declared operations
 
-An integration whose operations Kingdom executes generically declares them here, one module per resource kind: `threads.ts` for a Foundry's `threads` resource, `archive.ts` for an Archive's `archiveLibrary`. Each declares its operation enum, display names, the input each operation takes, its lens schema and the lens's narrowing. `declaredOperationSchema` and `operationInputSchemas` join them (operation names are unique across contracts), `operationInputKeys(operation)` gives the `access/execute` keys an operation takes besides `resourceId` and `limit`, and `operationInputFromAccess(operation, input)` picks and parses exactly those. Kingdom's catalog, its input check and its dispatch read these, so a new operation is added here first.
+An integration whose operations Kingdom executes generically declares them here, one module per resource kind: `threads.ts` for a Foundry's `threads` resource, `archive.ts` for an Archive's `archiveLibrary`, `github.ts` for a GitHub `repository` (reads by object id; its lens pins a grant to commits, and a pinned grant reaches no tree or blob, since reading a commit never reached its tree). Each declares its operation enum, display names, the input each operation takes, its lens schema and the lens's narrowing. `declaredOperationSchema` and `operationInputSchemas` join them (operation names are unique across contracts), `operationInputKeys(operation)` gives the `access/execute` keys an operation takes besides `resourceId` and `limit`, and `operationInputFromAccess(operation, input)` picks and parses exactly those. Kingdom's catalog, its input check and its dispatch read these, so a new operation is added here first.
 
 - **Archive** (`archiveLibrary`): `documents.read`, `documents.search`, `sessions.write`, `sessions.delete`. The lens is `{ documentIds?, fields? }` (`{}` reaches every document) and `narrowsArchiveLens` narrows it. `archiveSourceOperations` (`sessions.write`, `sessions.delete`) are a paired local Archive acting on its own sessions: Kingdom binds them to its `sourceId`, so their grant takes no lens. `archiveLensRefusal(operation, lens)` says why a grant can't carry a lens (search needs content over every document).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Present Kingdom Signets: the wire contracts, DPoP proofs, device pairing and a renewing client shared by Kingdom, Archive, Foundry and Oracle.",
   "type": "module",
   "main": "src/index.ts",
@@ -35,7 +35,7 @@
   "devDependencies": {
     "@asteasolutions/zod-to-openapi": "^9.1.0",
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.158",
+    "@inixiative/config": "^0.5.164",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/contracts.ts

@@ -8,6 +8,14 @@ import {
   archiveOperationSchema,
   narrowsArchiveLens,
 } from './archive';
+import {
+  githubInputSchemas,
+  githubOperationSchema,
+  gitObjectIdSchema,
+  narrowsRepositoryLens,
+  repositoryLensSchema,
+  repositoryResourceKind,
+} from './github';
 import {
   foundryIdSchema,
   narrowsThreadsLens,
@@ -21,6 +29,7 @@ import {
 } from './threads';
 
 export * from './archive';
+export * from './github';
 export * from './threads';
 
 const token43 = /^[A-Za-z0-9_-]{43}$/;
@@ -44,6 +53,21 @@ export const ownerRefSchema = z.object({
 });
 export type OwnerRef = z.infer<typeof ownerRefSchema>;
 
+/** Kingdom's canonical owner key: `ownerModel:userId:organizationId:spaceId`, absent ids empty. */
+export const ownerKey = (
+  owner: Pick<OwnerRef, 'ownerModel'> & {
+    [K in 'userId' | 'organizationId' | 'spaceId']?: string | null;
+  },
+) =>
+  [owner.ownerModel, owner.userId ?? '', owner.organizationId ?? '', owner.spaceId ?? ''].join(':');
+
+const uuidOrEmpty =
+  '(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})?';
+/** An `ownerKey` string. */
+export const ownerKeySchema = z
+  .string()
+  .regex(new RegExp(`^(?:${ownerModelSchema.options.join('|')})(?::${uuidOrEmpty}){3}$`));
+
 export const publicClientKeySchema = z.strictObject({
   kty: z.literal('EC'),
   crv: z.literal('P-256'),
@@ -65,7 +89,11 @@ export const emptyLensSchema = z.strictObject({});
  * kind, and Kingdom checks that with `resourceLensSchema` against the kind it stores (review R9).
  * `{}` parses as the empty Archive lens: "no lens", valid for every kind but `threads`.
  */
-export const signetLensSchema = z.union([archiveLensSchema, threadsLensSchema]);
+export const signetLensSchema = z.union([
+  archiveLensSchema,
+  threadsLensSchema,
+  repositoryLensSchema,
+]);
 export type SignetLens = z.infer<typeof signetLensSchema>;
 
 /** The lens shape a resource of `kind` takes. */
@@ -74,7 +102,9 @@ export const resourceLensSchema = (kind: string) =>
     ? archiveLensSchema
     : kind === threadsResourceKind
       ? threadsLensSchema
-      : emptyLensSchema;
+      : kind === repositoryResourceKind
+        ? repositoryLensSchema
+        : emptyLensSchema;
 
 /**
  * `granted` reaches nothing `requested` doesn't, for lenses of the same resource. Approving someone
@@ -84,7 +114,22 @@ export const resourceLensSchema = (kind: string) =>
 export const narrowsSignetLens = (granted: SignetLens, requested: SignetLens): boolean => {
   if ('threads' in granted || 'threads' in requested)
     return 'threads' in granted && 'threads' in requested && narrowsThreadsLens(granted, requested);
-  return narrowsArchiveLens(granted, requested);
+  if ('commits' in granted || 'commits' in requested) {
+    const repositoryGranted = repositoryLensSchema.safeParse(granted);
+    const repositoryRequested = repositoryLensSchema.safeParse(requested);
+    return (
+      repositoryGranted.success &&
+      repositoryRequested.success &&
+      narrowsRepositoryLens(repositoryGranted.data, repositoryRequested.data)
+    );
+  }
+  const archiveGranted = archiveLensSchema.safeParse(granted);
+  const archiveRequested = archiveLensSchema.safeParse(requested);
+  return (
+    archiveGranted.success &&
+    archiveRequested.success &&
+    narrowsArchiveLens(archiveGranted.data, archiveRequested.data)
+  );
 };
 
 export const signetResourceSchema = z.strictObject({
@@ -408,6 +453,7 @@ export const accessInputSchema = z.strictObject({
   floor: threadFloorActionSchema.optional(),
   promptId: foundryIdSchema.optional(),
   answer: threadInputSchemas['prompt.resolve'].shape.answer.optional(),
+  objectId: gitObjectIdSchema.optional(),
 });
 export const accessRequestSchema = z.strictObject({
   requestId: z.uuid(),
@@ -422,18 +468,20 @@ export type AccessRequest = z.infer<typeof accessRequestSchema>;
 export const accessResultSchema = z.object({ executionId: z.uuid(), result: z.unknown() });
 
 /**
- * Every operation a contract in this package declares (`threads.ts`, `archive.ts`), and the input
+ * Every operation a contract in this package declares (`threads.ts`, `archive.ts`, `github.ts`), and the input
  * each takes. Kingdom's `access/execute` check, its catalog and its dispatch read these, so a new
  * operation is added here and nowhere else. Operation names are unique across contracts.
  */
 export const declaredOperationSchema = z.enum([
   ...threadOperationSchema.options,
   ...archiveOperationSchema.options,
+  ...githubOperationSchema.options,
 ]);
 export type DeclaredOperation = z.infer<typeof declaredOperationSchema>;
 export const operationInputSchemas = {
   ...threadInputSchemas,
   ...archiveInputSchemas,
+  ...githubInputSchemas,
 } as const satisfies Record<DeclaredOperation, z.ZodObject>;
 export type OperationInput<O extends DeclaredOperation> = z.infer<
   (typeof operationInputSchemas)[O]

package/src/github.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+
+/**
+ * GitHub repositories (Kingdom `docs/OPERATOR-ACCESS.md` §9). A GitHub integration is one GitHub
+ * account; each repository it reaches is a `repository` resource, named `owner/name`. Kingdom admits
+ * each call through a Signet and reads the repository with the integration's credential, so the
+ * lens is applied by Kingdom.
+ */
+export const repositoryResourceKind = 'repository';
+
+/** A Git object id: an immutable commit, tree or blob SHA-1. */
+export const gitObjectIdSchema = z.string().regex(/^[a-f0-9]{40}$/);
+
+/**
+ * Which commits of a `repository` a grant reaches; `{}` reaches the whole repository. A grant pinned
+ * to commits reads only those commits: reading a commit never reaches its tree, so a pinned grant
+ * reaches no tree or blob.
+ */
+export const repositoryLensSchema = z.strictObject({
+  commits: z.array(gitObjectIdSchema).min(1).max(1000).optional(),
+});
+export type RepositoryLens = z.infer<typeof repositoryLensSchema>;
+
+/** `granted` reaches no commit `requested` doesn't. */
+export const narrowsRepositoryLens = (granted: RepositoryLens, requested: RepositoryLens) =>
+  !requested.commits ||
+  (granted.commits?.every((commit) => requested.commits?.includes(commit)) ?? false);
+
+/** The operations a `repository` resource carries. */
+export const githubOperationSchema = z.enum(['commits.read', 'trees.read', 'blobs.read']);
+export type GithubOperation = z.infer<typeof githubOperationSchema>;
+
+export const githubOperationNames: Record<GithubOperation, string> = {
+  'commits.read': 'Read an immutable repository commit',
+  'trees.read': 'Read an immutable repository tree',
+  'blobs.read': 'Read an immutable repository file',
+};
+
+/**
+ * The input each repository operation takes: the object to read. `access/execute` carries the same
+ * field beside `resourceId` and `limit` (`accessInputSchema`).
+ */
+export const githubInputSchemas = {
+  'commits.read': z.strictObject({ objectId: gitObjectIdSchema }),
+  'trees.read': z.strictObject({ objectId: gitObjectIdSchema }),
+  'blobs.read': z.strictObject({ objectId: gitObjectIdSchema }),
+} as const satisfies Record<GithubOperation, z.ZodObject>;
+
+/** Why a grant of `operation` can't carry `lens`, or null when it can. */
+export const repositoryLensRefusal = (operation: GithubOperation, lens: RepositoryLens) =>
+  lens.commits && operation !== 'commits.read'
+    ? 'A grant pinned to commits reads only those commits; trees and blobs need an unpinned grant'
+    : null;
+
+/** Whether every lens a call is admitted under reaches `objectId` for `operation`. */
+export const lensesSelectObject = (
+  lenses: RepositoryLens[],
+  operation: GithubOperation,
+  objectId: string,
+) =>
+  lenses.every(
+    (lens) =>
+      !repositoryLensRefusal(operation, lens) && (!lens.commits || lens.commits.includes(objectId)),
+  );

package/src/holders.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { SignetClient, SignetHttpError } from './client';
+import {
+  type ParsedSignetDescription,
+  parseSignetDescription,
+  type SignetHolder,
+  signetHolderSchema,
+} from './contracts';
+
+/**
+ * A held Signet as Kingdom's extended `access/describe` reports it, with its `holder` (null for a
+ * person-held Signet). Read per entry (`parseSignetDescription`), so a resource this package can't
+ * read costs that resource, never the holder.
+ */
+export const parseHeldSignetDescription = (value: unknown) => ({
+  ...parseSignetDescription(value),
+  holder: z.object({ holder: signetHolderSchema.nullable() }).parse(value).holder,
+});
+
+export interface HolderView {
+  /** `described`: Kingdom answered; `revoked`: Kingdom refused the Signet (403); `unavailable`: no answer. */
+  status: 'described' | 'revoked' | 'unavailable';
+  holder: SignetHolder | null;
+  description: ParsedSignetDescription | null;
+  checkedAt: number;
+}
+
+/** One held Signet: the Kingdom it is from, its id, and the credential file that presents it. */
+export type HeldSignetRef = { url: string; signetId: string; credentialFile: string };
+
+export type DescribeHeldSignet<Ref extends HeldSignetRef = HeldSignetRef> = (
+  signet: Ref,
+) => Promise<unknown>;
+
+const describeWithSignet: DescribeHeldSignet = async ({ url, credentialFile, signetId }) =>
+  new SignetClient(url, credentialFile, signetId).post('describe', { signetId }, undefined, {
+    timeoutMs: 5_000,
+  });
+
+/**
+ * Descriptions per held Signet, cached: read at most once per `ttlMs`, again after the
+ * installation socket reports a change (`stale()`), and shared by concurrent readers. Entries are
+ * keyed by `keyOf` (default: the credential file), the same key `forget` takes.
+ */
+export class SignetHolders<Ref extends HeldSignetRef = HeldSignetRef> {
+  private cache = new Map<string, { view: HolderView; stale: boolean }>();
+  private inflight = new Map<string, Promise<HolderView>>();
+  private readonly ttlMs: number;
+  private readonly describe: DescribeHeldSignet<Ref>;
+  private readonly keyOf: (signet: Ref) => string;
+  constructor(
+    options: {
+      ttlMs?: number;
+      describe?: DescribeHeldSignet<Ref>;
+      keyOf?: (signet: Ref) => string;
+    } = {},
+  ) {
+    this.ttlMs = options.ttlMs ?? 10 * 60_000;
+    this.describe = options.describe ?? describeWithSignet;
+    this.keyOf = options.keyOf ?? ((signet) => signet.credentialFile);
+  }
+
+  /** The installation snapshot changed: what Kingdom holds may have too. */
+  stale() {
+    for (const entry of this.cache.values()) entry.stale = true;
+  }
+
+  forget(key: string) {
+    this.cache.delete(key);
+  }
+
+  /** The cached view when fresh; otherwise a new read, waiting at most `waitMs` before answering with the last one. */
+  async get(signet: Ref, waitMs = 3_000): Promise<HolderView> {
+    const key = this.keyOf(signet);
+    const cached = this.cache.get(key);
+    if (cached && !cached.stale && Date.now() - cached.view.checkedAt < this.ttlMs)
+      return cached.view;
+    let read = this.inflight.get(key);
+    if (!read) {
+      read = this.read(signet).then((view) => {
+        this.cache.set(key, { view, stale: false });
+        return view;
+      });
+      read.finally(() => this.inflight.delete(key)).catch(() => {});
+      this.inflight.set(key, read);
+    }
+    const fallback: HolderView = cached?.view ?? {
+      status: 'unavailable',
+      holder: null,
+      description: null,
+      checkedAt: Date.now(),
+    };
+    return Promise.race([
+      read,
+      new Promise<HolderView>((resolve) => setTimeout(() => resolve(fallback), waitMs).unref?.()),
+    ]);
+  }
+
+  private async read(signet: Ref): Promise<HolderView> {
+    const checkedAt = Date.now();
+    try {
+      const description = parseHeldSignetDescription(await this.describe(signet));
+      return { status: 'described', holder: description.holder, description, checkedAt };
+    } catch (error) {
+      const status =
+        error instanceof SignetHttpError && error.status === 403 ? 'revoked' : 'unavailable';
+      return { status, holder: null, description: null, checkedAt };
+    }
+  }
+}

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from './client';
 export * from './contracts';
 export * from './files';
+export * from './holders';
+export * from './installation';
 export * from './installationPairing';
 export * from './installationSocket';
 export * from './proof';

package/src/installation.ts

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import { chmod, lstat, mkdir, readdir } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  generateSignetKey,
+  kingdomUrl,
+  type SignetCredential,
+  signetCredentialSchema,
+} from './client';
+import { readPrivateJson, writePrivateJson } from './files';
+
+/**
+ * Where an installation keeps what it holds for one Kingdom under `root`, without creating
+ * anything: one directory per Kingdom host, its key, and one file per Signet.
+ */
+export function installationPaths(root: string, url: string) {
+  const directory = join(resolve(root), new URL(kingdomUrl(url)).host);
+  return { directory, keyFile: join(directory, 'installation-key.json') };
+}
+
+/** `installationPaths`, creating the installation key on first use. */
+export async function installationDirectory(root: string, url: string) {
+  const paths = installationPaths(root, url);
+  if (!existsSync(paths.keyFile)) await writePrivateJson(paths.keyFile, generateSignetKey());
+  return paths;
+}
+
+export const signetCredentialFile = (directory: string, signetId: string) =>
+  join(directory, `signet-${signetId}.json`);
+
+/** Creates `path` as a 0700 directory owned by this user, or makes an existing one so. */
+export async function privateDirectory(path: string) {
+  const directory = resolve(path);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await lstat(directory);
+  if (
+    !stat.isDirectory() ||
+    stat.isSymbolicLink() ||
+    (process.getuid && stat.uid !== process.getuid())
+  )
+    throw Error(`${directory} must be a directory owned by this user`);
+  await chmod(directory, 0o700);
+}
+
+/** The name an installation registers under unless its person picks one: `<product> on <host>`. */
+export const defaultInstallationName = (product: string) =>
+  `${product} on ${hostname()}`.slice(0, 120);
+
+export type HeldCredential = SignetCredential & { credentialFile: string };
+
+const credentialFileName = /^signet-[0-9a-f-]{36}\.json$/;
+
+/** Every Signet credential file in one Kingdom's installation directory that parses; others are skipped. */
+export async function heldCredentials(directory: string): Promise<HeldCredential[]> {
+  const names = await readdir(directory).catch(() => [] as string[]);
+  const held = await Promise.all(
+    names
+      .filter((name) => credentialFileName.test(name))
+      .map(async (name) => {
+        const credentialFile = join(directory, name);
+        const parsed = signetCredentialSchema.safeParse(
+          await readPrivateJson(credentialFile).catch(() => null),
+        );
+        return parsed.success ? [{ ...parsed.data, credentialFile }] : [];
+      }),
+  );
+  return held.flat();
+}

package/src/installationPairing.ts

@@ -2,14 +2,17 @@ import { existsSync } from 'node:fs';
 import { mkdir, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import {
+  cancelInstallationInquiry,
   collectSignet,
   enrollInstallationSignet,
-  generateSignetKey,
+  enrollSignet,
   installationInquiries,
+  installationSignets,
   kingdomUrl,
   registerInstallation,
   requestRegistration,
   SignetHttpError,
+  type SignetRequestOptions,
   saveCollectedSignet,
   signetCredentialSchema,
 } from './client';
@@ -19,20 +22,10 @@ import type {
   OwnerRef,
   RegistrationRequest,
 } from './contracts';
-import { readPrivateJson, writePrivateJson } from './files';
+import { readPrivateJson } from './files';
+import { installationDirectory, installationPaths, signetCredentialFile } from './installation';
 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) {
-  const directory = join(root, new URL(kingdomUrl(url)).host);
-  const keyFile = join(directory, 'installation-key.json');
-  if (!existsSync(keyFile)) await writePrivateJson(keyFile, generateSignetKey());
-  return { directory, keyFile };
-}
-
-export const signetCredentialFile = (directory: string, signetId: string) =>
-  join(directory, `signet-${signetId}.json`);
-
 export type HeldSignet = {
   signetId: string;
   integrationId: string;
@@ -50,8 +43,12 @@ const heldEnrollment = async (credentialFile: string) => {
 
 const lockStaleMs = 60_000;
 
-/** One holder at a time per directory, so two processes never enroll over each other. */
-async function withHoldLock<T>(directory: string, fn: () => Promise<T>): Promise<T> {
+/**
+ * One holder at a time per installation directory, so two processes never enroll or write
+ * credentials over each other. Every hold in this package takes it; take it to write a Signet
+ * credential into the directory by other means.
+ */
+export async function withHoldLock<T>(directory: string, fn: () => Promise<T>): Promise<T> {
   const lock = join(directory, '.hold-lock');
   for (const started = Date.now(); ; ) {
     try {
@@ -112,6 +109,118 @@ export async function holdInstallationSignets(
   });
 }
 
+export type PersonSignet = {
+  signetId: string;
+  /** The Signet's current revision, as the person read it (`/me/overview`); Kingdom refuses a stale one. */
+  expectedRevision: number;
+  integrationId: string;
+  owner?: OwnerRef;
+};
+
+export type HeldPersonSignet = {
+  signetId: string;
+  integrationId: string;
+  owner?: OwnerRef;
+  credentialFile: string;
+  /** False when a credential file was already held and kept. */
+  enrolled: boolean;
+};
+
+/**
+ * Enrolls this installation's key on Signets issued to the person a Kingdom API token belongs to,
+ * under the same lock as `holdInstallationSignets`, so a person login and an installation sync
+ * never enroll over each other. A Signet whose credential file already parses is kept unless
+ * `replace` is set. The token authorizes the enrollment and is never written.
+ */
+export async function holdPersonSignets(
+  url: string,
+  keyFile: string,
+  directory: string,
+  apiToken: string,
+  signets: readonly PersonSignet[],
+  options: SignetRequestOptions & { name: string; replace?: boolean },
+): Promise<HeldPersonSignet[]> {
+  const { name, replace, ...request } = options;
+  return withHoldLock(directory, async () => {
+    const held: HeldPersonSignet[] = [];
+    for (const signet of signets) {
+      const credentialFile = signetCredentialFile(directory, signet.signetId);
+      const kept = !replace && (await heldEnrollment(credentialFile));
+      if (!kept) {
+        const enrolled = await enrollSignet(
+          url,
+          keyFile,
+          apiToken,
+          { signetId: signet.signetId, expectedRevision: signet.expectedRevision, name },
+          request,
+        );
+        await saveCollectedSignet(credentialFile, url, keyFile, {
+          ...enrolled,
+          integrationId: signet.integrationId,
+          ...(signet.owner ? { owner: signet.owner } : {}),
+        });
+      }
+      held.push({
+        signetId: signet.signetId,
+        integrationId: signet.integrationId,
+        ...(signet.owner ? { owner: signet.owner } : {}),
+        credentialFile,
+        enrolled: !kept,
+      });
+    }
+    return held;
+  });
+}
+
+/** Which Signets each Kingdom lists for this installation: one read per Kingdom; null when it refused or is unreachable. */
+export async function listedSignets(root: string, urls: readonly string[]) {
+  const listed = new Map<string, Set<string> | null>();
+  await Promise.all(
+    [...new Set(urls)].map(async (url) => {
+      const { keyFile } = installationPaths(root, url);
+      try {
+        if (!existsSync(keyFile)) throw Error('No installation key');
+        const { signets } = await installationSignets(url, keyFile, { timeoutMs: 5000 });
+        listed.set(url, new Set(signets.map((signet) => signet.signetId)));
+      } catch {
+        listed.set(url, null);
+      }
+    }),
+  );
+  return listed;
+}
+
+/** The local file of a Signet this installation holds, enrolling it now if Kingdom lists it but no file exists yet. */
+export async function heldSignetFile(root: string, url: string, signetId: string) {
+  const { keyFile, directory } = await installationDirectory(root, url);
+  const file = signetCredentialFile(directory, signetId);
+  if (existsSync(file)) return file;
+  const listed = (await installationSignets(url, keyFile)).signets.filter(
+    (signet) => signet.signetId === signetId,
+  );
+  if (!listed.length) throw Error(`Kingdom does not list Signet ${signetId} for this installation`);
+  await holdInstallationSignets(url, keyFile, directory, listed);
+  if (!existsSync(file)) throw Error(`Signet ${signetId} could not be enrolled here`);
+  return file;
+}
+
+/**
+ * Withdraws every open registration of this installation, so a later approval in Kingdom mints no
+ * integration nothing collects. One pairing runs at a time per installation, so every open
+ * registration belongs to a pairing that no longer waits. Kingdom's refusals are thrown.
+ */
+export async function withdrawRegistration(root: string, url: string) {
+  const origin = kingdomUrl(url);
+  const { keyFile } = installationPaths(root, origin);
+  if (!existsSync(keyFile)) return [];
+  const { inquiries } = await installationInquiries(origin, keyFile);
+  const open = inquiries.filter(
+    (inquiry) => inquiry.type === 'registerIntegration' && openStatuses.has(inquiry.status),
+  );
+  for (const inquiry of open) await cancelInstallationInquiry(origin, keyFile, inquiry.id);
+  return open.map((inquiry) => inquiry.id);
+}
+
 export type InstallationPairing = {
   url: string;
   root: string;