@poppykit/client 0.5.0 → 0.6.0

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)

package/dist/operations.d.ts

@@ -0,0 +1,103 @@
+import type { Json, JsonObject, Message } from './protocol/wire.js';
+import { supportsOperations } from './protocol/operations.js';
+import type { BusinessOperation, OperationApproval, OperationRequest } from './protocol/operations.js';
+export interface BusinessClientContext {
+    companyId: string;
+    companyName: string;
+    clientId: string;
+    userId: string;
+    /** Local grant identity when signed in; exact Session identity otherwise. Never a token. */
+    authority: string;
+    operations: boolean;
+}
+export interface BusinessAttempt {
+    version: 1;
+    id: string;
+    context: BusinessClientContext;
+    request: OperationRequest;
+    operation: BusinessOperation;
+    phase: 'pending_consent' | 'consenting' | 'approved' | 'declined' | 'withdrawn' | 'expired' | 'uncertain' | 'completed';
+    consentToken?: string;
+    result?: Json;
+    retryAt?: number;
+    headers?: [string, string][];
+    messageId: string;
+    withdrawalRequested?: true;
+    previousDecisions?: {
+        revision: string;
+        phase: BusinessAttempt['phase'];
+    }[];
+}
+/** Atomic, cross-process synchronous mutation of one detached attempt; rollback on throw; reject unknown versions. */
+export interface BusinessAttemptStore {
+    pending(after: string | undefined, limit: number): Promise<string[]>;
+    transaction<T>(id: string, action: (slot: {
+        record?: BusinessAttempt;
+    }) => T): Promise<T>;
+}
+export interface TrustedOperationConsent {
+    /** Trusted UI only: show companyName and summary as inert literal text, plus all differences. Ask for this operation.
+     * This adapter MUST collect the actual user's answer. Never expose it, or a consent result, as a model tool.
+     */
+    confirm(input: {
+        attemptId: string;
+        companyId: string;
+        companyName: string;
+        summary: string;
+        terms?: JsonObject;
+        differences: string[];
+    }): Promise<'approve' | 'decline'>;
+}
+export type OperationDelivery = {
+    kind: 'completed';
+    result: Json;
+} | {
+    kind: 'pending';
+    retryAfterMs?: number;
+};
+export declare class OperationClientError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function createOperationClient(options: {
+    store: BusinessAttemptStore;
+    context(): Promise<BusinessClientContext>;
+    consent: TrustedOperationConsent;
+    /** Trusted application comparison, independent of Company/model claims. Return differences to show to the User. */
+    checkTerms(request: OperationRequest, operation: BusinessOperation): Promise<string[]>;
+    send(attempt: Readonly<BusinessAttempt>, approval: OperationApproval, signal: AbortSignal): Promise<OperationDelivery>;
+    now?: () => number;
+}): {
+    receive: (id: string, request: OperationRequest, value: unknown, headers?: [string, string][]) => Promise<BusinessAttempt>;
+    receiveApi(id: string, request: Request, response: Response): Promise<BusinessAttempt>;
+    receiveMcp(id: string, request: Extract<OperationRequest, {
+        channel: "mcp";
+    }>, result: unknown): Promise<BusinessAttempt>;
+    receiveConversation(id: string, request: Extract<OperationRequest, {
+        channel: "conversation";
+    }>, message: unknown): Promise<BusinessAttempt>;
+    recover(after?: string, limit?: number): Promise<(BusinessAttempt | {
+        id: string;
+        error: string;
+    })[]>;
+    get(id: string): Promise<BusinessAttempt>;
+    requestConsent(id: string): Promise<BusinessAttempt>;
+    /** Explicitly dismiss the old UI first. Its late callback is fenced; a fresh answer is required. */
+    resumeConsent(id: string): Promise<BusinessAttempt>;
+    withdraw(id: string): Promise<BusinessAttempt>;
+    retry(id: string): Promise<BusinessAttempt>;
+    /** Trusted host lookup of actual business state; an operation returned on retry is not reconciliation. */
+    reconcile(id: string, lookup: (attempt: Readonly<BusinessAttempt>) => Promise<OperationDelivery>): Promise<BusinessAttempt>;
+};
+export declare function approvedApiRequest(attempt: BusinessAttempt, approval: OperationApproval, signal?: AbortSignal): Request;
+export declare function approvedMcpParams(attempt: BusinessAttempt, approval: OperationApproval): JsonObject;
+export declare function approvedConversationMessage(attempt: BusinessAttempt, approval: OperationApproval): Message;
+/** Adapters must use verified SDK channel targets and current authorization; a conversation acceptance is still pending work. */
+export declare function createOperationSender(channels: {
+    api(request: Request, context: BusinessClientContext): Promise<Response>;
+    mcp(url: string, params: JsonObject, signal: AbortSignal, context: BusinessClientContext): Promise<JsonObject>;
+    conversation(request: Extract<OperationRequest, {
+        channel: 'conversation';
+    }>, message: Message, signal: AbortSignal, context: BusinessClientContext): Promise<void>;
+}): (attempt: Readonly<BusinessAttempt>, approval: OperationApproval, signal: AbortSignal) => Promise<OperationDelivery>;
+export { supportsOperations };