@inixiative/signet 0.7.0 → 0.8.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.7.0",
+  "version": "0.8.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.163",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/contracts.ts

@@ -44,6 +44,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'),

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;