@poppykit/server 0.3.1 → 0.5.0

package/dist/browser.js

@@ -1,8 +1,6 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { compactVerify, createLocalJWKSet, decodeJwt, errors } from 'jose';
 import { secureUrl } from './network/transport.js';
-import { parseJson, object } from './protocol/wire.js';
-import { assertUniqueJwtMembers } from './auth/dpop.js';
+import { object, parseJson } from './protocol/wire.js';
 import { AuthorityError } from './auth/authority.js';
 const hash = (value) => createHash('sha256').update(value).digest('base64url');
 export async function boundedText(request, max) {
@@ -32,75 +30,111 @@ export async function boundedText(request, max) {
     return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
 }
 export function createBrowserSessions(options) {
-    secureUrl(options.endpoint);
-    const name = options.cookieName ?? '__Host-poppy-session', sameSite = options.sameSite ?? 'Lax', lifetime = options.cookieLifetimeSeconds ?? 3600;
+    const endpoint = secureUrl(options.endpoint), name = options.cookieName ?? '__Host-poppy-session';
+    const sameSite = options.sameSite ?? 'Lax', lifetime = options.cookieLifetimeSeconds ?? 3600;
     if (!/^[A-Za-z0-9_-]+$/.test(name) || !['Lax', 'None'].includes(sameSite) || !Number.isSafeInteger(lifetime) || lifetime < 1 || !/^[a-z0-9.-]+$/i.test(options.domain))
         throw new TypeError('browser options');
-    const invalid = () => new Error('Invalid browser session');
+    if (name === '__Host-poppy_join' || (endpoint.hostname !== options.domain.toLowerCase() && !endpoint.hostname.endsWith(`.${options.domain.toLowerCase()}`)))
+        throw new TypeError('browser options');
+    const failure = new Error('Invalid browser session');
+    const invalid = () => failure;
+    const authorizationEndpoint = new URL(endpoint);
+    authorizationEndpoint.pathname = endpoint.pathname.replace(/\/$/, '') + '/authorize';
     async function authenticate(request) {
         const cookies = (request.headers.get('cookie') ?? '').split(';').map(part => part.trim().split('='));
         const matches = cookies.filter(([key]) => key === name);
         if (matches.length !== 1 || matches[0].length !== 2 || !/^[A-Za-z0-9_-]{43}$/.test(matches[0][1]))
             throw invalid();
         const binding = await options.cookies.get(hash(matches[0][1]));
-        if (!binding || binding.expiresAt <= options.now())
+        if (!binding?.principal || binding.expiresAt <= options.now())
             throw invalid();
-        const session = await options.authority.current(binding);
-        if (session.expiresAt <= options.now() || session.clientId !== binding.clientId || session.userId !== binding.userId || session.sessionId !== binding.sessionId || session.issuerGeneration !== binding.issuerGeneration)
+        const principal = binding.principal;
+        if (principal.clientId !== binding.clientId || principal.userId !== binding.userId || principal.sessionId !== binding.sessionId)
             throw invalid();
-        return session.principal;
+        return options.policy.withCurrent(principal, [], async () => principal);
     }
     return {
         authenticate,
         async withSession(request, scopes, action) {
             const principal = await authenticate(request);
-            return options.policy.withCurrent(principal, [], async () => {
-                const current = await options.authority.current(principal);
-                if (!scopes.every(scope => current.principal.scopes.includes(scope)))
-                    throw new AuthorityError('insufficient_scope');
-                return action(current.principal);
-            });
+            return options.policy.withCurrent(principal, scopes, () => action(principal));
         },
-        async join(request) {
+        async authorize(request) {
             try {
-                if (request.method !== 'POST' || request.url !== options.endpoint || request.headers.get('content-type')?.split(';')[0] !== 'application/x-www-form-urlencoded')
+                if (request.url !== authorizationEndpoint.href || request.method !== 'POST' || request.headers.get('content-type')?.split(';')[0] !== 'application/json')
                     throw invalid();
-                const fields = new URLSearchParams(await boundedText(request, 16384));
-                if (fields.getAll('assertion').length !== 1 || [...fields.keys()].some(key => key !== 'assertion'))
+                let value;
+                try {
+                    value = object(parseJson(await boundedText(request, 4096)));
+                }
+                catch {
+                    throw failure;
+                }
+                if (typeof value.code !== 'string' || !/^[A-Za-z0-9_-]{1,256}$/.test(value.code))
                     throw invalid();
-                const jwt = fields.get('assertion');
-                if (jwt.length > 8192)
+                const principal = await options.authenticator.authenticate(request);
+                const success = await options.policy.withCurrent(principal, [], () => options.cookies.authorizeJoin(hash(value.code), principal, options.now()));
+                if (!success)
                     throw invalid();
-                assertUniqueJwtMembers(jwt);
-                const untrusted = decodeJwt(jwt);
-                if (typeof untrusted.iss !== 'string')
+                return new Response(null, { status: 204, headers: { 'Cache-Control': 'no-store' } });
+            }
+            catch (error) {
+                if (error instanceof AuthorityError)
+                    return error.response();
+                if (error !== failure)
+                    throw error;
+                return Response.json({ error: 'invalid_request' }, { status: 400, headers: { 'Cache-Control': 'no-store' } });
+            }
+        },
+        async join(request) {
+            try {
+                if (request.url !== options.endpoint)
                     throw invalid();
-                const client = await options.metadata.resolveClient(untrusted.iss);
-                let keys = await options.metadata.resolveJwks(client.jwks_uri);
-                let verified;
-                try {
-                    verified = await compactVerify(jwt, createLocalJWKSet(keys), { algorithms: ['ES256', 'RS256'] });
+                if (request.method === 'GET') {
+                    const code = randomBytes(32).toString('base64url'), cookie = randomBytes(32).toString('base64url');
+                    await options.cookies.putJoin(hash(code), { cookieHash: hash(cookie), expiresAt: options.now() + 60000 });
+                    return new Response(`<!doctype html><title>Connecting</title><form method="post"><input type="hidden" name="code" value="${code}"><button>Continue</button></form>`, { headers: {
+                            'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store',
+                            'Content-Security-Policy': "default-src 'none'; form-action 'self'; frame-ancestors 'none'", 'Cross-Origin-Opener-Policy': 'same-origin',
+                            'Set-Cookie': '__Host-poppy_join=' + cookie + '; Path=/; Max-Age=60; Secure; HttpOnly; SameSite=Strict',
+                        } });
                 }
-                catch (error) {
-                    if (!(error instanceof errors.JWKSNoMatchingKey))
-                        throw error;
-                    keys = await options.metadata.resolveJwks(client.jwks_uri, { refresh: true });
-                    verified = await compactVerify(jwt, createLocalJWKSet(keys), { algorithms: ['ES256', 'RS256'] });
-                }
-                const claims = object(parseJson(new TextDecoder().decode(verified.payload)));
-                if (verified.protectedHeader.typ?.toLowerCase().replace(/^application\//, '') !== 'poppy-browser+jwt' || claims.iss !== client.client_id || claims.aud !== options.endpoint || typeof claims.sub !== 'string' || !claims.sub || claims.sub.length > 256 || typeof claims.session_id !== 'string' || !claims.session_id || typeof claims.jti !== 'string' || !claims.jti || claims.jti.length > 256 || !Number.isSafeInteger(claims.iat) || !Number.isSafeInteger(claims.exp) || claims.exp <= options.now() / 1000 || claims.iat > options.now() / 1000 + 30 || claims.exp <= claims.iat || claims.exp - claims.iat > 60 || typeof claims.return_to !== 'string')
+                if (request.method !== 'POST' || request.headers.get('content-type')?.split(';')[0] !== 'application/x-www-form-urlencoded')
+                    throw invalid();
+                const fields = new URLSearchParams(await boundedText(request, 16384)), codes = fields.getAll('code');
+                const issued = [];
+                for (const code of new Set(codes))
+                    issued.push(await options.cookies.consumeJoin(hash(code)));
+                if (codes.length !== 1 || [...fields.keys()].some(key => key !== 'code'))
+                    throw invalid();
+                const binding = issued[0];
+                const cookies = (request.headers.get('cookie') ?? '').split(';').map(part => part.trim().split('='));
+                const matches = cookies.filter(([key]) => key === '__Host-poppy_join');
+                if (!binding?.principal || binding.expiresAt <= options.now() || matches.length !== 1 || matches[0].length !== 2 || hash(matches[0][1]) !== binding.cookieHash)
                     throw invalid();
-                const destination = secureUrl(claims.return_to);
-                if (destination.hostname !== options.domain.toLowerCase() && !destination.hostname.endsWith(`.${options.domain.toLowerCase()}`))
+                const origin = request.headers.get('origin'), site = request.headers.get('sec-fetch-site');
+                if ((origin !== null && origin !== endpoint.origin) || (site !== null && !['same-origin', 'none'].includes(site)))
                     throw invalid();
-                const session = await options.authority.join({ clientId: client.client_id, userId: claims.sub, sessionId: claims.session_id }, { jti: claims.jti, expiresAt: claims.exp * 1000 });
-                const seconds = Math.floor(Math.min(session.expiresAt - options.now(), lifetime * 1000) / 1000);
-                if (seconds < 1)
+                const principal = { ...binding.principal };
+                const seconds = Math.floor(Math.min((principal.sessionExpiresAt ?? principal.tokenExpiresAt) - options.now(), lifetime * 1000) / 1000);
+                if (seconds < 1 || (principal.accountId && !options.clearLogin))
                     throw invalid();
+                principal.tokenExpiresAt = options.now() + seconds * 1000;
                 const value = randomBytes(32).toString('base64url');
-                const { clientId, userId, sessionId, issuerGeneration } = session;
-                await options.cookies.put(hash(value), { clientId, userId, sessionId, ...(issuerGeneration === undefined ? {} : { issuerGeneration }), expiresAt: options.now() + seconds * 1000 });
-                return new Response(null, { status: 303, headers: { Location: claims.return_to, 'Set-Cookie': `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=${sameSite}; Max-Age=${seconds}`, 'Cache-Control': 'no-store' } });
+                return await options.policy.withCurrent(principal, [], async () => {
+                    const headers = new Headers({ Location: new URL('/', options.endpoint).href, 'Cache-Control': 'no-store' });
+                    if (principal.accountId)
+                        await options.clearLogin(request, headers);
+                    const previous = cookies.filter(([key]) => key === name);
+                    if (previous.length > 1)
+                        throw invalid();
+                    if (previous[0]?.[1])
+                        await options.cookies.remove(hash(previous[0][1]));
+                    await options.cookies.put(hash(value), { clientId: principal.clientId, userId: principal.userId, sessionId: principal.sessionId, ...(principal.issuerGeneration === undefined ? {} : { issuerGeneration: principal.issuerGeneration }), principal, expiresAt: principal.tokenExpiresAt });
+                    headers.append('Set-Cookie', `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=${sameSite}; Max-Age=${seconds}`);
+                    headers.append('Set-Cookie', '__Host-poppy_join=; Path=/; Max-Age=0; Secure; HttpOnly; SameSite=Strict');
+                    return new Response(null, { status: 303, headers });
+                });
             }
             catch {
                 return new Response('Invalid browser session', { status: 400, headers: { 'Cache-Control': 'no-store', 'Content-Type': 'text/plain' } });

package/dist/conversation/service.d.ts

@@ -1,15 +1,18 @@
-import type { ConversationEvent, JsonObject, Message, Sender, Status } from '../protocol/wire.js';
+import type { OperationApproval, OperationRequest } from '../protocol/operations.js';
+import type { MetadataResolver } from '../network/discovery.js';
+import type { ConversationEvent, JsonObject, Message, AuthorType, Status } from '../protocol/wire.js';
 import type { ConversationStore, ConversationNotifications } from './store.js';
-import type { AcceptedAuthority, AuthorityPolicy, RequestAuthenticator, WorkRevocationPolicy } from '../auth/authority.js';
+import type { AcceptedAuthority, AuthorityPolicy, Principal, RequestAuthenticator, WorkRevocationPolicy } from '../auth/authority.js';
 export interface ConversationRecord {
     id: string;
     issuer: string;
     clientId: string;
     userId: string;
     bindingId: string;
+    operationApprovals?: string[];
     lastUserMessage?: Message;
     status: Status;
-    responder: Sender;
+    responder: AuthorType;
     context: JsonObject;
     events: ConversationEvent[];
     eventWindow?: {
@@ -43,7 +46,7 @@ export interface MessageRecord {
 }
 export interface ConversationStoreState {
     cursorStatus?: 'expired' | 'invalid';
-    version: 1;
+    version: 2;
     generation: string;
     conversations: Record<string, ConversationRecord>;
     bindings: Record<string, {
@@ -53,6 +56,8 @@ export interface ConversationStoreState {
     work: WorkRecord[];
 }
 export interface ConversationOptions {
+    /** Enable only with durable business execution and published Company v2 capability. Unsupported clients are refused. */
+    operations?: MetadataResolver;
     endpoint: string;
     store: ConversationStore;
     authenticator: RequestAuthenticator;
@@ -76,8 +81,8 @@ export interface ConversationOptions {
     authorizeOperator?: (operator: unknown, conversationId: string) => Promise<void>;
     /** Mandatory for requestAuthorization: the scopes the issuer's Direct Sign-In grants; work may ask only for these. */
     directScopes?: readonly string[];
-    /** Scopes that allow reading account-bound history; default ['poppy:read']. A Company offering only custom scopes sets its own. */
-    historyScopes?: readonly string[];
+    /** Required nonempty company scopes for account-bound history. */
+    historyScopes: readonly string[];
 }
 export interface WorkRef {
     workId: string;
@@ -92,8 +97,13 @@ export interface ConversationService {
     /** Protocol errors become responses; anything else is re-thrown, so hosts must catch it and answer 500. */
     handle(request: Request): Promise<Response>;
     claim(): Promise<WorkClaim | null>;
+    operationContext(work: WorkRef): Promise<{
+        principal: Principal;
+        request: OperationRequest;
+        approval?: OperationApproval;
+    }>;
     renew(work: WorkRef): Promise<void>;
-    /** Conversation history for a model or handler; account-bound history needs the bound account and poppy:read. */
+    /** Conversation history for a model or handler; account-bound history needs the bound account and configured historyScopes. */
     history(work: WorkRef): Promise<ConversationEvent[]>;
     /** Account-use gate: call before any account read or tool. Checks accepted authority, then binds the shared ownership once. */
     requireAccount(work: WorkRef, scopes: readonly string[]): Promise<{
@@ -109,7 +119,7 @@ export interface ConversationService {
     handoff(work: WorkRef): Promise<void>;
     /** The company closes the conversation (and its open Direct Conversation); idempotent. */
     close(work: WorkRef): Promise<void>;
-    /** A person joins: automated work is fenced and the returned claim publishes with sender human. Renew it within operatorLeaseMs. */
+    /** A person joins: automated work is fenced and the returned claim publishes with author.type human. Renew it within operatorLeaseMs. */
     joinHuman(operator: unknown, conversationId: string): Promise<WorkClaim>;
     /** Nobody can join a queued conversation: the agent says why and the conversation leaves the queue. No-op unless queued. */
     noHumanAvailable(operator: unknown, conversationId: string, reason: string): Promise<void>;

package/dist/conversation/service.js

@@ -1,6 +1,8 @@
+import { supportsOperations, parseOperationApproval } from '../protocol/operations.js';
+import { companyScopes } from '../network/discovery.js';
 import { randomBytes } from 'node:crypto';
 import { createConversationNotifications } from './store.js';
-import { ValidationError, canonical, parseJson, object, parseConversationRequest, parseMessage, parseReadOptions } from '../protocol/wire.js';
+import { ValidationError, canonical, parseJson, object, parseEvent, parseConversationRequest, parseMessage, parseReadOptions } from '../protocol/wire.js';
 import { secureUrl } from '../network/transport.js';
 import { own } from '../store.js';
 import { AuthorityError } from '../auth/authority.js';
@@ -13,12 +15,12 @@ export class PublicationError extends Error {
     }
 }
 // Spec 7.10: text or data in a Direct Conversation is the User's own words; context-only messages may come from the agent.
-const directWords = (message) => message.sender !== 'human' && (message.text !== undefined || message.data !== undefined);
+const directWords = (message) => message.author.type !== 'human' && (message.text !== undefined || message.data !== undefined);
 const maxBodyBytes = 1048576;
 const maxWaitSeconds = 30;
 const randomId = (prefix) => prefix + randomBytes(16).toString('base64url');
 export function initialConversationState() {
-    return { version: 1, generation: randomId(''), conversations: {}, bindings: {}, messages: {}, work: [] };
+    return { version: 2, generation: randomId(''), conversations: {}, bindings: {}, messages: {}, work: [] };
 }
 /** For the host's reset transaction: a fresh state with a new generation, so every old fence is stale. */
 export function resetConversationState(draft) {
@@ -71,7 +73,11 @@ async function readJson(request) {
 export function createConversationService(options) {
     const { store, authenticator, policy, clock } = options;
     const pageSize = options.pageSize ?? 100;
-    const historyScopes = [...(options.historyScopes ?? ['poppy:read'])];
+    const historyScopes = [...companyScopes(options.historyScopes)];
+    if (options.supportedScopes)
+        companyScopes(options.supportedScopes, true);
+    if (options.directScopes)
+        companyScopes(options.directScopes, true);
     const leaseMs = options.leaseMs ?? 60000;
     const operatorLeaseMs = options.operatorLeaseMs ?? 900000;
     const pollIntervalMs = options.pollIntervalMs ?? 1000;
@@ -209,7 +215,8 @@ export function createConversationService(options) {
         }
         const events = [];
         let bytes = 1024; // Worst-case IDs, status, responder, cursor and JSON envelope.
-        for (const event of conversation.events.slice(start, start + pageSize)) {
+        for (const stored of conversation.events.slice(start, start + pageSize)) {
+            const event = parseEvent(stored, !!options.operations);
             const size = Buffer.byteLength(JSON.stringify(event)) + 1;
             if (bytes + size > maxPageBytes)
                 break;
@@ -226,7 +233,7 @@ export function createConversationService(options) {
     function ack(conversation) {
         return { conversation_id: conversation.id, status: conversation.status, responder: conversation.responder };
     }
-    // Account-bound history needs poppy:read; sending alone does not read history. Other readers fail ownership first.
+    // Account-bound history needs the configured scopes; sending alone does not read history. Other readers fail ownership first.
     const scopesFor = (state, principal, conversation, history) => 
     // Only an owner may see a scope error; for anyone else ownership fails first with 404, so existence never leaks.
     conversation && history && conversation.issuer === principal.issuer && conversation.clientId === principal.clientId && principal.accountId !== undefined
@@ -241,7 +248,7 @@ export function createConversationService(options) {
             return conversation;
         // Spec 7.11: the same User not signed in to the bound account (signed out or another account) is told to sign in; anyone else learns nothing.
         if (accountId !== undefined && conversation.userId === principal.userId)
-            throw new AuthorityError('sign_in_required');
+            throw new AuthorityError(principal.accountId ? 'insufficient_scope' : 'account_required', { scope: historyScopes.join(' ') });
         throw notFound();
     }
     // Runs change under withCurrent; target() and history() decide the scopes from the state being checked.
@@ -266,11 +273,13 @@ export function createConversationService(options) {
     async function accept(request, principal, url, conversationId) {
         const read = parseReadOptions(url, maxWaitSeconds);
         const waiting = url.searchParams.has('wait');
-        const body = parseConversationRequest(await readJson(request));
+        const body = parseConversationRequest(await readJson(request), !!options.operations);
+        if (body.message.approval && conversationId === undefined)
+            throw new ValidationError('message.approval');
         const parentId = conversationId === undefined ? body.parent_conversation_id : undefined;
         // A Direct Conversation carries the User's own words (7.10).
         if (parentId !== undefined && directWords(body.message))
-            throw new ValidationError('message.sender');
+            throw new ValidationError('message.author.type');
         const key = JSON.stringify([principal.issuer, principal.clientId, principal.userId, body.message.id]);
         const fingerprint = canonical({ target: conversationId ?? null, request: body });
         const authority = JSON.parse(JSON.stringify({ principal, acceptedAt: clock.now(), revocationPolicy }));
@@ -326,11 +335,21 @@ export function createConversationService(options) {
                 if (conversation.childId !== undefined)
                     throw directOpen(conversation.childId);
                 if (conversation.parentId !== undefined && directWords(body.message))
-                    throw new ValidationError('message.sender');
+                    throw new ValidationError('message.author.type');
                 if (read.cursor !== undefined)
                     page(conversation, read.cursor, draft.cursorStatus);
                 conversation.authority = authority;
             }
+            if (body.message.approval) {
+                const approved = parseOperationApproval(body.message.approval);
+                const approvalKey = canonical([approved.operation_id, approved.revision]);
+                if (conversation.operationApprovals?.includes(approvalKey)) {
+                    const result = { status: 202, body: ack(conversation) };
+                    draft.messages[key] = { conversationId: conversation.id, fingerprint, receipt: result };
+                    return result;
+                }
+                conversation.operationApprovals = [...(conversation.operationApprovals ?? []), approvalKey];
+            }
             pruneWork(draft);
             const message = body.message;
             conversation.lastUserMessage = message;
@@ -339,7 +358,7 @@ export function createConversationService(options) {
             addEvent(conversation, { type: 'message', message: { ...message, role: 'user' } });
             // A context-only message asks nothing. Work always records this message's own accepted authority; while queued
             // for or answered by a person it is held for them and reaches automation only if they never answer it.
-            if ('text' in message || 'data' in message) {
+            if ('text' in message || 'data' in message || 'approval' in message) {
                 const held = conversation.responder === 'human' || conversation.status === 'queued';
                 draft.work.push({ id: randomId('wrk_'), conversationId: conversation.id, message, authority, phase: held ? 'held' : 'pending', outputs: {} });
                 if (!held && conversation.status === 'idle')
@@ -492,6 +511,8 @@ export function createConversationService(options) {
         if (request.method !== method)
             throw new HttpError(405, { error: 'method_not_allowed' }, { Allow: method });
         const principal = await authenticator.authenticate(request);
+        if (options.operations && !supportsOperations(await options.operations.resolveClient(principal.clientId)))
+            throw new HttpError(403, { error: 'extension_required', extension: 'operations' }, { 'WWW-Authenticate': 'Bearer error="extension_required", extension="operations"' });
         if (!match)
             return accept(request, principal, url);
         const [, id, action] = match;
@@ -597,7 +618,7 @@ export function createConversationService(options) {
                     return json(400, { error: 'invalid_request' });
                 // Status/code/headers only, never the raw message.
                 if (error instanceof AuthorityError)
-                    return json(error.status, { error: error.code }, error.headers);
+                    return error.code === 'account_required' || error.code === 'invalid_session' ? error.response() : json(error.status, { error: error.code }, error.headers);
                 throw error;
             }
         },
@@ -619,7 +640,7 @@ export function createConversationService(options) {
                     work.phase = 'claimed';
                     work.fence = newFence(draft);
                     work.leaseUntil = now + leaseMs;
-                    return { workId: work.id, fence: work.fence, conversationId: work.conversationId, message: work.message, context: conversation.context };
+                    return { workId: work.id, fence: work.fence, conversationId: work.conversationId, message: parseMessage(work.message, { operations: !!options.operations }), context: conversation.context };
                 }
                 return null;
             });
@@ -635,8 +656,8 @@ export function createConversationService(options) {
             return publish(ref, (state, work) => boundAccount(state, work) === undefined ? [] : historyScopes, (draft, work, conversation) => {
                 const accountId = boundAccount(draft, work);
                 if (accountId !== undefined && work.authority.principal.accountId !== accountId)
-                    throw new AuthorityError('sign_in_required');
-                return linkedHistory(draft, conversation);
+                    throw new AuthorityError('insufficient_scope', { scope: historyScopes.join(' ') });
+                return linkedHistory(draft, conversation).map(event => parseEvent(event, !!options.operations));
             }, never, true);
         },
         requireAccount(ref, scopes) {
@@ -645,17 +666,32 @@ export function createConversationService(options) {
                 const binding = draft.bindings[conversation.bindingId];
                 // Parent and child share this record, so the first account use wins for both and no other account can.
                 if (accountId === undefined || (binding.accountId ?? accountId) !== accountId)
-                    throw new AuthorityError('sign_in_required');
+                    throw new AuthorityError('insufficient_scope', { scope: (scopes.length ? scopes : historyScopes).join(' ') });
                 binding.accountId = accountId;
                 return { accountId };
             });
         },
+        operationContext(ref) {
+            if (!options.operations)
+                throw new TypeError('operations not configured');
+            return publish(ref, noScopes, (_draft, work, conversation) => ({
+                principal: structuredClone(work.authority.principal),
+                request: { channel: 'conversation', endpoint: options.endpoint, conversationId: conversation.id },
+                ...(work.message.approval ? { approval: parseOperationApproval(work.message.approval) } : {}),
+            }));
+        },
         async reply(ref, outputId, message) {
-            const parsed = parseMessage(message, { company: true });
+            if (message.operation) {
+                const state = await store.read({ workId: ref.workId });
+                const work = state.work.find(row => row.id === ref.workId);
+                if (!work || !options.operations || !supportsOperations(await options.operations.resolveClient(work.authority.principal.clientId)))
+                    throw new ValidationError('message.operation');
+            }
+            const parsed = parseMessage(message, { company: true, operations: !!options.operations });
             const payload = canonical({ reply: parsed });
             await publish(ref, noScopes, (draft, work, conversation) => {
-                if (parsed.sender !== conversation.responder)
-                    throw new ValidationError('message.sender');
+                if (parsed.author.type !== conversation.responder)
+                    throw new ValidationError('message.author.type');
                 if (!firstOutput(work, outputId, payload))
                     return;
                 // A person's reply answers the messages held for them so far.
@@ -673,14 +709,10 @@ export function createConversationService(options) {
             if (!Array.isArray(scopes) || !scopes.length || !scopes.every(scope => typeof scope === 'string' && direct.includes(scope)))
                 throw new TypeError('scopes');
             const scope = [...new Set(scopes)].join(' ');
-            await publish(ref, noScopes, (draft, work, conversation, live) => {
+            await publish(ref, noScopes, (_draft, work, conversation) => {
                 if (!firstOutput(work, outputId, canonical({ authorization: scope })))
                     return;
-                const { accountId, scopes: granted } = work.authority.principal;
-                const bound = boundAccount(draft, work);
-                // More scopes only helps a live sign-in on the right account; signed out, another account or revoked all need sign-in.
-                const narrow = live && accountId !== undefined && (bound ?? accountId) === accountId && !scopes.every(item => granted.includes(item));
-                addEvent(conversation, { type: 'authorization', error: narrow ? 'insufficient_scope' : 'sign_in_required', scope });
+                addEvent(conversation, { type: 'authorization', error: 'insufficient_scope', scope });
             }, always);
         },
         async requestUser(ref, outputId, reason) {
@@ -701,7 +733,7 @@ export function createConversationService(options) {
                 delete work.leaseUntil;
                 // Spec 7.8: 'human' means a person's own words, so a person's failed work gets no canned apology.
                 if (outcome === 'failed' && !work.human) {
-                    addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', sender: 'agent', text: 'Sorry, something went wrong and this request could not be completed.' } });
+                    addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', author: { type: 'agent' }, text: 'Sorry, something went wrong and this request could not be completed.' } });
                 }
                 if (conversation.status === 'working')
                     setState(conversation, idleOrWorking(draft, conversation.id));
@@ -727,7 +759,7 @@ export function createConversationService(options) {
                 const source = conversation.lastUserMessage ?? last?.message;
                 if (!source)
                     throw new PublicationError('stale_work');
-                const { role: _role, ...message } = source;
+                const { role: _role, ...message } = parseMessage(source, { operations: !!options.operations });
                 const work = { id: randomId('wrk_'), conversationId, message, authority, phase: 'claimed', fence: newFence(draft), leaseUntil: clock.now() + operatorLeaseMs, human: true, outputs: {} };
                 conversation.humanUntil = work.leaseUntil;
                 draft.work.push(work);
@@ -746,7 +778,7 @@ export function createConversationService(options) {
                     throw new PublicationError('stale_work');
                 // Messages sent while queued were meant for a person; the agent answers them now.
                 release(draft, conversationId);
-                addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', sender: 'agent', text: reason } });
+                addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', author: { type: 'agent' }, text: reason } });
                 setState(conversation, idleOrWorking(draft, conversationId), 'agent');
             });
         },

package/dist/feedback.d.ts

@@ -1,8 +1,8 @@
 import type { RequestAuthenticator, AuthorityPolicy, Principal } from './auth/authority.js';
 export interface FeedbackReport {
-    kind: string;
     task: string;
     description: string;
+    [key: string]: unknown;
 }
 export declare function createFeedbackHandler(options: {
     endpoint: string;

package/dist/feedback.js

@@ -12,7 +12,7 @@ export function createFeedbackHandler(options) {
         }
         catch (error) {
             if (error instanceof AuthorityError)
-                return new Response(null, { status: error.status, headers: error.headers });
+                return error.response();
             throw error;
         }
         if (request.url !== options.endpoint || request.method !== 'POST' || request.headers.get('content-type')?.split(';')[0] !== 'application/json')
@@ -20,9 +20,9 @@ export function createFeedbackHandler(options) {
         let report;
         try {
             const value = object(parseJson(await boundedText(request, 16384)));
-            if (typeof value.kind !== 'string' || !value.kind.length || typeof value.task !== 'string' || !value.task.length || [...value.task].length > 200 || typeof value.description !== 'string' || !value.description.length || [...value.description].length > 2000)
+            if (typeof value.task !== 'string' || !value.task.length || [...value.task].length > 200 || typeof value.description !== 'string' || !value.description.length || [...value.description].length > 2000)
                 throw 0;
-            report = { kind: value.kind, task: value.task, description: value.description };
+            report = { ...value, task: value.task, description: value.description };
         }
         catch {
             return fail(400, 'invalid_request');
@@ -30,14 +30,14 @@ export function createFeedbackHandler(options) {
         try {
             return await options.policy.withCurrent(principal, [], async () => {
                 if (options.allow && !await options.allow(principal))
-                    return fail(429, 'rate_limited');
+                    return Response.json({ error: 'temporarily_unavailable' }, { status: 429, headers: { 'Cache-Control': 'no-store', 'Retry-After': '60' } });
                 await options.accept(Object.freeze(report), principal);
                 return new Response(null, { status: 202 });
             });
         }
         catch (error) {
             if (error instanceof AuthorityError)
-                return new Response(null, { status: error.status, headers: error.headers });
+                return error.response();
             throw error;
         }
     };

package/dist/index.d.ts

@@ -5,7 +5,12 @@ export * from './conversation/service.js';
 export type { ConversationStore, ConversationSelection, ConversationNotifications } from './conversation/store.js';
 export { createConversationNotifications } from './conversation/store.js';
 export { createBrowserSessions } from './browser.js';
-export type { BrowserBinding, BrowserSession, BrowserSessionAuthority, BrowserCookieStore } from './browser.js';
+export type { BrowserBinding, BrowserCookieStore, BrowserJoin } from './browser.js';
 export { createFeedbackHandler } from './feedback.js';
 export type { FeedbackReport } from './feedback.js';
 export { mcpResourceMetadata, mcpAuthorizationError } from './mcp.js';
+export type { Author, AuthorType, Message, RecordedMessage, ConversationRequest, ConversationState, ConversationEvent, KnownEvent, EventPage } from './protocol/wire.js';
+export { createSessionAuthority } from './auth/session.js';
+export type { SessionRecord, SessionState, SessionAdmission, SessionStore, SessionAuthority } from './auth/session.js';
+export * from './operations.js';
+export * from './protocol/operations.js';

package/dist/index.js

@@ -5,3 +5,6 @@ export { createConversationNotifications } from './conversation/store.js';
 export { createBrowserSessions } from './browser.js';
 export { createFeedbackHandler } from './feedback.js';
 export { mcpResourceMetadata, mcpAuthorizationError } from './mcp.js';
+export { createSessionAuthority } from './auth/session.js';
+export * from './operations.js';
+export * from './protocol/operations.js';

package/dist/mcp.d.ts

@@ -1,7 +1,7 @@
 import type { AuthorityError } from './auth/authority.js';
 export declare function mcpResourceMetadata(input: {
     resource: string;
-    issuer: string;
+    issuer?: string;
     dpop: boolean;
 }): Record<string, unknown>;
 export declare function mcpAuthorizationError(error: AuthorityError, metadataUrl: string, dpop: boolean): Response;

package/dist/mcp.js

@@ -1,14 +1,18 @@
 import { secureUrl } from './network/transport.js';
 export function mcpResourceMetadata(input) {
     secureUrl(input.resource);
-    secureUrl(input.issuer);
-    return { resource: input.resource, authorization_servers: [input.issuer], bearer_methods_supported: ['header'], ...(input.dpop ? { dpop_signing_alg_values_supported: ['ES256'] } : {}) };
+    if (input.issuer)
+        secureUrl(input.issuer);
+    return { resource: input.resource, authorization_servers: input.issuer ? [input.issuer] : [], bearer_methods_supported: ['header'], ...(input.dpop ? { dpop_signing_alg_values_supported: ['ES256'] } : {}) };
 }
 export function mcpAuthorizationError(error, metadataUrl, dpop) {
+    if (error.code === 'invalid_session' || error.code === 'rate_limited')
+        return error.response();
     secureUrl(metadataUrl);
     if (/["\x00-\x20\\]/.test(metadataUrl))
         throw new TypeError('metadataUrl');
-    const scope = error.headers.get('www-authenticate')?.match(/, scope="[^"]*"/)?.[0] ?? '';
-    const challenge = (scheme) => `${scheme} error="${error.code}"${scope}, resource_metadata="${metadataUrl}"`;
+    const scope = error.headers.get('www-authenticate')?.match(/(?:^|[ ,])scope="([^"]*)"/)?.[1];
+    const attributes = [...(error.code === 'account_required' ? [] : [`error="${error.code}"`]), ...(scope === undefined ? [] : [`scope="${scope}"`]), `resource_metadata="${metadataUrl}"`];
+    const challenge = (scheme) => `${scheme} ${attributes.join(', ')}`;
     return new Response(null, { status: error.status, headers: { 'WWW-Authenticate': [challenge('Bearer'), ...(dpop ? [challenge('DPoP')] : [])].join(', '), 'Cache-Control': 'no-store' } });
 }