@inixiative/signet 0.1.0 → 0.2.1

package/package.json

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

package/src/client.ts

@@ -6,18 +6,22 @@ import {
   accessResultSchema,
   accessTokenPattern,
   collectedSignetSchema,
-  type IntegrationPairingProposal,
+  type InstallationKind,
+  installationInquiriesResponseSchema,
+  installationSignetsResponseSchema,
   nonceSchema,
   ownerRefSchema,
   publicClientKeySchema,
+  type RegistrationTerms,
+  registerInstallationResponseSchema,
   renewalCredentialPattern,
+  requestRegistrationResponseSchema,
   signetDescriptionSchema,
   signetKeySchema,
   signetLifecycleSchema,
-  signetRequestResponseSchema,
 } from './contracts';
 import { readPrivateJson, writePrivateJson } from './files';
-import { createSignetProof } from './proof';
+import { createSignetProof, keyThumbprint } from './proof';
 
 /** A Kingdom API origin: HTTPS, or HTTP on loopback, with no path or credentials. */
 export const kingdomUrl = (value: string) => {
@@ -201,48 +205,109 @@ export async function signetProof(
   });
 }
 
-export type PairingTerms = Omit<IntegrationPairingProposal, 'lifecycle' | 'taskId'>;
-
-/** Ask Kingdom to pair this device as an integration; the owner approves the review code. */
-export async function requestPairing(
+/** A call an Installation makes as itself: no access token, a DPoP proof by its key. */
+async function installationPost<T>(
   url: string,
   keyFile: string,
-  terms: PairingTerms,
+  action: string,
+  body: unknown,
+  schema: z.ZodType<T>,
   options: SignetRequestOptions = {},
-) {
-  const publicKey = signetPublicKey(await readPrivateJson(keyFile));
-  return signetRequestResponseSchema.parse(
+): Promise<T> {
+  return schema.parse(
     await signetPost(
       url,
-      'requestSignet',
-      { ...terms, lifecycle: 'ongoing', publicKey },
-      { DPoP: await signetProof(url, 'requestSignet', keyFile, undefined, options) },
+      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 an approved pairing. Returns null while it awaits review (Kingdom answers 409; stop
- * polling at the request's expiresAt) and throws once it is denied (403).
+ * 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 collectPairing(
+export async function collectSignet(
   url: string,
   keyFile: string,
-  deviceCode: string,
+  inquiryId: string,
   options: SignetRequestOptions = {},
 ) {
   try {
-    return collectedSignetSchema.parse(
-      await signetPost(
-        url,
-        'collectSignet',
-        { deviceCode },
-        { DPoP: await signetProof(url, 'collectSignet', keyFile, undefined, options) },
-        undefined,
-        options,
-      ),
+    return await installationPost(
+      url,
+      keyFile,
+      'collectSignet',
+      { inquiryId },
+      collectedSignetSchema,
+      options,
     );
   } catch (error) {
     if (error instanceof SignetHttpError && error.status === 409) return null;
@@ -250,7 +315,64 @@ export async function collectPairing(
   }
 }
 
-/** Write a collected pairing next to its key; the file is what a SignetClient presents. */
+/** 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,

package/src/contracts.ts

@@ -5,7 +5,6 @@ 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 deviceCodeSchema = z.string().regex(token43);
 
 export const archiveDocumentIdSchema = z.string().regex(/^[a-f0-9]{64}$/);
 export const archiveFieldSchema = z.enum(['id', 'title', 'content', 'tags', 'createdAt']);
@@ -94,58 +93,93 @@ const signetTerms = {
   maxRequests: z.number().int().min(1).max(100000).nullable(),
   maxConcurrent: z.number().int().min(1).max(20),
 };
-/** Kinds of integration a device can pair as; approval creates one and issues it a Signet. */
-export const pairableProviderSchema = z.enum(['foundry', 'archive']);
-export type PairableProvider = z.infer<typeof pairableProviderSchema>;
+/** 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),
 });
-/** A local Archive names its sourceId; Kingdom binds every write through its Signets to it. */
-const deviceIdentity = (value: { provider?: PairableProvider; deviceId?: string }) =>
-  value.provider !== 'archive' || z.uuid().safeParse(value.deviceId).success;
-const deviceIdentityMessage = { message: 'A local Archive pairs with its sourceId as deviceId' };
-export const integrationPairingProposalSchema = z
-  .strictObject({
-    ...signetTerms,
-    provider: pairableProviderSchema,
-    deviceId: z.string().min(1).max(256).optional(),
-    resources: z.array(signetResourceSchema).max(100),
-    lifecycle: z.literal('ongoing'),
-  })
-  .refine(deviceIdentity, deviceIdentityMessage);
-export const signetRequestSchema = z
-  .strictObject({
-    ...signetTerms,
-    integrationId: z.uuid().optional(),
-    provider: pairableProviderSchema.optional(),
-    deviceId: z.string().min(1).max(256).optional(),
-    resources: z.array(signetResourceSchema).max(100),
-    publicKey: publicClientKeySchema,
-  })
-  .refine((value) => Boolean(value.integrationId) !== Boolean(value.provider), {
-    message: 'Name the host integration, or the kind of integration to pair',
-  })
-  .refine((value) => Boolean(value.provider) || !value.deviceId, {
-    message: 'Only integration pairing names a device',
-  })
-  .refine(deviceIdentity, deviceIdentityMessage);
+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(),
-  deviceCode: deviceCodeSchema,
   expiresAt: z.iso.datetime(),
 });
-export const signetReviewProposalSchema = z.strictObject({
-  ...signetTerms,
-  resources: z.array(signetResourceSchema).max(100),
-});
 export type SignetProposal = z.infer<typeof signetProposalSchema>;
-export type IntegrationPairingProposal = z.infer<typeof integrationPairingProposalSchema>;
+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(),