@inixiative/signet 0.3.0 → 0.4.0

package/README.md

@@ -10,17 +10,21 @@ This package is the one implementation of that protocol, shared by Kingdom (whic
 - `proof`: create and verify DPoP proofs (ES256, nonce-bound, access-token-bound).
 - `files`: private 0600 JSON files for keys and credentials.
 - `client`:
-  - an **Installation** (a local Foundry, Archive or Oracle) is an actor known to Kingdom by its key: `registerInstallation`, then `requestRegistration` returns a review code a person claims in Kingdom (a `registerIntegration` Inquiry), then `collectSignet` and `saveCollectedSignet`. `installationInquiries`, `installationSignets`, `cancelInstallationInquiry`, `enrollInstallationSignet` and `rotateInstallationKey` act as the installation;
+  - 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;
-  - `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`).
+  - `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
 import { holdInstallationSignets, InstallationSocket, pairInstallation, SignetClient } from '@inixiative/signet';
 
 const paired = await pairInstallation({
   url: kingdom, root: dataDir, kind: 'archive', name: 'Laptop Archive', sourceId,
-  terms: { name: 'Laptop Archive', lifecycle: 'ongoing', resources: [], expiresAt: null, maxRequests: null, maxConcurrent: 4 },
+  terms: {
+    name: 'Laptop Archive', lifecycle: 'ongoing', expiresAt: null, maxRequests: null, maxConcurrent: 4,
+    owner: { ownerModel: 'Organization', organization: 'inixiative' },
+    resources: [{ resourceKind: 'archiveLibrary', operations: ['sessions.write'] }],
+  },
   onReview: ({ review }) => console.log(`Approve in Kingdom: ${review}`),
   confirmOwner: async ({ ownerName }) => confirm(`Pair with ${ownerName}?`),
 });

package/package.json

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

package/src/client.ts

@@ -12,7 +12,7 @@ import {
   nonceSchema,
   ownerRefSchema,
   publicClientKeySchema,
-  type RegistrationTerms,
+  type RegistrationRequest,
   registerInstallationResponseSchema,
   renewalCredentialPattern,
   requestRegistrationResponseSchema,
@@ -249,7 +249,7 @@ export const registerInstallation = (
 export const requestRegistration = (
   url: string,
   keyFile: string,
-  terms: RegistrationTerms,
+  terms: RegistrationRequest,
   options: SignetRequestOptions = {},
 ) =>
   installationPost(
@@ -411,7 +411,9 @@ export type SignetAction =
   | 'resolveRun'
   | 'delegateRun'
   | 'renewRun'
-  | 'revokeRun';
+  | 'revokeRun'
+  | 'releaseSubscription'
+  | 'reportSubscriptionLimits';
 const signetActions: SignetAction[] = [
   'describe',
   'execute',
@@ -422,6 +424,8 @@ const signetActions: SignetAction[] = [
   'delegateRun',
   'renewRun',
   'revokeRun',
+  'releaseSubscription',
+  'reportSubscriptionLimits',
 ];
 
 /** Presents one enrolled Signet: renews its access token and signs each call with the device key. */

package/src/contracts.ts

@@ -104,12 +104,33 @@ 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. */
+/** The terms a person approves when registering an Installation as an owner's integration. */
 export const registrationTermsSchema = z.strictObject({
   ...signetTerms,
   lifecycle: z.literal('ongoing'),
   resources: z.array(signetResourceSchema).max(100),
 });
+/** The owner an Installation asks to belong to; `organization` is the organization's id or slug. */
+export const requestedOwnerSchema = z.strictObject({
+  ownerModel: ownerModelSchema,
+  organization: z.string().trim().min(1).max(120).optional(),
+  spaceId: z.uuid().optional(),
+});
+/** A resource asked for by kind, and optionally name, when the Installation does not know its id. */
+export const requestedResourceKindSchema = z.strictObject({
+  resourceKind: z.string().min(1).max(80),
+  resourceName: z.string().trim().min(1).max(120).optional(),
+  operations: z.array(z.string().min(1).max(80)).min(1).max(100),
+  lens: signetLensSchema.default({}),
+});
+export const requestedResourceSchema = z.union([signetResourceSchema, requestedResourceKindSchema]);
+/** What an Installation asks for: the owner it expects and the resources and operations it needs. */
+export const registrationRequestSchema = z.strictObject({
+  ...signetTerms,
+  lifecycle: z.literal('ongoing'),
+  owner: requestedOwnerSchema.optional(),
+  resources: z.array(requestedResourceSchema).max(100),
+});
 /** A person asks for a Signet on an integration, to be presented with `publicKey`. */
 export const signetRequestSchema = z.strictObject({
   ...signetTerms,
@@ -124,6 +145,9 @@ export const signetRequestResponseSchema = z.object({
 });
 export type SignetProposal = z.infer<typeof signetProposalSchema>;
 export type RegistrationTerms = z.infer<typeof registrationTermsSchema>;
+export type RequestedOwner = z.infer<typeof requestedOwnerSchema>;
+export type RequestedResource = z.input<typeof requestedResourceSchema>;
+export type RegistrationRequest = z.input<typeof registrationRequestSchema>;
 export type SignetRequest = z.infer<typeof signetRequestSchema>;
 export type SignetRequestResponse = z.infer<typeof signetRequestResponseSchema>;
 
@@ -139,7 +163,7 @@ export const registerInstallationSchema = z
     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 requestRegistrationSchema = z.strictObject({ terms: registrationRequestSchema });
 export const requestRegistrationResponseSchema = z.object({
   reviewCode: z.string(),
   expiresAt: z.iso.datetime(),

package/src/installationPairing.ts

@@ -12,7 +12,7 @@ import {
   saveCollectedSignet,
   signetCredentialSchema,
 } from './client';
-import type { InstallationKind, OwnerRef, RegistrationTerms } from './contracts';
+import type { InstallationKind, OwnerRef, RegistrationRequest } from './contracts';
 import { readPrivateJson, writePrivateJson } from './files';
 import { type InstallationSnapshot, InstallationSocket } from './installationSocket';
 
@@ -109,7 +109,7 @@ export type InstallationPairing = {
   kind: InstallationKind;
   name: string;
   sourceId?: string;
-  terms: RegistrationTerms;
+  terms: RegistrationRequest;
   onReview: (review: { reviewCode: string; review: string; expiresAt: string }) => void;
   confirmOwner?: (owner: { ownerName: string | null; owner: OwnerRef | null }) => Promise<boolean>;
   /** Failures while waiting (a poll Kingdom refused, a dropped socket); waiting continues. */