@poppykit/server 0.4.0 → 0.5.0

package/dist/adapter-contract.js

@@ -23,6 +23,63 @@ export function runIssuerAdapterContract(fixture) {
         }
     });
 }
+export function runSessionAdapterContract(fixture) {
+    test('Session adapter contract: admission counts, concurrent writers, detached snapshots and rollback', async () => {
+        const f = await fixture(), at = 1790900000000, client = 'https://agent.example/client', sid = 'session_a';
+        try {
+            const empty = await f.store.read(client, sid);
+            assert.equal(empty.record, null);
+            assert.equal((await f.second.read(client, sid)).generation, empty.generation);
+            await Promise.all(Array.from({ length: 8 }, (_, i) => (i % 2 ? f.store : f.second).transaction(client, sid, at, state => {
+                assert.equal(state.activeCount, state.record ? 1 : 0);
+                state.record ??= { instanceId: 'instance_a', clientId: client, sid, userId: 'user_a', createdAt: at, expiresAt: at + 1000, ended: false };
+                state.record.expiresAt++;
+            })));
+            const snapshot = await f.second.read(client, sid);
+            assert.equal(snapshot.record.expiresAt, at + 1008);
+            snapshot.record.userId = 'detached';
+            assert.equal((await f.store.read(client, sid)).record.userId, 'user_a');
+            await assert.rejects(f.store.transaction(client, sid, at, state => { state.record.userId = 'rollback'; throw new Error('rollback'); }), /rollback/);
+            await assert.rejects(f.store.transaction(client, sid, at, async (state) => { state.record.userId = 'async'; }));
+            assert.equal((await f.second.read(client, sid)).record.userId, 'user_a');
+            await f.second.transaction(client, 'absent', at, state => { assert.equal(state.activeCount, 1); assert.equal(state.earliestExpiry, at + 1008); });
+            await f.store.transaction(client, 'absent', at + 1008, state => { assert.equal(state.activeCount, 0); assert.equal(state.earliestExpiry, null); });
+            assert.equal((await f.store.read('https://other.example/client', sid)).record, null);
+        }
+        finally {
+            await f.close();
+        }
+    });
+}
+export function runBrowserCookieAdapterContract(fixture) {
+    test('browser adapter contract: one authorization and consumption across handles, fixed detached cookies', async () => {
+        const f = await fixture(), at = 1790900000000, principal = { issuer: 'https://company.example', clientId: 'https://agent.example/client', userId: 'user_a', sessionId: 'session_a', sessionVersion: 1, scopes: ['read'], tokenExpiresAt: at + 1000 };
+        try {
+            await f.store.putJoin('code', { cookieHash: 'cookie', expiresAt: at + 1000 });
+            const authorized = await Promise.all([f.store.authorizeJoin('code', principal, at), f.second.authorizeJoin('code', principal, at)]);
+            assert.deepEqual(authorized.sort(), [false, true]);
+            const consumed = await Promise.all([f.store.consumeJoin('code'), f.second.consumeJoin('code')]);
+            assert.equal(consumed.filter(Boolean).length, 1);
+            assert.deepEqual(consumed.find(Boolean).principal, principal);
+            await f.store.putJoin('expired', { cookieHash: 'cookie', expiresAt: at - 1 });
+            assert.equal(await f.second.authorizeJoin('expired', principal, at), false);
+            assert.ok(await f.second.consumeJoin('expired'));
+            assert.equal(await f.store.consumeJoin('expired'), null);
+            const binding = { clientId: principal.clientId, userId: principal.userId, sessionId: principal.sessionId, principal, expiresAt: at + 1000 };
+            await f.store.put('browser', binding);
+            principal.scopes.push('write');
+            const cookie = await f.second.get('browser');
+            assert.deepEqual(cookie.principal.scopes, ['read']);
+            cookie.principal.scopes.push('admin');
+            assert.deepEqual((await f.store.get('browser')).principal.scopes, ['read']);
+            await f.second.remove('browser');
+            assert.equal(await f.store.get('browser'), null);
+        }
+        finally {
+            await f.close();
+        }
+    });
+}
 const endpoint = 'https://contract.example.test/poppy/conversations';
 const base = { issuer: 'https://auth.contract.test', clientId: 'https://agent.contract.test/client', sessionId: 's1', userId: 'u_1', scopes: [], tokenExpiresAt: 9e12, sessionVersion: 1 };
 const principals = {
@@ -195,3 +252,25 @@ export function runConversationAdapterContract(fixture) {
         assert.equal((await call(a, `/${id}/events`, 'signedOut')).status, 404);
     }));
 }
+export function runBusinessOperationAdapterContract(fixture) {
+    test('business operation adapter contract: absent-row races, rollback, detached snapshots and version fences', async () => {
+        const f = await fixture();
+        try {
+            await Promise.all(Array.from({ length: 10 }, (_, n) => (n % 2 ? f.store : f.second).transaction('action', async (slot) => {
+                slot.record ??= { version: 1, id: 'action', owner: { companyId: 'https://company.example', clientId: 'https://agent.example/client', userId: 'user', sessionId: 'sid', sessionInstanceId: 'instance', sessionGeneration: 'generation' }, scopes: [], revisions: {} };
+                slot.record.scopes.push(String(n));
+            })));
+            const read = () => f.store.transaction('action', async (slot) => slot.record);
+            const record = await read();
+            assert.equal(record.scopes.length, 10);
+            record.scopes.length = 0;
+            await assert.rejects(f.second.transaction('action', async (slot) => { slot.record.scopes = []; throw Error('rollback'); }), /rollback/);
+            assert.equal((await read()).scopes.length, 10);
+            await assert.rejects(f.store.transaction('action', async (slot) => { Object.assign(slot.record, { version: 99 }); }), /binding|version/);
+            assert.equal((await read()).version, 1);
+        }
+        finally {
+            await f.close();
+        }
+    });
+}

package/dist/auth/authenticator.d.ts

@@ -1,6 +1,8 @@
 import type { ExternalAuthorityAdapter, RequestAuthenticator, ResourceEndpoint } from './authority.js';
+import type { SessionAuthority } from './session.js';
 export declare function createRequestAuthenticator(options: {
-    authority: Pick<ExternalAuthorityAdapter, 'introspect'>;
+    authority?: Pick<ExternalAuthorityAdapter, 'introspect'>;
+    sessions?: SessionAuthority;
     endpoints: ResourceEndpoint[];
     now: () => number;
 }): RequestAuthenticator;

package/dist/auth/authenticator.js

@@ -1,51 +1,56 @@
 import { secureUrl } from '../network/transport.js';
 import { AuthorityError } from './authority.js';
 import { verifyDpopProof } from './dpop.js';
-const DPOP_AUTHORIZATION = /^DPoP ([A-Za-z0-9\-._~+/]+=*)$/i;
-// Only introspect is used here; the policy half of the adapter is consumed by the conversation service.
 export function createRequestAuthenticator(options) {
     for (const endpoint of options.endpoints) {
         if (secureUrl(endpoint.origin).origin !== endpoint.origin || !endpoint.pathPrefix.startsWith('/'))
             throw new TypeError('Invalid resource endpoint');
-        if (endpoint.mcp && (endpoint.resource !== `${endpoint.origin}${endpoint.pathPrefix}` || secureUrl(endpoint.mcp.metadataUrl).href !== endpoint.mcp.metadataUrl))
-            throw new TypeError('Invalid MCP resource');
+        if (endpoint.mcp) {
+            const resource = secureUrl(endpoint.resource ?? '');
+            if (resource.origin !== endpoint.origin || resource.pathname !== endpoint.pathPrefix || secureUrl(endpoint.mcp.metadataUrl).href !== endpoint.mcp.metadataUrl)
+                throw new TypeError('Invalid MCP resource');
+        }
     }
     return {
         async authenticate(request) {
-            // The Request URL must already be the trusted public URL; forwarding headers are never read.
             const url = new URL(request.url);
             const endpoint = options.endpoints
                 .filter(item => url.origin === item.origin && (url.pathname === item.pathPrefix || (!item.mcp && url.pathname.startsWith(item.pathPrefix.endsWith('/') ? item.pathPrefix : `${item.pathPrefix}/`))))
                 .sort((a, b) => b.pathPrefix.length - a.pathPrefix.length)[0];
-            if (!endpoint)
+            if (!endpoint || (endpoint.mcp && request.url !== endpoint.resource))
+                throw new AuthorityError('invalid_token');
+            const authorization = request.headers.get('authorization');
+            if (authorization === null) {
+                if (!options.sessions)
+                    throw new AuthorityError('invalid_session');
+                return options.sessions.authenticate(request);
+            }
+            const credentials = /^(Bearer|DPoP) ([A-Za-z0-9\-._~+/]+=*)$/i.exec(authorization);
+            if (!credentials || credentials[2].length > 4096 || !options.authority)
                 throw new AuthorityError('invalid_token');
-            if (endpoint.mcp && request.url !== endpoint.resource)
+            const token = credentials[2], scheme = credentials[1].toLowerCase();
+            const { principal, dpopJkt } = await options.authority.introspect(token, endpoint.resource);
+            if (principal.tokenExpiresAt <= options.now())
                 throw new AuthorityError('invalid_token');
-            if (endpoint.mcp && /^Bearer /i.test(request.headers.get('authorization') ?? '')) {
-                const bearer = /^Bearer ([A-Za-z0-9\-._~+/]+=*)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
-                if (!bearer || bearer.length > 4096)
+            if (scheme === 'bearer') {
+                if (dpopJkt !== null)
                     throw new AuthorityError('invalid_token');
-                const { principal, dpopJkt } = await options.authority.introspect(bearer, endpoint.resource);
-                // Ordinary MCP issuers return null only for unbound Bearer tokens. A bound token never downgrades.
-                if (dpopJkt !== null || principal.tokenExpiresAt <= options.now())
+            }
+            else {
+                if (endpoint.mcp && !endpoint.mcp.dpop)
                     throw new AuthorityError('invalid_token');
-                if (!principal.userId && !principal.accountId)
+                const proof = await verifyDpopProof(request.headers.get('dpop'), { method: request.method, url: `${url.origin}${url.pathname}`, nowMs: options.now(), accessToken: token });
+                if (dpopJkt !== proof.jkt)
+                    throw new AuthorityError('invalid_dpop_proof');
+            }
+            if (endpoint.mcp && !request.headers.has('poppy-session')) {
+                if (!principal.accountId)
                     throw new AuthorityError('invalid_token');
-                return principal;
+                return { ...principal, userId: '', sessionId: '', sessionVersion: 0 };
             }
-            if (endpoint.mcp && !endpoint.mcp.dpop)
-                throw new AuthorityError('invalid_token');
-            const token = DPOP_AUTHORIZATION.exec(request.headers.get('authorization') ?? '')?.[1];
-            if (!token || token.length > 4096)
-                throw new AuthorityError('invalid_token');
-            const nowMs = options.now();
-            const proof = await verifyDpopProof(request.headers.get('dpop'), { method: request.method, url: `${url.origin}${url.pathname}`, nowMs, accessToken: token });
-            const { principal, dpopJkt } = await options.authority.introspect(token, endpoint.resource);
-            if (principal.tokenExpiresAt <= nowMs)
-                throw new AuthorityError('invalid_token');
-            if (dpopJkt !== proof.jkt)
-                throw new AuthorityError('invalid_dpop_proof');
-            return principal;
-        }
+            if (!options.sessions)
+                throw new AuthorityError('invalid_session');
+            return options.sessions.authenticate(request, { token, principal });
+        },
     };
 }

package/dist/auth/authority.d.ts

@@ -9,6 +9,10 @@ export interface Principal {
     tokenExpiresAt: number;
     sessionVersion: number;
     issuerGeneration?: string;
+    agentId?: string;
+    sessionGeneration?: string;
+    sessionInstanceId?: string;
+    sessionExpiresAt?: number;
 }
 export type WorkRevocationPolicy = 'stop-account-work' | 'allow-accepted-work-to-finish';
 export interface AcceptedAuthority {
@@ -44,12 +48,14 @@ export interface ExternalAuthorityAdapter {
     }>;
     policy: AuthorityPolicy;
 }
-export type AuthorityErrorCode = 'invalid_token' | 'invalid_dpop_proof' | 'use_dpop_nonce' | 'sign_in_required' | 'insufficient_scope';
+export type AuthorityErrorCode = 'invalid_token' | 'invalid_dpop_proof' | 'use_dpop_nonce' | 'invalid_session' | 'account_required' | 'rate_limited' | 'insufficient_scope';
 export declare class AuthorityError extends Error {
     readonly code: AuthorityErrorCode;
-    readonly status: 401 | 403;
+    readonly status: 400 | 401 | 403 | 429;
     readonly headers: Headers;
     constructor(code: AuthorityErrorCode, options?: {
         scope?: string;
+        retryAfter?: number;
     });
+    response(): Response;
 }

package/dist/auth/authority.js

@@ -7,10 +7,15 @@ export class AuthorityError extends Error {
         super(`Authorization failed: ${code}`);
         this.code = code;
         this.name = 'AuthorityError';
-        this.status = code === 'sign_in_required' || code === 'insufficient_scope' ? 403 : 401;
+        this.status = code === 'rate_limited' ? 429 : code === 'invalid_session' ? 400 : code === 'insufficient_scope' ? 403 : 401;
         if (options.scope !== undefined && !/^[\x21\x23-\x5B\x5D-\x7E ]*$/.test(options.scope))
             throw new TypeError('scope');
         const scope = options.scope === undefined ? '' : `, scope="${options.scope}"`;
-        this.headers = new Headers({ 'WWW-Authenticate': `DPoP error="${code}"${scope}, algs="ES256"` });
+        if (options.retryAfter !== undefined && (!Number.isSafeInteger(options.retryAfter) || options.retryAfter < 1))
+            throw new TypeError('retryAfter');
+        this.headers = code === 'rate_limited' ? new Headers({ 'Content-Type': 'application/json', 'Cache-Control': 'no-store', 'Retry-After': String(options.retryAfter ?? 60) }) : code === 'invalid_session' ? new Headers({ 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }) : new Headers({ 'WWW-Authenticate': code === 'account_required' ? `Bearer${scope ? ' ' + scope.slice(2) : ''}, DPoP${scope ? ' ' + scope.slice(2) : ''}` : `DPoP error="${code}"${scope}, algs="ES256", Bearer error="${code}"${scope}` });
+    }
+    response() {
+        return new Response(this.code === 'invalid_session' || this.code === 'rate_limited' ? JSON.stringify({ error: this.code }) : null, { status: this.status, headers: this.headers });
     }
 }

package/dist/auth/session.d.ts

@@ -0,0 +1,47 @@
+import type { AuthorityCoordinator, AuthorityPolicy, Principal } from './authority.js';
+import type { MetadataResolver } from '../network/discovery.js';
+export interface SessionRecord {
+    instanceId: string;
+    clientId: string;
+    sid: string;
+    userId: string;
+    agentId?: string;
+    createdAt: number;
+    expiresAt: number;
+    ended: boolean;
+    accountId?: string;
+}
+export interface SessionState {
+    version: 1;
+    generation: string;
+    record: SessionRecord | null;
+}
+export interface SessionAdmission extends SessionState {
+    activeCount: number;
+    earliestExpiry: number | null;
+}
+/** Serialize admission per client across processes; callbacks are synchronous, detached, and atomic. */
+export interface SessionStore {
+    read(clientId: string, sid: string): Promise<SessionState>;
+    transaction<T>(clientId: string, sid: string, at: number, change: (state: SessionAdmission) => T): Promise<T>;
+}
+export interface SessionAuthority {
+    authenticate(request: Request, account?: {
+        token: string;
+        principal: Principal;
+    }): Promise<Principal>;
+    end(clientId: string, sid: string): Promise<void>;
+    policy: AuthorityPolicy;
+}
+/** Resources own Sessions; an OAuth issuer supplies only account authority. */
+export declare function createSessionAuthority(options: {
+    companyId: string;
+    metadata: MetadataResolver;
+    store: SessionStore;
+    coordinator: AuthorityCoordinator;
+    now: () => number;
+    accountPolicy?: AuthorityPolicy;
+    lifetimeSeconds?: number;
+    maxSessionsPerClient?: number;
+    acceptClient?: (clientId: string) => Promise<boolean>;
+}): SessionAuthority;

package/dist/auth/session.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { AuthorityError } from './authority.js';
+import { verifySessionJwt } from '../protocol/session.js';
+import { secureUrl } from '../network/transport.js';
+/** Resources own Sessions; an OAuth issuer supplies only account authority. */
+export function createSessionAuthority(options) {
+    secureUrl(options.companyId);
+    const lifetime = options.lifetimeSeconds ?? 86400;
+    if (!Number.isSafeInteger(lifetime) || lifetime < 1 || lifetime > 31_536_000)
+        throw new TypeError('Session lifetime');
+    const maxSessions = options.maxSessionsPerClient ?? 10000;
+    if (!Number.isSafeInteger(maxSessions) || maxSessions < 1)
+        throw new TypeError('maxSessionsPerClient');
+    const invalid = () => new AuthorityError('invalid_session');
+    async function current(principal) {
+        const state = await options.store.read(principal.clientId, principal.sessionId), record = state.record;
+        if (principal.issuer !== options.companyId || principal.sessionGeneration !== state.generation || !record || record.ended || record.expiresAt <= options.now()
+            || record.clientId !== principal.clientId || record.sid !== principal.sessionId || record.userId !== principal.userId || record.instanceId !== principal.sessionInstanceId || record.agentId !== principal.agentId)
+            throw invalid();
+    }
+    const policy = {
+        withCurrent: (principal, scopes, action) => options.coordinator.run(async () => {
+            await current(principal);
+            if (principal.tokenExpiresAt <= options.now())
+                throw new AuthorityError('invalid_token');
+            if (!scopes.every(scope => principal.scopes.includes(scope)))
+                throw new AuthorityError(principal.accountId ? 'insufficient_scope' : 'account_required', { scope: scopes.join(' ') });
+            if (principal.accountId) {
+                if (!options.accountPolicy)
+                    throw new AuthorityError('invalid_token');
+                return options.accountPolicy.withCurrent(principal, scopes, action);
+            }
+            return action();
+        }),
+        withAccepted: (accepted, scopes, action) => options.coordinator.run(async () => {
+            const state = await options.store.read(accepted.principal.clientId, accepted.principal.sessionId);
+            if (accepted.principal.issuer !== options.companyId || state.generation !== accepted.principal.sessionGeneration)
+                throw invalid();
+            if (!scopes.every(scope => accepted.principal.scopes.includes(scope)))
+                throw new AuthorityError('insufficient_scope', { scope: scopes.join(' ') });
+            if (accepted.principal.accountId) {
+                if (!options.accountPolicy)
+                    throw new AuthorityError('invalid_token');
+                return options.accountPolicy.withAccepted(accepted, scopes, action);
+            }
+            return action();
+        }),
+    };
+    return {
+        policy,
+        async authenticate(request, account) {
+            let claims;
+            try {
+                claims = await verifySessionJwt(request.headers.get('poppy-session'), {
+                    companyId: options.companyId, method: request.method, url: request.url, nowMs: options.now(), metadata: options.metadata,
+                    ...(account ? { accessToken: account.token, tokenClientId: account.principal.clientId } : {}),
+                });
+                if (options.acceptClient && !await options.acceptClient(claims.iss))
+                    throw invalid();
+            }
+            catch {
+                throw invalid();
+            }
+            if (account && (account.principal.issuer !== options.companyId || account.principal.tokenExpiresAt <= options.now() || !account.principal.accountId))
+                throw new AuthorityError('invalid_token');
+            return options.coordinator.run(() => options.store.transaction(claims.iss, claims.sid, options.now(), state => {
+                const at = options.now();
+                if (claims.iat < at / 1000 - 60 || claims.delegationExpiresAt <= at)
+                    throw invalid();
+                if (!Number.isSafeInteger(state.activeCount) || state.activeCount < 0)
+                    throw new TypeError('Session admission count');
+                if (!state.record && state.activeCount >= maxSessions)
+                    throw new AuthorityError('rate_limited', { retryAfter: Math.max(1, Math.ceil(((state.earliestExpiry ?? at + lifetime * 1000) - at) / 1000)) });
+                const record = state.record ??= { instanceId: randomUUID(), clientId: claims.iss, sid: claims.sid, userId: claims.sub,
+                    ...(claims.agent_id === undefined ? {} : { agentId: claims.agent_id }), createdAt: at, expiresAt: at + lifetime * 1000, ended: false };
+                if (record.clientId !== claims.iss || record.sid !== claims.sid || record.userId !== claims.sub || record.agentId !== claims.agent_id || record.ended || record.expiresAt <= at)
+                    throw invalid();
+                record.instanceId ??= randomUUID();
+                if (account) {
+                    if (record.accountId !== undefined && record.accountId !== account.principal.accountId)
+                        throw invalid();
+                    record.accountId = account.principal.accountId;
+                }
+                return { ...(account?.principal ?? { issuer: options.companyId, scopes: [], tokenExpiresAt: record.expiresAt }),
+                    issuer: options.companyId, clientId: claims.iss, userId: claims.sub, sessionId: claims.sid,
+                    ...(claims.agent_id === undefined ? {} : { agentId: claims.agent_id }), sessionVersion: 1, sessionInstanceId: record.instanceId, sessionGeneration: state.generation, sessionExpiresAt: record.expiresAt };
+            }));
+        },
+        async end(clientId, sid) {
+            await options.coordinator.run(() => options.store.transaction(clientId, sid, options.now(), state => { if (state.record)
+                state.record.ended = true; }));
+        },
+    };
+}

package/dist/browser.d.ts

@@ -1,17 +1,15 @@
-import type { Principal, AuthorityPolicy } from './auth/authority.js';
+import type { Principal, AuthorityPolicy, RequestAuthenticator } from './auth/authority.js';
 export interface BrowserBinding {
     clientId: string;
     userId: string;
     sessionId: string;
     issuerGeneration?: string;
+    principal?: Principal;
 }
-export interface BrowserSession extends BrowserBinding {
-    principal: Principal;
+export interface BrowserJoin {
+    cookieHash: string;
     expiresAt: number;
-}
-export interface BrowserSessionAuthority {
-    join(sessionKey: string): Promise<BrowserSession>;
-    current(binding: BrowserBinding): Promise<BrowserSession>;
+    principal?: Principal;
 }
 export interface BrowserCookieStore {
     put(hash: string, binding: BrowserBinding & {
@@ -20,28 +18,29 @@ export interface BrowserCookieStore {
     get(hash: string): Promise<(BrowserBinding & {
         expiresAt: number;
     }) | null>;
-    putJoin(codeHash: string, binding: {
-        cookieHash: string;
-        expiresAt: number;
-    }): Promise<void>;
-    consumeJoin(codeHash: string): Promise<{
-        cookieHash: string;
-        expiresAt: number;
-    } | null>;
+    remove(hash: string): Promise<void>;
+    putJoin(codeHash: string, binding: BrowserJoin): Promise<void>;
+    /** Atomically authorize an unexpired, never-authorized code. Do not consume it. */
+    authorizeJoin(codeHash: string, principal: Principal, at: number): Promise<boolean>;
+    /** Atomically remove and return, even when submission will fail. */
+    consumeJoin(codeHash: string): Promise<BrowserJoin | null>;
 }
 export declare function boundedText(request: Request, max: number): Promise<string>;
 export declare function createBrowserSessions(options: {
     endpoint: string;
     domain: string;
-    authority: BrowserSessionAuthority;
+    authenticator: RequestAuthenticator;
     cookies: BrowserCookieStore;
     policy: AuthorityPolicy;
     now: () => number;
+    /** Required for signed-in joins: clear the host's prior login without restoring it later. */
+    clearLogin?: (request: Request, headers: Headers) => Promise<void>;
     cookieName?: string;
     sameSite?: 'Lax' | 'None';
     cookieLifetimeSeconds?: number;
 }): {
     authenticate: (request: Request) => Promise<Principal>;
     withSession<T>(request: Request, scopes: readonly string[], action: (principal: Principal) => Promise<T>): Promise<T>;
+    authorize(request: Request): Promise<Response>;
     join(request: Request): Promise<Response>;
 };

package/dist/browser.js

@@ -1,6 +1,6 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { secureUrl } from './network/transport.js';
-import { verifyDpopProof } 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) {
@@ -30,36 +30,61 @@ export async function boundedText(request, max) {
     return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
 }
 export function createBrowserSessions(options) {
-    const endpoint = 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');
     if (name === '__Host-poppy_join' || (endpoint.hostname !== options.domain.toLowerCase() && !endpoint.hostname.endsWith(`.${options.domain.toLowerCase()}`)))
         throw new TypeError('browser options');
-    const invalid = () => new Error('Invalid browser session');
+    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 authorize(request) {
+            try {
+                if (request.url !== authorizationEndpoint.href || request.method !== 'POST' || request.headers.get('content-type')?.split(';')[0] !== 'application/json')
+                    throw invalid();
+                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 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();
+                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 {
@@ -68,7 +93,7 @@ export function createBrowserSessions(options) {
                 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}"><input type="text" name="proof"></form>`, { headers: {
+                    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',
@@ -76,33 +101,40 @@ export function createBrowserSessions(options) {
                 }
                 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));
-                const codes = fields.getAll('code');
-                // Consume every identifiable code before checking cookies, origin, proof or duplicate fields.
-                const issued = await Promise.all([...new Set(codes)].map(code => options.cookies.consumeJoin(hash(code))));
-                if (codes.length !== 1 || fields.getAll('proof').length !== 1 || [...fields.keys()].some(key => !['code', 'proof'].includes(key)))
+                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 || binding.expiresAt <= options.now() || matches.length !== 1 || matches[0].length !== 2 || hash(matches[0][1]) !== binding.cookieHash)
+                if (!binding?.principal || binding.expiresAt <= options.now() || matches.length !== 1 || matches[0].length !== 2 || hash(matches[0][1]) !== binding.cookieHash)
                     throw invalid();
                 const origin = request.headers.get('origin'), site = request.headers.get('sec-fetch-site');
-                if ((origin !== null && origin !== new URL(options.endpoint).origin) || (site !== null && !['same-origin', 'none'].includes(site)))
-                    throw invalid();
-                const verified = await verifyDpopProof(fields.get('proof'), { method: 'POST', url: options.endpoint, nowMs: options.now() });
-                if (verified.claims.nonce !== codes[0])
+                if ((origin !== null && origin !== endpoint.origin) || (site !== null && !['same-origin', 'none'].includes(site)))
                     throw invalid();
-                const session = await options.authority.join(verified.jkt);
-                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 });
-                const headers = new Headers({ Location: new URL('/', options.endpoint).href, 'Set-Cookie': `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=${sameSite}; Max-Age=${seconds}`, 'Cache-Control': 'no-store' });
-                headers.append('Set-Cookie', '__Host-poppy_join=; Path=/; Max-Age=0; Secure; HttpOnly; SameSite=Strict');
-                return new Response(null, { status: 303, headers });
+                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,12 +1,15 @@
+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: AuthorType;
@@ -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;
@@ -92,6 +97,11 @@ 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 configured historyScopes. */
     history(work: WorkRef): Promise<ConversationEvent[]>;