@poppykit/server 0.3.0 → 0.4.0

package/dist/conversation/service.js

@@ -1,6 +1,7 @@
+import { companyScopes } from '../network/discovery.js';
 import { randomBytes } from 'node:crypto';
 import { createConversationNotifications } from './store.js';
-import { ValidationError, canonical, parseJson, object, parseConversationRequest, parseMessage, parseReadOptions } from '../protocol/wire.js';
+import { ValidationError, canonical, parseJson, object, parseEvent, parseConversationRequest, parseMessage, parseReadOptions } from '../protocol/wire.js';
 import { secureUrl } from '../network/transport.js';
 import { own } from '../store.js';
 import { AuthorityError } from '../auth/authority.js';
@@ -13,12 +14,12 @@ export class PublicationError extends Error {
     }
 }
 // Spec 7.10: text or data in a Direct Conversation is the User's own words; context-only messages may come from the agent.
-const directWords = (message) => message.sender !== 'human' && (message.text !== undefined || message.data !== undefined);
+const directWords = (message) => message.author.type !== 'human' && (message.text !== undefined || message.data !== undefined);
 const maxBodyBytes = 1048576;
 const maxWaitSeconds = 30;
 const randomId = (prefix) => prefix + randomBytes(16).toString('base64url');
 export function initialConversationState() {
-    return { version: 1, generation: randomId(''), conversations: {}, bindings: {}, messages: {}, work: [] };
+    return { version: 2, generation: randomId(''), conversations: {}, bindings: {}, messages: {}, work: [] };
 }
 /** For the host's reset transaction: a fresh state with a new generation, so every old fence is stale. */
 export function resetConversationState(draft) {
@@ -71,7 +72,11 @@ async function readJson(request) {
 export function createConversationService(options) {
     const { store, authenticator, policy, clock } = options;
     const pageSize = options.pageSize ?? 100;
-    const historyScopes = [...(options.historyScopes ?? ['poppy:read'])];
+    const historyScopes = [...companyScopes(options.historyScopes)];
+    if (options.supportedScopes)
+        companyScopes(options.supportedScopes, true);
+    if (options.directScopes)
+        companyScopes(options.directScopes, true);
     const leaseMs = options.leaseMs ?? 60000;
     const operatorLeaseMs = options.operatorLeaseMs ?? 900000;
     const pollIntervalMs = options.pollIntervalMs ?? 1000;
@@ -209,7 +214,8 @@ export function createConversationService(options) {
         }
         const events = [];
         let bytes = 1024; // Worst-case IDs, status, responder, cursor and JSON envelope.
-        for (const event of conversation.events.slice(start, start + pageSize)) {
+        for (const stored of conversation.events.slice(start, start + pageSize)) {
+            const event = parseEvent(stored);
             const size = Buffer.byteLength(JSON.stringify(event)) + 1;
             if (bytes + size > maxPageBytes)
                 break;
@@ -226,7 +232,7 @@ export function createConversationService(options) {
     function ack(conversation) {
         return { conversation_id: conversation.id, status: conversation.status, responder: conversation.responder };
     }
-    // Account-bound history needs poppy:read; sending alone does not read history. Other readers fail ownership first.
+    // Account-bound history needs the configured scopes; sending alone does not read history. Other readers fail ownership first.
     const scopesFor = (state, principal, conversation, history) => 
     // Only an owner may see a scope error; for anyone else ownership fails first with 404, so existence never leaks.
     conversation && history && conversation.issuer === principal.issuer && conversation.clientId === principal.clientId && principal.accountId !== undefined
@@ -241,7 +247,7 @@ export function createConversationService(options) {
             return conversation;
         // Spec 7.11: the same User not signed in to the bound account (signed out or another account) is told to sign in; anyone else learns nothing.
         if (accountId !== undefined && conversation.userId === principal.userId)
-            throw new AuthorityError('sign_in_required');
+            throw new AuthorityError('insufficient_scope', { scope: historyScopes.join(' ') });
         throw notFound();
     }
     // Runs change under withCurrent; target() and history() decide the scopes from the state being checked.
@@ -270,7 +276,7 @@ export function createConversationService(options) {
         const parentId = conversationId === undefined ? body.parent_conversation_id : undefined;
         // A Direct Conversation carries the User's own words (7.10).
         if (parentId !== undefined && directWords(body.message))
-            throw new ValidationError('message.sender');
+            throw new ValidationError('message.author.type');
         const key = JSON.stringify([principal.issuer, principal.clientId, principal.userId, body.message.id]);
         const fingerprint = canonical({ target: conversationId ?? null, request: body });
         const authority = JSON.parse(JSON.stringify({ principal, acceptedAt: clock.now(), revocationPolicy }));
@@ -326,7 +332,7 @@ export function createConversationService(options) {
                 if (conversation.childId !== undefined)
                     throw directOpen(conversation.childId);
                 if (conversation.parentId !== undefined && directWords(body.message))
-                    throw new ValidationError('message.sender');
+                    throw new ValidationError('message.author.type');
                 if (read.cursor !== undefined)
                     page(conversation, read.cursor, draft.cursorStatus);
                 conversation.authority = authority;
@@ -619,7 +625,7 @@ export function createConversationService(options) {
                     work.phase = 'claimed';
                     work.fence = newFence(draft);
                     work.leaseUntil = now + leaseMs;
-                    return { workId: work.id, fence: work.fence, conversationId: work.conversationId, message: work.message, context: conversation.context };
+                    return { workId: work.id, fence: work.fence, conversationId: work.conversationId, message: parseMessage(work.message), context: conversation.context };
                 }
                 return null;
             });
@@ -635,8 +641,8 @@ export function createConversationService(options) {
             return publish(ref, (state, work) => boundAccount(state, work) === undefined ? [] : historyScopes, (draft, work, conversation) => {
                 const accountId = boundAccount(draft, work);
                 if (accountId !== undefined && work.authority.principal.accountId !== accountId)
-                    throw new AuthorityError('sign_in_required');
-                return linkedHistory(draft, conversation);
+                    throw new AuthorityError('insufficient_scope', { scope: historyScopes.join(' ') });
+                return linkedHistory(draft, conversation).map(parseEvent);
             }, never, true);
         },
         requireAccount(ref, scopes) {
@@ -645,7 +651,7 @@ export function createConversationService(options) {
                 const binding = draft.bindings[conversation.bindingId];
                 // Parent and child share this record, so the first account use wins for both and no other account can.
                 if (accountId === undefined || (binding.accountId ?? accountId) !== accountId)
-                    throw new AuthorityError('sign_in_required');
+                    throw new AuthorityError('insufficient_scope', { scope: (scopes.length ? scopes : historyScopes).join(' ') });
                 binding.accountId = accountId;
                 return { accountId };
             });
@@ -654,8 +660,8 @@ export function createConversationService(options) {
             const parsed = parseMessage(message, { company: true });
             const payload = canonical({ reply: parsed });
             await publish(ref, noScopes, (draft, work, conversation) => {
-                if (parsed.sender !== conversation.responder)
-                    throw new ValidationError('message.sender');
+                if (parsed.author.type !== conversation.responder)
+                    throw new ValidationError('message.author.type');
                 if (!firstOutput(work, outputId, payload))
                     return;
                 // A person's reply answers the messages held for them so far.
@@ -673,14 +679,10 @@ export function createConversationService(options) {
             if (!Array.isArray(scopes) || !scopes.length || !scopes.every(scope => typeof scope === 'string' && direct.includes(scope)))
                 throw new TypeError('scopes');
             const scope = [...new Set(scopes)].join(' ');
-            await publish(ref, noScopes, (draft, work, conversation, live) => {
+            await publish(ref, noScopes, (_draft, work, conversation) => {
                 if (!firstOutput(work, outputId, canonical({ authorization: scope })))
                     return;
-                const { accountId, scopes: granted } = work.authority.principal;
-                const bound = boundAccount(draft, work);
-                // More scopes only helps a live sign-in on the right account; signed out, another account or revoked all need sign-in.
-                const narrow = live && accountId !== undefined && (bound ?? accountId) === accountId && !scopes.every(item => granted.includes(item));
-                addEvent(conversation, { type: 'authorization', error: narrow ? 'insufficient_scope' : 'sign_in_required', scope });
+                addEvent(conversation, { type: 'authorization', error: 'insufficient_scope', scope });
             }, always);
         },
         async requestUser(ref, outputId, reason) {
@@ -701,7 +703,7 @@ export function createConversationService(options) {
                 delete work.leaseUntil;
                 // Spec 7.8: 'human' means a person's own words, so a person's failed work gets no canned apology.
                 if (outcome === 'failed' && !work.human) {
-                    addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', sender: 'agent', text: 'Sorry, something went wrong and this request could not be completed.' } });
+                    addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', author: { type: 'agent' }, text: 'Sorry, something went wrong and this request could not be completed.' } });
                 }
                 if (conversation.status === 'working')
                     setState(conversation, idleOrWorking(draft, conversation.id));
@@ -727,7 +729,7 @@ export function createConversationService(options) {
                 const source = conversation.lastUserMessage ?? last?.message;
                 if (!source)
                     throw new PublicationError('stale_work');
-                const { role: _role, ...message } = source;
+                const { role: _role, ...message } = parseMessage(source);
                 const work = { id: randomId('wrk_'), conversationId, message, authority, phase: 'claimed', fence: newFence(draft), leaseUntil: clock.now() + operatorLeaseMs, human: true, outputs: {} };
                 conversation.humanUntil = work.leaseUntil;
                 draft.work.push(work);
@@ -746,7 +748,7 @@ export function createConversationService(options) {
                     throw new PublicationError('stale_work');
                 // Messages sent while queued were meant for a person; the agent answers them now.
                 release(draft, conversationId);
-                addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', sender: 'agent', text: reason } });
+                addEvent(conversation, { type: 'message', message: { id: randomId('msg_'), role: 'company', author: { type: 'agent' }, text: reason } });
                 setState(conversation, idleOrWorking(draft, conversationId), 'agent');
             });
         },

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export type { BrowserBinding, BrowserSession, BrowserSessionAuthority, BrowserCo
 export { createFeedbackHandler } from './feedback.js';
 export type { FeedbackReport } from './feedback.js';
 export { mcpResourceMetadata, mcpAuthorizationError } from './mcp.js';
+export type { Author, AuthorType, Message, RecordedMessage, ConversationRequest, ConversationState, ConversationEvent, KnownEvent, EventPage } from './protocol/wire.js';

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,5 +1,5 @@
 import { initialConversationState } from './conversation/service.js';
-import { initialIssuerState } from './reference-auth/index.js';
+import { initialIssuerState, upgradeIssuerState } from './reference-auth/index.js';
 import { clientRevisionKey, accountRevisionKey } from './reference-auth/store.js';
 import { PostgresRuntime, json } from './postgres-runtime.js';
 export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
@@ -43,6 +43,8 @@ export class PostgresCompanyDatabase {
     conversations(namespace) {
         const load = async (selection) => {
             const state = { ...await this.meta(namespace, 'conversation_meta', () => { const { version, generation } = initialConversationState(); return { version, generation }; }), conversations: {}, bindings: {}, messages: {}, work: [] };
+            if (state.version !== 2)
+                throw new Error('conversation reset required for draft 0.3');
             if (selection.messageKey)
                 await this.db.lock(JSON.stringify([namespace, 'message', selection.messageKey]));
             let id = selection.conversationId;
@@ -186,10 +188,10 @@ export class PostgresCompanyDatabase {
         };
     }
     issuer(namespace) {
-        const kinds = ['sessions', 'grants', 'refreshTokens', 'authorizations', 'codes', 'signIns', 'accessTokens', 'replay'];
+        const kinds = ['sessions', 'sessionKeys', 'grants', 'refreshTokens', 'authorizations', 'codes', 'signIns', 'accessTokens', 'replay'];
         const load = async (selection) => {
             await this.db.lock(JSON.stringify([namespace, 'issuer']));
-            const state = { ...await this.meta(namespace, 'issuer_meta', () => { const { version, generation, nonces } = initialIssuerState(); return { version, generation, nonces }; }), sessions: {}, grants: {}, refreshTokens: {}, authorizations: {}, codes: {}, signIns: {}, accessTokens: {}, replay: {} };
+            const state = { ...await this.meta(namespace, 'issuer_meta', () => { const { version, generation, nonces } = initialIssuerState(); return { version, generation, nonces }; }), sessions: {}, sessionKeys: {}, grants: {}, refreshTokens: {}, authorizations: {}, codes: {}, signIns: {}, accessTokens: {}, replay: {} };
             const get = async (kind, id) => {
                 if (!id)
                     return;
@@ -201,6 +203,23 @@ export class PostgresCompanyDatabase {
                 for (const row of await this.rows(namespace, kind, where, params))
                     state[kind][row.id] = JSON.parse(row.body);
             };
+            if (state.version === 3) {
+                for (const kind of kinds)
+                    await find(kind, '');
+                const before = structuredClone(state);
+                upgradeIssuerState(state);
+                for (const kind of kinds)
+                    await this.save(namespace, kind, before[kind], state[kind]);
+                await this.put(namespace, 'issuer_meta', 'meta', { version: state.version, generation: state.generation, nonces: state.nonces });
+                for (const kind of kinds)
+                    state[kind] = {};
+            }
+            if (state.version !== 4)
+                throw new Error('unsupported issuer state version');
+            if ((selection.kind === 'token' || selection.kind === 'sign_in') && selection.sessionKey) {
+                await get('sessionKeys', selection.sessionKey);
+                await get('sessions', state.sessionKeys[selection.sessionKey]);
+            }
             if (selection.kind === 'access')
                 await get('accessTokens', selection.hash);
             if (selection.kind === 'sign_in') {
@@ -226,7 +245,6 @@ export class PostgresCompanyDatabase {
                 await get('signIns', selection.revocationKey);
             }
             if (selection.kind === 'token') {
-                await get('sessions', selection.sessionId);
                 await get('codes', selection.codeHash);
                 await get('refreshTokens', selection.refreshHash);
                 for (const key of selection.replayKeys)

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;