@inixiative/signet 0.4.0 → 0.4.2

package/README.md

@@ -13,6 +13,7 @@ This package is the one implementation of that protocol, shared by Kingdom (whic
   - an **Installation** (a local Foundry, Archive or Oracle) is an actor known to Kingdom by its key: `registerInstallation`, then `requestRegistration` asks for what it needs (the owner it expects, by organization id or slug, and resources by id or by kind and name, with their operations) and returns a review code a person claims in Kingdom (a `registerIntegration` Inquiry), where the review opens with that owner and those resources selected, then `collectSignet` and `saveCollectedSignet`. `installationInquiries`, `installationSignets`, `cancelInstallationInquiry`, `enrollInstallationSignet` and `rotateInstallationKey` act as the installation;
   - `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;
   - `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
@@ -39,4 +40,23 @@ const signet = await SignetClient.fromFile(paired.credentialFile);
 await signet.execute({ integrationId, operation: 'sessions.write', input: { resourceId, snapshot, previousDigest: null } });
 ```
 
+A person's agent, with an API token minted in Kingdom:
+
+```ts
+import { awaitSignet, enrollSignet, generateSignetKey, requestSignet, saveCollectedSignet, SignetClient, writePrivateJson } from '@inixiative/signet';
+
+await writePrivateJson(keyFile, generateSignetKey());
+const { requestId, reviewCode } = await requestSignet(kingdom, keyFile, apiToken, {
+  name: 'Research agent', integrationId, lifecycle: 'ongoing', expiresAt: null, maxRequests: null, maxConcurrent: 1,
+  resources: [{ resourceId, operations: ['documents.read'] }],
+});
+const collected = await awaitSignet(kingdom, keyFile, requestId); // or, for a granted Signet:
+// const collected = await enrollSignet(kingdom, keyFile, apiToken, { signetId, expectedRevision, name: 'Research agent' });
+await saveCollectedSignet(credentialFile, kingdom, keyFile, collected);
+const signet = await SignetClient.fromFile(credentialFile);
+await signet.describe();
+```
+
+Kingdom's OpenAPI spec (`/openapi/docs`) publishes each step's raw HTTP call and credentials.
+
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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",
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.78",
+    "@inixiative/config": "^0.5.90",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/client.ts

@@ -16,10 +16,14 @@ import {
   registerInstallationResponseSchema,
   renewalCredentialPattern,
   requestRegistrationResponseSchema,
+  type SignetRequestResponse,
   setInstallationCredentialResponseSchema,
+  signetCredentialsSchema,
   signetDescriptionSchema,
   signetKeySchema,
   signetLifecycleSchema,
+  signetProposalSchema,
+  signetRequestResponseSchema,
 } from './contracts';
 import { readPrivateJson, writePrivateJson } from './files';
 import { createSignetProof, keyThumbprint } from './proof';
@@ -60,7 +64,12 @@ export const signetCredentialSchema = z
   })
   .strict();
 export type SignetCredential = z.infer<typeof signetCredentialSchema>;
+/** A collected or enrolled Signet, as `saveCollectedSignet` writes it next to its key. */
 export const deliveredSignetSchema = signetCredentialSchema.omit({ url: true, keyFile: true });
+export type DeliveredSignet = z.infer<typeof deliveredSignetSchema>;
+const enrolledCredentialsSchema = signetCredentialsSchema.required({ renewalCredential: true });
+/** What `enrollSignet` returns: the enrollment's credentials and the Signet they present. */
+export type EnrolledSignet = z.infer<typeof enrolledCredentialsSchema> & { signetId: string };
 const renewalResponseSchema = deliveredSignetSchema.omit({
   signetId: true,
   integrationId: true,
@@ -111,17 +120,16 @@ function abortable<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
   });
 }
 
+/** Kingdom's JSON reason, else the start of the raw body (a proxy's page). */
 const errorDetail = async (response: Response) => {
+  const text = (await response.text().catch(() => '')).slice(0, 65_536).trim();
   try {
-    const body = JSON.parse((await response.text()).slice(0, 4096)) as {
-      message?: unknown;
-      error?: { message?: unknown };
-    };
-    const message = body.error?.message ?? body.message;
-    return typeof message === 'string' ? message.slice(0, 500) : undefined;
-  } catch {
-    return undefined;
-  }
+    const body = JSON.parse(text) as { message?: unknown; error?: unknown };
+    const error = body.error as { message?: unknown } | string | undefined;
+    const message = typeof error === 'string' ? error : (error?.message ?? body.message);
+    if (typeof message === 'string') return message.slice(0, 500);
+  } catch {}
+  return text.replace(/\s+/g, ' ').slice(0, 500) || undefined;
 };
 
 /** POST to Kingdom's access API and return the response's `data`. */
@@ -206,21 +214,25 @@ export async function signetProof(
   });
 }
 
-/** A call an Installation makes as itself: no access token, a DPoP proof by its key. */
-async function installationPost<T>(
+/**
+ * A call signed by the caller's key with no access token: an Installation acting as itself, or a
+ * person acting through `headers` (their Kingdom API token).
+ */
+async function keyPost<T>(
   url: string,
   keyFile: string,
   action: string,
   body: unknown,
   schema: z.ZodType<T>,
   options: SignetRequestOptions = {},
+  headers: Record<string, string> = {},
 ): Promise<T> {
   return schema.parse(
     await signetPost(
       url,
       action,
       body,
-      { DPoP: await signetProof(url, action, keyFile, undefined, options) },
+      { ...headers, DPoP: await signetProof(url, action, keyFile, undefined, options) },
       undefined,
       options,
     ),
@@ -235,7 +247,7 @@ export const registerInstallation = (
   options: SignetRequestOptions = {},
 ) =>
   readPrivateJson(keyFile).then((key) =>
-    installationPost(
+    keyPost(
       url,
       keyFile,
       'registerInstallation',
@@ -252,7 +264,7 @@ export const requestRegistration = (
   terms: RegistrationRequest,
   options: SignetRequestOptions = {},
 ) =>
-  installationPost(
+  keyPost(
     url,
     keyFile,
     'requestRegistration',
@@ -267,14 +279,7 @@ export const installationInquiries = (
   keyFile: string,
   options: SignetRequestOptions = {},
 ) =>
-  installationPost(
-    url,
-    keyFile,
-    'installationInquiries',
-    {},
-    installationInquiriesResponseSchema,
-    options,
-  );
+  keyPost(url, keyFile, 'installationInquiries', {}, installationInquiriesResponseSchema, options);
 
 export const cancelInstallationInquiry = (
   url: string,
@@ -282,7 +287,7 @@ export const cancelInstallationInquiry = (
   inquiryId: string,
   options: SignetRequestOptions = {},
 ) =>
-  installationPost(
+  keyPost(
     url,
     keyFile,
     'cancelInstallationInquiry',
@@ -302,7 +307,7 @@ export async function collectSignet(
   options: SignetRequestOptions = {},
 ) {
   try {
-    return await installationPost(
+    return await keyPost(
       url,
       keyFile,
       'collectSignet',
@@ -316,21 +321,87 @@ export async function collectSignet(
   }
 }
 
-/** The Signets held by this installation's integrations. */
-export const installationSignets = (
+/** Poll `collectSignet` until the request is approved; throws once it is declined or expires. */
+export async function awaitSignet(
   url: string,
   keyFile: string,
+  inquiryId: string,
+  { intervalMs = 5000, signal }: { intervalMs?: number; signal?: AbortSignal } = {},
+) {
+  for (;;) {
+    signal?.throwIfAborted();
+    const collected = await collectSignet(url, keyFile, inquiryId, { signal });
+    if (collected) return collected;
+    await new Promise<void>((resolve, reject) => {
+      const done = () => {
+        signal?.removeEventListener('abort', aborted);
+        resolve();
+      };
+      const timer = setTimeout(done, intervalMs);
+      const aborted = () => {
+        clearTimeout(timer);
+        reject(signal?.reason);
+      };
+      signal?.addEventListener('abort', aborted, { once: true });
+    });
+  }
+}
+
+/**
+ * Ask for a Signet on an integration, to be presented with this key. Kingdom records a
+ * `signetRequest` Inquiry (approved at once when the caller manages the integration); pass the
+ * returned `requestId` to `collectSignet` or `awaitSignet`.
+ */
+export const requestSignet = async (
+  url: string,
+  keyFile: string,
+  apiToken: string,
+  request: z.input<typeof signetProposalSchema>,
   options: SignetRequestOptions = {},
-) =>
-  installationPost(
+): Promise<SignetRequestResponse> =>
+  keyPost(
     url,
     keyFile,
-    'installationSignets',
-    {},
-    installationSignetsResponseSchema,
+    'requestSignet',
+    {
+      ...signetProposalSchema.parse(request),
+      publicKey: signetPublicKey(await readPrivateJson(keyFile)),
+    },
+    signetRequestResponseSchema,
     options,
+    { authorization: `Bearer ${apiToken}` },
   );
 
+/**
+ * Enroll this key on a Signet issued to the caller (an owner's `owner/grant`), or re-enroll after
+ * the enrollment or its idle window expired. `expectedRevision` is the Signet's current revision.
+ */
+export const enrollSignet = async (
+  url: string,
+  keyFile: string,
+  apiToken: string,
+  enrollment: { signetId: string; expectedRevision: number; name: string },
+  options: SignetRequestOptions = {},
+): Promise<EnrolledSignet> => ({
+  ...(await keyPost(
+    url,
+    keyFile,
+    'enrollSignet',
+    { ...enrollment, publicKey: signetPublicKey(await readPrivateJson(keyFile)) },
+    enrolledCredentialsSchema,
+    options,
+    { authorization: `Bearer ${apiToken}` },
+  )),
+  signetId: enrollment.signetId,
+});
+
+/** The Signets held by this installation's integrations. */
+export const installationSignets = (
+  url: string,
+  keyFile: string,
+  options: SignetRequestOptions = {},
+) => keyPost(url, keyFile, 'installationSignets', {}, installationSignetsResponseSchema, options);
+
 /** Enroll this installation's key on a Signet one of its integrations holds. */
 export const enrollInstallationSignet = (
   url: string,
@@ -338,14 +409,7 @@ export const enrollInstallationSignet = (
   signetId: string,
   options: SignetRequestOptions = {},
 ) =>
-  installationPost(
-    url,
-    keyFile,
-    'enrollInstallationSignet',
-    { signetId },
-    collectedSignetSchema,
-    options,
-  );
+  keyPost(url, keyFile, 'enrollInstallationSignet', { signetId }, collectedSignetSchema, options);
 
 /** Give Kingdom the credential it uses to reach this installation's integration (Foundry's tunnel token). */
 export const setInstallationCredential = (
@@ -355,7 +419,7 @@ export const setInstallationCredential = (
   token: string,
   options: SignetRequestOptions = {},
 ) =>
-  installationPost(
+  keyPost(
     url,
     keyFile,
     'setInstallationCredential',
@@ -380,7 +444,7 @@ export async function rotateInstallationKey(
     currentThumbprint,
     options,
   );
-  return installationPost(
+  return keyPost(
     url,
     keyFile,
     'rotateInstallationKey',
@@ -395,7 +459,7 @@ export async function saveCollectedSignet(
   credentialFile: string,
   url: string,
   keyFile: string,
-  collected: z.infer<typeof collectedSignetSchema>,
+  collected: DeliveredSignet,
 ) {
   const credential = signetCredentialSchema.parse({ ...collected, url, keyFile });
   await writePrivateJson(credentialFile, credential);