@poppykit/server 0.3.1 → 0.5.0

package/dist/adapter-contract.js

@@ -23,15 +23,72 @@ 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 = {
     signedOut: base,
-    account1: { ...base, accountId: 'acct_1', scopes: ['poppy:read'] },
-    account2: { ...base, accountId: 'acct_2', scopes: ['poppy:read'] },
+    account1: { ...base, accountId: 'acct_1', scopes: ['orders:read'] },
+    account2: { ...base, accountId: 'acct_2', scopes: ['orders:read'] },
 };
-const message = { id: 'msg_1', sender: 'agent', text: 'Where is order 1042?' };
-const reply = { id: 'msg_r1', sender: 'agent', text: 'Shipped.' };
+const message = { id: 'msg_1', author: { type: 'agent' }, text: 'Where is order 1042?' };
+const reply = { id: 'msg_r1', author: { type: 'agent' }, text: 'Shipped.' };
 function check(held, needed, action) {
     if (!needed.every(scope => held.includes(scope)))
         return Promise.reject(new AuthorityError('insufficient_scope'));
@@ -50,7 +107,7 @@ function serviceOn(store, clock) {
             return principal;
         },
     };
-    return createConversationService({ endpoint, store, authenticator, policy, clock, leaseMs: 1000, supportedScopes: ['poppy:read'] });
+    return createConversationService({ historyScopes: ['orders:read'], endpoint, store, authenticator, policy, clock, leaseMs: 1000, supportedScopes: ['orders:read'] });
 }
 async function call(service, path, as, body, query = '') {
     const response = await service.handle(new Request(`${endpoint}${path}${query}`, {
@@ -114,12 +171,12 @@ export function runConversationAdapterContract(fixture) {
         const parentWork = (await a.claim());
         const outcome = (promise) => promise.then(value => value.accountId, error => String(error.code));
         const results = await Promise.all([
-            outcome(a.requireAccount(parentWork, ['poppy:read'])),
+            outcome(a.requireAccount(parentWork, ['orders:read'])),
             (async () => {
-                const opened = await call(b, '', 'account2', { parent_conversation_id: parent, message: { id: 'msg_c', sender: 'human', text: 'Hi.' } });
+                const opened = await call(b, '', 'account2', { parent_conversation_id: parent, message: { id: 'msg_c', author: { type: 'human' }, text: 'Hi.' } });
                 if (opened.status !== 201)
                     return String(opened.body.error);
-                return outcome(b.claim().then(work => b.requireAccount(work, ['poppy:read'])));
+                return outcome(b.claim().then(work => b.requireAccount(work, ['orders:read'])));
             })(),
         ]);
         const winners = results.filter(result => result.startsWith('acct_'));
@@ -129,7 +186,7 @@ export function runConversationAdapterContract(fixture) {
         assert.deepEqual(state.bindings[parent], { accountId: winners[0] });
         const loser = winners[0] === 'acct_1' ? 'account2' : 'account1';
         for (const id of Object.keys(state.conversations))
-            assert.deepEqual((await call(b, `/${id}/events`, loser)).body, { error: 'sign_in_required' });
+            assert.deepEqual((await call(b, `/${id}/events`, loser)).body, { error: 'insufficient_scope' });
     }));
     test('adapter contract: lease reclaim on the other handle fences the old worker; output IDs dedupe', () => withFixture(async ({ store, second }) => {
         const [a, b] = [serviceOn(store, clock), serviceOn(second, clock)];
@@ -155,8 +212,8 @@ export function runConversationAdapterContract(fixture) {
             await a.reply(work, outputId, value);
             await b.reply(work, outputId, value);
             await assert.rejects(b.reply(work, outputId, { ...value, text: 'changed' }), { code: 'output_conflict' });
-            await a.requestAuthorization(work, `auth_${outputId}`, ['poppy:read']);
-            await b.requestAuthorization(work, `auth_${outputId}`, ['poppy:read']);
+            await a.requestAuthorization(work, `auth_${outputId}`, ['orders:read']);
+            await b.requestAuthorization(work, `auth_${outputId}`, ['orders:read']);
             await a.requestUser(work, `user_${outputId}`, outputId);
             await b.requestUser(work, `user_${outputId}`, outputId);
             await assert.rejects(b.requestUser(work, `user_${outputId}`, 'changed'), { code: 'output_conflict' });
@@ -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,21 +1,15 @@
-import type { MetadataResolver } from './network/discovery.js';
-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(binding: BrowserBinding, assertion: {
-        jti: string;
-        expiresAt: number;
-    }): Promise<BrowserSession>;
-    current(binding: BrowserBinding): Promise<BrowserSession>;
+    principal?: Principal;
 }
 export interface BrowserCookieStore {
     put(hash: string, binding: BrowserBinding & {
@@ -24,21 +18,29 @@ export interface BrowserCookieStore {
     get(hash: string): Promise<(BrowserBinding & {
         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;
-    metadata: MetadataResolver;
-    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>;
 };