@inixiative/signet 0.5.1 → 0.6.1

package/README.md

@@ -57,6 +57,12 @@ const signet = await SignetClient.fromFile(credentialFile);
 await signet.describe();
 ```
 
+## Declared operations
+
+An integration whose operations Kingdom executes generically declares them here, one module per resource kind: `threads.ts` for a Foundry's `threads` resource, `archive.ts` for an Archive's `archiveLibrary`. Each declares its operation enum, display names, the input each operation takes, its lens schema and the lens's narrowing. `declaredOperationSchema` and `operationInputSchemas` join them (operation names are unique across contracts), `operationInputKeys(operation)` gives the `access/execute` keys an operation takes besides `resourceId` and `limit`, and `operationInputFromAccess(operation, input)` picks and parses exactly those. Kingdom's catalog, its input check and its dispatch read these, so a new operation is added here first.
+
+- **Archive** (`archiveLibrary`): `documents.read`, `documents.search`, `sessions.write`, `sessions.delete`. The lens is `{ documentIds?, fields? }` (`{}` reaches every document) and `narrowsArchiveLens` narrows it. `archiveSourceOperations` (`sessions.write`, `sessions.delete`) are a paired local Archive acting on its own sessions: Kingdom binds them to its `sourceId`, so their grant takes no lens. `archiveLensRefusal(operation, lens)` says why a grant can't carry a lens (search needs content over every document).
+
 ## Agent conversations
 
 A conversation wraps a host Foundry's main thread (Kingdom `docs/AGENT-CONVERSATIONS.md`, Foundry `docs/reference/CONVERSATIONS.md`). A member is a Signet on the host Foundry's one `threads` resource; Kingdom admits each call and relays it over the host's Installation socket, and stores no conversation or message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.5.1",
+  "version": "0.6.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",
@@ -35,15 +35,15 @@
   "devDependencies": {
     "@asteasolutions/zod-to-openapi": "^9.1.0",
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.116",
-    "@types/bun": "1.4.2",
+    "@inixiative/config": "^0.5.157",
+    "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",
     "zod": "^4.3.6"
   },
-  "packageManager": "bun@1.4.2",
+  "packageManager": "bun@1.4.4",
   "engines": {
-    "bun": ">=1.4.2"
+    "bun": ">=1.4.4"
   },
   "repository": {
     "type": "git",

package/src/archive.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+
+/**
+ * Archive libraries (Kingdom `docs/kingdom.md`, Archive `docs/KINGDOM.md`). A hosted Archive is an
+ * integration with one `archiveLibrary` resource. Kingdom admits each call through a Signet and runs
+ * it against that Archive with the integration's credential. The Archive server never sees the lens,
+ * so Kingdom applies it.
+ */
+export const archiveLibraryResourceKind = 'archiveLibrary';
+
+/** An Archive session id: `archiveKey(snapshot)`, the digest of its source and session. */
+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>;
+
+/** Which documents and fields of an `archiveLibrary` a grant reaches; `{}` reaches all of them. */
+export const archiveLensSchema = z.strictObject({
+  documentIds: z.array(archiveDocumentIdSchema).max(1000).optional(),
+  fields: z.array(archiveFieldSchema).max(6).optional(),
+});
+export type ArchiveLens = z.infer<typeof archiveLensSchema>;
+
+const subset = <T>(granted: T[] | undefined, requested: T[] | undefined) =>
+  !requested || (granted !== undefined && granted.every((item) => requested.includes(item)));
+
+/** `granted` reaches no document or field `requested` doesn't. */
+export const narrowsArchiveLens = (granted: ArchiveLens, requested: ArchiveLens): boolean =>
+  subset(granted.documentIds, requested.documentIds) && subset(granted.fields, requested.fields);
+
+/** The operations an `archiveLibrary` resource carries. */
+export const archiveOperationSchema = z.enum([
+  'documents.read',
+  'documents.search',
+  'sessions.write',
+  'sessions.delete',
+]);
+export type ArchiveOperation = z.infer<typeof archiveOperationSchema>;
+
+export const archiveOperationNames: Record<ArchiveOperation, string> = {
+  'documents.read': 'Read permitted archive documents',
+  'documents.search': 'Search permitted archive documents',
+  'sessions.write': 'Write sessions from a paired local Archive',
+  'sessions.delete': 'Delete sessions a paired local Archive wrote',
+};
+
+/**
+ * Operations a paired local Archive runs on its own sessions: Kingdom binds each one to the
+ * Archive's `sourceId`, so a grant of them takes no lens.
+ */
+export const archiveSourceOperations = [
+  'sessions.write',
+  'sessions.delete',
+] as const satisfies readonly ArchiveOperation[];
+export const isArchiveSourceOperation = (operation: ArchiveOperation) =>
+  (archiveSourceOperations as readonly ArchiveOperation[]).includes(operation);
+
+const fieldsSchema = z.array(archiveFieldSchema).min(1).max(5);
+
+/**
+ * The input each Archive operation takes. `access/execute` carries the same fields beside
+ * `resourceId` and `limit` (`accessInputSchema`); Kingdom allows exactly these keys per operation.
+ */
+export const archiveInputSchemas = {
+  /** Without `documentId`, the newest documents the lens reaches, up to `limit`. */
+  'documents.read': z.strictObject({
+    documentId: archiveDocumentIdSchema.optional(),
+    fields: fieldsSchema.optional(),
+  }),
+  'documents.search': z.strictObject({
+    query: z.string().max(1000).optional(),
+    budget: z.number().int().min(16).max(32768).optional(),
+    fields: fieldsSchema.optional(),
+    projectId: z.string().min(1).max(256).optional(),
+    tag: z.string().min(1).max(120).optional(),
+  }),
+  /**
+   * An Archive snapshot (`@inixiative/archive`), parsed by Kingdom before it is stored. `restore`
+   * brings back a session deleted at the hosted Archive on purpose (a routed part sent back), which
+   * its tombstone otherwise refuses.
+   */
+  'sessions.write': z.strictObject({
+    snapshot: z.record(z.string(), z.unknown()),
+    previousDigest: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .nullable()
+      .optional(),
+    restore: z.boolean().optional(),
+  }),
+  'sessions.delete': z.strictObject({ documentId: archiveDocumentIdSchema }),
+} as const satisfies Record<ArchiveOperation, z.ZodObject>;
+
+/** Why a grant of `operation` can't carry `lens`, or null when it can. */
+export const archiveLensRefusal = (operation: ArchiveOperation, lens: ArchiveLens) => {
+  if (isArchiveSourceOperation(operation) && Object.keys(lens).length > 0)
+    return 'Writing or deleting sessions takes no lens';
+  if (
+    operation === 'documents.search' &&
+    (lens.documentIds || (lens.fields && !lens.fields.includes('content')))
+  )
+    return 'Search needs a lens that shows content and is not limited to chosen documents';
+  return null;
+};

package/src/contracts.ts

@@ -1,16 +1,26 @@
 import { z } from 'zod';
+import {
+  archiveDocumentIdSchema,
+  archiveFieldSchema,
+  archiveInputSchemas,
+  archiveLensSchema,
+  archiveLibraryResourceKind,
+  archiveOperationSchema,
+  narrowsArchiveLens,
+} from './archive';
 import {
   foundryIdSchema,
   narrowsThreadsLens,
-  type ThreadOperation,
   threadFloorActionSchema,
   threadIdSchema,
   threadInputSchemas,
+  threadOperationSchema,
   threadsLensSchema,
   threadsResourceKind,
   threadTextLimit,
 } from './threads';
 
+export * from './archive';
 export * from './threads';
 
 const token43 = /^[A-Za-z0-9_-]{43}$/;
@@ -19,10 +29,6 @@ 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',
@@ -50,14 +56,6 @@ export const signetKeySchema = publicClientKeySchema.extend({
 export type PublicClientKey = z.infer<typeof publicClientKeySchema>;
 export type SignetKey = z.infer<typeof signetKeySchema>;
 
-/** The resource kind of a hosted Archive library: one per Archive integration. */
-export const archiveLibraryResourceKind = 'archiveLibrary';
-/** Which documents and fields of an `archiveLibrary` a grant reaches; `{}` reaches all of them. */
-export const archiveLensSchema = z.strictObject({
-  documentIds: z.array(archiveDocumentIdSchema).max(1000).optional(),
-  fields: z.array(archiveFieldSchema).max(6).optional(),
-});
-export type ArchiveLens = z.infer<typeof archiveLensSchema>;
 /** Every other resource kind takes no lens. */
 export const emptyLensSchema = z.strictObject({});
 
@@ -78,9 +76,6 @@ export const resourceLensSchema = (kind: string) =>
       ? threadsLensSchema
       : emptyLensSchema;
 
-const subset = <T>(granted: T[] | undefined, requested: T[] | undefined) =>
-  !requested || (granted !== undefined && granted.every((item) => requested.includes(item)));
-
 /**
  * `granted` reaches nothing `requested` doesn't, for lenses of the same resource. Approving someone
  * else's request may only narrow; an owner revising their own grant may widen (review U3). A lens of
@@ -89,9 +84,7 @@ const subset = <T>(granted: T[] | undefined, requested: T[] | undefined) =>
 export const narrowsSignetLens = (granted: SignetLens, requested: SignetLens): boolean => {
   if ('threads' in granted || 'threads' in requested)
     return 'threads' in granted && 'threads' in requested && narrowsThreadsLens(granted, requested);
-  return (
-    subset(granted.documentIds, requested.documentIds) && subset(granted.fields, requested.fields)
-  );
+  return narrowsArchiveLens(granted, requested);
 };
 
 export const signetResourceSchema = z.strictObject({
@@ -406,6 +399,7 @@ export const accessInputSchema = z.strictObject({
     .regex(/^[a-f0-9]{64}$/)
     .nullable()
     .optional(),
+  restore: z.boolean().optional(),
   threadId: threadIdSchema.optional(),
   postId: z.uuid().optional(),
   text: z.string().min(1).max(threadTextLimit).optional(),
@@ -428,20 +422,43 @@ export type AccessRequest = z.infer<typeof accessRequestSchema>;
 export const accessResultSchema = z.object({ executionId: z.uuid(), result: z.unknown() });
 
 /**
- * The host-side input of a thread operation, taken from an `access/execute` input: exactly the keys
- * that operation takes (no `resourceId`, no `limit`). Kingdom builds `thread.request` frames with it.
+ * Every operation a contract in this package declares (`threads.ts`, `archive.ts`), and the input
+ * each takes. Kingdom's `access/execute` check, its catalog and its dispatch read these, so a new
+ * operation is added here and nowhere else. Operation names are unique across contracts.
+ */
+export const declaredOperationSchema = z.enum([
+  ...threadOperationSchema.options,
+  ...archiveOperationSchema.options,
+]);
+export type DeclaredOperation = z.infer<typeof declaredOperationSchema>;
+export const operationInputSchemas = {
+  ...threadInputSchemas,
+  ...archiveInputSchemas,
+} as const satisfies Record<DeclaredOperation, z.ZodObject>;
+export type OperationInput<O extends DeclaredOperation> = z.infer<
+  (typeof operationInputSchemas)[O]
+>;
+
+/** The `access/execute` input keys a declared operation takes, besides `resourceId` and `limit`. */
+export const operationInputKeys = <O extends DeclaredOperation>(operation: O) =>
+  Object.keys(operationInputSchemas[operation].shape) as (keyof OperationInput<O>)[];
+
+/**
+ * A declared operation's input, taken from an `access/execute` input: exactly the keys that
+ * operation takes (no `resourceId`, no `limit`). Kingdom builds `thread.request` frames and Archive
+ * calls with it.
  */
-export const threadInputFromAccess = <O extends ThreadOperation>(
+export const operationInputFromAccess = <O extends DeclaredOperation>(
   operation: O,
   input: AccessRequest['input'],
 ) => {
-  const schema = threadInputSchemas[operation];
+  const schema = operationInputSchemas[operation];
   const picked = Object.fromEntries(
     Object.keys(schema.shape).flatMap((key) =>
       key in input ? [[key, input[key as keyof typeof input]]] : [],
     ),
   );
-  return schema.safeParse(picked) as z.ZodSafeParseResult<z.infer<(typeof threadInputSchemas)[O]>>;
+  return schema.safeParse(picked) as z.ZodSafeParseResult<OperationInput<O>>;
 };
 
 /** What Kingdom pushes over the Installation socket, and what a poll of both reads assembles. */

package/src/threads.ts

@@ -106,13 +106,22 @@ export const threadOperationSchema = z.enum([
 ]);
 export type ThreadOperation = z.infer<typeof threadOperationSchema>;
 
+export const threadOperationNames: Record<ThreadOperation, string> = {
+  'thread.read': "Read a conversation's thread through this member's view",
+  'thread.prompt': 'Post into a conversation',
+  'thread.floor': "Request, release or pass a conversation's floor",
+  'prompt.resolve': "Answer the host's held prompts (owner only)",
+};
+
 /**
  * A party in a conversation, as Foundry names it (not "participant": that is a Warden contributor).
+ * `local` is a member on the host's own machine (its own Codex, a local Herald), joined in-process
+ * with no Signet; `signet` is one that reaches the host through Kingdom.
  * Read paths (entries, views) use plain objects, so a host that adds a field never costs an older
  * member its entries; lenses and request frames stay strict.
  */
 export const conversationMemberSchema = z.object({
-  kind: z.enum(['owner', 'local-herald', 'signet']),
+  kind: z.enum(['owner', 'local', 'signet']),
   id: z.string().min(1).max(128),
 });
 export type ConversationMember = z.infer<typeof conversationMemberSchema>;
@@ -154,10 +163,6 @@ export const threadInputSchemas = {
     }),
   }),
 } as const satisfies Record<ThreadOperation, z.ZodObject>;
-/** The `access/execute` input keys each thread operation takes, besides `resourceId`. */
-export const threadInputKeys = <O extends ThreadOperation>(operation: O) =>
-  Object.keys(threadInputSchemas[operation].shape) as (keyof ThreadInput<O>)[];
-export type ThreadInput<O extends ThreadOperation> = z.infer<(typeof threadInputSchemas)[O]>;
 
 /**
  * One entry of the main thread's journal as a member sees it: an owner message, a main-agent