@poppykit/client 0.4.1 → 0.6.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) => {
@@ -19,7 +19,9 @@ export class SqliteAuthStore {
             this.db.exec('CREATE TABLE IF NOT EXISTS auth_meta (id INTEGER PRIMARY KEY CHECK(id=1), body TEXT NOT NULL)');
             for (const table of tables)
                 this.db.exec(`CREATE TABLE IF NOT EXISTS auth_${table} (id TEXT PRIMARY KEY, body TEXT NOT NULL)`);
-            this.db.exec(`CREATE INDEX IF NOT EXISTS operations_connection ON auth_operations(json_extract(body,'$.connectionId'));
+            this.db.exec(`CREATE INDEX IF NOT EXISTS connections_grant ON auth_connections(json_extract(body,'$.grantId'));
+      CREATE INDEX IF NOT EXISTS connections_account ON auth_connections(json_extract(body,'$.issuer'),json_extract(body,'$.userId'));
+      CREATE INDEX IF NOT EXISTS operations_connection ON auth_operations(json_extract(body,'$.connectionId'));
       CREATE UNIQUE INDEX IF NOT EXISTS operations_callback ON auth_operations(json_extract(body,'$.direct.stateHash'));
       CREATE INDEX IF NOT EXISTS operations_pending ON auth_operations(id) WHERE json_extract(body,'$.phase')!='terminal';
       CREATE INDEX IF NOT EXISTS operations_cleanup ON auth_operations(json_extract(body,'$.createdAt')) WHERE json_extract(body,'$.phase')='terminal' AND json_extract(body,'$.status')!='uncertain';
@@ -42,6 +44,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 || state.version === 2) {
+            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 !== 3)
+            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)
@@ -60,7 +76,11 @@ export class SqliteAuthStore {
             history();
             return state;
         }
-        if ('connectionId' in selection)
+        if ('account' in selection) {
+            get('identities', selection.account.issuer);
+            rows('connections', "WHERE json_extract(body,'$.issuer')=? AND json_extract(body,'$.userId')=?", selection.account.issuer, selection.account.userId);
+        }
+        else if ('connectionId' in selection)
             get('connections', selection.connectionId);
         else if ('operationId' in selection)
             get('operations', selection.operationId);
@@ -70,6 +90,9 @@ export class SqliteAuthStore {
             rows('connections', '');
         for (const operation of Object.values(state.operations))
             get('connections', operation.connectionId);
+        const linked = new Set([...Object.values(state.connections).map(row => row.grantId), ...Object.values(state.operations).map(row => row.grantId)].filter((id) => id !== null));
+        for (const grantId of linked)
+            rows('connections', "WHERE json_extract(body,'$.grantId')=?", grantId);
         for (const connection of Object.values(state.connections)) {
             if (connection.grantId)
                 get('grants', connection.grantId);
@@ -85,7 +108,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/auth/store.d.ts

@@ -1,11 +1,16 @@
 import type { ClientAuthState } from './client-auth.js';
-/** A connection aggregate includes its grants, operations and cleanup; never other connections. */
+/** Include the selected connections, shared-grant peers, and their grants, operations and cleanup. */
 export type AuthSelection = ({
     connectionId: string;
 } | {
     operationId: string;
 } | {
     issuer: string;
+} | {
+    account: {
+        issuer: string;
+        userId: string;
+    };
 } | {
     callbackHash: string;
 } | {

package/dist/conversation.d.ts

@@ -1,3 +1,4 @@
+import type { ClientMetadata, PoppyDocument } from './network/discovery.js';
 import type { AuthorizationRequirement } from './auth/client-auth.js';
 import type { ConversationEvent } from './protocol/wire.js';
 import type { ConversationStore } from './conversation-store.js';
@@ -49,6 +50,11 @@ export declare class ConversationError extends Error {
     get requiredScopes(): string[];
 }
 export interface ConversationClientOptions {
+    /** Verified metadata for both peers; omit until trusted Operations consent/recovery is configured. */
+    operations?: {
+        client: ClientMetadata;
+        company: PoppyDocument;
+    };
     authorizedRequest(request: Request): Promise<Response>;
     endpoint: string;
     connectionId: string;

package/dist/conversation.js

@@ -1,10 +1,13 @@
+import { supportsOperations } from './protocol/operations.js';
 import { parseEventStream } from './protocol/sse.js';
-import { authChallenge } from './auth/challenge.js';
+import { authChallenge, schemeChallenge, dpopChallenge } from './auth/challenge.js';
 import { secureUrl, TransportError } from './network/transport.js';
 import { canonical, id as parseId, parseJson, parseConversationRequest, parseConversationState, parseEventPage, parseMessage, parseProtocolError, retryAfterMilliseconds, ValidationError } from './protocol/wire.js';
 export const initialConversationClientState = () => ({ version: 1, outbound: [], consumers: [] });
 // Only known spec codes (7.13, 6) reach messages and callers; a company-chosen string never does.
-const knownCodes = new Set(['conversation_not_found', 'conversation_closed', 'direct_conversation_open', 'message_id_conflict', 'invalid_cursor', 'cursor_expired', 'invalid_request', 'extension_required', 'rate_limited', 'invalid_token', 'invalid_dpop_proof', 'use_dpop_nonce', 'sign_in_required', 'insufficient_scope']);
+const knownCodes = new Set(['conversation_not_found', 'conversation_closed', 'direct_conversation_open', 'message_id_conflict', 'invalid_cursor', 'cursor_expired', 'invalid_request', 'extension_required', 'rate_limited', 'invalid_token', 'invalid_dpop_proof', 'use_dpop_nonce', 'invalid_session', 'insufficient_scope']);
+const knownEvents = new Set(['message', 'state', 'authorization', 'user_requested', 'direct_opened', 'direct_closed']);
+const visiblePage = (page) => ({ ...page, events: page.events.filter(event => knownEvents.has(event.type)) });
 export class ConversationError extends Error {
     code;
     status;
@@ -30,6 +33,7 @@ export class ConversationError extends Error {
 const definite = (status) => status >= 400 && status < 500 && ![401, 403, 408, 429].includes(status);
 export function createConversationClient(options) {
     const { authorizedRequest, store, clock, connectionId, issuer } = options;
+    const operations = !!options.operations && supportsOperations(options.operations.client) && supportsOperations(options.operations.company);
     const endpoint = secureUrl(options.endpoint).href;
     const newId = options.newId ?? (() => `msg_${Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString('base64url')}`); // 128 random bits
     const random = options.random ?? Math.random;
@@ -98,7 +102,8 @@ export function createConversationClient(options) {
         catch { /* The header can carry the complete challenge. */ }
         const challenge = authChallenge(response.headers.get('www-authenticate'), body);
         const raw = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
-        let code = challenge.error ?? (typeof raw.error === 'string' && knownCodes.has(raw.error) ? raw.error : 'http_error');
+        const offered = dpopChallenge(response.headers.get('www-authenticate')) ?? schemeChallenge(response.headers.get('www-authenticate'), 'Bearer');
+        let code = challenge.error ?? (response.status === 401 && offered !== undefined && offered.error === undefined ? 'insufficient_scope' : undefined) ?? (typeof raw.error === 'string' && knownCodes.has(raw.error) ? raw.error : 'http_error');
         let conversationId;
         try {
             if (challenge.conversationId)
@@ -139,10 +144,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 ? visiblePage(parseEventPage(record.response, record.read?.cursor, operations)) : 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, operations);
         const url = new URL(record.target === null ? endpoint : conversationUrl(record.target, 'messages'));
         if (record.read?.cursor !== undefined)
             url.searchParams.set('cursor', record.read.cursor);
@@ -154,13 +169,13 @@ export function createConversationClient(options) {
             try {
                 const body = parseJson(await responseText(response));
                 // A 2xx means accepted; a company that ignores wait answers with a plain state.
-                state = body && typeof body === 'object' && ['events', 'cursor', 'has_more'].some(key => key in body) ? parseEventPage(body, record.read?.cursor) : parseConversationState(body);
+                state = body && typeof body === 'object' && ['events', 'cursor', 'has_more'].some(key => key in body) ? parseEventPage(body, record.read?.cursor, operations) : parseConversationState(body);
             }
             catch {
                 throw new ConversationError('invalid_response', response.status);
             }
             await store.settleOutbound(key, id, { phase: 'accepted', response: state });
-            return state;
+            return 'events' in state ? visiblePage(state) : state;
         }
         const error = await failure(response);
         // direct_conversation_open lasts only until the Direct Conversation closes (spec 7.10), so the same message stays retryable.
@@ -179,8 +194,8 @@ export function createConversationClient(options) {
             if (read.wait === undefined)
                 throw new ConversationError('invalid_request');
         } // spec 7.3 adds cursor alongside wait
-        const message = parseMessage({ ...input, id: input.id ?? newId() });
-        const request = parseConversationRequest({ message, ...(parent === undefined ? {} : { parent_conversation_id: parent }) });
+        const message = parseMessage({ ...input, id: input.id ?? newId() }, { operations });
+        const request = parseConversationRequest({ message, ...(parent === undefined ? {} : { parent_conversation_id: parent }) }, operations);
         if (Buffer.byteLength(JSON.stringify(request)) > 1048576)
             throw new ConversationError('body_limit');
         const fingerprint = canonical({ target, request });
@@ -216,7 +231,6 @@ export function createConversationClient(options) {
             const maxReconnects = opts.maxReconnects ?? 4;
             if (!Number.isSafeInteger(maxReconnects) || maxReconnects < 0)
                 throw new ConversationError('invalid_request');
-            const knownEvents = new Set(['message', 'state', 'authorization', 'user_requested', 'direct_opened', 'direct_closed']);
             const seen = new Set(); // Bounded per watch; durable consumers ack explicitly.
             const eventAck = (event, previous) => ({ event, async ack() { if (opts.consumer !== undefined)
                     await store.advanceCheckpoint(key, { connectionId, issuer, conversationId, name: opts.consumer, cursor: event.id }, [previous]); } });
@@ -259,7 +273,7 @@ export function createConversationClient(options) {
                         if (!response.body)
                             throw new ConversationError('invalid_response');
                         let partialBytes = 0;
-                        for await (const frame of parseEventStream(response.body, { signal: opts.signal })) {
+                        for await (const frame of parseEventStream(response.body, { signal: opts.signal, operations })) {
                             if (frame.kind === 'delta') {
                                 partialBytes += Buffer.byteLength(frame.text);
                                 if (partialBytes > 1048576)
@@ -287,7 +301,7 @@ export function createConversationClient(options) {
                         if (++pages > maxPages)
                             throw new ConversationError('too_many_pages');
                         const beforePage = cursor;
-                        const page = parseEventPage(parseJson(await responseText(response)), cursor);
+                        const page = parseEventPage(parseJson(await responseText(response)), cursor, operations);
                         more = page.has_more;
                         for (const event of page.events) {
                             if (seen.has(event.id))
@@ -349,7 +363,7 @@ export function createConversationClient(options) {
                 throw await failure(response); // cursor_expired (410) is the explicit history gap: see resetConsumer
             let page;
             try {
-                page = parseEventPage(parseJson(await responseText(response)), cursor);
+                page = visiblePage(parseEventPage(parseJson(await responseText(response)), cursor, operations));
             }
             catch {
                 throw new ConversationError('invalid_response', response.status);
@@ -373,7 +387,7 @@ export function createConversationClient(options) {
                 if (!page.has_more)
                     return pages;
                 // has_more with no new events or an unchanged cursor can never finish.
-                if (!page.events.length || page.cursor === null || page.cursor === cursor)
+                if (page.cursor === null || page.cursor === cursor)
                     throw new ConversationError('invalid_response');
                 cursor = page.cursor;
                 chain.push(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,8 @@ 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';
+export * from './operations.js';
+export * from './protocol/operations.js';

package/dist/index.js

@@ -1,7 +1,9 @@
 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';
 export { protectedResourceMetadataUrl } from './integrations.js';
+export * from './operations.js';
+export * from './protocol/operations.js';

package/dist/integrations.d.ts

@@ -1,3 +1,4 @@
+import { protectedResourceMetadataUrl } from './network/discovery.js';
 import type { CompanyMetadata, MetadataResolver } from './network/discovery.js';
 import type { HttpTransport } from './network/transport.js';
 export interface ApiTarget {
@@ -10,21 +11,32 @@ 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;
         };
         validateRedirect(status: number, location: string): string;
     }): Promise<void>;
+    navigate(url: string): Promise<void>;
 }
 export interface FeedbackReport {
-    kind: 'missing';
     task: string;
     description: string;
+    [key: string]: unknown;
 }
 export declare function validateFeedback(value: FeedbackReport): void;
 export declare function browserDestination(value: string, domain: string): void;
-export declare function protectedResourceMetadataUrl(resource: string): string;
-export declare function mcpScheme(transport: HttpTransport, issuer: string, resource: string): Promise<'DPoP' | 'Bearer'>;
+export { protectedResourceMetadataUrl };
+export declare function serviceAuthorization(metadata: CompanyMetadata, resolver: MetadataResolver, transport: HttpTransport, endpoint: string, options?: {
+    mcp?: boolean;
+    metadataUrl?: string;
+    refresh?: boolean;
+}): Promise<{
+    resource?: string;
+    scheme: 'DPoP' | 'Bearer';
+}>;
 export declare function resolveApiTarget(metadata: CompanyMetadata, resolver: MetadataResolver, transport: HttpTransport, apiUrl: string, destination?: string): Promise<ApiTarget>;

package/dist/integrations.js

@@ -1,7 +1,8 @@
+import { companyIdentifier, createMetadataResolver, protectedResourceMetadataUrl } from './network/discovery.js';
 import { secureUrl } from './network/transport.js';
-import { object, parseJson, ValidationError } from './protocol/wire.js';
+import { ValidationError } from './protocol/wire.js';
 export function validateFeedback(value) {
-    if (!value || value.kind !== 'missing' || typeof value.task !== 'string' || !value.task.length || [...value.task].length > 200 || typeof value.description !== 'string' || !value.description.length || [...value.description].length > 2000)
+    if (!value || typeof value.task !== 'string' || !value.task.length || [...value.task].length > 200 || typeof value.description !== 'string' || !value.description.length || [...value.description].length > 2000)
         throw new ValidationError('feedback');
 }
 export function browserDestination(value, domain) {
@@ -9,50 +10,41 @@ export function browserDestination(value, domain) {
     if (url.hostname !== domain.toLowerCase() && !url.hostname.endsWith(`.${domain.toLowerCase()}`))
         throw new ValidationError('return_to');
 }
-export function protectedResourceMetadataUrl(resource) {
-    const url = secureUrl(resource);
-    if (url.search)
+export { protectedResourceMetadataUrl };
+// Discovery is credential-free; a network or malformed-metadata failure never means default authority.
+export async function serviceAuthorization(metadata, resolver, transport, endpoint, options = {}) {
+    secureUrl(endpoint);
+    const found = await (resolver.resolveResource ? resolver : createMetadataResolver(transport)).resolveResource(endpoint, options);
+    const domain = `https://${metadata.document.organization.domain.toLowerCase()}`, issuer = metadata.authorization?.issuer;
+    if (found) {
+        if (found.resource !== endpoint && found.resource !== domain)
+            throw new ValidationError('resource');
+        if (issuer && (options.mcp || found.authorization_servers?.length) && !found.authorization_servers?.includes(issuer))
+            throw new ValidationError('resource_issuer');
+        if (!issuer && found.authorization_servers?.length)
+            throw new ValidationError('resource_issuer');
+        if (Array.isArray(found.bearer_methods_supported) && !found.bearer_methods_supported.includes('header'))
+            throw new ValidationError('bearer_methods_supported');
+    }
+    if (options.mcp && issuer && (!found || found.resource !== endpoint))
         throw new ValidationError('resource');
-    return `${url.origin}/.well-known/oauth-protected-resource${url.pathname === '/' ? '' : url.pathname}`;
-}
-export async function mcpScheme(transport, issuer, resource) {
-    const response = await transport.fetch(new Request(protectedResourceMetadataUrl(resource)), { mode: 'discovery' });
-    if (response.status !== 200)
-        throw new ValidationError('resource_metadata');
-    const metadata = object(parseJson(await response.text()));
-    if (metadata.resource !== resource || !Array.isArray(metadata.authorization_servers) || !metadata.authorization_servers.includes(issuer))
-        throw new ValidationError('resource_issuer');
-    for (const server of metadata.authorization_servers)
-        secureUrl(server);
-    if ('bearer_methods_supported' in metadata && (!Array.isArray(metadata.bearer_methods_supported) || !metadata.bearer_methods_supported.includes('header')))
-        throw new ValidationError('bearer_methods_supported');
-    if (!Object.hasOwn(metadata, 'dpop_signing_alg_values_supported'))
-        return 'Bearer';
-    if (!Array.isArray(metadata.dpop_signing_alg_values_supported) || !metadata.dpop_signing_alg_values_supported.includes('ES256') || !metadata.dpop_signing_alg_values_supported.every(value => typeof value === 'string'))
-        throw new ValidationError('dpop_signing_alg_values_supported');
-    return 'DPoP';
+    const algorithms = options.mcp ? found?.dpop_signing_alg_values_supported : metadata.authorization?.dpop_signing_alg_values_supported;
+    return { ...(options.mcp ? { resource: endpoint } : found && found.resource !== domain ? { resource: found.resource } : {}), scheme: algorithms?.includes('ES256') ? 'DPoP' : 'Bearer' };
 }
 export async function resolveApiTarget(metadata, resolver, transport, apiUrl, destination) {
-    const api = metadata.document.apis?.find(entry => entry.url === apiUrl);
-    const issuer = metadata.authorization?.issuer;
-    if (!api || !issuer || !['openapi', 'mcp'].includes(api.type))
+    const api = metadata.document.apis?.find(entry => entry.url === apiUrl), issuer = companyIdentifier(metadata);
+    if (!api || !['openapi', 'mcp'].includes(api.type))
         throw new ValidationError('api');
     if (api.type === 'mcp') {
-        if ((api.resource !== undefined && api.resource !== api.url) || (destination !== undefined && destination !== api.url))
+        if (destination !== undefined && destination !== api.url)
             throw new ValidationError('resource');
-        const scheme = await mcpScheme(transport, issuer, api.url);
-        if (scheme === 'Bearer' && metadata.document.agent?.protocols.some(protocol => protocol.resource === api.url))
-            throw new ValidationError('resource');
-        return { kind: 'mcp', apiUrl, issuer, endpoint: api.url, resource: api.url, scheme };
+        return { kind: 'mcp', apiUrl, issuer, endpoint: api.url, ...await serviceAuthorization(metadata, resolver, transport, api.url, { mcp: true }) };
     }
-    // An OpenAPI servers entry is data. The destination host must independently vouch for this issuer.
+    // A description is data. The destination host independently vouches for the same Company.
     if (!destination)
         throw new ValidationError('destination');
-    const url = secureUrl(destination);
-    if (url.search)
-        throw new ValidationError('destination');
-    const serving = await resolver.resolveCompany(url.host);
-    if (serving.authorization?.issuer !== issuer || serving.document.organization.domain !== url.hostname)
+    const url = secureUrl(destination), serving = await resolver.resolveCompany(url.host);
+    if (companyIdentifier(serving) !== issuer || serving.document.organization.domain.toLowerCase() !== url.hostname)
         throw new ValidationError('destination_issuer');
-    return { kind: 'openapi', apiUrl, issuer, endpoint: destination, ...(api.resource ? { resource: api.resource } : {}), scheme: 'DPoP' };
+    return { kind: 'openapi', apiUrl, issuer, endpoint: destination, ...await serviceAuthorization(metadata, resolver, transport, destination) };
 }

package/dist/network/discovery.d.ts

@@ -1,36 +1,26 @@
 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: {
-                name: string;
-                label: string;
-                secret: boolean;
-            }[];
-            scopes: string[];
-        };
-        custom_scopes?: Record<string, string>;
+        issuer?: string;
+        scopes?: Record<string, string>;
+        scope_hints?: Record<string, ScopeHint>;
         [key: string]: unknown;
     };
     agent?: {
         protocols: {
             type: string;
             endpoint: string;
-            resource?: string;
             [key: string]: unknown;
         }[];
     };
@@ -38,13 +28,15 @@ export interface PoppyDocument {
         type: string;
         url: string;
         description: string;
-        resource?: string;
         [key: string]: unknown;
     }[];
     web?: {
         browser_session_endpoint?: string;
         [key: string]: unknown;
     };
+    excluded_tasks?: {
+        url: string;
+    };
     feedback?: {
         endpoint: string;
         [key: string]: unknown;
@@ -60,7 +52,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[];
@@ -73,6 +67,10 @@ export interface ClientMetadata {
     jwks_uri: string;
     redirect_uris: string[];
     token_endpoint_auth_method: 'private_key_jwt';
+    extensions?: Record<string, {
+        version: string;
+        [key: string]: unknown;
+    }>;
     [key: string]: unknown;
 }
 export interface CompanyMetadata {
@@ -82,16 +80,47 @@ export interface CompanyMetadata {
 }
 export interface MetadataResolver {
     resolveCompany(domain: string): Promise<CompanyMetadata>;
+    resolveResource?(resource: string, options?: {
+        metadataUrl?: string;
+        refresh?: boolean;
+    }): Promise<ProtectedResourceMetadata | null>;
     resolveClient(clientId: string): Promise<ClientMetadata>;
     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 parseAuthorizationMetadata(value: unknown, document: PoppyDocument, issuer?: string | undefined): AuthorizationMetadata;
+export declare function signInMethods(metadata: CompanyMetadata): {
+    method: 'direct' | 'device' | 'mediated';
+    scopes: string[];
+}[];
+export declare const MEDIATED_GRANT = "https://personalagentprotocol.org/grant/mediated-sign-in";
+export interface MediatedSignIn {
+    version: '1';
+    fields: {
+        name: string;
+        label: string;
+        secret: boolean;
+    }[];
+    scopes: string[];
+}
+export declare function parseMediatedSignIn(value: unknown): MediatedSignIn;
+export declare function mediatedSignIn(document: PoppyDocument): MediatedSignIn | undefined;
+export declare function companyIdentifier(metadata: CompanyMetadata): string;
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers?: string[];
+    dpop_signing_alg_values_supported?: string[];
+    [key: string]: unknown;
+}
+export declare function protectedResourceMetadataUrl(resource: string): string;
+export declare function parseProtectedResourceMetadata(value: unknown): ProtectedResourceMetadata;
 export declare function parseClientMetadata(value: unknown, clientId: string): ClientMetadata;
 export declare function createMetadataResolver(transport: HttpTransport, options?: {
     now?: () => number;