@poppykit/server 0.4.0 → 0.5.1

package/dist/conversation/service.js

@@ -1,3 +1,4 @@
+import { supportsOperations, parseOperationApproval } from '../protocol/operations.js';
 import { companyScopes } from '../network/discovery.js';
 import { randomBytes } from 'node:crypto';
 import { createConversationNotifications } from './store.js';
@@ -215,7 +216,7 @@ export function createConversationService(options) {
         const events = [];
         let bytes = 1024; // Worst-case IDs, status, responder, cursor and JSON envelope.
         for (const stored of conversation.events.slice(start, start + pageSize)) {
-            const event = parseEvent(stored);
+            const event = parseEvent(stored, !!options.operations);
             const size = Buffer.byteLength(JSON.stringify(event)) + 1;
             if (bytes + size > maxPageBytes)
                 break;
@@ -247,7 +248,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('insufficient_scope', { scope: historyScopes.join(' ') });
+            throw new AuthorityError(principal.accountId ? 'insufficient_scope' : 'account_required', { scope: historyScopes.join(' ') });
         throw notFound();
     }
     // Runs change under withCurrent; target() and history() decide the scopes from the state being checked.
@@ -272,7 +273,9 @@ export function createConversationService(options) {
     async function accept(request, principal, url, conversationId) {
         const read = parseReadOptions(url, maxWaitSeconds);
         const waiting = url.searchParams.has('wait');
-        const body = parseConversationRequest(await readJson(request));
+        const body = parseConversationRequest(await readJson(request), !!options.operations);
+        if (body.message.approval && conversationId === undefined)
+            throw new ValidationError('message.approval');
         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))
@@ -337,6 +340,16 @@ export function createConversationService(options) {
                     page(conversation, read.cursor, draft.cursorStatus);
                 conversation.authority = authority;
             }
+            if (body.message.approval) {
+                const approved = parseOperationApproval(body.message.approval);
+                const approvalKey = canonical([approved.operation_id, approved.revision]);
+                if (conversation.operationApprovals?.includes(approvalKey)) {
+                    const result = { status: 202, body: ack(conversation) };
+                    draft.messages[key] = { conversationId: conversation.id, fingerprint, receipt: result };
+                    return result;
+                }
+                conversation.operationApprovals = [...(conversation.operationApprovals ?? []), approvalKey];
+            }
             pruneWork(draft);
             const message = body.message;
             conversation.lastUserMessage = message;
@@ -345,7 +358,7 @@ export function createConversationService(options) {
             addEvent(conversation, { type: 'message', message: { ...message, role: 'user' } });
             // A context-only message asks nothing. Work always records this message's own accepted authority; while queued
             // for or answered by a person it is held for them and reaches automation only if they never answer it.
-            if ('text' in message || 'data' in message) {
+            if ('text' in message || 'data' in message || 'approval' in message) {
                 const held = conversation.responder === 'human' || conversation.status === 'queued';
                 draft.work.push({ id: randomId('wrk_'), conversationId: conversation.id, message, authority, phase: held ? 'held' : 'pending', outputs: {} });
                 if (!held && conversation.status === 'idle')
@@ -498,6 +511,8 @@ export function createConversationService(options) {
         if (request.method !== method)
             throw new HttpError(405, { error: 'method_not_allowed' }, { Allow: method });
         const principal = await authenticator.authenticate(request);
+        if (options.operations && !supportsOperations(await options.operations.resolveClient(principal.clientId)))
+            throw new HttpError(403, { error: 'extension_required', extension: 'operations' }, { 'WWW-Authenticate': 'Bearer error="extension_required", extension="operations"' });
         if (!match)
             return accept(request, principal, url);
         const [, id, action] = match;
@@ -603,7 +618,7 @@ export function createConversationService(options) {
                     return json(400, { error: 'invalid_request' });
                 // Status/code/headers only, never the raw message.
                 if (error instanceof AuthorityError)
-                    return json(error.status, { error: error.code }, error.headers);
+                    return error.code === 'account_required' || error.code === 'invalid_session' ? error.response() : json(error.status, { error: error.code }, error.headers);
                 throw error;
             }
         },
@@ -625,7 +640,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: parseMessage(work.message), context: conversation.context };
+                    return { workId: work.id, fence: work.fence, conversationId: work.conversationId, message: parseMessage(work.message, { operations: !!options.operations }), context: conversation.context };
                 }
                 return null;
             });
@@ -642,7 +657,7 @@ export function createConversationService(options) {
                 const accountId = boundAccount(draft, work);
                 if (accountId !== undefined && work.authority.principal.accountId !== accountId)
                     throw new AuthorityError('insufficient_scope', { scope: historyScopes.join(' ') });
-                return linkedHistory(draft, conversation).map(parseEvent);
+                return linkedHistory(draft, conversation).map(event => parseEvent(event, !!options.operations));
             }, never, true);
         },
         requireAccount(ref, scopes) {
@@ -656,8 +671,23 @@ export function createConversationService(options) {
                 return { accountId };
             });
         },
+        operationContext(ref) {
+            if (!options.operations)
+                throw new TypeError('operations not configured');
+            return publish(ref, noScopes, (_draft, work, conversation) => ({
+                principal: structuredClone(work.authority.principal),
+                request: { channel: 'conversation', endpoint: options.endpoint, conversationId: conversation.id },
+                ...(work.message.approval ? { approval: parseOperationApproval(work.message.approval) } : {}),
+            }));
+        },
         async reply(ref, outputId, message) {
-            const parsed = parseMessage(message, { company: true });
+            if (message.operation) {
+                const state = await store.read({ workId: ref.workId });
+                const work = state.work.find(row => row.id === ref.workId);
+                if (!work || !options.operations || !supportsOperations(await options.operations.resolveClient(work.authority.principal.clientId)))
+                    throw new ValidationError('message.operation');
+            }
+            const parsed = parseMessage(message, { company: true, operations: !!options.operations });
             const payload = canonical({ reply: parsed });
             await publish(ref, noScopes, (draft, work, conversation) => {
                 if (parsed.author.type !== conversation.responder)
@@ -729,7 +759,7 @@ export function createConversationService(options) {
                 const source = conversation.lastUserMessage ?? last?.message;
                 if (!source)
                     throw new PublicationError('stale_work');
-                const { role: _role, ...message } = parseMessage(source);
+                const { role: _role, ...message } = parseMessage(source, { operations: !!options.operations });
                 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);

package/dist/feedback.d.ts

@@ -1,8 +1,8 @@
 import type { RequestAuthenticator, AuthorityPolicy, Principal } from './auth/authority.js';
 export interface FeedbackReport {
-    kind: string;
     task: string;
     description: string;
+    [key: string]: unknown;
 }
 export declare function createFeedbackHandler(options: {
     endpoint: string;

package/dist/feedback.js

@@ -12,7 +12,7 @@ export function createFeedbackHandler(options) {
         }
         catch (error) {
             if (error instanceof AuthorityError)
-                return new Response(null, { status: error.status, headers: error.headers });
+                return error.response();
             throw error;
         }
         if (request.url !== options.endpoint || request.method !== 'POST' || request.headers.get('content-type')?.split(';')[0] !== 'application/json')
@@ -20,9 +20,9 @@ export function createFeedbackHandler(options) {
         let report;
         try {
             const value = object(parseJson(await boundedText(request, 16384)));
-            if (typeof value.kind !== 'string' || !value.kind.length || typeof value.task !== 'string' || !value.task.length || [...value.task].length > 200 || typeof value.description !== 'string' || !value.description.length || [...value.description].length > 2000)
+            if (typeof value.task !== 'string' || !value.task.length || [...value.task].length > 200 || typeof value.description !== 'string' || !value.description.length || [...value.description].length > 2000)
                 throw 0;
-            report = { kind: value.kind, task: value.task, description: value.description };
+            report = { ...value, task: value.task, description: value.description };
         }
         catch {
             return fail(400, 'invalid_request');
@@ -30,14 +30,14 @@ export function createFeedbackHandler(options) {
         try {
             return await options.policy.withCurrent(principal, [], async () => {
                 if (options.allow && !await options.allow(principal))
-                    return fail(429, 'rate_limited');
+                    return Response.json({ error: 'temporarily_unavailable' }, { status: 429, headers: { 'Cache-Control': 'no-store', 'Retry-After': '60' } });
                 await options.accept(Object.freeze(report), principal);
                 return new Response(null, { status: 202 });
             });
         }
         catch (error) {
             if (error instanceof AuthorityError)
-                return new Response(null, { status: error.status, headers: error.headers });
+                return error.response();
             throw error;
         }
     };

package/dist/index.d.ts

@@ -5,8 +5,12 @@ export * from './conversation/service.js';
 export type { ConversationStore, ConversationSelection, ConversationNotifications } from './conversation/store.js';
 export { createConversationNotifications } from './conversation/store.js';
 export { createBrowserSessions } from './browser.js';
-export type { BrowserBinding, BrowserSession, BrowserSessionAuthority, BrowserCookieStore } from './browser.js';
+export type { BrowserBinding, BrowserCookieStore, BrowserJoin } from './browser.js';
 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';
+export { createSessionAuthority } from './auth/session.js';
+export type { SessionRecord, SessionState, SessionAdmission, SessionStore, SessionAuthority } from './auth/session.js';
+export * from './operations.js';
+export * from './protocol/operations.js';

package/dist/index.js

@@ -5,3 +5,6 @@ export { createConversationNotifications } from './conversation/store.js';
 export { createBrowserSessions } from './browser.js';
 export { createFeedbackHandler } from './feedback.js';
 export { mcpResourceMetadata, mcpAuthorizationError } from './mcp.js';
+export { createSessionAuthority } from './auth/session.js';
+export * from './operations.js';
+export * from './protocol/operations.js';

package/dist/mcp.d.ts

@@ -1,7 +1,7 @@
 import type { AuthorityError } from './auth/authority.js';
 export declare function mcpResourceMetadata(input: {
     resource: string;
-    issuer: string;
+    issuer?: string;
     dpop: boolean;
 }): Record<string, unknown>;
 export declare function mcpAuthorizationError(error: AuthorityError, metadataUrl: string, dpop: boolean): Response;

package/dist/mcp.js

@@ -1,14 +1,18 @@
 import { secureUrl } from './network/transport.js';
 export function mcpResourceMetadata(input) {
     secureUrl(input.resource);
-    secureUrl(input.issuer);
-    return { resource: input.resource, authorization_servers: [input.issuer], bearer_methods_supported: ['header'], ...(input.dpop ? { dpop_signing_alg_values_supported: ['ES256'] } : {}) };
+    if (input.issuer)
+        secureUrl(input.issuer);
+    return { resource: input.resource, authorization_servers: input.issuer ? [input.issuer] : [], bearer_methods_supported: ['header'], ...(input.dpop ? { dpop_signing_alg_values_supported: ['ES256'] } : {}) };
 }
 export function mcpAuthorizationError(error, metadataUrl, dpop) {
+    if (error.code === 'invalid_session' || error.code === 'rate_limited')
+        return error.response();
     secureUrl(metadataUrl);
     if (/["\x00-\x20\\]/.test(metadataUrl))
         throw new TypeError('metadataUrl');
-    const scope = error.headers.get('www-authenticate')?.match(/, scope="[^"]*"/)?.[0] ?? '';
-    const challenge = (scheme) => `${scheme} error="${error.code}"${scope}, resource_metadata="${metadataUrl}"`;
+    const scope = error.headers.get('www-authenticate')?.match(/(?:^|[ ,])scope="([^"]*)"/)?.[1];
+    const attributes = [...(error.code === 'account_required' ? [] : [`error="${error.code}"`]), ...(scope === undefined ? [] : [`scope="${scope}"`]), `resource_metadata="${metadataUrl}"`];
+    const challenge = (scheme) => `${scheme} ${attributes.join(', ')}`;
     return new Response(null, { status: error.status, headers: { 'WWW-Authenticate': [challenge('Bearer'), ...(dpop ? [challenge('DPoP')] : [])].join(', '), 'Cache-Control': 'no-store' } });
 }

package/dist/network/discovery.d.ts

@@ -12,16 +12,7 @@ export interface PoppyDocument {
         domain: string;
     };
     auth?: {
-        issuer: string;
-        mediated?: {
-            endpoint: string;
-            fields: {
-                name: string;
-                label: string;
-                secret: boolean;
-            }[];
-            scopes: string[];
-        };
+        issuer?: string;
         scopes?: Record<string, string>;
         scope_hints?: Record<string, ScopeHint>;
         [key: string]: unknown;
@@ -30,7 +21,6 @@ export interface PoppyDocument {
         protocols: {
             type: string;
             endpoint: string;
-            resource?: string;
             [key: string]: unknown;
         }[];
     };
@@ -38,7 +28,6 @@ export interface PoppyDocument {
         type: string;
         url: string;
         description: string;
-        resource?: string;
         [key: string]: unknown;
     }[];
     web?: {
@@ -78,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 {
@@ -87,6 +80,10 @@ 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;
@@ -98,11 +95,32 @@ export declare function companyScopes(value: unknown, allowEmpty?: boolean): str
 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;

package/dist/network/discovery.js

@@ -1,5 +1,5 @@
 import { validRedirect } from './redirect.js';
-import { object, string, member, canonical, parseJson, ValidationError } from '../protocol/wire.js';
+import { object, string, member, 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; }
@@ -8,7 +8,7 @@ function strings(value, field, allowEmpty = false) { if (!Array.isArray(value) |
 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:'))
+        if (!/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope))
             throw new ValidationError('scopes');
     return result;
 }
@@ -40,24 +40,10 @@ export function parsePoppyDocument(value, servingUrl) {
     const web = 'web' in doc ? object(doc.web, 'web') : undefined;
     if (web && 'browser_session_endpoint' in web)
         url(web.browser_session_endpoint, 'browser_session_endpoint');
-    if (['agent', 'apis', 'feedback'].some(key => key in doc) || (web && 'browser_session_endpoint' in web))
-        object(doc.auth, 'auth');
     if ('auth' in doc) {
         const auth = object(doc.auth, 'auth');
-        authorizationMetadataUrl(url(auth.issuer, 'issuer'));
-        if ('mediated' in auth) {
-            const mediated = object(auth.mediated, 'mediated');
-            url(mediated.endpoint, 'mediated.endpoint');
-            companyScopes(mediated.scopes);
-            if (!Array.isArray(mediated.fields) || !mediated.fields.length)
-                throw new ValidationError('mediated.fields');
-            for (const field of mediated.fields) {
-                const item = object(field);
-                string(item.name, 'field.name');
-                string(item.label, 'field.label');
-                member(item.secret, [true, false], 'field.secret');
-            }
-        }
+        if ('issuer' in auth)
+            authorizationMetadataUrl(url(auth.issuer, 'issuer'));
         if ('scope_hints' in auth) {
             const hints = object(auth.scope_hints, 'scope_hints');
             for (const [scope, value] of Object.entries(hints)) {
@@ -82,8 +68,8 @@ export function parsePoppyDocument(value, servingUrl) {
             const item = object(protocol);
             string(item.type, 'protocol.type');
             url(item.endpoint, 'protocol.endpoint');
-            if ('resource' in item)
-                url(item.resource, 'protocol.resource');
+            if (item.type === 'poppy' && 'access' in item)
+                string(item.access, 'protocol.access');
         }
     }
     if ('apis' in doc) {
@@ -94,8 +80,6 @@ export function parsePoppyDocument(value, servingUrl) {
             string(item.type, 'api.type');
             string(item.description, 'api.description');
             url(item.url, 'api.url');
-            if ('resource' in item)
-                url(item.resource, 'api.resource');
         }
     }
     if ('excluded_tasks' in doc)
@@ -109,21 +93,22 @@ export function parsePoppyDocument(value, servingUrl) {
             if ('endpoint' in item)
                 url(item.endpoint, 'extension.endpoint');
         }
+    const mediated = doc.extensions?.['mediated-sign-in'];
+    if (mediated && object(mediated).version === '1')
+        parseMediatedSignIn(mediated);
     return doc;
 }
-export function parseAuthorizationMetadata(value, document) {
+export function parseAuthorizationMetadata(value, document, issuer = document.auth?.issuer) {
     const metadata = object(value);
-    const auth = document.auth;
-    if (metadata.issuer !== auth.issuer)
+    if (!issuer || metadata.issuer !== issuer)
         throw new ValidationError('issuer');
     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');
+    if (!grants.includes('refresh_token'))
+        throw new ValidationError('grant_types_supported');
     for (const key of ['token_endpoint', 'revocation_endpoint'])
         url(metadata[key], key);
     for (const [key, grant] of [['authorization_endpoint', 'authorization_code'], ['device_authorization_endpoint', 'urn:ietf:params:oauth:grant-type:device_code']])
@@ -131,15 +116,13 @@ export function parseAuthorizationMetadata(value, document) {
             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 ('scopes_supported' in metadata)
+        companyScopes(metadata.scopes_supported, true);
+    const mediated = mediatedSignIn(document);
+    if (mediated && !grants.includes(MEDIATED_GRANT))
+        throw new ValidationError('mediated.grant');
+    if ('dpop_signing_alg_values_supported' in metadata)
+        strings(metadata.dpop_signing_alg_values_supported, '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;
@@ -152,10 +135,53 @@ export function signInMethods(metadata) {
         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] });
+    const mediated = mediatedSignIn(metadata.document);
+    if (mediated && auth.grant_types_supported.includes(MEDIATED_GRANT))
+        methods.push({ method: 'mediated', scopes: [...mediated.scopes] });
     return methods;
 }
+export const MEDIATED_GRANT = 'https://personalagentprotocol.org/grant/mediated-sign-in';
+export function parseMediatedSignIn(value) {
+    const extension = object(value, 'mediated-sign-in');
+    member(extension.version, ['1'], 'mediated.version');
+    companyScopes(extension.scopes);
+    if (!Array.isArray(extension.fields) || !extension.fields.length)
+        throw new ValidationError('mediated.fields');
+    const names = new Set();
+    const reserved = new Set(['grant_type', 'scope', 'resource', 'client_id', 'client_secret', 'client_assertion', 'client_assertion_type', 'sign_in_id', 'one_time_code']);
+    for (const value of extension.fields) {
+        const field = object(value);
+        const name = string(field.name, 'field.name');
+        if (reserved.has(name) || names.has(name))
+            throw new ValidationError('field.name');
+        names.add(name);
+        string(field.label, 'field.label');
+        member(field.secret, [true, false], 'field.secret');
+    }
+    return extension;
+}
+export function mediatedSignIn(document) {
+    const extension = document.extensions?.['mediated-sign-in'];
+    return extension?.version === '1' ? parseMediatedSignIn(extension) : undefined;
+}
+export function companyIdentifier(metadata) {
+    return metadata.authorization?.issuer ?? `https://${metadata.document.organization.domain.toLowerCase()}`;
+}
+export function protectedResourceMetadataUrl(resource) {
+    const parsed = secureUrl(resource);
+    return `${parsed.origin}/.well-known/oauth-protected-resource${parsed.pathname === '/' ? '' : parsed.pathname}${parsed.search}`;
+}
+export function parseProtectedResourceMetadata(value) {
+    const metadata = object(value, 'resource_metadata');
+    url(metadata.resource, 'resource');
+    if ('authorization_servers' in metadata)
+        strings(metadata.authorization_servers, 'authorization_servers', true).forEach(value => authorizationMetadataUrl(url(value, 'authorization_servers')));
+    if ('bearer_methods_supported' in metadata)
+        strings(metadata.bearer_methods_supported, 'bearer_methods_supported', true);
+    if ('dpop_signing_alg_values_supported' in metadata)
+        strings(metadata.dpop_signing_alg_values_supported, 'dpop_signing_alg_values_supported', true);
+    return metadata;
+}
 export function parseClientMetadata(value, clientId) {
     const parsed = validateClientId(clientId);
     const metadata = object(value);
@@ -166,6 +192,9 @@ export function parseClientMetadata(value, clientId) {
     const redirects = strings(metadata.redirect_uris, 'redirect_uris', true);
     if (secureUrl(url(metadata.jwks_uri, 'jwks_uri')).hostname !== parsed.hostname || redirects.some(endpoint => !validRedirect(endpoint, clientId)))
         throw new ValidationError('client_endpoint_domain');
+    if ('extensions' in metadata)
+        for (const extension of Object.values(object(metadata.extensions)))
+            string(object(extension).version, 'extension.version');
     if ('logo_uri' in metadata)
         url(metadata.logo_uri, 'logo_uri');
     return metadata;
@@ -186,7 +215,7 @@ function remember(map, key, value, max, expired) {
     }
 }
 // Defaults: 1000 entries per map; at most 16 cold fetch operations in flight and 120 started per 60 s (excess is rejected, not queued).
-// Invariant: maxFetchesPerMinute * 5 (300 s TTL cap) must stay below maxEntries, or a flood can evict live authDocuments/refreshes entries.
+// Refresh throttling entries share the same bound as metadata cache entries.
 // shortcut: limits are global per resolver, not per caller, and cap total cold-fetch throughput; move per-caller limiting to the server HTTP layer before production use.
 export function createMetadataResolver(transport, options = {}) {
     const now = options.now ?? Date.now;
@@ -198,13 +227,12 @@ export function createMetadataResolver(transport, options = {}) {
     const cache = new Map();
     const pending = new Map();
     const refreshes = new Map();
-    const authDocuments = new Map();
-    async function get(target, validate, mode, refresh = false) {
+    async function get(target, validate, mode, refresh = false, allowMissing = false) {
         secureUrl(target);
         const key = `${mode}:${target}`;
         const cached = cache.get(key);
         if (!refresh && cached && cached.expires > now()) {
-            validate(cached.value, cached.url);
+            validate(cached.value, cached.url, cached.missing);
             return structuredClone(cached);
         }
         let task = pending.get(key);
@@ -225,24 +253,25 @@ export function createMetadataResolver(transport, options = {}) {
                 else if (cached?.modified)
                     headers.set('if-modified-since', cached.modified);
                 const response = await transport.fetch(new Request(target, { headers }), { mode });
-                if (response.status !== 200 && !(response.status === 304 && cached))
+                if (response.status !== 200 && !(allowMissing && response.status === 404) && !(response.status === 304 && cached))
                     throw new ValidationError('metadata.status');
                 let value;
                 try {
-                    value = response.status === 304 ? cached.value : parseJson(await response.text());
+                    value = response.status === 304 ? cached.value : response.status === 404 ? null : parseJson(await response.text());
                 }
                 catch {
                     throw new ValidationError('metadata.json');
                 }
+                const missing = response.status === 404 || (response.status === 304 && cached?.missing === true);
                 const servedUrl = response.url || (response.status === 304 ? cached.url : target);
-                validate(value, servedUrl);
+                validate(value, servedUrl, missing);
                 if (response.status === 304)
-                    validate(value, cached.url);
+                    validate(value, cached.url, missing);
                 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: servedUrl, expires, etag: response.headers.get('etag') ?? cached?.etag, modified: response.headers.get('last-modified') ?? cached?.modified };
+                const result = { value, control, missing, 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))
@@ -255,7 +284,7 @@ export function createMetadataResolver(transport, options = {}) {
         }
         try {
             const result = await task;
-            validate(result.value, result.url);
+            validate(result.value, result.url, result.missing);
             return structuredClone(result);
         }
         finally {
@@ -266,36 +295,44 @@ export function createMetadataResolver(transport, options = {}) {
     return {
         invalidate(target) { epoch++; pending.clear(); if (target === undefined) {
             cache.clear();
-            authDocuments.clear();
         }
         else {
             for (const key of cache.keys())
                 if (key.endsWith(`:${target}`))
                     cache.delete(key);
-            authDocuments.clear();
         } },
         async resolveCompany(input) {
-            const startedEpoch = epoch;
             if (!/^[a-z0-9.-]+(?::\d{1,5})?$/i.test(input))
                 throw new ValidationError('domain');
             const target = `https://${input}/.well-known/poppy.json`;
             const found = await get(target, parsePoppyDocument, 'discovery');
             const document = parsePoppyDocument(found.value, found.url);
-            if (!document.auth)
+            const resource = `https://${document.organization.domain.toLowerCase()}`;
+            const protectedMetadata = await get(protectedResourceMetadataUrl(resource), (value, _servedUrl, missing) => {
+                if (!missing) {
+                    const metadata = parseProtectedResourceMetadata(value);
+                    if (!/^https:\/\/[^/:?#]+$/.test(metadata.resource) || metadata.resource.slice(8).toLowerCase() !== document.organization.domain.toLowerCase())
+                        throw new ValidationError('resource');
+                }
+            }, 'discovery', false, true);
+            const servers = protectedMetadata.missing ? [] : parseProtectedResourceMetadata(protectedMetadata.value).authorization_servers ?? [];
+            const selected = document.auth?.issuer;
+            if (!servers.length) {
+                if (selected || mediatedSignIn(document) || document.agent?.protocols.some(item => item.type === 'poppy' && item.access === 'signed_in'))
+                    throw new ValidationError('issuer');
                 return { document, url: found.url };
-            const auth = await get(authorizationMetadataUrl(document.auth.issuer), value => parseAuthorizationMetadata(value, document), 'discovery');
-            if (startedEpoch !== epoch)
-                return { document, authorization: parseAuthorizationMetadata(auth.value, document), url: found.url };
-            const entries = authDocuments.get(document.auth.issuer) ?? new Map();
-            const spelling = canonical(document.auth);
-            const currentDomain = document.organization.domain.toLowerCase();
-            for (const [otherDomain, entry] of entries)
-                if (otherDomain !== currentDomain && entry.expires > now() && entry.auth !== spelling)
-                    throw new ValidationError('auth.consistency');
-            const expiredEntry = (entry) => entry.expires <= now();
-            remember(entries, currentDomain, { auth: spelling, expires: found.expires }, maxEntries, expiredEntry);
-            remember(authDocuments, document.auth.issuer, entries, maxEntries, inner => [...inner.values()].every(expiredEntry));
-            return { document, authorization: parseAuthorizationMetadata(auth.value, document), url: found.url };
+            }
+            const issuer = selected ?? (servers.length === 1 ? servers[0] : undefined);
+            if (!issuer || !servers.includes(issuer))
+                throw new ValidationError('issuer');
+            const auth = await get(authorizationMetadataUrl(issuer), value => parseAuthorizationMetadata(value, document, issuer), 'discovery');
+            return { document, authorization: parseAuthorizationMetadata(auth.value, document, issuer), url: found.url };
+        },
+        async resolveResource(resource, settings = {}) {
+            const target = settings.metadataUrl ?? protectedResourceMetadataUrl(resource);
+            const found = await get(target, (value, _servedUrl, missing) => { if (!missing)
+                parseProtectedResourceMetadata(value); }, 'discovery', settings.refresh, true);
+            return found.missing ? null : parseProtectedResourceMetadata(found.value);
         },
         async resolveExcludedTasks(document) {
             if (!document.excluded_tasks)