@inixiative/signet 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inixiative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @inixiative/signet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Present Kingdom Signets.
+
+A **Signet** is Kingdom's only grant for using an integration. It names the resources, operations, lens and limits, and it can be revoked. Its grantee is a user or an integration, for example a paired Foundry or a machine's local Archive. The grantee presents it with an access token plus a DPoP proof signed by its device key (RFC 9449).
+
+This package is the one implementation of that protocol, shared by Kingdom (which verifies) and Archive, Foundry and Oracle (which present):
+
+- `contracts`: the wire schemas: keys, lenses, proposals, pairing requests, delivered credentials, `describe` and `execute`.
+- `proof`: create and verify DPoP proofs (ES256, nonce-bound, access-token-bound).
+- `files`: private 0600 JSON files for keys and credentials.
+- `client`:
+  - device pairing: `requestPairing`, then the owner approves the review code in Kingdom, then `collectPairing` and `saveCollectedSignet`;
+  - `SignetClient`, which renews its access token and signs each `describe` / `execute` call.
+
+```ts
+import { collectPairing, generateClientKey, requestPairing, saveCollectedSignet, SignetClient, writePrivateJson } from '@inixiative/signet';
+
+await writePrivateJson(keyFile, generateClientKey());
+const pending = await requestPairing(kingdom, keyFile, {
+  provider: 'archive', name: 'Laptop Archive', resources: [], expiresAt: null, maxRequests: null, maxConcurrent: 4,
+});
+// Show pending.reviewCode; poll until approved (null while pending, until pending.expiresAt).
+const collected = await collectPairing(kingdom, keyFile, pending.deviceCode);
+await saveCollectedSignet(credentialFile, kingdom, keyFile, collected!);
+
+const signet = new SignetClient(credentialFile);
+const { operations } = await signet.describe();
+await signet.execute({ integrationId, operation: 'sessions.write', input: { resourceId, snapshot, previousDigest: null } });
+```
+
+MIT

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "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",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contracts": "./src/contracts.ts",
+    "./proof": "./src/proof.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "check": "bun run typecheck && bun run lint && bun run test",
+    "prepublishOnly": "bun run check",
+    "lint": "biome check .",
+    "prepare": "if git rev-parse --git-dir >/dev/null 2>&1; then lefthook install; fi"
+  },
+  "keywords": [
+    "kingdom",
+    "signet",
+    "dpop",
+    "access",
+    "grant"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.2",
+    "@inixiative/config": "^0.5.55",
+    "@types/bun": "1.4.2",
+    "lefthook": "2.1.9",
+    "typescript": "6.0.3",
+    "zod": "^4.3.6"
+  },
+  "packageManager": "bun@1.4.2",
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inixiative/signet.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.6"
+  }
+}

package/src/client.ts

@@ -0,0 +1,510 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { z } from 'zod';
+import {
+  type AccessRequest,
+  accessResultSchema,
+  accessTokenPattern,
+  collectedSignetSchema,
+  type InstallationKind,
+  installationInquiriesResponseSchema,
+  installationSignetsResponseSchema,
+  nonceSchema,
+  ownerRefSchema,
+  publicClientKeySchema,
+  type RegistrationTerms,
+  registerInstallationResponseSchema,
+  renewalCredentialPattern,
+  requestRegistrationResponseSchema,
+  signetDescriptionSchema,
+  signetKeySchema,
+  signetLifecycleSchema,
+} from './contracts';
+import { readPrivateJson, writePrivateJson } from './files';
+import { createSignetProof, keyThumbprint } from './proof';
+
+/** A Kingdom API origin: HTTPS, or HTTP on loopback, with no path or credentials. */
+export const kingdomUrl = (value: string) => {
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== '/' ||
+    (url.protocol !== 'https:' &&
+      !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))
+  )
+    throw Error('Kingdom requires an HTTPS origin or loopback HTTP');
+  return url.origin;
+};
+
+/** What a presenting client keeps on disk (0600) for one enrolled Signet. */
+export const signetCredentialSchema = z
+  .object({
+    url: z.string().transform(kingdomUrl),
+    signetId: z.uuid(),
+    integrationId: z.uuid().optional(),
+    owner: ownerRefSchema.optional(),
+    enrollmentId: z.uuid(),
+    lifecycle: signetLifecycleSchema,
+    taskId: z.uuid().nullable(),
+    keyFile: z.string().refine(isAbsolute),
+    renewalCredential: z.string().regex(renewalCredentialPattern),
+    accessToken: z.string().regex(accessTokenPattern),
+    expiresAt: z.iso.datetime(),
+    renewalExpiresAt: z.iso.datetime(),
+    idleExpiresAt: z.iso.datetime(),
+    tokenType: z.literal('DPoP'),
+  })
+  .strict();
+export type SignetCredential = z.infer<typeof signetCredentialSchema>;
+export const deliveredSignetSchema = signetCredentialSchema.omit({ url: true, keyFile: true });
+const renewalResponseSchema = deliveredSignetSchema.omit({
+  signetId: true,
+  integrationId: true,
+  owner: true,
+  renewalCredential: true,
+});
+const refreshing = new Map<string, Promise<SignetCredential>>();
+
+export const generateSignetKey = () =>
+  signetKeySchema.parse(
+    generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).privateKey.export({ format: 'jwk' }),
+  );
+export const signetPublicKey = (key: unknown) =>
+  publicClientKeySchema.parse(
+    createPublicKey(createPrivateKey({ key: signetKeySchema.parse(key), format: 'jwk' })).export({
+      format: 'jwk',
+    }),
+  );
+
+export class SignetHttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly detail?: string,
+  ) {
+    super(`Signet request refused (${status})${detail ? `: ${detail}` : ''}`);
+  }
+}
+export interface SignetRequestOptions {
+  signal?: AbortSignal;
+  /** Defaults to 20 s; raise it for large uploads. */
+  timeoutMs?: number;
+}
+const requestSignal = ({ signal, timeoutMs = 20000 }: SignetRequestOptions = {}) =>
+  signal
+    ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+    : AbortSignal.timeout(timeoutMs);
+
+/** Stop this caller waiting without canceling shared credential renewal. */
+function abortable<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) {
+    void pending.catch(() => {});
+    return Promise.reject(signal.reason);
+  }
+  return new Promise<T>((resolve, reject) => {
+    const aborted = () => reject(signal.reason);
+    signal.addEventListener('abort', aborted, { once: true });
+    pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted));
+  });
+}
+
+const errorDetail = async (response: Response) => {
+  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;
+  }
+};
+
+/** POST to Kingdom's access API and return the response's `data`. */
+export async function signetPost(
+  url: string,
+  action: string,
+  body: unknown,
+  headers: Record<string, string> = {},
+  onDispatch?: () => void,
+  options: SignetRequestOptions = {},
+): Promise<unknown> {
+  if (!/^[a-zA-Z]+$/.test(action)) throw Error('Invalid Signet action');
+  const signal = requestSignal(options);
+  signal.throwIfAborted();
+  const serialized = JSON.stringify(body);
+  onDispatch?.();
+  signal.throwIfAborted();
+  const pendingResponse = fetch(`${kingdomUrl(url)}/api/v1/access/${action}`, {
+    method: 'POST',
+    redirect: 'error',
+    signal,
+    headers: { 'content-type': 'application/json', ...headers },
+    body: serialized,
+  });
+  // Also close a response from a transport that settles after cancellation.
+  void pendingResponse.then(
+    (response) => {
+      if (signal.aborted) void response.body?.cancel().catch(() => {});
+    },
+    () => {},
+  );
+  const response = await abortable(pendingResponse, signal);
+  if (signal.aborted) {
+    void response.body?.cancel().catch(() => {});
+    signal.throwIfAborted();
+  }
+  if (!response.ok) throw new SignetHttpError(response.status, await errorDetail(response));
+  const reader = response.body?.getReader();
+  if (!reader) throw Error('Signet response unavailable');
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const next = await abortable(reader.read(), signal);
+      signal.throwIfAborted();
+      if (next.done) break;
+      bytes += next.value.byteLength;
+      if (bytes > 1_048_576) throw Error('Signet response exceeds limit');
+      chunks.push(next.value);
+    }
+  } finally {
+    void reader.cancel().catch(() => {});
+  }
+  signal.throwIfAborted();
+  return z.object({ data: z.unknown() }).parse(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+    .data;
+}
+
+/** A DPoP proof for one call to `action`, bound to a fresh Kingdom nonce (and the token, if any). */
+export async function signetProof(
+  url: string,
+  action: string,
+  keyFile: string,
+  token?: string,
+  options: SignetRequestOptions = {},
+): Promise<string> {
+  const signal = requestSignal(options);
+  signal.throwIfAborted();
+  const key = signetKeySchema.parse(await abortable(readPrivateJson(keyFile), signal));
+  signal.throwIfAborted();
+  const { nonce } = z
+    .object({ nonce: nonceSchema })
+    .parse(await signetPost(url, 'nonce', {}, {}, undefined, { signal }));
+  signal.throwIfAborted();
+  return createSignetProof({
+    privateKey: key,
+    publicKey: signetPublicKey(key),
+    nonce,
+    url: `${kingdomUrl(url)}/api/v1/access/${action}`,
+    method: 'POST',
+    token,
+  });
+}
+
+/** A call an Installation makes as itself: no access token, a DPoP proof by its key. */
+async function installationPost<T>(
+  url: string,
+  keyFile: string,
+  action: string,
+  body: unknown,
+  schema: z.ZodType<T>,
+  options: SignetRequestOptions = {},
+): Promise<T> {
+  return schema.parse(
+    await signetPost(
+      url,
+      action,
+      body,
+      { DPoP: await signetProof(url, action, keyFile, undefined, options) },
+      undefined,
+      options,
+    ),
+  );
+}
+
+/** Make this installation known to Kingdom. Idempotent for the same key. */
+export const registerInstallation = (
+  url: string,
+  keyFile: string,
+  installation: { kind: InstallationKind; name: string; sourceId?: string },
+  options: SignetRequestOptions = {},
+) =>
+  readPrivateJson(keyFile).then((key) =>
+    installationPost(
+      url,
+      keyFile,
+      'registerInstallation',
+      { ...installation, publicKey: signetPublicKey(key) },
+      registerInstallationResponseSchema,
+      options,
+    ),
+  );
+
+/** Ask to be registered as an integration; a person claims the review code in Kingdom. */
+export const requestRegistration = (
+  url: string,
+  keyFile: string,
+  terms: RegistrationTerms,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'requestRegistration',
+    { terms },
+    requestRegistrationResponseSchema,
+    options,
+  );
+
+/** This installation's pending request and its inquiries. */
+export const installationInquiries = (
+  url: string,
+  keyFile: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'installationInquiries',
+    {},
+    installationInquiriesResponseSchema,
+    options,
+  );
+
+export const cancelInstallationInquiry = (
+  url: string,
+  keyFile: string,
+  inquiryId: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'cancelInstallationInquiry',
+    { inquiryId },
+    z.object({ id: z.uuid() }),
+    options,
+  );
+
+/**
+ * Collect the Signet an approved inquiry minted. Returns null while it awaits review (Kingdom
+ * answers 409) and throws once it is declined, denied or past its delivery deadline (403).
+ */
+export async function collectSignet(
+  url: string,
+  keyFile: string,
+  inquiryId: string,
+  options: SignetRequestOptions = {},
+) {
+  try {
+    return await installationPost(
+      url,
+      keyFile,
+      'collectSignet',
+      { inquiryId },
+      collectedSignetSchema,
+      options,
+    );
+  } catch (error) {
+    if (error instanceof SignetHttpError && error.status === 409) return null;
+    throw error;
+  }
+}
+
+/** The Signets held by this installation's integrations. */
+export const installationSignets = (
+  url: string,
+  keyFile: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'installationSignets',
+    {},
+    installationSignetsResponseSchema,
+    options,
+  );
+
+/** Enroll this installation's key on a Signet one of its integrations holds. */
+export const enrollInstallationSignet = (
+  url: string,
+  keyFile: string,
+  signetId: string,
+  options: SignetRequestOptions = {},
+) =>
+  installationPost(
+    url,
+    keyFile,
+    'enrollInstallationSignet',
+    { signetId },
+    collectedSignetSchema,
+    options,
+  );
+
+/** Move this installation to a new key; both keys sign, the new proof bound to the current key. */
+export async function rotateInstallationKey(
+  url: string,
+  keyFile: string,
+  newKeyFile: string,
+  options: SignetRequestOptions = {},
+) {
+  const publicKey = signetPublicKey(await readPrivateJson(newKeyFile));
+  const currentThumbprint = await keyThumbprint(signetPublicKey(await readPrivateJson(keyFile)));
+  const proof = await signetProof(
+    url,
+    'rotateInstallationKey',
+    newKeyFile,
+    currentThumbprint,
+    options,
+  );
+  return installationPost(
+    url,
+    keyFile,
+    'rotateInstallationKey',
+    { publicKey, proof },
+    registerInstallationResponseSchema,
+    options,
+  );
+}
+
+/** Write a collected Signet next to its key; the file is what a SignetClient presents. */
+export async function saveCollectedSignet(
+  credentialFile: string,
+  url: string,
+  keyFile: string,
+  collected: z.infer<typeof collectedSignetSchema>,
+) {
+  const credential = signetCredentialSchema.parse({ ...collected, url, keyFile });
+  await writePrivateJson(credentialFile, credential);
+  return credential;
+}
+
+export type SignetAction = 'describe' | 'execute' | 'closeTask' | 'verifyAuthority' | 'settleTask';
+const signetActions: SignetAction[] = [
+  'describe',
+  'execute',
+  'closeTask',
+  'verifyAuthority',
+  'settleTask',
+];
+
+/** Presents one enrolled Signet: renews its access token and signs each call with the device key. */
+export class SignetClient {
+  constructor(
+    readonly url: string,
+    private credentialFile: string,
+    private signetId: string,
+  ) {
+    this.url = kingdomUrl(url);
+  }
+  /** A client for the Signet a credential file holds. */
+  static async fromFile(credentialFile: string) {
+    const credential = signetCredentialSchema.parse(await readPrivateJson(credentialFile));
+    return new SignetClient(credential.url, credentialFile, credential.signetId);
+  }
+  private async credentials(force = false, signal = requestSignal(), allowRenewal = true) {
+    signal.throwIfAborted();
+    const credential = signetCredentialSchema.parse(
+      await abortable(readPrivateJson(this.credentialFile), signal),
+    );
+    signal.throwIfAborted();
+    if (credential.url !== this.url || credential.signetId !== this.signetId)
+      throw Error('Signet credential audience mismatch');
+    if (Date.parse(credential.idleExpiresAt) <= Date.now())
+      throw Error('Signet enrollment idle timeout; enroll this device again');
+    if (!allowRenewal) {
+      if (Date.parse(credential.expiresAt) <= Date.now())
+        throw Error('Task settlement requires an unexpired existing access token');
+      return credential;
+    }
+    if (!force && Date.parse(credential.expiresAt) > Date.now() + 30000) return credential;
+    if (Date.parse(credential.renewalExpiresAt) <= Date.now())
+      throw Error('Signet enrollment expired; request renewed approval');
+    const existing = refreshing.get(this.credentialFile);
+    if (existing) return abortable(existing, signal);
+    const refresh = (async () => {
+      // Renewal belongs to the credential file, not the first waiting caller.
+      const refreshSignal = requestSignal();
+      const response = renewalResponseSchema.parse(
+        await signetPost(
+          this.url,
+          'renewSignet',
+          { renewalCredential: credential.renewalCredential },
+          {
+            DPoP: await signetProof(this.url, 'renewSignet', credential.keyFile, undefined, {
+              signal: refreshSignal,
+            }),
+          },
+          undefined,
+          { signal: refreshSignal },
+        ),
+      );
+      if (
+        response.enrollmentId !== credential.enrollmentId ||
+        response.lifecycle !== credential.lifecycle ||
+        response.taskId !== credential.taskId
+      )
+        throw Error('Signet enrollment changed');
+      const updated = signetCredentialSchema.parse({ ...credential, ...response });
+      await writePrivateJson(this.credentialFile, updated);
+      return updated;
+    })();
+    refreshing.set(this.credentialFile, refresh);
+    const settled = refresh.finally(() => refreshing.delete(this.credentialFile));
+    return abortable(settled, signal);
+  }
+  async renew(options: SignetRequestOptions = {}): Promise<void> {
+    const signal = requestSignal(options);
+    await this.credentials(true, signal);
+    signal.throwIfAborted();
+  }
+  async post(
+    action: SignetAction,
+    body: unknown,
+    onDispatch?: () => void,
+    options: SignetRequestOptions = {},
+  ) {
+    if (!signetActions.includes(action)) throw Error('Unsupported Signet action');
+    const signal = requestSignal(options);
+    signal.throwIfAborted();
+    const credential = await this.credentials(false, signal, action !== 'settleTask');
+    signal.throwIfAborted();
+    const proof = await signetProof(this.url, action, credential.keyFile, credential.accessToken, {
+      signal,
+      timeoutMs: options.timeoutMs,
+    });
+    signal.throwIfAborted();
+    return signetPost(
+      this.url,
+      action,
+      body,
+      { authorization: `DPoP ${credential.accessToken}`, DPoP: proof },
+      onDispatch,
+      { signal, timeoutMs: options.timeoutMs },
+    );
+  }
+  async describe(options: SignetRequestOptions = {}) {
+    return signetDescriptionSchema.parse(
+      await this.post('describe', { signetId: this.signetId }, undefined, options),
+    );
+  }
+  /** Run one integration operation through the Signet; every call is a new request id. */
+  async execute(
+    request: Omit<AccessRequest, 'requestId' | 'signetId'>,
+    options: SignetRequestOptions = {},
+  ) {
+    return accessResultSchema.parse(
+      await this.post(
+        'execute',
+        { ...request, signetId: this.signetId, requestId: crypto.randomUUID() },
+        undefined,
+        options,
+      ),
+    );
+  }
+}

package/src/contracts.ts

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+
+const token43 = /^[A-Za-z0-9_-]{43}$/;
+
+export const accessTokenPattern = /^kingdom_[A-Za-z0-9_-]{43}$/;
+export const renewalCredentialPattern = /^signet_renew_[A-Za-z0-9_-]{43}$/;
+export const nonceSchema = z.string().regex(token43);
+
+export const archiveDocumentIdSchema = z.string().regex(/^[a-f0-9]{64}$/);
+export const archiveFieldSchema = z.enum(['id', 'title', 'content', 'tags', 'createdAt']);
+export type ArchiveField = z.infer<typeof archiveFieldSchema>;
+
+export const ownerModelSchema = z.enum([
+  'User',
+  'OrganizationUser',
+  'Organization',
+  'Space',
+  'SpaceUser',
+]);
+export const ownerRefSchema = z.object({
+  ownerModel: ownerModelSchema,
+  userId: z.uuid().nullable(),
+  organizationId: z.uuid().nullable(),
+  spaceId: z.uuid().nullable(),
+});
+export type OwnerRef = z.infer<typeof ownerRefSchema>;
+
+export const publicClientKeySchema = z.strictObject({
+  kty: z.literal('EC'),
+  crv: z.literal('P-256'),
+  x: z.string().regex(token43),
+  y: z.string().regex(token43),
+});
+export const signetKeySchema = publicClientKeySchema.extend({
+  d: z.string().regex(token43),
+});
+export type PublicClientKey = z.infer<typeof publicClientKeySchema>;
+export type SignetKey = z.infer<typeof signetKeySchema>;
+
+export const signetLensSchema = z.strictObject({
+  documentIds: z.array(archiveDocumentIdSchema).max(1000).optional(),
+  fields: z.array(archiveFieldSchema).max(6).optional(),
+});
+export const signetResourceSchema = z.strictObject({
+  resourceId: z.uuid(),
+  operations: z.array(z.string().min(1).max(80)).min(1).max(100),
+  lens: signetLensSchema.default({}),
+});
+export const signetRecipientSchema = z.discriminatedUnion('recipientModel', [
+  z.strictObject({ recipientModel: z.literal('User'), userId: z.uuid() }),
+  z.strictObject({ recipientModel: z.literal('Integration'), integrationId: z.uuid() }),
+]);
+export const signetLifecycleSchema = z.enum(['request', 'task', 'ongoing']);
+export type SignetLens = z.infer<typeof signetLensSchema>;
+export type SignetRecipient = z.infer<typeof signetRecipientSchema>;
+export type SignetResource = z.infer<typeof signetResourceSchema>;
+
+export const signetEnrollmentSchema = z.strictObject({
+  signetId: z.uuid(),
+  runtimeInstallationId: z.uuid().optional(),
+  expectedRevision: z.number().int().min(1),
+  name: z.string().trim().min(1).max(120),
+  publicKey: publicClientKeySchema,
+});
+export const signetRenewSchema = z.strictObject({
+  renewalCredential: z.string().regex(renewalCredentialPattern),
+});
+export const signetCredentialsSchema = z.object({
+  enrollmentId: z.uuid(),
+  lifecycle: signetLifecycleSchema,
+  taskId: z.uuid().nullable(),
+  accessToken: z.string().regex(accessTokenPattern),
+  renewalCredential: z.string().regex(renewalCredentialPattern).optional(),
+  expiresAt: z.iso.datetime(),
+  renewalExpiresAt: z.iso.datetime(),
+  idleExpiresAt: z.iso.datetime(),
+  tokenType: z.literal('DPoP'),
+});
+export const collectedSignetSchema = signetCredentialsSchema.extend({
+  renewalCredential: z.string().regex(renewalCredentialPattern),
+  signetId: z.uuid(),
+  integrationId: z.uuid(),
+  owner: ownerRefSchema,
+});
+export type SignetCredentials = z.infer<typeof signetCredentialsSchema>;
+export type CollectedSignet = z.infer<typeof collectedSignetSchema>;
+
+const signetTerms = {
+  name: z.string().trim().min(1).max(120),
+  lifecycle: signetLifecycleSchema,
+  taskId: z.uuid().optional(),
+  expiresAt: z.iso.datetime().nullable(),
+  maxRequests: z.number().int().min(1).max(100000).nullable(),
+  maxConcurrent: z.number().int().min(1).max(20),
+};
+/** A local Foundry, Archive or Oracle known to Kingdom by its key. */
+export const installationKindSchema = z.enum(['foundry', 'archive', 'oracle']);
+export type InstallationKind = z.infer<typeof installationKindSchema>;
+export const signetProposalSchema = z.strictObject({
+  ...signetTerms,
+  integrationId: z.uuid(),
+  resources: z.array(signetResourceSchema).min(1).max(100),
+});
+export const signetReviewProposalSchema = z.strictObject({
+  ...signetTerms,
+  resources: z.array(signetResourceSchema).max(100),
+});
+/** What an Installation asks for when it asks to be registered as an owner's integration. */
+export const registrationTermsSchema = z.strictObject({
+  ...signetTerms,
+  lifecycle: z.literal('ongoing'),
+  resources: z.array(signetResourceSchema).max(100),
+});
+/** A person asks for a Signet on an integration, to be presented with `publicKey`. */
+export const signetRequestSchema = z.strictObject({
+  ...signetTerms,
+  integrationId: z.uuid(),
+  resources: z.array(signetResourceSchema).min(1).max(100),
+  publicKey: publicClientKeySchema,
+});
+export const signetRequestResponseSchema = z.object({
+  requestId: z.uuid(),
+  reviewCode: z.string(),
+  expiresAt: z.iso.datetime(),
+});
+export type SignetProposal = z.infer<typeof signetProposalSchema>;
+export type RegistrationTerms = z.infer<typeof registrationTermsSchema>;
+export type SignetRequest = z.infer<typeof signetRequestSchema>;
+export type SignetRequestResponse = z.infer<typeof signetRequestResponseSchema>;
+
+/** A local Archive names its sourceId; Kingdom binds every write through its Signets to it. */
+export const registerInstallationSchema = z
+  .strictObject({
+    kind: installationKindSchema,
+    name: z.string().trim().min(1).max(120),
+    sourceId: z.uuid().optional(),
+    publicKey: publicClientKeySchema,
+  })
+  .refine((value) => value.kind !== 'archive' || Boolean(value.sourceId), {
+    message: 'A local Archive registers with its sourceId',
+  });
+export const registerInstallationResponseSchema = z.object({ installationId: z.uuid() });
+export const requestRegistrationSchema = z.strictObject({ terms: registrationTermsSchema });
+export const requestRegistrationResponseSchema = z.object({
+  reviewCode: z.string(),
+  expiresAt: z.iso.datetime(),
+});
+export const installationInquirySchema = z.object({
+  id: z.uuid(),
+  type: z.string(),
+  status: z.enum(['draft', 'sent', 'changesRequested', 'approved', 'denied', 'canceled']),
+  createdAt: z.iso.datetime(),
+  expiresAt: z.iso.datetime().nullable(),
+  owner: ownerRefSchema.nullable(),
+  ownerName: z.string().nullable(),
+  integrationId: z.uuid().nullable(),
+  signetId: z.uuid().nullable(),
+  deliverBefore: z.iso.datetime().nullable(),
+});
+export const installationInquiriesResponseSchema = z.object({
+  pending: z.object({ reviewCode: z.string(), expiresAt: z.iso.datetime() }).nullable(),
+  declinedAt: z.iso.datetime().nullable(),
+  inquiries: z.array(installationInquirySchema),
+});
+export const inquiryReferenceSchema = z.strictObject({ inquiryId: z.uuid() });
+export const installationSignetsResponseSchema = z.object({
+  signets: z.array(
+    z.object({
+      signetId: z.uuid(),
+      integrationId: z.uuid(),
+      name: z.string(),
+      owner: ownerRefSchema,
+    }),
+  ),
+});
+export const enrollInstallationSignetSchema = z.strictObject({ signetId: z.uuid() });
+export const rotateInstallationKeySchema = z.strictObject({
+  publicKey: publicClientKeySchema,
+  proof: z.string().max(8192),
+});
+export type InstallationInquiry = z.infer<typeof installationInquirySchema>;
+
+export const signetDescriptionSchema = z.object({
+  signetId: z.uuid(),
+  integrationId: z.uuid(),
+  provider: z.string().nullable(),
+  name: z.string(),
+  expiresAt: z.iso.datetime().nullable(),
+  lifecycle: signetLifecycleSchema,
+  taskId: z.uuid().nullable(),
+  currentRevision: z.number().int(),
+  remainingRequests: z.number().nullable(),
+  operations: z.array(
+    z.object({
+      key: z.string(),
+      name: z.string(),
+      resources: z.array(
+        z.object({ id: z.uuid(), name: z.string(), kind: z.string(), integrationId: z.uuid() }),
+      ),
+    }),
+  ),
+});
+export type SignetDescription = z.infer<typeof signetDescriptionSchema>;
+
+/** Operation-specific fields; Kingdom validates each against the operation it names. */
+export const accessInputSchema = z.strictObject({
+  resourceId: z.uuid(),
+  documentId: archiveDocumentIdSchema.optional(),
+  fields: z.array(archiveFieldSchema).min(1).max(5).optional(),
+  limit: z.number().int().min(1).max(50).default(20),
+  query: z.string().max(1000).optional(),
+  projectId: z.string().min(1).max(256).optional(),
+  tag: z.string().min(1).max(120).optional(),
+  budget: z.number().int().min(16).max(32768).optional(),
+  snapshot: z.record(z.string(), z.unknown()).optional(),
+  previousDigest: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .nullable()
+    .optional(),
+});
+export const accessRequestSchema = z.strictObject({
+  requestId: z.uuid(),
+  taskId: z.uuid().optional(),
+  runId: z.uuid().optional(),
+  integrationId: z.uuid(),
+  signetId: z.uuid(),
+  operation: z.string().min(1).max(80),
+  input: accessInputSchema,
+});
+export type AccessRequest = z.infer<typeof accessRequestSchema>;
+export const accessResultSchema = z.object({ executionId: z.uuid(), result: z.unknown() });

package/src/files.ts

@@ -0,0 +1,44 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/** Reads a private JSON file: owned by this user, mode 0600, not a link. */
+export async function readPrivateJson(path: string): Promise<unknown> {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await file.stat();
+    if (
+      !stat.isFile() ||
+      stat.nlink !== 1 ||
+      stat.size > 65536 ||
+      (stat.mode & 0o077) !== 0 ||
+      (process.getuid && stat.uid !== process.getuid())
+    )
+      throw Error('Signet credential file must be an owned private regular file (0600)');
+    return JSON.parse(await file.readFile('utf8'));
+  } finally {
+    await file.close();
+  }
+}
+
+/** Atomically writes a private JSON file into an owned 0700 directory, creating it if absent. */
+export async function writePrivateJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const parent = await lstat(dirname(path));
+  if (
+    !parent.isDirectory() ||
+    parent.isSymbolicLink() ||
+    (parent.mode & 0o077) !== 0 ||
+    (process.getuid && parent.uid !== process.getuid())
+  )
+    throw Error('Signet credential directory must be owned and private (0700)');
+  const temporary = join(dirname(path), `.credential-${crypto.randomUUID()}`);
+  try {
+    await writeFile(temporary, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './client';
+export * from './contracts';
+export * from './files';
+export * from './proof';

package/src/proof.ts

@@ -0,0 +1,83 @@
+import {
+  calculateJwkThumbprint,
+  decodeProtectedHeader,
+  importJWK,
+  type JWK,
+  jwtVerify,
+  SignJWT,
+} from 'jose';
+import { publicClientKeySchema } from './contracts';
+
+export const digestCredential = async (value: string): Promise<string> =>
+  Buffer.from(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value))).toString(
+    'base64url',
+  );
+export const proofTarget = (url: string): string => {
+  const target = new URL(url);
+  target.search = '';
+  target.hash = '';
+  return target.href;
+};
+export const verifySignetProof = async (input: {
+  proof: string;
+  url: string;
+  method: string;
+  now: Date;
+  token?: string;
+  keyThumbprint?: string;
+}) => {
+  if (input.proof.length > 8192) throw new Error('Invalid proof');
+  const header = decodeProtectedHeader(input.proof);
+  const publicKey = publicClientKeySchema.parse(header.jwk);
+  const keyThumbprint = await calculateJwkThumbprint(publicKey);
+  if (input.keyThumbprint && input.keyThumbprint !== keyThumbprint)
+    throw new Error('Wrong proof key');
+  const { payload } = await jwtVerify(input.proof, await importJWK(publicKey, 'ES256'), {
+    algorithms: ['ES256'],
+    typ: 'dpop+jwt',
+    currentDate: input.now,
+    requiredClaims: ['iat', 'jti', 'htu', 'htm', 'nonce'],
+  });
+  const now = Math.floor(input.now.getTime() / 1000);
+  if (
+    !Number.isInteger(payload.iat) ||
+    payload.iat! < now - 60 ||
+    payload.iat! > now + 5 ||
+    typeof payload.jti !== 'string' ||
+    payload.jti.length < 16 ||
+    payload.jti.length > 128 ||
+    typeof payload.nonce !== 'string' ||
+    !/^[A-Za-z0-9_-]{43}$/.test(payload.nonce) ||
+    payload.htu !== proofTarget(input.url) ||
+    payload.htm !== input.method.toUpperCase() ||
+    (input.token && payload.ath !== (await digestCredential(input.token)))
+  )
+    throw new Error('Invalid proof binding');
+  return { publicKey, keyThumbprint, proofId: payload.jti, nonce: payload.nonce };
+};
+export const createSignetProof = async (input: {
+  privateKey: JWK;
+  publicKey: JWK;
+  nonce: string;
+  url: string;
+  method: string;
+  token?: string;
+  proofId?: string;
+}) =>
+  new SignJWT({
+    htu: proofTarget(input.url),
+    htm: input.method.toUpperCase(),
+    nonce: input.nonce,
+    ...(input.token ? { ath: await digestCredential(input.token) } : {}),
+  })
+    .setProtectedHeader({
+      alg: 'ES256',
+      typ: 'dpop+jwt',
+      jwk: publicClientKeySchema.parse(input.publicKey),
+    })
+    .setIssuedAt()
+    .setJti(input.proofId ?? crypto.randomUUID())
+    .sign(await importJWK(input.privateKey, 'ES256'));
+
+export const keyThumbprint = (key: unknown) =>
+  calculateJwkThumbprint(publicClientKeySchema.parse(key));