@poppykit/client 0.5.0 → 0.6.0

package/dist/protocol/wire.d.ts

@@ -1,3 +1,4 @@
+import type { BusinessOperation, OperationApproval } from './operations.js';
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -19,6 +20,8 @@ export interface Message {
     text?: string;
     data?: JsonObject;
     context?: JsonObject;
+    operation?: BusinessOperation;
+    approval?: OperationApproval;
     [key: string]: unknown;
 }
 export interface RecordedMessage extends Message {
@@ -67,7 +70,7 @@ export interface EventPage extends ConversationState {
 export interface TokenResponse {
     access_token: string;
     token_type: 'DPoP' | 'Bearer';
-    expires_in: number;
+    expires_in?: number;
     scope?: string;
     refresh_token?: string;
     refresh_token_expires_in?: number;
@@ -93,11 +96,12 @@ export declare function id(value: unknown, field: string): string;
 export declare function parseMessage(value: unknown, options?: {
     recorded?: boolean;
     company?: boolean;
+    operations?: boolean;
 }): Message | RecordedMessage;
-export declare function parseConversationRequest(value: unknown): ConversationRequest;
+export declare function parseConversationRequest(value: unknown, operations?: boolean): ConversationRequest;
 export declare function parseConversationState(value: unknown): ConversationState;
-export declare function parseEvent(value: unknown): ConversationEvent;
-export declare function parseEventPage(value: unknown, requestCursor?: string): EventPage;
+export declare function parseEvent(value: unknown, operations?: boolean): ConversationEvent;
+export declare function parseEventPage(value: unknown, requestCursor?: string, operations?: boolean): EventPage;
 export declare function parseTokenResponse(value: unknown): TokenResponse;
 export declare function parseProtocolError(value: unknown): ProtocolErrorBody;
 export declare function parseReadOptions(url: URL, maxWaitSeconds: number): {

package/dist/protocol/wire.js

@@ -1,3 +1,4 @@
+import { parseBusinessOperation, parseOperationApproval } from './operations.js';
 export class ValidationError extends Error {
     field;
     constructor(field) {
@@ -70,7 +71,18 @@ export function parseMessage(value, options = {}) {
             throw new ValidationError('message.author.image');
         }
     }
-    if (!['text', 'data', 'context'].some(key => key in message))
+    const company = options.company || (options.recorded && message.role === 'company');
+    if ('operation' in message) {
+        if (!company || !options.operations)
+            throw new ValidationError('message.operation');
+        message.operation = parseBusinessOperation(message.operation);
+    }
+    if ('approval' in message) {
+        if (company || !options.operations)
+            throw new ValidationError('message.approval');
+        message.approval = parseOperationApproval(message.approval);
+    }
+    if (!['text', 'data', 'context', ...(options.operations ? [company ? 'operation' : 'approval'] : [])].some(key => key in message))
         throw new ValidationError('message.content');
     if ('text' in message)
         string(message.text, 'message.text', false);
@@ -109,20 +121,24 @@ export function parseMessage(value, options = {}) {
     }
     return message;
 }
-export function parseConversationRequest(value) {
+export function parseConversationRequest(value, operations = false) {
     const request = object(value);
     if ('parent_conversation_id' in request)
         id(request.parent_conversation_id, 'parent_conversation_id');
-    return { ...request, message: parseMessage(request.message) };
+    return { ...request, message: parseMessage(request.message, { operations }) };
 }
 export function parseConversationState(value) {
     const state = object(value);
     id(state.conversation_id, 'conversation_id');
-    member(state.status, ['working', 'idle', 'queued', 'closed'], 'status');
-    member(state.responder, ['agent', 'human'], 'responder');
+    string(state.status, 'status');
+    string(state.responder, 'responder');
+    if (!['working', 'idle', 'queued', 'closed'].includes(state.status))
+        state.status = 'working';
+    if (!['agent', 'human'].includes(state.responder))
+        state.responder = 'human';
     return state;
 }
-export function parseEvent(value) {
+export function parseEvent(value, operations = false) {
     const event = object(value, 'event');
     id(event.id, 'event.id');
     string(event.type, 'event.type');
@@ -138,12 +154,14 @@ export function parseEvent(value) {
         throw new ValidationError('event.created_at');
     switch (event.type) {
         case 'message':
-            parseMessage(event.message, { recorded: true });
+            parseMessage(event.message, { recorded: true, operations });
             break;
-        case 'state':
-            member(event.status, ['working', 'idle', 'queued', 'closed'], 'event.status');
-            member(event.responder, ['agent', 'human'], 'event.responder');
+        case 'state': {
+            const state = parseConversationState({ conversation_id: 'state', status: event.status, responder: event.responder });
+            event.status = state.status;
+            event.responder = state.responder;
             break;
+        }
         case 'authorization':
             member(event.error, ['insufficient_scope'], 'event.error');
             if (!/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(string(event.scope, 'event.scope')))
@@ -159,11 +177,11 @@ export function parseEvent(value) {
     }
     return event;
 }
-export function parseEventPage(value, requestCursor) {
+export function parseEventPage(value, requestCursor, operations = false) {
     const page = parseConversationState(value);
     if (!Array.isArray(page.events))
         throw new ValidationError('events');
-    page.events.forEach(parseEvent);
+    page.events.forEach(event => parseEvent(event, operations));
     member(page.has_more, [true, false], 'has_more');
     if (page.cursor === null) {
         if (requestCursor !== undefined || page.events.length || page.has_more)
@@ -172,7 +190,7 @@ export function parseEventPage(value, requestCursor) {
     else {
         string(page.cursor, 'cursor');
         const expected = page.events.length ? page.events.at(-1).id : requestCursor;
-        if (expected !== undefined && page.cursor !== expected)
+        if (expected === undefined || page.cursor !== expected)
             throw new ValidationError('cursor');
     }
     return page;
@@ -185,8 +203,12 @@ export function parseTokenResponse(value) {
         if (scope !== '' && (!/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(scope) || new Set(scope.split(' ')).size !== scope.split(' ').length))
             throw new ValidationError('scope');
     }
-    member(token.token_type, ['DPoP', 'Bearer'], 'token_type');
-    positive(token.expires_in, 'expires_in');
+    const type = string(token.token_type, 'token_type').toLowerCase();
+    if (type !== 'bearer' && type !== 'dpop')
+        throw new ValidationError('token_type');
+    token.token_type = type === 'bearer' ? 'Bearer' : 'DPoP';
+    if ('expires_in' in token && (!Number.isSafeInteger(token.expires_in) || token.expires_in < 0))
+        throw new ValidationError('expires_in');
     if ('refresh_token' in token)
         string(token.refresh_token, 'refresh_token');
     if ('refresh_token_expires_in' in token)

package/dist/provider-postgres.js

@@ -42,15 +42,15 @@ export class PostgresProviderStore {
                         await lock('user', key);
                         await one('user', key);
                     }
-                    if (selection.kind === 'begin' || selection.kind === 'revoke') {
+                    if (selection.kind === 'begin' || selection.kind === 'delegate' || selection.kind === 'revoke') {
                         const operations = await this.db.query("SELECT id,body FROM poppy_provider.records WHERE ns=$1 AND kind='operation' AND split_part(id,':',1)=$2 ORDER BY id LIMIT 1001", [this.namespace, enrollmentId]);
                         for (const row of operations)
                             rows.set(JSON.stringify(['operation', row.id]), JSON.parse(row.body));
                         if (operations.length > 1000)
                             throw new Error('provider aggregate exceeds retained operation limit');
-                        if (selection.kind === 'begin') {
+                        if (selection.kind === 'begin' || selection.kind === 'delegate') {
                             const states = new Set();
-                            if (selection.stateHash)
+                            if ('stateHash' in selection && selection.stateHash)
                                 states.add(selection.stateHash);
                             for (const row of operations) {
                                 const hash = JSON.parse(row.body).binding?.stateHash;

package/dist/provider-storage.js

@@ -14,8 +14,8 @@ export function scopedProviderTransaction(selection, raw) {
     const states = new Set();
     if (selection.kind === 'callback')
         states.add(selection.stateHash);
-    if (selection.kind === 'begin') {
-        if (selection.stateHash)
+    if (selection.kind === 'begin' || selection.kind === 'delegate') {
+        if ('stateHash' in selection && selection.stateHash)
             states.add(selection.stateHash);
         for (const row of raw.list('operation', `${enrollmentId}:`, 1001))
             if (row.value.binding?.stateHash)
@@ -34,7 +34,7 @@ export function scopedProviderTransaction(selection, raw) {
         else {
             allowed = (kind === 'enrollment' && id === enrollmentId) || (kind === 'user' && id === userKey) || (kind === 'state' && states.has(id));
             if (kind === 'operation')
-                allowed = (selection.kind === 'begin' || selection.kind === 'revoke') ? id.startsWith(`${enrollmentId}:`) : id === `${enrollmentId}:${operationId}`;
+                allowed = (selection.kind === 'begin' || selection.kind === 'delegate' || selection.kind === 'revoke') ? id.startsWith(`${enrollmentId}:`) : id === `${enrollmentId}:${operationId}`;
         }
         if (!allowed)
             throw new TypeError('provider access outside selection');
@@ -44,7 +44,7 @@ export function scopedProviderTransaction(selection, raw) {
         put(kind, id, value) { check(kind, id, true); raw.put(kind, id, value); },
         remove(kind, id) { check(kind, id); raw.remove(kind, id); },
         list(kind, prefix, limit) {
-            if (!['begin', 'revoke'].includes(selection.kind) || kind !== 'operation' || prefix !== `${enrollmentId}:` || !Number.isSafeInteger(limit) || limit < 1 || limit > 1001)
+            if (!['begin', 'delegate', 'revoke'].includes(selection.kind) || kind !== 'operation' || prefix !== `${enrollmentId}:` || !Number.isSafeInteger(limit) || limit < 1 || limit > 1001)
                 throw new TypeError('provider list outside selection');
             return raw.list(kind, prefix, limit);
         },

package/dist/provider.d.ts

@@ -23,6 +23,14 @@ export type ProviderSelection = {
     kind: 'operation';
     enrollmentId: string;
     operationId: string;
+} | {
+    kind: 'delegate';
+    enrollmentId: string;
+    operationId: string;
+    at: number;
+} | {
+    kind: 'metadata';
+    enrollmentId: string;
 } | {
     kind: 'begin';
     enrollmentId: string;
@@ -64,6 +72,10 @@ export interface ProviderOptions {
     store: ProviderStore;
     cipher: ResultCipher;
     metadata: MetadataResolver;
+    /** Publish only for enrollments whose agent has all Operations channels, trusted consent and durable recovery configured. */
+    operations?: {
+        ready(enrollmentId: string): Promise<boolean>;
+    };
     signer: IdentitySigner;
     /** Publish new keys before use and retain retired public keys through assertion expiry + skew. */
     publishedKeys?: () => Promise<Record<string, any>[]>;
@@ -83,7 +95,7 @@ export declare function createProvider(options: ProviderOptions): {
         callbackUrl: string;
     }>;
     identity(credential: string, input: Row): Promise<{
-        clientId: string;
+        clientId: any;
         userId: string;
     }>;
     begin(credential: string, input: Row): Promise<{
@@ -93,6 +105,10 @@ export declare function createProvider(options: ProviderOptions): {
         assertion: string;
         expiresAt: number;
     }>;
+    delegate(credential: string, input: Row): Promise<{
+        delegation: string;
+        expiresAt: number;
+    }>;
     callback(callbackUrl: string): Promise<{
         status: any;
     }>;
@@ -127,16 +143,23 @@ export declare function createProviderClient(options: {
         assertion: string;
         expiresAt: number;
     }>;
+    delegate: (request: {
+        operationId: string;
+        jwk: import("./protocol/wire.js").JsonObject;
+    }) => Promise<{
+        delegation: string;
+        expiresAt: number;
+    }>;
     beginDirect: (input: {
         operationId: string;
         issuer: string;
-        sessionKey: string;
+        sessionKey: string | null;
         state: string;
     }) => Promise<Row>;
     takeResult: (input: {
         operationId: string;
         issuer: string;
-        sessionKey: string;
+        sessionKey: string | null;
     }) => Promise<Row>;
     cancel: (operationId: string) => Promise<Row>;
     revokeEnrollment: () => Promise<Row>;

package/dist/provider.js

@@ -1,6 +1,9 @@
+import { importJWK } from 'jose';
+import { parseJson } from './protocol/wire.js';
 /** Optional PoppyKit provider v1. Hosting, human authentication and key custody belong to the operator. */
 import { createHash, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
 import { secureUrl } from './network/transport.js';
+import { companyIdentifier } from './network/discovery.js';
 /** Explicit migration aid for existing local synchronous stores; unsuitable for remote I/O. */
 export function adaptLegacyProviderStore(store) {
     return { async transaction(_selection, action) {
@@ -53,6 +56,7 @@ function publicKey(value) {
 export function createProvider(options) {
     const { store, cipher } = options, now = options.now ?? Date.now;
     const client = https(options.clientId);
+    const enrolledClientId = (enrollmentId) => { const url = new URL(client); url.pathname = url.pathname.replace(/\/$/, '') + '/enrollments/' + enrollmentId; return url.href; };
     if ([options.callbackUrl, options.jwksUri].some(value => https(value).hostname !== client.hostname) || https(options.callbackUrl).search)
         throw new Error('provider metadata endpoints must share client domain; callback cannot contain query');
     function auth(tx, credential, installationId) {
@@ -66,7 +70,7 @@ export function createProvider(options) {
         const row = tx.get('operation', `${enrollment.enrollmentId}:${operationId}`);
         if (!row)
             fail('binding_conflict');
-        if (row.binding.purpose === 'direct' && (typeof row.binding.sessionKey !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(row.binding.sessionKey)))
+        if (row.binding.purpose === 'direct' && row.binding.sessionKey !== null && (typeof row.binding.sessionKey !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(row.binding.sessionKey)))
             fail('binding_conflict');
         if (row.expiresAt <= now())
             fail('expired');
@@ -78,7 +82,7 @@ export function createProvider(options) {
     }
     async function verified(domain, issuer) {
         const metadata = await options.metadata.resolveCompany(domain);
-        if (metadata.authorization?.issuer !== issuer)
+        if (companyIdentifier(metadata) !== issuer)
             fail('binding_conflict');
         return metadata;
     }
@@ -122,9 +126,9 @@ export function createProvider(options) {
                 tx.put('capacity', 'enrollments', { count: count + 1 });
                 tx.put('visitor', subjectKey, { id: visitor });
                 const enrollmentId = id(), secret = id();
-                tx.put('enrollment', enrollmentId, { installationId, visitor, verifier: hash(secret), allowedCompanies: [...new Set(human.allowedCompanies)], revoked: false, starts: [] });
+                tx.put('enrollment', enrollmentId, { clientId: enrolledClientId(enrollmentId), installationId, visitor, verifier: hash(secret), allowedCompanies: [...new Set(human.allowedCompanies)], revoked: false, starts: [] });
                 tx.put('enrollmentRequest', key, { enrollmentId });
-                return { enrollmentId, credential: `${enrollmentId}.${secret}`, clientId: options.clientId, callbackUrl: options.callbackUrl };
+                return { enrollmentId, credential: `${enrollmentId}.${secret}`, clientId: enrolledClientId(enrollmentId), callbackUrl: options.callbackUrl };
             });
         },
         async identity(credential, input) {
@@ -135,12 +139,12 @@ export function createProvider(options) {
                 const enrollment = auth(tx, credential, text(input.installationId));
                 if (!enrollment.allowedCompanies.includes(metadata.document.organization.domain))
                     fail('unauthorized');
-                return { clientId: options.clientId, userId: user(tx, enrollment.visitor, input.issuer) };
+                return { clientId: enrollment.clientId ?? options.clientId, userId: user(tx, enrollment.visitor, input.issuer) };
             });
         },
         async begin(credential, input) {
             exact(input, ['version', 'installationId', 'operationId', 'domain', 'issuer', 'purpose', 'sessionId', 'sessionKey', 'state']);
-            if (!['client-authentication', 'session', 'direct'].includes(input.purpose))
+            if (!['client-authentication', 'direct'].includes(input.purpose))
                 fail('binding_conflict');
             text(input.operationId);
             if (input.sessionId !== undefined)
@@ -150,7 +154,7 @@ export function createProvider(options) {
                 fail('binding_conflict');
             if (input.purpose !== 'direct' && input.state !== undefined)
                 fail('binding_conflict');
-            if (input.purpose === 'direct' && (typeof input.state !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(input.state) || typeof input.sessionKey !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(input.sessionKey)))
+            if (input.purpose === 'direct' && (typeof input.state !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(input.state) || (input.sessionKey !== null && (typeof input.sessionKey !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(input.sessionKey)))))
                 fail('binding_conflict');
             if (input.purpose !== 'direct' && input.sessionKey !== undefined)
                 fail('binding_conflict');
@@ -196,7 +200,7 @@ export function createProvider(options) {
             exact(input, ['version', 'installationId', 'operationId', 'purpose']);
             const snapshot = await store.transaction(selectedOperation(credential, input), tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), op = operation(tx, enrollment, text(input.operationId));
-                if (op.binding.purpose !== input.purpose || !['client-authentication', 'session'].includes(input.purpose))
+                if (op.binding.purpose !== input.purpose || input.purpose !== 'client-authentication')
                     fail('binding_conflict');
                 throttle(tx, enrollment);
                 return { enrollment, op };
@@ -204,8 +208,9 @@ export function createProvider(options) {
             const b = snapshot.op.binding;
             await verified(b.domain, b.issuer);
             const iat = Math.floor(now() / 1000), exp = iat + 60;
-            const claims = { iss: options.clientId, sub: b.purpose === 'client-authentication' ? options.clientId : b.userId, aud: b.issuer, iat, exp, jti: id() };
-            const header = { alg: 'ES256', kid: options.signer.kid, typ: b.purpose === 'client-authentication' ? 'client-authentication+jwt' : 'JWT' };
+            const signingClientId = snapshot.enrollment.clientId ?? options.clientId;
+            const claims = { iss: signingClientId, sub: signingClientId, aud: b.issuer, iat, exp, jti: id() };
+            const header = { alg: 'ES256', kid: options.signer.kid, typ: 'client-authentication+jwt' };
             const unsigned = `${Buffer.from(JSON.stringify(header)).toString('base64url')}.${Buffer.from(JSON.stringify(claims)).toString('base64url')}`;
             const signature = await options.signer.sign(new TextEncoder().encode(unsigned));
             if (signature.length !== 64)
@@ -214,6 +219,64 @@ export function createProvider(options) {
             await store.transaction(selectedOperation(credential, input), tx => { const enrollment = auth(tx, credential, input.installationId), op = operation(tx, enrollment, input.operationId); tx.put('operation', `${enrollment.enrollmentId}:${input.operationId}`, { ...op, status: 'signed' }); });
             return { assertion: `${unsigned}.${Buffer.from(signature).toString('base64url')}`, expiresAt: exp };
         },
+        async delegate(credential, input) {
+            exact(input, ['version', 'installationId', 'operationId', 'jwk']);
+            const source = object(input.jwk);
+            if (source.kty !== 'EC' || source.crv !== 'P-256' || typeof source.x !== 'string' || typeof source.y !== 'string' || ['d', 'p', 'q', 'dp', 'dq', 'qi', 'oth', 'k'].some(name => name in source))
+                fail('binding_conflict');
+            const jwk = { kty: 'EC', crv: 'P-256', x: source.x, y: source.y };
+            try {
+                await importJWK(jwk, 'ES256');
+            }
+            catch {
+                fail('binding_conflict');
+            }
+            const operationId = text(input.operationId), installationId = text(input.installationId);
+            const selection = { kind: 'delegate', enrollmentId: enrollmentId(credential), operationId, at: now() };
+            const claim = await store.transaction(selection, tx => {
+                const enrollment = auth(tx, credential, installationId);
+                if (!enrollment.clientId || enrollment.allowedCompanies.length !== 1)
+                    fail('binding_conflict'); // Legacy shared-client enrollments cannot release delegated authority.
+                const key = `${enrollment.enrollmentId}:${operationId}`, existing = tx.get('operation', key);
+                const binding = { purpose: 'delegation', jwk };
+                if (existing) {
+                    if (!same(existing.binding, binding) || existing.expiresAt <= now() || existing.status === 'canceled')
+                        fail('binding_conflict');
+                    return { clientId: enrollment.clientId, existing: existing.result ? cipher.open(existing.result) : null, expiresAt: existing.expiresAt };
+                }
+                throttle(tx, enrollment);
+                const rows = tx.list('operation', `${enrollment.enrollmentId}:`, 1001);
+                for (const row of rows)
+                    if (row.value.expiresAt + 30000 <= now()) {
+                        tx.remove('operation', row.id);
+                        if (row.value.binding.stateHash)
+                            tx.remove('state', row.value.binding.stateHash);
+                    }
+                if (rows.filter(row => row.value.expiresAt + 30000 > now()).length >= 1000)
+                    throw new ProviderError('rate_limited', now() + 60000);
+                const expiresAt = (Math.floor(now() / 1800000) * 1800 + 3600) * 1000;
+                tx.put('operation', key, { binding, expiresAt, status: 'pending', result: null, resultHash: null });
+                return { clientId: enrollment.clientId, existing: null, expiresAt };
+            });
+            if (claim.existing)
+                return { delegation: claim.existing, expiresAt: Math.floor(claim.expiresAt / 1000) };
+            const exp = Math.floor(claim.expiresAt / 1000), iat = exp - 3600;
+            const header = { alg: 'ES256', typ: 'pap-delegation+jwt', kid: options.signer.kid };
+            const payload = { iss: claim.clientId, cnf: { jwk }, iat, exp, jti: id() };
+            const unsigned = Buffer.from(JSON.stringify(header)).toString('base64url') + '.' + Buffer.from(JSON.stringify(payload)).toString('base64url');
+            const signature = await options.signer.sign(new TextEncoder().encode(unsigned));
+            if (!(signature instanceof Uint8Array) || signature.length !== 64)
+                fail('unavailable');
+            const delegation = unsigned + '.' + Buffer.from(signature).toString('base64url');
+            return store.transaction({ kind: 'operation', enrollmentId: enrollmentId(credential), operationId }, tx => {
+                const enrollment = auth(tx, credential, installationId), op = operation(tx, enrollment, operationId);
+                if (op.binding.purpose !== 'delegation' || !same(op.binding.jwk, jwk))
+                    fail('binding_conflict');
+                const result = op.result ? cipher.open(op.result) : delegation;
+                tx.put('operation', `${enrollment.enrollmentId}:${operationId}`, { ...op, status: 'signed', result: cipher.seal(result) });
+                return { delegation: result, expiresAt: exp };
+            });
+        },
         async callback(callbackUrl) {
             const url = new URL(callbackUrl), base = new URL(options.callbackUrl);
             if (url.origin !== base.origin || url.pathname !== base.pathname || url.username || url.password || url.hash || ['state', 'iss', 'code', 'error', 'error_description', 'error_uri'].some(key => url.searchParams.getAll(key).length > 1))
@@ -279,6 +342,18 @@ export function createProvider(options) {
             try {
                 if (request.url === options.clientId && request.method === 'GET')
                     return Response.json({ client_id: options.clientId, client_name: options.clientName, jwks_uri: options.jwksUri, redirect_uris: [options.callbackUrl], token_endpoint_auth_method: 'private_key_jwt' }, { headers });
+                if (request.method === 'GET') {
+                    const prefix = client.pathname.replace(/\/$/, '') + '/enrollments/', requested = new URL(request.url);
+                    if (requested.origin === client.origin && requested.pathname.startsWith(prefix)) {
+                        const enrollmentId = requested.pathname.slice(prefix.length);
+                        if (!/^[A-Za-z0-9_-]{43}$/.test(enrollmentId) || request.url !== enrolledClientId(enrollmentId))
+                            return new Response(null, { status: 404 });
+                        const enrollment = await store.transaction({ kind: 'metadata', enrollmentId }, tx => tx.get('enrollment', enrollmentId));
+                        if (!enrollment || enrollment.revoked || enrollment.clientId !== request.url)
+                            return new Response(null, { status: 404 });
+                        return Response.json({ client_id: request.url, client_name: options.clientName, jwks_uri: options.jwksUri, redirect_uris: [options.callbackUrl], token_endpoint_auth_method: 'private_key_jwt', ...(await options.operations?.ready(enrollmentId) ? { extensions: { operations: { version: '2' } } } : {}) }, { headers });
+                    }
+                }
                 if (request.url === options.jwksUri && request.method === 'GET')
                     return Response.json({ keys: (options.publishedKeys ? await options.publishedKeys() : [{ ...await options.signer.publicJwk(), kid: options.signer.kid }]).map(publicKey) }, { headers });
                 const url = new URL(request.url);
@@ -310,11 +385,11 @@ export function createProvider(options) {
                     finally {
                         await reader.cancel().catch(() => { });
                     }
-                const input = object(JSON.parse(body));
+                const input = object(parseJson(body));
                 if (input.version !== 1)
                     fail('binding_conflict');
                 const action = url.pathname.slice(url.pathname.lastIndexOf('/') + 1), credential = request.headers.get('authorization')?.match(/^Bearer (\S+)$/)?.[1] ?? '';
-                const allowed = ['enroll', 'identity', 'begin', 'assert', 'takeResult', 'cancel', 'revokeEnrollment'];
+                const allowed = ['enroll', 'identity', 'begin', 'assert', 'delegate', 'takeResult', 'cancel', 'revokeEnrollment'];
                 if (!allowed.includes(action))
                     fail('binding_conflict');
                 const result = action === 'enroll' ? await api.enroll(request, input) : await api[action](credential, input);
@@ -352,7 +427,13 @@ export function createProviderClient(options) {
         const value = await call('assert', { operationId: request.operationId, purpose: request.purpose });
         return { assertion: text(value.assertion), expiresAt: value.expiresAt };
     };
-    return { identity, assert, beginDirect: (input) => call('begin', { ...input, domain: options.domain, purpose: 'direct' }),
+    const delegate = async (request) => {
+        const value = await call('delegate', request);
+        if (typeof value.expiresAt !== 'number')
+            throw new ProviderError('invalid_response');
+        return { delegation: text(value.delegation), expiresAt: value.expiresAt };
+    };
+    return { identity, assert, delegate, beginDirect: (input) => call('begin', { ...input, domain: options.domain, purpose: 'direct' }),
         takeResult: (input) => call('takeResult', input),
         cancel: (operationId) => call('cancel', { operationId }), revokeEnrollment: () => call('revokeEnrollment', {}) };
 }

package/dist/sqlite.d.ts

@@ -1,3 +1,4 @@
+import type { BusinessAttemptStore } from './operations.js';
 export { SqliteAuthStore } from './auth/sqlite-store.js';
 import type { ConversationKey, ConversationStore } from './conversation-store.js';
 import type { ConsumerCheckpoint, OutboundRecord } from './conversation.js';
@@ -18,3 +19,14 @@ export declare class SqliteConversationStore implements ConversationStore {
     advanceCheckpoint(key: ConversationKey, row: ConsumerCheckpoint, from: readonly (string | undefined)[]): Promise<void>;
     resetCheckpoint(key: ConversationKey, conversation: string, name: string): Promise<void>;
 }
+/** Separate from authentication lifecycle operations. Never discard uncertain business attempts. */
+export declare class SqliteBusinessAttemptStore implements BusinessAttemptStore {
+    readonly namespace: string;
+    private readonly db;
+    constructor(path: string, namespace: string);
+    close(): void;
+    pending(after: string | undefined, limit: number): Promise<string[]>;
+    transaction<T>(id: string, action: (slot: {
+        record?: import('./operations.js').BusinessAttempt;
+    }) => T): Promise<T>;
+}

package/dist/sqlite.js

@@ -1,3 +1,4 @@
+import { validateJson } from './protocol/wire.js';
 import { DatabaseSync } from 'node:sqlite';
 import { initializeSqlite } from './sqlite-init.js';
 export { SqliteAuthStore } from './auth/sqlite-store.js';
@@ -78,3 +79,44 @@ export class SqliteConversationStore {
         this.db.prepare('DELETE FROM checkpoints WHERE connection=? AND issuer=? AND endpoint=? AND conversation=? AND name=?').run(key.connectionId, key.issuer, key.endpoint, conversation, name);
     }
 }
+/** Separate from authentication lifecycle operations. Never discard uncertain business attempts. */
+export class SqliteBusinessAttemptStore {
+    namespace;
+    db;
+    constructor(path, namespace) {
+        this.namespace = namespace;
+        this.db = new DatabaseSync(path);
+        initializeSqlite(this.db, () => this.db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+      CREATE TABLE IF NOT EXISTS business_attempts (ns TEXT NOT NULL, id TEXT NOT NULL, body TEXT NOT NULL, PRIMARY KEY(ns,id));`));
+    }
+    close() { this.db.close(); }
+    async pending(after, limit) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('business recovery limit');
+        return this.db.prepare("SELECT id FROM business_attempts WHERE ns=? AND id>? AND json_extract(body,'$.phase') IN ('pending_consent','consenting','approved','uncertain') ORDER BY id LIMIT ?").all(this.namespace, after ?? '', limit).map(row => row.id);
+    }
+    async transaction(id, action) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const row = this.db.prepare('SELECT body FROM business_attempts WHERE ns=? AND id=?').get(this.namespace, id);
+            const slot = { record: row ? JSON.parse(row.body) : undefined };
+            if (slot.record && slot.record.version !== 1)
+                throw new Error('unsupported business attempt version');
+            const result = action(slot);
+            if (result && typeof result.then === 'function')
+                throw new TypeError('async business attempt transaction');
+            if (slot.record) {
+                if (slot.record.version !== 1 || slot.record.id !== id)
+                    throw new TypeError('business attempt binding');
+                validateJson(slot.record);
+                this.db.prepare('INSERT INTO business_attempts VALUES (?,?,?) ON CONFLICT(ns,id) DO UPDATE SET body=excluded.body').run(this.namespace, id, JSON.stringify(slot.record));
+            }
+            this.db.exec('COMMIT');
+            return structuredClone(result);
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}

package/examples/operations.mjs

@@ -0,0 +1,25 @@
+// Synthetic Company flow. The trusted terminal asks each time; --self-check always declines.
+import assert from 'node:assert/strict';
+import {mkdtemp,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {createInterface} from 'node:readline/promises';
+import {createOperationClient} from '../dist/index.js';
+import {SqliteBusinessAttemptStore} from '../dist/sqlite.js';
+const dir=await mkdtemp(join(tmpdir(),'poppy-operation-example-')),store=new SqliteBusinessAttemptStore(join(dir,'attempts.db'),'synthetic-user');
+const selfCheck=process.argv.includes('--self-check');let sends=0;
+try{
+  const client=createOperationClient({store,context:async()=>({companyId:'https://example.com',companyName:'Example Company',clientId:'https://agent.example/client',userId:'synthetic',authority:'session:synthetic',operations:true}),
+    checkTerms:async(request,operation)=>operation.terms?.order_id===request.arguments?.order_id?[]:['Order differs from your request.'],
+    consent:{confirm:async({attemptId,companyId,companyName,summary,terms,differences})=>{
+      if(selfCheck)return 'decline';
+      if(!process.stdin.isTTY||!process.stderr.isTTY)throw new Error('Trusted terminal required');
+      const saved=await client.get(attemptId),display=JSON.stringify({companyId,companyName,summary,terms,differences,request:saved.request,expiresAt:saved.operation.expires_at},null,2).replace(/[\u007f-\u009f\u2028-\u202e\u2066-\u2069]/g,c=>'\\u'+c.charCodeAt(0).toString(16).padStart(4,'0'));
+      const terminal=createInterface({input:process.stdin,output:process.stderr});
+      try{const answer=await terminal.question(`${display}\nApprove these exact terms? Type yes: `);return answer==='yes'?'approve':'decline';}finally{terminal.close();}
+    }},send:async()=>{sends++;return {kind:'completed',result:{synthetic:true,done:true}};}});
+  await client.receiveMcp('exchange-order-one',{channel:'mcp',url:'https://example.com/mcp',name:'exchange',arguments:{order_id:'one'}},{isError:true,structuredContent:{operation:{operation_id:'exchange_one',revision:'revision_one',summary:'Exchange order one for the blue jacket for $70.',terms:{order_id:'one',amount:'70.00'},expires_at:new Date(Date.now()+900000).toISOString()}}});
+  const decision=await client.requestConsent('exchange-order-one');
+  if(decision.phase==='approved')console.log((await client.retry(decision.id)).phase);else console.log(decision.phase);
+  if(selfCheck){assert.equal(decision.phase,'declined');assert.equal(sends,0);}
+}finally{store.close();await rm(dir,{recursive:true,force:true});}

package/examples/quickstart.mjs

@@ -6,6 +6,7 @@ const domain = selfCheck ? 'company.example' : process.argv[2];
 if (!domain) throw new Error('usage: node examples/quickstart.mjs DOMAIN|--self-check');
 const transport = selfCheck ? {
   async fetch(request) {
+    if (request.url === 'https://company.example/.well-known/oauth-protected-resource') return new Response(null, {status:404});
     assert.equal(request.url, 'https://company.example/.well-known/poppy.json');
     return Response.json({ protocol_version: '0.3', organization: { name: 'Example Company', domain }, web: {} });
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/client",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "description": "Personal Agent Protocol client SDK",
   "repository": {
@@ -43,7 +43,9 @@
     "RELEASING.md",
     "examples",
     "LICENSE",
-    "migrations"
+    "migrations",
+    "CONFORMANCE.md",
+    "OPERATIONS.md"
   ],
   "exports": {
     ".": {
@@ -80,6 +82,7 @@
     }
   },
   "dependencies": {
+    "@agentsig/structured-fields": "0.1.1",
     "jose": "6.2.12"
   },
   "license": "MIT",