@poppykit/client 0.4.0 → 0.5.0

package/dist/auth/sqlite-store.js

@@ -1,6 +1,6 @@
 import { DatabaseSync } from 'node:sqlite';
 import { initializeSqlite } from '../sqlite-init.js';
-import { initialClientAuthState } from './client-auth.js';
+import { initialClientAuthState, upgradeClientAuthState } from './client-auth.js';
 const tables = ['identities', 'connections', 'grants', 'operations', 'cleanup'];
 function json(value) {
     return JSON.stringify(value, (_key, item) => {
@@ -42,6 +42,20 @@ export class SqliteAuthStore {
     }
     select(selection) {
         const state = { ...JSON.parse(this.db.prepare('SELECT body FROM auth_meta WHERE id=1').get().body), identities: {}, connections: {}, grants: {}, operations: {}, cleanup: {} };
+        if (state.version === 1) {
+            for (const table of tables)
+                for (const row of this.db.prepare(`SELECT id,body FROM auth_${table}`).all())
+                    state[table][row.id] = JSON.parse(row.body);
+            upgradeClientAuthState(state);
+            for (const table of tables)
+                for (const [id, value] of Object.entries(state[table]))
+                    this.db.prepare(`UPDATE auth_${table} SET body=? WHERE id=?`).run(json(value), id);
+            this.db.prepare('UPDATE auth_meta SET body=? WHERE id=1').run(json({ version: state.version, epoch: state.epoch, owner: state.owner }));
+            for (const table of tables)
+                state[table] = {};
+        }
+        if (state.version !== 2)
+            throw new Error('unsupported auth state version');
         const get = (table, id) => {
             const row = this.db.prepare(`SELECT body FROM auth_${table} WHERE id=?`).get(id);
             if (row)
@@ -85,7 +99,7 @@ export class SqliteAuthStore {
         return state;
     }
     async read(selection) {
-        this.db.exec('BEGIN');
+        this.db.exec('BEGIN IMMEDIATE');
         try {
             const state = this.select(selection);
             this.db.exec('COMMIT');

package/dist/conversation.js

@@ -139,10 +139,20 @@ export function createConversationClient(options) {
             throw new ConversationError('unknown_operation');
         if (record.endpoint !== endpoint)
             throw new ConversationError('invalid_target');
-        if (record.phase === 'accepted')
-            return record.response;
+        if (record.phase === 'accepted') {
+            try {
+                return record.response && 'events' in record.response ? parseEventPage(record.response, record.read?.cursor) : parseConversationState(record.response);
+            }
+            catch {
+                throw new ConversationError('stored_operation_reset_required');
+            }
+        }
         if (record.phase === 'rejected')
             throw new ConversationError(record.error.code, record.error.status, undefined, undefined, record.error.conversationId);
+        // A legacy pending body may already be accepted remotely. Never rewrite or replay it as a new contract.
+        if ('sender' in record.request.message)
+            throw new ConversationError('legacy_message_uncertain');
+        parseConversationRequest(record.request);
         const url = new URL(record.target === null ? endpoint : conversationUrl(record.target, 'messages'));
         if (record.read?.cursor !== undefined)
             url.searchParams.set('cursor', record.read.cursor);

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { createClientAuth, initialClientAuthState, AuthFailure } from './auth/cl
 export type { ClientAuth, ClientAuthOptions, SignOutOutcome, ClientAuthState, AuthStore, AuthSelection, SecretStore, IdentitySigner, Connection, ConnectionStatus, AuthOutcome, OperationStatus, ConversationTarget } from './auth/client-auth.js';
 export { createNodeTransport } from './network/transport.js';
 export type { HttpTransport, NetworkOptions } from './network/transport.js';
-export { createMetadataResolver } from './network/discovery.js';
+export { createMetadataResolver, signInMethods } from './network/discovery.js';
 export type { MetadataResolver } from './network/discovery.js';
 export { createConversationClient, initialConversationClientState, ConversationError } from './conversation.js';
 export type { ConversationClientOptions, ConsumerCheckpoint, ConversationClientState, OutboundInput, OutboundRecord, ReadOptions, ReadParams } from './conversation.js';
@@ -16,3 +16,6 @@ export { authChallenge } from './auth/challenge.js';
 export type { AuthChallenge } from './auth/challenge.js';
 export type { ApiTarget, AgentBrowserController, FeedbackReport } from './integrations.js';
 export { protectedResourceMetadataUrl } from './integrations.js';
+export type { Author, AuthorType, Message, RecordedMessage, ConversationRequest, ConversationState, ConversationEvent, KnownEvent, EventPage } from './protocol/wire.js';
+export type { Alternative, AlternativeReference, ExcludedTask } from './network/tasks.js';
+export type { ScopeHint } from './network/discovery.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { createClientAuth, initialClientAuthState, AuthFailure } from './auth/client-auth.js';
 export { createNodeTransport } from './network/transport.js';
-export { createMetadataResolver } from './network/discovery.js';
+export { createMetadataResolver, signInMethods } from './network/discovery.js';
 export { createConversationClient, initialConversationClientState, ConversationError } from './conversation.js';
 export { parseEventStream } from './protocol/sse.js';
 export { authChallenge } from './auth/challenge.js';

package/dist/integrations.d.ts

@@ -10,13 +10,18 @@ export interface ApiTarget {
 }
 export interface AgentBrowserController {
     readonly kind: 'agent-controlled';
+    loadJoinForm(url: string): Promise<{
+        code: string;
+    }>;
     postForm(input: {
         url: string;
         fields: {
-            assertion: string;
+            code: string;
+            proof: string;
         };
         validateRedirect(status: number, location: string): string;
     }): Promise<void>;
+    navigate(url: string): Promise<void>;
 }
 export interface FeedbackReport {
     kind: 'missing';

package/dist/network/discovery.d.ts

@@ -1,19 +1,18 @@
 import type { JsonObject } from '../protocol/wire.js';
 import type { HttpTransport } from './transport.js';
+import type { ExcludedTask } from './tasks.js';
+export interface ScopeHint {
+    changes: 'none' | 'reversible' | 'irreversible';
+    personal_data: boolean;
+}
 export interface PoppyDocument {
-    protocol_version: '0.2';
+    protocol_version: '0.3';
     organization: {
         name: string;
         domain: string;
     };
     auth?: {
         issuer: string;
-        direct?: {
-            scopes: string[];
-        };
-        device?: {
-            scopes: string[];
-        };
         mediated?: {
             endpoint: string;
             fields: {
@@ -23,7 +22,8 @@ export interface PoppyDocument {
             }[];
             scopes: string[];
         };
-        custom_scopes?: Record<string, string>;
+        scopes?: Record<string, string>;
+        scope_hints?: Record<string, ScopeHint>;
         [key: string]: unknown;
     };
     agent?: {
@@ -45,6 +45,9 @@ export interface PoppyDocument {
         browser_session_endpoint?: string;
         [key: string]: unknown;
     };
+    excluded_tasks?: {
+        url: string;
+    };
     feedback?: {
         endpoint: string;
         [key: string]: unknown;
@@ -60,7 +63,9 @@ export interface AuthorizationMetadata {
     issuer: string;
     token_endpoint: string;
     revocation_endpoint: string;
-    poppy_domains: string[];
+    protected_resources: string[];
+    grant_types_supported: string[];
+    scopes_supported?: string[];
     authorization_endpoint?: string;
     device_authorization_endpoint?: string;
     dpop_signing_alg_values_supported?: string[];
@@ -86,12 +91,18 @@ export interface MetadataResolver {
     resolveJwks(uri: string, options?: {
         refresh?: boolean;
     }): Promise<JsonObject>;
+    resolveExcludedTasks?(document: PoppyDocument): Promise<ExcludedTask[]>;
     invalidate?(target?: string): void;
 }
+export declare function companyScopes(value: unknown, allowEmpty?: boolean): string[];
 export declare function authorizationMetadataUrl(issuer: string): string;
 export declare function validateClientId(clientId: string): URL;
 export declare function parsePoppyDocument(value: unknown, servingUrl: string): PoppyDocument;
 export declare function parseAuthorizationMetadata(value: unknown, document: PoppyDocument): AuthorizationMetadata;
+export declare function signInMethods(metadata: CompanyMetadata): {
+    method: 'direct' | 'device' | 'mediated';
+    scopes: string[];
+}[];
 export declare function parseClientMetadata(value: unknown, clientId: string): ClientMetadata;
 export declare function createMetadataResolver(transport: HttpTransport, options?: {
     now?: () => number;

package/dist/network/discovery.js

@@ -1,11 +1,17 @@
+import { validRedirect } from './redirect.js';
 import { object, string, member, canonical, parseJson, ValidationError } from '../protocol/wire.js';
 import { secureUrl } from './transport.js';
+import { parseExcludedTasks } from './tasks.js';
 function url(value, field) { const valueString = string(value, field); secureUrl(valueString); return valueString; }
 function strings(value, field, allowEmpty = false) { if (!Array.isArray(value) || (!allowEmpty && !value.length))
     throw new ValidationError(field); value.forEach(item => string(item, field)); return value; }
-function scopes(value) { for (const scope of strings(value, 'scopes'))
-    if (!/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope))
-        throw new ValidationError('scopes'); }
+export function companyScopes(value, allowEmpty = false) {
+    const result = strings(value, 'scopes', allowEmpty);
+    for (const scope of result)
+        if (!/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope) || scope.startsWith('poppy:'))
+            throw new ValidationError('scopes');
+    return result;
+}
 function domain(value) { const text = string(value, 'domain'); if (!/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i.test(text) || text.includes('..'))
     throw new ValidationError('domain'); return text; }
 export function authorizationMetadataUrl(issuer) { const parsed = secureUrl(issuer); if (parsed.search)
@@ -21,7 +27,10 @@ export function validateClientId(clientId) {
 }
 export function parsePoppyDocument(value, servingUrl) {
     const doc = object(value);
-    member(doc.protocol_version, ['0.2'], 'protocol_version');
+    member(doc.protocol_version, ['0.3'], 'protocol_version');
+    const served = secureUrl(servingUrl);
+    if (served.pathname !== '/.well-known/poppy.json' || servingUrl.includes('?'))
+        throw new ValidationError('discovery.url');
     const organization = object(doc.organization, 'organization');
     string(organization.name, 'organization.name');
     if (domain(organization.domain).toLowerCase() !== secureUrl(servingUrl).hostname.toLowerCase())
@@ -36,13 +45,10 @@ export function parsePoppyDocument(value, servingUrl) {
     if ('auth' in doc) {
         const auth = object(doc.auth, 'auth');
         authorizationMetadataUrl(url(auth.issuer, 'issuer'));
-        for (const key of ['direct', 'device'])
-            if (key in auth)
-                scopes(object(auth[key], key).scopes);
         if ('mediated' in auth) {
             const mediated = object(auth.mediated, 'mediated');
             url(mediated.endpoint, 'mediated.endpoint');
-            scopes(mediated.scopes);
+            companyScopes(mediated.scopes);
             if (!Array.isArray(mediated.fields) || !mediated.fields.length)
                 throw new ValidationError('mediated.fields');
             for (const field of mediated.fields) {
@@ -52,8 +58,21 @@ export function parsePoppyDocument(value, servingUrl) {
                 member(item.secret, [true, false], 'field.secret');
             }
         }
-        if ('custom_scopes' in auth)
-            Object.values(object(auth.custom_scopes)).forEach(value => string(value, 'custom_scopes', false));
+        if ('scope_hints' in auth) {
+            const hints = object(auth.scope_hints, 'scope_hints');
+            for (const [scope, value] of Object.entries(hints)) {
+                companyScopes([scope]);
+                const hint = object(value, 'scope_hint');
+                string(hint.changes, 'changes');
+                member(hint.personal_data, [true, false], 'personal_data');
+                hints[scope] = { changes: ['none', 'reversible', 'irreversible'].includes(hint.changes) ? hint.changes : 'irreversible', personal_data: hint.personal_data };
+            }
+        }
+        if ('scopes' in auth)
+            for (const [scope, description] of Object.entries(object(auth.scopes, 'auth.scopes'))) {
+                companyScopes([scope]);
+                string(description, 'auth.scopes');
+            }
     }
     if ('agent' in doc) {
         const protocols = object(doc.agent, 'agent').protocols;
@@ -79,6 +98,8 @@ export function parsePoppyDocument(value, servingUrl) {
                 url(item.resource, 'api.resource');
         }
     }
+    if ('excluded_tasks' in doc)
+        url(object(doc.excluded_tasks).url, 'excluded_tasks.url');
     if ('feedback' in doc)
         url(object(doc.feedback).endpoint, 'feedback.endpoint');
     if ('extensions' in doc)
@@ -95,21 +116,46 @@ export function parseAuthorizationMetadata(value, document) {
     const auth = document.auth;
     if (metadata.issuer !== auth.issuer)
         throw new ValidationError('issuer');
-    const domains = strings(metadata.poppy_domains, 'poppy_domains');
-    domains.forEach(domain);
-    if (!domains.some(item => item.toLowerCase() === document.organization.domain.toLowerCase()))
-        throw new ValidationError('poppy_domains');
+    const resources = strings(metadata.protected_resources, 'protected_resources');
+    resources.forEach(value => url(value, 'protected_resources'));
+    if (!resources.some(value => /^https:\/\/[^/:?#]+$/.test(value) && value.slice(8).toLowerCase() === document.organization.domain.toLowerCase()))
+        throw new ValidationError('protected_resources');
+    const grants = strings(metadata.grant_types_supported, 'grant_types_supported');
+    for (const grant of ['urn:ietf:params:oauth:grant-type:jwt-bearer', 'refresh_token'])
+        if (!grants.includes(grant))
+            throw new ValidationError('grant_types_supported');
     for (const key of ['token_endpoint', 'revocation_endpoint'])
         url(metadata[key], key);
-    for (const [key, required] of [['authorization_endpoint', !!auth.direct], ['device_authorization_endpoint', !!auth.device]])
-        if (required || key in metadata)
+    for (const [key, grant] of [['authorization_endpoint', 'authorization_code'], ['device_authorization_endpoint', 'urn:ietf:params:oauth:grant-type:device_code']])
+        if (grants.includes(grant) || key in metadata)
             url(metadata[key], key);
+    if ('pushed_authorization_request_endpoint' in metadata)
+        url(metadata.pushed_authorization_request_endpoint, 'pushed_authorization_request_endpoint');
+    const signIn = grants.includes('authorization_code') || grants.includes('urn:ietf:params:oauth:grant-type:device_code') || !!auth.mediated;
+    const supported = signIn || 'scopes_supported' in metadata ? companyScopes(metadata.scopes_supported, true) : [];
+    if (auth.mediated && !auth.mediated.scopes.every(scope => supported.includes(scope)))
+        throw new ValidationError('mediated.scopes');
+    // Scope descriptions may instead live in a listed OpenAPI document.
+    if (!document.apis?.some(api => api.type === 'openapi') && supported.some(scope => !Object.hasOwn(auth.scopes ?? {}, scope)))
+        throw new ValidationError('auth.scopes');
     if ('dpop_signing_alg_values_supported' in metadata && !strings(metadata.dpop_signing_alg_values_supported, 'dpop_signing_alg_values_supported').includes('ES256'))
         throw new ValidationError('dpop_signing_alg_values_supported');
     if ('client_id_metadata_document_supported' in metadata)
         member(metadata.client_id_metadata_document_supported, [true, false], 'client_id_metadata_document_supported');
     return metadata;
 }
+export function signInMethods(metadata) {
+    const auth = metadata.authorization, methods = [];
+    if (!auth)
+        return methods;
+    if (auth.grant_types_supported.includes('authorization_code') && auth.authorization_endpoint)
+        methods.push({ method: 'direct', scopes: [...auth.scopes_supported ?? []] });
+    if (auth.grant_types_supported.includes('urn:ietf:params:oauth:grant-type:device_code') && auth.device_authorization_endpoint)
+        methods.push({ method: 'device', scopes: [...auth.scopes_supported ?? []] });
+    if (metadata.document.auth?.mediated)
+        methods.push({ method: 'mediated', scopes: [...metadata.document.auth.mediated.scopes] });
+    return methods;
+}
 export function parseClientMetadata(value, clientId) {
     const parsed = validateClientId(clientId);
     const metadata = object(value);
@@ -118,9 +164,8 @@ export function parseClientMetadata(value, clientId) {
     string(metadata.client_name, 'client_name');
     member(metadata.token_endpoint_auth_method, ['private_key_jwt'], 'token_endpoint_auth_method');
     const redirects = strings(metadata.redirect_uris, 'redirect_uris', true);
-    for (const endpoint of [url(metadata.jwks_uri, 'jwks_uri'), ...redirects])
-        if (secureUrl(endpoint).hostname.toLowerCase() !== parsed.hostname.toLowerCase())
-            throw new ValidationError('client_endpoint_domain');
+    if (secureUrl(url(metadata.jwks_uri, 'jwks_uri')).hostname !== parsed.hostname || redirects.some(endpoint => !validRedirect(endpoint, clientId)))
+        throw new ValidationError('client_endpoint_domain');
     if ('logo_uri' in metadata)
         url(metadata.logo_uri, 'logo_uri');
     return metadata;
@@ -189,13 +234,15 @@ export function createMetadataResolver(transport, options = {}) {
                 catch {
                     throw new ValidationError('metadata.json');
                 }
-                const servedUrl = response.status === 304 ? cached.url : response.url || target;
+                const servedUrl = response.url || (response.status === 304 ? cached.url : target);
                 validate(value, servedUrl);
+                if (response.status === 304)
+                    validate(value, cached.url);
                 const control = response.headers.get('cache-control') ?? (response.status === 304 ? cached?.control : undefined) ?? '';
                 const age = Number(response.headers.get('age') ?? 0);
                 const seconds = Number(/(?:^|,)\s*max-age=(\d+)/i.exec(control)?.[1] ?? 60); // no max-age: 60 s floor (guide: at least a minute)
                 const expires = now() + (/\b(?:no-store|no-cache)\b/i.test(control) ? 0 : Math.max(0, Math.min(300, seconds - (Number.isFinite(age) ? age : 0)))) * 1000;
-                const result = { value, control, url: response.status === 304 ? cached.url : servedUrl, expires, etag: response.headers.get('etag') ?? cached?.etag, modified: response.headers.get('last-modified') ?? cached?.modified };
+                const result = { value, control, url: servedUrl, expires, etag: response.headers.get('etag') ?? cached?.etag, modified: response.headers.get('last-modified') ?? cached?.modified };
                 if (startedEpoch !== epoch)
                     return result;
                 if (!/\bno-store\b/i.test(control))
@@ -250,6 +297,12 @@ export function createMetadataResolver(transport, options = {}) {
             remember(authDocuments, document.auth.issuer, entries, maxEntries, inner => [...inner.values()].every(expiredEntry));
             return { document, authorization: parseAuthorizationMetadata(auth.value, document), url: found.url };
         },
+        async resolveExcludedTasks(document) {
+            if (!document.excluded_tasks)
+                return [];
+            const found = await get(document.excluded_tasks.url, value => parseExcludedTasks(value, document), 'discovery');
+            return parseExcludedTasks(found.value, document);
+        },
         async resolveClient(clientId) { validateClientId(clientId); const found = await get(clientId, value => parseClientMetadata(value, clientId), 'endpoint'); return parseClientMetadata(found.value, clientId); },
         async resolveJwks(uri, settings = {}) {
             const validate = (value) => {

package/dist/network/redirect.d.ts

@@ -0,0 +1,3 @@
+export declare function loopbackRedirect(value: string): boolean;
+export declare function validRedirect(value: string, clientId: string): boolean;
+export declare function registeredRedirect(value: string, registered: readonly string[], clientId: string): boolean;

package/dist/network/redirect.js

@@ -0,0 +1,38 @@
+import { secureUrl } from './transport.js';
+// RFC 8252 loopback callbacks are a return address, never a metadata/fetch exception.
+export function loopbackRedirect(value) {
+    if (!/^http:\/\/(127\.0\.0\.1|\[::1\])(?::[0-9]+)?\//.test(value) || /[\\\s\x00-\x1f]/.test(value))
+        return false;
+    try {
+        const url = new URL(value);
+        return !url.username && !url.password && !url.hash;
+    }
+    catch {
+        return false;
+    }
+}
+export function validRedirect(value, clientId) {
+    if (/[\\\s\x00-\x1f]/.test(value))
+        return false;
+    if (loopbackRedirect(value))
+        return true;
+    try {
+        return secureUrl(value).hostname === secureUrl(clientId).hostname;
+    }
+    catch {
+        return false;
+    }
+}
+export function registeredRedirect(value, registered, clientId) {
+    if (!validRedirect(value, clientId))
+        return false;
+    return registered.some(entry => {
+        if (entry === value)
+            return true;
+        if (!loopbackRedirect(entry) || !loopbackRedirect(value))
+            return false;
+        // Compare the original URI strings: only the literal port may differ.
+        const withoutPort = (uri) => uri.replace(/^(http:\/\/(?:127\.0\.0\.1|\[::1\]))(?::[0-9]+)?(?=\/)/, '$1');
+        return withoutPort(entry) === withoutPort(value);
+    });
+}

package/dist/network/tasks.d.ts

@@ -0,0 +1,23 @@
+import type { PoppyDocument } from './discovery.js';
+export type AlternativeReference = {
+    type: 'web';
+    url: string;
+} | {
+    type: 'openapi';
+    url: string;
+    operation_id: string;
+} | {
+    type: 'mcp';
+    url: string;
+    tool: string;
+};
+export interface Alternative {
+    instructions?: string;
+    references?: AlternativeReference[];
+}
+export interface ExcludedTask {
+    task: string;
+    alternative?: Alternative;
+}
+export declare function parseAlternative(value: unknown, document: PoppyDocument): Alternative;
+export declare function parseExcludedTasks(value: unknown, document: PoppyDocument): ExcludedTask[];

package/dist/network/tasks.js

@@ -0,0 +1,45 @@
+import { object, string, ValidationError } from '../protocol/wire.js';
+import { secureUrl } from './transport.js';
+function text(value, field, max) {
+    const result = string(value, field);
+    if ([...result].length > max)
+        throw new ValidationError(field);
+    return result;
+}
+export function parseAlternative(value, document) {
+    const item = object(value, 'alternative'), result = {};
+    if (!('instructions' in item) && !('references' in item))
+        throw new ValidationError('alternative');
+    if ('instructions' in item)
+        result.instructions = text(item.instructions, 'instructions', 2000);
+    if ('references' in item) {
+        if (!Array.isArray(item.references))
+            throw new ValidationError('references');
+        result.references = [];
+        for (const reference of item.references) {
+            const ref = object(reference, 'reference'), type = string(ref.type, 'reference.type');
+            if (!['web', 'openapi', 'mcp'].includes(type))
+                continue;
+            const url = string(ref.url, 'reference.url');
+            if (type !== 'web' && !document.apis?.some(api => api.type === type && api.url === url))
+                continue;
+            secureUrl(url);
+            if (type === 'web')
+                result.references.push({ type, url });
+            else {
+                const field = type === 'openapi' ? 'operation_id' : 'tool', name = string(ref[field], field);
+                result.references.push(type === 'openapi' ? { type, url, operation_id: name } : { type: 'mcp', url, tool: name });
+            }
+        }
+    }
+    return result;
+}
+export function parseExcludedTasks(value, document) {
+    const tasks = object(value, 'excluded_tasks').tasks;
+    if (!Array.isArray(tasks))
+        throw new ValidationError('tasks');
+    return tasks.map(value => {
+        const item = object(value, 'task');
+        return { task: text(item.task, 'task', 200), ...('alternative' in item ? { alternative: parseAlternative(item.alternative, document) } : {}) };
+    });
+}

package/dist/postgres.js

@@ -1,4 +1,4 @@
-import { initialClientAuthState } from './auth/client-auth.js';
+import { initialClientAuthState, upgradeClientAuthState } from './auth/client-auth.js';
 import { PostgresRuntime, json, synchronous } from './postgres-runtime.js';
 export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
 const tables = ['identities', 'connections', 'grants', 'operations', 'cleanup'];
@@ -27,6 +27,19 @@ export class PostgresAuthStore {
             for (const row of await this.db.query(`SELECT id,body FROM poppy_client.records WHERE ns=$1 AND kind=$2 ${where}`, [this.namespace, table, ...values]))
                 state[table][row.id] = JSON.parse(row.body);
         };
+        if (state.version === 1) {
+            for (const table of tables)
+                await rows(table, '');
+            upgradeClientAuthState(state);
+            for (const table of tables)
+                for (const [id, value] of Object.entries(state[table]))
+                    await this.put(table, id, value);
+            await this.put('auth_meta', 'meta', { version: state.version, epoch: state.epoch, owner: state.owner });
+            for (const table of tables)
+                state[table] = {};
+        }
+        if (state.version !== 2)
+            throw new Error('unsupported auth state version');
         if ('issuer' in selection)
             await one('identities', selection.issuer);
         else {

package/dist/protocol/wire.d.ts

@@ -4,11 +4,18 @@ export type Json = null | boolean | number | string | Json[] | {
 export type JsonObject = {
     [key: string]: Json;
 };
-export type Sender = 'agent' | 'human';
+export type AuthorType = 'agent' | 'human';
+export interface Author {
+    type: AuthorType;
+    id?: string;
+    name?: string;
+    image?: string;
+    [key: string]: unknown;
+}
 export type Status = 'working' | 'idle' | 'queued' | 'closed';
 export interface Message {
     id: string;
-    sender: Sender;
+    author: Author;
     text?: string;
     data?: JsonObject;
     context?: JsonObject;
@@ -25,7 +32,7 @@ export interface ConversationRequest {
 export interface ConversationState {
     conversation_id: string;
     status: Status;
-    responder: Sender;
+    responder: AuthorType;
     [key: string]: unknown;
 }
 export interface ConversationEvent {
@@ -40,11 +47,7 @@ export type KnownEvent = (ConversationEvent & {
 }) | (ConversationEvent & {
     type: 'state';
     status: Status;
-    responder: Sender;
-}) | (ConversationEvent & {
-    type: 'authorization';
-    error: 'sign_in_required';
-    scope?: string;
+    responder: AuthorType;
 }) | (ConversationEvent & {
     type: 'authorization';
     error: 'insufficient_scope';
@@ -65,9 +68,7 @@ export interface TokenResponse {
     access_token: string;
     token_type: 'DPoP' | 'Bearer';
     expires_in: number;
-    scope: string;
-    session_id: string;
-    signed_in: boolean;
+    scope?: string;
     refresh_token?: string;
     refresh_token_expires_in?: number;
     [key: string]: unknown;

package/dist/protocol/wire.js

@@ -50,7 +50,26 @@ function positive(value, field) {
 export function parseMessage(value, options = {}) {
     const message = { ...object(value, 'message') };
     id(message.id, 'message.id');
-    member(message.sender, ['agent', 'human'], 'message.sender');
+    const author = object(message.author, 'message.author');
+    member(author.type, ['agent', 'human'], 'message.author.type');
+    if ('sender' in message)
+        throw new ValidationError('message.sender');
+    for (const key of ['id', 'name', 'image'])
+        if (key in author) {
+            if (!options.company && !(options.recorded && message.role === 'company'))
+                throw new ValidationError('message.author.' + key);
+            string(author[key], 'message.author.' + key);
+        }
+    if ('image' in author) {
+        try {
+            const url = new URL(author.image);
+            if (url.protocol !== 'https:' || url.username || url.password)
+                throw 0;
+        }
+        catch {
+            throw new ValidationError('message.author.image');
+        }
+    }
     if (!['text', 'data', 'context'].some(key => key in message))
         throw new ValidationError('message.content');
     if ('text' in message)
@@ -126,9 +145,9 @@ export function parseEvent(value) {
             member(event.responder, ['agent', 'human'], 'event.responder');
             break;
         case 'authorization':
-            member(event.error, ['sign_in_required', 'insufficient_scope'], 'event.error');
-            if (event.error === 'insufficient_scope' || 'scope' in event)
-                string(event.scope, 'event.scope', false);
+            member(event.error, ['insufficient_scope'], 'event.error');
+            if (!/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(string(event.scope, 'event.scope')))
+                throw new ValidationError('event.scope');
             break;
         case 'user_requested':
             string(event.reason, 'event.reason', false);
@@ -161,10 +180,12 @@ export function parseEventPage(value, requestCursor) {
 export function parseTokenResponse(value) {
     const token = object(value);
     string(token.access_token, 'access_token');
-    string(token.session_id, 'session_id');
-    string(token.scope, 'scope', false);
+    if ('scope' in token) {
+        const scope = string(token.scope, 'scope', false);
+        if (scope !== '' && (!/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(scope) || new Set(scope.split(' ')).size !== scope.split(' ').length))
+            throw new ValidationError('scope');
+    }
     member(token.token_type, ['DPoP', 'Bearer'], 'token_type');
-    member(token.signed_in, [true, false], 'signed_in');
     positive(token.expires_in, 'expires_in');
     if ('refresh_token' in token)
         string(token.refresh_token, 'refresh_token');
@@ -215,6 +236,11 @@ export function parseAssertionClaims(value) {
     const claims = object(value, 'claims');
     for (const key of ['iss', 'sub', 'aud', 'jti'])
         string(claims[key], key);
+    if ('agent_id' in claims) {
+        string(claims.agent_id, 'agent_id');
+        if (claims.agent_id.length > 256)
+            throw new ValidationError('agent_id');
+    }
     // 128 random bits is at least 16 bytes; cap length since jti lands in the replay store. Encoding is not constrained.
     if (claims.jti.length < 16 || claims.jti.length > 256)
         throw new ValidationError('jti');

package/dist/provider.d.ts

@@ -72,13 +72,6 @@ export interface ProviderOptions {
         subject: string;
         allowedCompanies: string[];
     } | null>;
-    /** Required for browser assertions: independently prove session belongs to this client AND derived user. */
-    verifySession?(binding: {
-        clientId: string;
-        userId: string;
-        issuer: string;
-        sessionId: string;
-    }): Promise<boolean>;
     now?: () => number;
     maxEnrollments?: number;
 }
@@ -137,13 +130,13 @@ export declare function createProviderClient(options: {
     beginDirect: (input: {
         operationId: string;
         issuer: string;
-        sessionId: string;
+        sessionKey: string;
         state: string;
     }) => Promise<Row>;
     takeResult: (input: {
         operationId: string;
         issuer: string;
-        sessionId: string;
+        sessionKey: string;
     }) => Promise<Row>;
     cancel: (operationId: string) => Promise<Row>;
     revokeEnrollment: () => Promise<Row>;