@inixiative/signet 0.4.6 → 0.5.1

package/README.md

@@ -6,7 +6,7 @@ A **Signet** is Kingdom's only grant for using an integration. It names the reso
 
 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`.
+- `contracts`: the wire schemas: keys, lenses, proposals, pairing requests, delivered credentials, `describe` and `execute`, and the conversation frames.
 - `proof`: create and verify DPoP proofs (ES256, nonce-bound, access-token-bound).
 - `files`: private 0600 JSON files for keys and credentials.
 - `client`:
@@ -57,6 +57,35 @@ const signet = await SignetClient.fromFile(credentialFile);
 await signet.describe();
 ```
 
+## 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.
+
+- **Lens.** `signetLensSchema` is a union of strict shapes, `archiveLensSchema | threadsLensSchema`, because a resource grant names its resource by id with no kind. `resourceLensSchema(kind)` gives the shape a kind takes; Kingdom checks every grant with it against the kind it stores. A threads lens is `{ threads, view: 'own' | 'thread', delivery: 'note' | 'turn', outbound: 'review' | 'auto' }`, the terms defaulting to the narrowest value. `threads` is a selector, a union on `form`: v1 builds `{ form: 'ids', ids }` (1–100 thread ids); `withMember` and `tag` are named for standing Signets and fail to parse everywhere until a release adds them, so a new form never widens access silently. `narrowsSignetLens` is the rule for approving someone else's request: a subset of ids, `own` < `thread`, `note` < `turn`, `review` < `auto`.
+- **Join requests** may name a resource by kind: `requestSignet` takes `{ resourceKind: 'threads', operations, lens }`, and Kingdom resolves it before review.
+- **Per-entry reads.** `installationInquiries`, `installationSignets`, the socket snapshot and `describe` read each entry on its own. An entry this package can't read is dropped and listed in `dropped`, and the rest is kept. Inside a Signet, resources are read one by one: a resource with a lens this package can't read (a selector form from a newer Kingdom, a lens that doesn't fit its resource's kind) is dropped, and the Signet stays, so an installation never loses a held Signet, or mistakes a member for revoked, over one resource. The snapshot carries `hostedSignets` (members of this Foundry's conversations) and `hostedSignetRequests` (join requests aimed at its integrations); held Signets carry their `resources`.
+- **Host.** `InstallationSocket` takes `threads`, one handler per operation (`thread.read`, `thread.prompt`, `thread.floor`, `prompt.resolve`, `thread.subscribe`), answering `threadResult(...)` or `threadRefused(code)`. A frame with an unknown selector is refused `unknown_selector` before any handler runs. `thread.subscribe` answers with the member's view and the `journalSeq` it was taken at, and the subscription starts there: `appendThread(subscriptionId, entry)` holds entries pushed meanwhile and never sends one twice. Each append carries a dense per-subscription `seq` (a filtered view skips journal entries, so `journalSeq` can't reveal loss); an entry that can't be sent still spends its `seq`, so Kingdom sees the gap and the member resyncs. A subscription ends on `thread.unsubscribe`, when Kingdom stops re-asserting its lease (`thread.lease`; dropped 90 s after the last one, so one late 45 s sweep is survived), or when the socket drops.
+- **Member.** An outside agent holds its live views with `SignetSocket`: it authenticates as its Signet's presentation (`authenticateSignet`, a proof bound to `POST /api/v1/access/signetSocket` with `ath`), renews it before the five-minute token expires (`renewPresentation`), and opens one `accessThread` stream per thread: a snapshot, then appends, with Kingdom's `seq`/`resync` rules. Frames are handled in order, one open is in flight per stream, and Kingdom's close carries the reason: after a revision the stream reopens under the new lens, while the host is offline it retries with backoff, when the presentation lapsed the socket re-presents and reopens, and on revocation or expiry it ends (`onClosed`). Posts are separate `execute` calls (`thread.prompt`), each admitted and metered. A Foundry holding a conversation Signet opens the same streams over its Installation socket (`threadStreams`, `openThread`).
+
+```ts
+import { SignetClient, SignetSocket } from '@inixiative/signet';
+
+const signet = await SignetClient.fromFile(credentialFile);
+const socket = new SignetSocket({
+  client: signet,
+  onSnapshot: ({ threadId }, view) => show(threadId, view.entries),
+  onEntry: ({ threadId }, entry) => append(threadId, entry),
+  onClosed: ({ threadId }, reason) => console.log(`left ${threadId}: ${reason}`),
+});
+socket.open(threadId);
+socket.start();
+await signet.execute({
+  integrationId,
+  operation: 'thread.prompt',
+  input: { resourceId, threadId, postId: crypto.randomUUID(), text: 'The role you wanted opened' },
+});
+```
+
 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.6",
+  "version": "0.5.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",
@@ -33,8 +33,9 @@
     "jose": "^6.2.3"
   },
   "devDependencies": {
+    "@asteasolutions/zod-to-openapi": "^9.1.0",
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.105",
+    "@inixiative/config": "^0.5.116",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/client.ts

@@ -7,10 +7,11 @@ import {
   accessTokenPattern,
   collectedSignetSchema,
   type InstallationKind,
-  installationInquiriesResponseSchema,
-  installationSignetsResponseSchema,
   nonceSchema,
   ownerRefSchema,
+  parseInstallationInquiries,
+  parseInstallationSignets,
+  parseSignetDescription,
   publicClientKeySchema,
   type RegistrationRequest,
   registerInstallationResponseSchema,
@@ -19,11 +20,11 @@ import {
   type SignetRequestResponse,
   setInstallationCredentialResponseSchema,
   signetCredentialsSchema,
-  signetDescriptionSchema,
   signetKeySchema,
   signetLifecycleSchema,
   signetProposalSchema,
   signetRequestResponseSchema,
+  signetSocketAction,
 } from './contracts';
 import { readPrivateJson, writePrivateJson } from './files';
 import { createSignetProof, keyThumbprint } from './proof';
@@ -224,7 +225,7 @@ async function keyPost<T>(
   keyFile: string,
   action: string,
   body: unknown,
-  schema: z.ZodType<T>,
+  schema: z.ZodType<T, unknown>,
   options: SignetRequestOptions = {},
   headers: Record<string, string> = {},
 ): Promise<T> {
@@ -274,13 +275,23 @@ export const requestRegistration = (
     options,
   );
 
-/** This installation's pending request and its inquiries. */
+/**
+ * This installation's pending request, its inquiries, and the join requests aimed at its
+ * integrations. Read per entry: an entry this package can't read is dropped and listed in `dropped`.
+ */
 export const installationInquiries = (
   url: string,
   keyFile: string,
   options: SignetRequestOptions = {},
 ) =>
-  keyPost(url, keyFile, 'installationInquiries', {}, installationInquiriesResponseSchema, options);
+  keyPost(
+    url,
+    keyFile,
+    'installationInquiries',
+    {},
+    z.unknown().transform((value) => parseInstallationInquiries(value)),
+    options,
+  );
 
 export const cancelInstallationInquiry = (
   url: string,
@@ -396,12 +407,23 @@ export const enrollSignet = async (
   signetId: enrollment.signetId,
 });
 
-/** The Signets held by this installation's integrations. */
+/**
+ * The Signets held by this installation's integrations, and those issued on them (`hostedSignets`).
+ * Read per entry: a Signet whose lens this package can't read is dropped and listed in `dropped`.
+ */
 export const installationSignets = (
   url: string,
   keyFile: string,
   options: SignetRequestOptions = {},
-) => keyPost(url, keyFile, 'installationSignets', {}, installationSignetsResponseSchema, options);
+) =>
+  keyPost(
+    url,
+    keyFile,
+    'installationSignets',
+    {},
+    z.unknown().transform((value) => parseInstallationSignets(value)),
+    options,
+  );
 
 /** Enroll this installation's key on a Signet one of its integrations holds. */
 export const enrollInstallationSignet = (
@@ -498,7 +520,7 @@ export class SignetClient {
   constructor(
     readonly url: string,
     private credentialFile: string,
-    private signetId: string,
+    readonly signetId: string,
   ) {
     this.url = kingdomUrl(url);
   }
@@ -588,11 +610,29 @@ export class SignetClient {
       { signal, timeoutMs: options.timeoutMs },
     );
   }
+  /** Read per entry: a resource whose lens this package can't read is dropped, listed in `dropped`. */
   async describe(options: SignetRequestOptions = {}) {
-    return signetDescriptionSchema.parse(
+    return parseSignetDescription(
       await this.post('describe', { signetId: this.signetId }, undefined, options),
     );
   }
+  /**
+   * The access token and a proof bound to the Signet socket, for `authenticateSignet` (or, with
+   * `renew`, a freshly renewed token for `renewPresentation`). Each proof spends one Kingdom nonce.
+   */
+  async socketPresentation(options: SignetRequestOptions & { renew?: boolean } = {}) {
+    const signal = requestSignal(options);
+    const credential = await this.credentials(options.renew ?? false, signal);
+    signal.throwIfAborted();
+    const proof = await signetProof(
+      this.url,
+      signetSocketAction,
+      credential.keyFile,
+      credential.accessToken,
+      { signal, timeoutMs: options.timeoutMs },
+    );
+    return { accessToken: credential.accessToken, proof, expiresAt: credential.expiresAt };
+  }
   /** Run one integration operation through the Signet; every call is a new request id. */
   async execute(
     request: Omit<AccessRequest, 'requestId' | 'signetId'>,

package/src/contracts.ts

@@ -1,4 +1,17 @@
 import { z } from 'zod';
+import {
+  foundryIdSchema,
+  narrowsThreadsLens,
+  type ThreadOperation,
+  threadFloorActionSchema,
+  threadIdSchema,
+  threadInputSchemas,
+  threadsLensSchema,
+  threadsResourceKind,
+  threadTextLimit,
+} from './threads';
+
+export * from './threads';
 
 const token43 = /^[A-Za-z0-9_-]{43}$/;
 
@@ -37,10 +50,50 @@ export const signetKeySchema = publicClientKeySchema.extend({
 export type PublicClientKey = z.infer<typeof publicClientKeySchema>;
 export type SignetKey = z.infer<typeof signetKeySchema>;
 
-export const signetLensSchema = z.strictObject({
+/** 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({});
+
+/**
+ * A grant's lens. `signetResourceSchema` names a resource by id with no `kind`, so the contract can
+ * only hold a union of the strict shapes; which shape a grant may carry depends on its resource's
+ * kind, and Kingdom checks that with `resourceLensSchema` against the kind it stores (review R9).
+ * `{}` parses as the empty Archive lens: "no lens", valid for every kind but `threads`.
+ */
+export const signetLensSchema = z.union([archiveLensSchema, threadsLensSchema]);
+export type SignetLens = z.infer<typeof signetLensSchema>;
+
+/** The lens shape a resource of `kind` takes. */
+export const resourceLensSchema = (kind: string) =>
+  kind === archiveLibraryResourceKind
+    ? archiveLensSchema
+    : kind === threadsResourceKind
+      ? 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
+ * another shape than the request's is refused.
+ */
+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)
+  );
+};
+
 export const signetResourceSchema = z.strictObject({
   resourceId: z.uuid(),
   operations: z.array(z.string().min(1).max(80)).min(1).max(100),
@@ -51,7 +104,6 @@ export const signetRecipientSchema = z.discriminatedUnion('recipientModel', [
   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>;
 
@@ -95,11 +147,25 @@ const signetTerms = {
 /** 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>;
+/**
+ * A resource asked for by kind, and optionally name, when the asker does not know its id: an
+ * Installation registering, or a party asking to join a Foundry's `threads` (one per Foundry, so the
+ * integration id names it). Kingdom resolves it to the resource's id before anyone reviews it.
+ */
+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 a party asks for on an integration: resources by id or by kind (review R8). */
 export const signetProposalSchema = z.strictObject({
   ...signetTerms,
   integrationId: z.uuid(),
-  resources: z.array(signetResourceSchema).min(1).max(100),
+  resources: z.array(requestedResourceSchema).min(1).max(100),
 });
+/** The terms as reviewed and issued: every resource named by id. */
 export const signetReviewProposalSchema = z.strictObject({
   ...signetTerms,
   resources: z.array(signetResourceSchema).max(100),
@@ -116,14 +182,6 @@ export const requestedOwnerSchema = z.strictObject({
   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,
@@ -132,10 +190,7 @@ export const registrationRequestSchema = z.strictObject({
   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,
-  integrationId: z.uuid(),
-  resources: z.array(signetResourceSchema).min(1).max(100),
+export const signetRequestSchema = signetProposalSchema.extend({
   publicKey: publicClientKeySchema,
 });
 export const signetRequestResponseSchema = z.object({
@@ -172,10 +227,18 @@ export const requestRegistrationResponseSchema = z.object({
   /** Where a person reviews the registration in Kingdom's web app. */
   reviewUrl: kingdomLinkSchema,
 });
+const inquiryStatusSchema = z.enum([
+  'draft',
+  'sent',
+  'changesRequested',
+  'approved',
+  'denied',
+  'canceled',
+]);
 export const installationInquirySchema = z.object({
   id: z.uuid(),
   type: z.string(),
-  status: z.enum(['draft', 'sent', 'changesRequested', 'approved', 'denied', 'canceled']),
+  status: inquiryStatusSchema,
   createdAt: z.iso.datetime(),
   expiresAt: z.iso.datetime().nullable(),
   owner: ownerRefSchema.nullable(),
@@ -184,23 +247,90 @@ export const installationInquirySchema = z.object({
   signetId: z.uuid().nullable(),
   deliverBefore: z.iso.datetime().nullable(),
 });
+/**
+ * A pending `signetRequest` whose target is one of the Installation's integrations: a party asking
+ * to join a Foundry's threads. The owner reviews it in Kingdom at `reviewUrl`.
+ */
+export const hostedSignetRequestSchema = z.object({
+  id: z.uuid(),
+  status: inquiryStatusSchema,
+  createdAt: z.iso.datetime(),
+  expiresAt: z.iso.datetime().nullable(),
+  /** The Installation's integration the request targets. */
+  integrationId: z.uuid(),
+  requester: z.object({ sourceModel: z.string(), id: z.uuid(), displayName: z.string() }),
+  terms: signetReviewProposalSchema,
+  reviewUrl: kingdomLinkSchema,
+});
+export type HostedSignetRequest = z.infer<typeof hostedSignetRequestSchema>;
 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),
+  hostedSignetRequests: z.array(hostedSignetRequestSchema),
 });
 export const inquiryReferenceSchema = z.strictObject({ inquiryId: z.uuid() });
+
+/** One resource a Signet reaches, with its stored kind, so its lens can be checked against it. */
+export const signetGrantSchema = z.object({
+  resourceId: z.uuid(),
+  kind: z.string().min(1).max(80),
+  operations: z.array(z.string().min(1).max(80)),
+  lens: signetLensSchema,
+});
+export type SignetGrant = z.infer<typeof signetGrantSchema>;
+const grantsSchema = z.array(signetGrantSchema);
+/** Whether a grant's lens is the shape its resource's kind takes. */
+export const grantLensFitsKind = (grant: Pick<SignetGrant, 'kind' | 'lens'>) =>
+  resourceLensSchema(grant.kind).safeParse(grant.lens).success;
+
+/** Who a Signet is issued to. Recipients run broad (2026-10-18); Kingdom widens issuing in K0. */
+export const signetRecipientModelSchema = z.enum([
+  'User',
+  'OrganizationUser',
+  'Organization',
+  'Space',
+  'SpaceUser',
+  'Integration',
+]);
+export const installationSignetSchema = z.object({
+  signetId: z.uuid(),
+  integrationId: z.uuid(),
+  name: z.string(),
+  /** The enrollment that is current for this installation's key, if any. */
+  enrollmentId: z.uuid().nullable(),
+  owner: ownerRefSchema,
+  /** What the Signet reaches, so a holder knows, for example, which threads it may open. */
+  resources: grantsSchema,
+});
+/**
+ * A Signet issued on one of the Installation's integrations: a member of a Foundry's conversations.
+ * For display and for cancelling a member's queued work once it is gone, never as an admission
+ * gate: Kingdom admits every call.
+ */
+export const hostedSignetSchema = z.object({
+  signetId: z.uuid(),
+  /** The Installation's integration the Signet is issued on. */
+  integrationId: z.uuid(),
+  name: z.string(),
+  /** The current revision; the host compares it with the `acceptedRevision` frames carry. */
+  revision: z.number().int().min(1),
+  lifecycle: signetLifecycleSchema,
+  expiresAt: z.iso.datetime().nullable(),
+  maxRequests: z.number().int().nullable(),
+  maxConcurrent: z.number().int(),
+  recipient: z.object({
+    recipientModel: signetRecipientModelSchema,
+    id: z.uuid(),
+    displayName: z.string(),
+  }),
+  resources: grantsSchema,
+});
+export type InstallationSignet = z.infer<typeof installationSignetSchema>;
+export type HostedSignet = z.infer<typeof hostedSignetSchema>;
 export const installationSignetsResponseSchema = z.object({
-  signets: z.array(
-    z.object({
-      signetId: z.uuid(),
-      integrationId: z.uuid(),
-      name: z.string(),
-      /** The enrollment that is current for this installation's key, if any. */
-      enrollmentId: z.uuid().nullable(),
-      owner: ownerRefSchema,
-    }),
-  ),
+  signets: z.array(installationSignetSchema),
+  hostedSignets: z.array(hostedSignetSchema),
 });
 export const enrollInstallationSignetSchema = z.strictObject({ signetId: z.uuid() });
 export const rotateInstallationKeySchema = z.strictObject({
@@ -209,6 +339,13 @@ export const rotateInstallationKeySchema = z.strictObject({
 });
 export type InstallationInquiry = z.infer<typeof installationInquirySchema>;
 
+export const signetDescriptionResourceSchema = z.object({
+  id: z.uuid(),
+  name: z.string(),
+  kind: z.string(),
+  integrationId: z.uuid(),
+  lens: signetLensSchema,
+});
 export const signetDescriptionSchema = z.object({
   signetId: z.uuid(),
   integrationId: z.uuid(),
@@ -223,9 +360,7 @@ export const signetDescriptionSchema = z.object({
     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() }),
-      ),
+      resources: z.array(signetDescriptionResourceSchema),
     }),
   ),
 });
@@ -271,6 +406,14 @@ export const accessInputSchema = z.strictObject({
     .regex(/^[a-f0-9]{64}$/)
     .nullable()
     .optional(),
+  threadId: threadIdSchema.optional(),
+  postId: z.uuid().optional(),
+  text: z.string().min(1).max(threadTextLimit).optional(),
+  inReplyTo: foundryIdSchema.optional(),
+  afterSeq: z.number().int().min(0).optional(),
+  floor: threadFloorActionSchema.optional(),
+  promptId: foundryIdSchema.optional(),
+  answer: threadInputSchemas['prompt.resolve'].shape.answer.optional(),
 });
 export const accessRequestSchema = z.strictObject({
   requestId: z.uuid(),
@@ -283,12 +426,195 @@ export const accessRequestSchema = z.strictObject({
 });
 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.
+ */
+export const threadInputFromAccess = <O extends ThreadOperation>(
+  operation: O,
+  input: AccessRequest['input'],
+) => {
+  const schema = threadInputSchemas[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]>>;
+};
+
 /** What Kingdom pushes over the Installation socket, and what a poll of both reads assembles. */
 export const installationSnapshotSchema = installationInquiriesResponseSchema.extend(
   installationSignetsResponseSchema.shape,
 );
+
+/** An entry a reader dropped instead of failing the whole read, and why (review U1). */
+export type DroppedEntry = { list: string; index: number; id: string | null; reason: string };
+export type InstallationSnapshot = z.infer<typeof installationSnapshotSchema> & {
+  dropped: DroppedEntry[];
+};
+
+const entryId = (value: unknown) => {
+  if (typeof value !== 'object' || value === null) return null;
+  const record = value as Record<string, unknown>;
+  const id = record.signetId ?? record.id;
+  return typeof id === 'string' ? id.slice(0, 80) : null;
+};
+/**
+ * Parse each entry on its own and drop the ones that don't parse. A Kingdom ahead of this package
+ * (a selector form it doesn't know, a new field shape) then costs only those entries: never the
+ * Installation's other grants or its own held Signets. A missing list reads as empty, reported.
+ */
+export function parseEntries<T>(
+  list: string,
+  value: unknown,
+  schema: z.ZodType<T>,
+  dropped: DroppedEntry[],
+  check: (entry: T) => string | null = () => null,
+): T[] {
+  if (!Array.isArray(value)) {
+    dropped.push({ list, index: -1, id: null, reason: 'missing or not a list' });
+    return [];
+  }
+  return value.flatMap((raw, index) => {
+    const parsed = schema.safeParse(raw);
+    const reason = parsed.success
+      ? check(parsed.data)
+      : parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+    if (reason === null && parsed.success) return [parsed.data];
+    dropped.push({ list, index, id: entryId(raw), reason: (reason ?? 'invalid').slice(0, 500) });
+    return [];
+  });
+}
+
+const lensFits = (grant: Pick<SignetGrant, 'kind' | 'lens'>) =>
+  grantLensFitsKind(grant) ? null : `a ${grant.kind} resource carries a lens of another shape`;
+
+/**
+ * Signets read per entry, and their resources per entry inside them: a resource this package can't
+ * read (a newer lens, a lens that doesn't fit its kind) is dropped and reported, and the Signet is
+ * kept, so the Installation never loses a held Signet (or mistakes a member for revoked) over one
+ * resource.
+ */
+function parseSignetsWithGrants<S extends z.ZodObject<{ resources: typeof grantsSchema }>>(
+  list: string,
+  value: unknown,
+  schema: S,
+  dropped: DroppedEntry[],
+): z.infer<S>[] {
+  const identity = schema.omit({ resources: true }).extend({ resources: z.unknown().optional() });
+  return parseEntries(list, value, identity, dropped).map(
+    (entry) =>
+      ({
+        ...entry,
+        resources: parseEntries(
+          `${list}.${entryId(entry)}.resources`,
+          entry.resources,
+          signetGrantSchema,
+          dropped,
+          lensFits,
+        ),
+      }) as z.infer<S>,
+  );
+}
+
+const inquiriesScalars = installationInquiriesResponseSchema.pick({
+  pending: true,
+  declinedAt: true,
+});
+
+/** `installationInquiries`, per entry. */
+export function parseInstallationInquiries(value: unknown, dropped: DroppedEntry[] = []) {
+  const record = z.object({}).loose().parse(value);
+  return {
+    ...inquiriesScalars.parse(record),
+    inquiries: parseEntries('inquiries', record.inquiries, installationInquirySchema, dropped),
+    hostedSignetRequests: parseEntries(
+      'hostedSignetRequests',
+      record.hostedSignetRequests,
+      hostedSignetRequestSchema,
+      dropped,
+    ),
+    dropped,
+  };
+}
+
+/** `installationSignets`, per Signet and per resource inside it. */
+export function parseInstallationSignets(value: unknown, dropped: DroppedEntry[] = []) {
+  const record = z.object({}).loose().parse(value);
+  return {
+    signets: parseSignetsWithGrants('signets', record.signets, installationSignetSchema, dropped),
+    hostedSignets: parseSignetsWithGrants(
+      'hostedSignets',
+      record.hostedSignets,
+      hostedSignetSchema,
+      dropped,
+    ),
+    dropped,
+  };
+}
+
+/** The Installation socket's snapshot frame (or a poll of both reads), per entry. */
+export function parseInstallationSnapshot(value: unknown): InstallationSnapshot {
+  const dropped: DroppedEntry[] = [];
+  const { dropped: _inquiries, ...inquiries } = parseInstallationInquiries(value, dropped);
+  const { dropped: _signets, ...signets } = parseInstallationSignets(value, dropped);
+  return { ...inquiries, ...signets, dropped };
+}
+
+export type ParsedSignetDescription = SignetDescription & { dropped: DroppedEntry[] };
+
+/** `access/describe`, per entry: a resource whose lens doesn't parse, or doesn't fit its kind, is dropped. */
+export function parseSignetDescription(value: unknown): ParsedSignetDescription {
+  const dropped: DroppedEntry[] = [];
+  const record = z
+    .object({ operations: z.array(z.object({}).loose()) })
+    .loose()
+    .parse(value);
+  const operations = record.operations.map((operation, index) => ({
+    ...signetDescriptionSchema.shape.operations.element.omit({ resources: true }).parse(operation),
+    resources: parseEntries(
+      `operations.${index}.resources`,
+      operation.resources,
+      signetDescriptionResourceSchema,
+      dropped,
+      (resource) => (grantLensFitsKind(resource) ? null : 'lens does not fit the resource kind'),
+    ),
+  }));
+  return { ...signetDescriptionSchema.parse({ ...record, operations }), dropped };
+}
+
 /** The path a socket proof is bound to (POST), though the socket itself opens at the API origin. */
 export const installationSocketAction = 'installationSocket';
+
+/**
+ * A Signet presenter's socket (design §5.6.1, review Round 4). Like the Installation socket: a DPoP
+ * proof bound to `POST /api/v1/access/signetSocket`, on a single-use Kingdom nonce, with `ath` over
+ * the access token. The socket then carries one actor, that Signet's presentation, until the token
+ * expires; `renewPresentation` (a new token, a new proof) extends it.
+ */
+export const signetSocketAction = 'signetSocket';
+const presentation = {
+  accessToken: z.string().regex(accessTokenPattern),
+  proof: z.string().max(8192),
+};
+export const authenticateSignetFrameSchema = z.strictObject({
+  action: z.literal('authenticateSignet'),
+  ...presentation,
+});
+export const renewPresentationFrameSchema = z.strictObject({
+  action: z.literal('renewPresentation'),
+  ...presentation,
+});
+/** Kingdom's answer to either: the presentation the socket now carries, and until when. */
+export const signetPresentedFrameSchema = z.object({
+  type: z.literal('signet'),
+  signetId: z.uuid(),
+  enrollmentId: z.uuid(),
+  expiresAt: z.iso.datetime(),
+});
+export const signetRejectedFrameSchema = z.object({ type: z.literal('signetRejected') });
 /** An installation hands Kingdom the credential Kingdom uses to reach it (a Foundry's tunnel token). */
 export const setInstallationCredentialSchema = z.strictObject({
   integrationId: z.uuid(),

package/src/index.ts

@@ -4,3 +4,5 @@ export * from './files';
 export * from './installationPairing';
 export * from './installationSocket';
 export * from './proof';
+export * from './signetSocket';
+export * from './threadStreams';