@poppykit/server 0.3.1 → 0.5.0

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;

package/dist/network/discovery.js

@@ -1,11 +1,17 @@
-import { object, string, member, canonical, parseJson, ValidationError } from '../protocol/wire.js';
+import { validRedirect } from './redirect.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; }
 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))
+            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())
@@ -31,29 +40,25 @@ 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'));
-        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);
-            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)) {
+                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 ('custom_scopes' in auth)
-            Object.values(object(auth.custom_scopes)).forEach(value => string(value, 'custom_scopes', false));
+        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;
@@ -63,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) {
@@ -75,10 +80,10 @@ 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)
+        url(object(doc.excluded_tasks).url, 'excluded_tasks.url');
     if ('feedback' in doc)
         url(object(doc.feedback).endpoint, 'feedback.endpoint');
     if ('extensions' in doc)
@@ -88,28 +93,95 @@ 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 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');
+    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, 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 ('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 ('pushed_authorization_request_endpoint' in metadata)
+        url(metadata.pushed_authorization_request_endpoint, 'pushed_authorization_request_endpoint');
+    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;
 }
+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 ?? []] });
+    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);
@@ -118,9 +190,11 @@ 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 ('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;
@@ -141,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;
@@ -153,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);
@@ -180,22 +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 servedUrl = response.status === 304 ? cached.url : response.url || target;
-                validate(value, servedUrl);
+                const missing = response.status === 404 || (response.status === 304 && cached?.missing === true);
+                const servedUrl = response.url || (response.status === 304 ? cached.url : target);
+                validate(value, servedUrl, missing);
+                if (response.status === 304)
+                    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: 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, 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))
@@ -208,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 {
@@ -219,36 +295,50 @@ 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)
+                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 = {}) {

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) } : {}) };
+    });
+}