@awiki/dsh-pap 0.0.0-stage → 0.1.0

package/lib/cooldown.d.ts

@@ -0,0 +1,11 @@
+import { PapError } from './errors.js';
+import type { HttpResponse, PapState } from './types.js';
+export declare const resourceCooldownKey: (companyId: string, resource: string) => string;
+export declare const asCooldownKey: (companyId: string, issuer: string) => string;
+export declare function responseHeader(response: HttpResponse, name: string): string | undefined;
+/** Delta-seconds are stored as exact integer milliseconds, never capped to a shorter server window. */
+export declare function retryAfterUntil(value: string | undefined, now: number): string;
+export declare function remainingCooldownMs(state: PapState, key: string, now: number): bigint;
+export declare function cooldownError(state: PapState, key: string, now: number): PapError;
+export declare function assertCooldownElapsed(state: PapState, key: string, now: number): void;
+export declare function recordCooldown(state: PapState, key: string, response: HttpResponse, now: number): void;

package/lib/cooldown.js

@@ -0,0 +1,88 @@
+import { PapError, requirePap } from './errors.js';
+import { sha256 } from './util.js';
+export const resourceCooldownKey = (companyId, resource) => sha256(JSON.stringify(['resource', companyId, resource]));
+export const asCooldownKey = (companyId, issuer) => sha256(JSON.stringify(['authorization_server', companyId, issuer]));
+export function responseHeader(response, name) {
+    const found = Object.entries(response.headers).filter(([key]) => key.toLowerCase() === name.toLowerCase());
+    return found.length === 1 ? found[0][1] : undefined;
+}
+const nowValue = (now) => { requirePap(Number.isSafeInteger(Math.floor(now)) && now >= 0, 'state_conflict'); return BigInt(Math.floor(now)); };
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+function httpDate(value, now) {
+    let year;
+    let month;
+    let day;
+    let hour;
+    let minute;
+    let second;
+    const modern = value.match(/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), ([0-9]{2}) ([A-Z][a-z]{2}) ([0-9]{4}) ([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT$/);
+    const old = value.match(/^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), ([0-9]{2})-([A-Z][a-z]{2})-([0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT$/);
+    const ascii = value.match(/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) ([A-Z][a-z]{2}) ([ 0-9][0-9]) ([0-9]{2}):([0-9]{2}):([0-9]{2}) ([0-9]{4})$/);
+    if (modern || old) {
+        const match = (modern ?? old);
+        day = Number(match[1]);
+        month = months.indexOf(match[2]);
+        year = Number(match[3]);
+        hour = Number(match[4]);
+        minute = Number(match[5]);
+        second = Number(match[6]);
+        if (old) {
+            const currentYear = new Date(now).getUTCFullYear();
+            year += Math.floor(currentYear / 100) * 100;
+            if (year > currentYear + 50)
+                year -= 100;
+        }
+    }
+    else if (ascii) {
+        month = months.indexOf(ascii[1]);
+        day = Number(ascii[2]);
+        hour = Number(ascii[3]);
+        minute = Number(ascii[4]);
+        second = Number(ascii[5]);
+        year = Number(ascii[6]);
+    }
+    else
+        return undefined;
+    if (month < 0 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59)
+        return undefined;
+    const date = new Date(Date.UTC(year, month, day, hour, minute, second));
+    if (!Number.isFinite(date.getTime()) || date.getUTCFullYear() !== year || date.getUTCMonth() !== month || date.getUTCDate() !== day)
+        return undefined;
+    return date.getTime();
+}
+/** Delta-seconds are stored as exact integer milliseconds, never capped to a shorter server window. */
+export function retryAfterUntil(value, now) {
+    const current = nowValue(now);
+    const input = value?.trim();
+    if (input && /^[0-9]{1,16384}$/.test(input))
+        return (current + BigInt(input) * 1000n).toString();
+    if (input && input.length <= 128) {
+        const date = httpDate(input, now);
+        if (date !== undefined)
+            return (BigInt(Math.trunc(date)) > current ? BigInt(Math.trunc(date)) : current).toString();
+    }
+    // Missing/malformed Retry-After gets a local one-second fence, not an inferred remote lifetime.
+    return (current + 1000n).toString();
+}
+export function remainingCooldownMs(state, key, now) {
+    const record = state.cooldowns[key];
+    if (!record)
+        return 0n;
+    requirePap(/^[0-9]{1,16416}$/.test(record.notBeforeMs), 'state_corrupt');
+    const remaining = BigInt(record.notBeforeMs) - nowValue(now);
+    return remaining > 0n ? remaining : 0n;
+}
+export function cooldownError(state, key, now) {
+    const seconds = (remainingCooldownMs(state, key, now) + 999n) / 1000n;
+    return new PapError('rate_limited', seconds <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(seconds) : seconds.toString());
+}
+export function assertCooldownElapsed(state, key, now) {
+    if (remainingCooldownMs(state, key, now) > 0n)
+        throw cooldownError(state, key, now);
+}
+export function recordCooldown(state, key, response, now) {
+    const until = retryAfterUntil(responseHeader(response, 'retry-after'), now);
+    const previous = state.cooldowns[key];
+    if (!previous || BigInt(until) > BigInt(previous.notBeforeMs))
+        state.cooldowns[key] = { notBeforeMs: until, generation: (previous?.generation ?? 0) + 1 };
+}

package/lib/credential-history.d.ts

@@ -0,0 +1,33 @@
+import type { PapState } from './types.js';
+export declare function ensureCredentialVault(state: PapState): NonNullable<PapState['credentialVault']>;
+/** Called inside existing encrypted state transactions before replacing/clearing a credential. */
+export declare function archiveCredentials(state: PapState, values: readonly (string | undefined)[]): void;
+export interface CredentialObservation {
+    accessToken: string;
+    accessExpiresInMs?: number;
+    refreshToken?: string;
+}
+/** Service-private redaction history. Live/unknown credentials are never evicted to fit a budget. */
+export declare class CredentialHistory {
+    private readonly clock;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly entries;
+    private readonly active;
+    private bytes;
+    private blocked;
+    private closed;
+    constructor(clock?: () => number, maxEntries?: number, maxBytes?: number);
+    private sweep;
+    assertUsable(): void;
+    restore(state: PapState): void;
+    /** Never throws while an AS response is being persisted; a limit latches public output closed. */
+    observe(input: CredentialObservation): void;
+    /** Restored values have no trustworthy process-monotonic remaining lifetime. */
+    rememberIfAbsent(secret: string): void;
+    private remember;
+    begin(): symbol;
+    values(): string[];
+    end(pin: symbol): void;
+    dispose(): void;
+}

package/lib/credential-history.js

@@ -0,0 +1,109 @@
+import { PapError } from './errors.js';
+import { createHash } from 'node:crypto';
+const MAX_ENTRIES = 4096;
+const MAX_BYTES = 4 * 1024 * 1024;
+export function ensureCredentialVault(state) {
+    if (!state.credentialVault) {
+        const accountEvidence = Object.keys(state.grants).length > 0 || Object.keys(state.transactions).length > 0 || Object.keys(state.accountSlots ?? {}).length > 0
+            || Object.keys(state.nonces).some(key => key.startsWith('authorization:')) || Object.values(state.retirements).some(value => value.key.purpose === 'pap_dpop');
+        state.credentialVault = { version: 1, completeness: accountEvidence ? 'legacy_incomplete' : 'complete', entries: {}, blocked: false };
+        // Seeding known current values never claims to reconstruct older replaced credentials.
+        if (accountEvidence)
+            for (const grant of Object.values(state.grants))
+                archiveCredentials(state, [grant.accessToken, grant.refreshToken]);
+    }
+    return state.credentialVault;
+}
+/** Called inside existing encrypted state transactions before replacing/clearing a credential. */
+export function archiveCredentials(state, values) {
+    const vault = ensureCredentialVault(state);
+    let bytes = Object.values(vault.entries).reduce((total, value) => total + Buffer.byteLength(value), 0);
+    for (const value of values) {
+        if (!value)
+            continue;
+        const key = createHash('sha256').update(JSON.stringify(value)).digest('hex');
+        if (vault.entries[key] !== undefined)
+            continue;
+        const size = Buffer.byteLength(value);
+        if (Object.keys(vault.entries).length >= MAX_ENTRIES || bytes + size > MAX_BYTES) {
+            vault.blocked = true;
+            continue;
+        }
+        vault.entries[key] = value;
+        bytes += size;
+    }
+}
+/** Service-private redaction history. Live/unknown credentials are never evicted to fit a budget. */
+export class CredentialHistory {
+    clock;
+    maxEntries;
+    maxBytes;
+    entries = new Map();
+    active = new Set();
+    bytes = 0;
+    blocked = false;
+    closed = false;
+    constructor(clock = () => performance.now(), maxEntries = MAX_ENTRIES, maxBytes = MAX_BYTES) {
+        this.clock = clock;
+        this.maxEntries = maxEntries;
+        this.maxBytes = maxBytes;
+    }
+    sweep() {
+        const now = this.clock();
+        for (const [secret, entry] of this.entries)
+            if (entry.deadline <= now && entry.pins.size === 0) {
+                this.entries.delete(secret);
+                this.bytes -= Buffer.byteLength(secret);
+            }
+    }
+    assertUsable() { if (this.closed || this.blocked)
+        throw new PapError('credential_unavailable'); }
+    restore(state) {
+        if (state.credentialVault?.blocked)
+            this.blocked = true;
+        for (const value of Object.values(state.credentialVault?.entries ?? {}))
+            this.rememberIfAbsent(value);
+    }
+    /** Never throws while an AS response is being persisted; a limit latches public output closed. */
+    observe(input) {
+        this.remember(input.accessToken, input.accessExpiresInMs);
+        if (input.refreshToken)
+            this.remember(input.refreshToken);
+    }
+    /** Restored values have no trustworthy process-monotonic remaining lifetime. */
+    rememberIfAbsent(secret) { if (secret && !this.entries.has(secret))
+        this.remember(secret); }
+    remember(secret, lifetime) {
+        if (!secret || this.closed || this.blocked)
+            return;
+        this.sweep();
+        const deadline = lifetime === undefined || !Number.isFinite(lifetime) ? Infinity : this.clock() + Math.max(0, lifetime);
+        const previous = this.entries.get(secret);
+        if (previous) {
+            previous.deadline = Math.max(previous.deadline, deadline);
+            for (const pin of this.active)
+                previous.pins.add(pin);
+            return;
+        }
+        const size = Buffer.byteLength(secret);
+        if (this.entries.size >= this.maxEntries || this.bytes + size > this.maxBytes) {
+            this.blocked = true;
+            return;
+        }
+        this.entries.set(secret, { deadline, pins: new Set(this.active) });
+        this.bytes += size;
+    }
+    begin() {
+        this.assertUsable();
+        this.sweep();
+        const pin = Symbol();
+        this.active.add(pin);
+        for (const entry of this.entries.values())
+            entry.pins.add(pin);
+        return pin;
+    }
+    values() { this.assertUsable(); this.sweep(); return [...this.entries.keys()]; }
+    end(pin) { this.active.delete(pin); for (const entry of this.entries.values())
+        entry.pins.delete(pin); this.sweep(); }
+    dispose() { this.closed = true; this.entries.clear(); this.active.clear(); this.bytes = 0; }
+}

package/lib/delegation.d.ts

@@ -0,0 +1,16 @@
+import type { PapSigningLease } from './host.js';
+import type { Delegation, KeyRef, PublicJwk, Subject } from './types.js';
+export declare function thumbprint(jwk: PublicJwk): string;
+export declare function verifyCompact(jwt: string, jwk: PublicJwk): boolean;
+export declare function checkDelegation(jwt: string, key: KeyRef, clientId: string, identity: {
+    alg: string;
+    kid: string;
+    publicJwk?: PublicJwk;
+}, now: number): number;
+export declare class DelegationAttemptFailure extends Error {
+    readonly code: import('./errors.js').PapErrorCode;
+    readonly key: KeyRef;
+    readonly retired: boolean;
+    constructor(code: import('./errors.js').PapErrorCode, key: KeyRef, retired: boolean);
+}
+export declare function newDelegation(subject: Subject, lease: PapSigningLease, generation: number, now: number, operationId: string): Promise<Delegation>;

package/lib/delegation.js

@@ -0,0 +1,59 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { PapError, requirePap } from './errors.js';
+import { jwtParts, scopeFor, sha256 } from './util.js';
+export function thumbprint(jwk) { return sha256(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y })); }
+export function verifyCompact(jwt, jwk) {
+    try {
+        const [head, payload, signature] = jwt.split('.');
+        return verify('sha256', Buffer.from(`${head}.${payload}`), { key: createPublicKey({ key: jwk, format: 'jwk' }), dsaEncoding: 'ieee-p1363' }, Buffer.from(signature, 'base64url'));
+    }
+    catch {
+        return false;
+    }
+}
+export function checkDelegation(jwt, key, clientId, identity, now) {
+    const { header, payload } = jwtParts(jwt);
+    requirePap(identity.alg === 'ES256' && identity.publicJwk && header.alg === 'ES256' && header.typ === 'poppy-delegation+jwt' && header.kid === identity.kid && verifyCompact(jwt, identity.publicJwk), 'delegation_blocked');
+    requirePap(Object.keys(payload).sort().join(',') === 'cnf,exp,iat,iss,jti', 'delegation_blocked');
+    const cnf = payload.cnf;
+    requirePap(cnf?.jwk && Object.keys(cnf.jwk).sort().join(',') === 'crv,kty,x,y' && cnf.jwk.kty === 'EC' && cnf.jwk.crv === 'P-256', 'delegation_blocked');
+    requirePap(thumbprint(cnf.jwk) === key.thumbprint && key.thumbprint === thumbprint(key.public_jwk), 'delegation_blocked');
+    requirePap(payload.iss === clientId && Number.isSafeInteger(payload.iat) && Number.isSafeInteger(payload.exp) && typeof payload.jti === 'string' && payload.jti.length > 0, 'delegation_blocked');
+    const iat = Number(payload.iat);
+    const exp = Number(payload.exp);
+    requirePap(iat <= Math.floor(now / 1000) + 5 && exp * 1000 > now && exp > iat && exp - iat <= 86400, 'delegation_blocked');
+    return exp * 1000;
+}
+export class DelegationAttemptFailure extends Error {
+    code;
+    key;
+    retired;
+    constructor(code, key, retired) {
+        super('Delegation attempt failed');
+        this.code = code;
+        this.key = key;
+        this.retired = retired;
+    }
+}
+export async function newDelegation(subject, lease, generation, now, operationId) {
+    const scope = scopeFor(subject);
+    const identity = await lease.getOAuthClientIdentity();
+    requirePap(identity.clientId === subject.binding.clientId, 'permission_denied');
+    const key = await lease.createDelegatedKey(scope, operationId);
+    try {
+        requirePap(key.purpose === 'pap_session', 'delegation_blocked');
+        const compact = await lease.issuePapDelegation(key, scope, 3600);
+        const expiresAt = checkDelegation(compact, key, subject.binding.clientId, identity, now);
+        await lease.assertActive();
+        return { subjectRef: subject.ref, key, compact, expiresAt, generation };
+    }
+    catch (error) {
+        let retired = false;
+        try {
+            await lease.retireTemporaryKey(key, scope);
+            retired = true;
+        }
+        catch { }
+        throw new DelegationAttemptFailure(error instanceof PapError ? error.code : 'delegation_blocked', key, retired);
+    }
+}

package/lib/discovery.d.ts

@@ -0,0 +1,8 @@
+import type { Company, HttpTransport } from './types.js';
+export declare class PapDiscovery {
+    private readonly transport;
+    private readonly clock;
+    constructor(transport: HttpTransport, clock?: () => number);
+    resolve(domain: string): Promise<Company>;
+    private discover;
+}

package/lib/discovery.js

@@ -0,0 +1,227 @@
+import { PapError, requirePap } from './errors.js';
+import { httpsUrl, id, object, parseJson, sha256, sha256Hex, strings } from './util.js';
+const optionalStrings = (value) => value === undefined ? undefined : strings(value);
+export class PapDiscovery {
+    transport;
+    clock;
+    constructor(transport, clock = () => Date.now()) {
+        this.transport = transport;
+        this.clock = clock;
+    }
+    async resolve(domain) {
+        try {
+            return await this.discover(domain);
+        }
+        catch (error) {
+            if (error instanceof PapError && ['unsupported_profile', 'unsafe_destination'].includes(error.code))
+                throw error;
+            throw new PapError('discovery_failed');
+        }
+    }
+    async discover(domain) {
+        requirePap(!/[/?#@\\]/.test(domain) && domain.length > 0, 'unsafe_destination');
+        let url = httpsUrl(`https://${domain}/.well-known/poppy.json`);
+        const sources = [];
+        const started = Date.now();
+        let requests = 0;
+        let bytes = 0;
+        const request = async (target) => {
+            requirePap(++requests <= 64 && Date.now() - started < 30000, 'discovery_failed');
+            const response = await this.transport.request(target, { signal: AbortSignal.timeout(Math.max(1, Math.min(10000, 30000 - (Date.now() - started)))) });
+            bytes += response.body.length;
+            requirePap(bytes <= 4 * 1024 * 1024, 'discovery_failed');
+            return response;
+        };
+        let response;
+        for (let hop = 0; hop <= 5; hop++) {
+            response = await request(url.href);
+            if ([301, 302, 303, 307, 308].includes(response.status)) {
+                requirePap(hop < 5 && response.headers.location, 'discovery_failed');
+                url = httpsUrl(new URL(response.headers.location, url).href);
+                continue;
+            }
+            break;
+        }
+        requirePap(response?.status === 200 && url.pathname === '/.well-known/poppy.json' && !url.search, 'discovery_failed');
+        const doc = parseJson(response);
+        const organization = object(doc.organization);
+        requirePap(doc.protocol_version === '0.3', 'unsupported_profile');
+        requirePap(typeof organization.domain === 'string' && organization.domain.toLowerCase() === url.host.toLowerCase() && typeof organization.name === 'string' && organization.name.length > 0, 'discovery_failed');
+        // Host comparison includes explicit ports in deliberately configured isolated deployments.
+        const origin = `https://${url.host.toLowerCase()}`;
+        const record = (response) => { sources.push({ url: response.url, digest: sha256(response.body) }); };
+        record(response);
+        const read = async (value) => {
+            const target = httpsUrl(value);
+            const result = await request(target.href);
+            requirePap(result.status === 200, 'discovery_failed');
+            record(result);
+            return parseJson(result);
+        };
+        const auth = doc.auth === undefined ? {} : object(doc.auth);
+        requirePap(auth.disabled === undefined || typeof auth.disabled === 'boolean', 'discovery_failed');
+        const prmResponse = await request(`${origin}/.well-known/oauth-protected-resource`);
+        let servers = [];
+        if (prmResponse.status !== 404) {
+            requirePap(prmResponse.status === 200, 'discovery_failed');
+            record(prmResponse);
+            const prm = parseJson(prmResponse);
+            requirePap(prm.resource === origin, 'discovery_failed');
+            servers = optionalStrings(prm.authorization_servers) ?? [];
+            requirePap(new Set(servers).size === servers.length, 'discovery_failed');
+            for (const server of servers)
+                httpsUrl(server);
+        }
+        let issuer;
+        if (servers.length === 0)
+            requirePap(auth.issuer === undefined && auth.scopes === undefined && auth.scope_hints === undefined && auth.direct === undefined && auth.device === undefined && auth.custom_scopes === undefined, 'discovery_failed');
+        else {
+            if (servers.length === 1) {
+                issuer = servers[0];
+                requirePap(auth.issuer === undefined || auth.issuer === issuer, 'discovery_failed');
+            }
+            else {
+                requirePap(typeof auth.issuer === 'string' && servers.includes(auth.issuer), 'discovery_failed');
+                issuer = auth.issuer;
+            }
+        }
+        const advertisedScopes = new Set();
+        let metadata;
+        if (issuer) {
+            const issuerUrl = httpsUrl(issuer);
+            requirePap(!issuerUrl.search && !issuerUrl.hash, 'discovery_failed');
+            const metadataUrl = `${issuerUrl.origin}/.well-known/oauth-authorization-server${issuerUrl.pathname === '/' ? '' : issuerUrl.pathname}`;
+            const meta = await read(metadataUrl);
+            if (meta.scopes_supported !== undefined)
+                strings(meta.scopes_supported).forEach(scope => advertisedScopes.add(scope));
+            requirePap(meta.issuer === issuer, 'discovery_failed');
+            const resources = strings(meta.protected_resources);
+            requirePap(resources.includes(origin), 'discovery_failed');
+            resources.forEach(httpsUrl);
+            httpsUrl(meta.token_endpoint);
+            if (meta.authorization_endpoint !== undefined)
+                httpsUrl(meta.authorization_endpoint);
+            if (meta.revocation_endpoint !== undefined)
+                httpsUrl(meta.revocation_endpoint);
+            metadata = {
+                issuer, token_endpoint: meta.token_endpoint, protected_resources: resources,
+                authorization_endpoint: meta.authorization_endpoint, revocation_endpoint: meta.revocation_endpoint,
+                grant_types_supported: optionalStrings(meta.grant_types_supported) ?? ['authorization_code', 'implicit'],
+                token_endpoint_auth_methods_supported: optionalStrings(meta.token_endpoint_auth_methods_supported),
+                dpop_signing_alg_values_supported: optionalStrings(meta.dpop_signing_alg_values_supported),
+                code_challenge_methods_supported: optionalStrings(meta.code_challenge_methods_supported),
+            };
+        }
+        const routes = [];
+        const discoveredScopes = new Set();
+        const resourceCache = new Map();
+        const serviceResource = async (service, mcp = false) => {
+            if (resourceCache.has(service))
+                return resourceCache.get(service);
+            const target = httpsUrl(service);
+            const response = await request(`${target.origin}/.well-known/oauth-protected-resource${target.pathname === '/' ? '' : target.pathname}`);
+            let resource = origin;
+            if (response.status !== 404) {
+                requirePap(response.status === 200, 'discovery_failed');
+                record(response);
+                const metadata = parseJson(response);
+                httpsUrl(metadata.resource);
+                if (metadata.scopes_supported !== undefined)
+                    strings(metadata.scopes_supported).forEach(scope => advertisedScopes.add(scope));
+                requirePap(metadata.resource === origin || metadata.resource === service, 'discovery_failed');
+                if (mcp)
+                    requirePap(metadata.resource === service, 'discovery_failed');
+                if (issuer && metadata.authorization_servers !== undefined)
+                    requirePap(strings(metadata.authorization_servers).includes(issuer), 'discovery_failed');
+                resource = metadata.resource;
+            }
+            else
+                requirePap(!mcp, 'discovery_failed');
+            resourceCache.set(service, resource);
+            return resource;
+        };
+        if (doc.apis !== undefined) {
+            requirePap(Array.isArray(doc.apis) && doc.apis.length <= 32, 'discovery_failed');
+            for (const item of doc.apis) {
+                const api = object(item);
+                const apiUrl = httpsUrl(api.url).href;
+                if (api.type === 'mcp') {
+                    // MCP target metadata is checked independently; an account token targets the exact MCP URL.
+                    await serviceResource(apiUrl, true);
+                    routes.push({ method: 'POST', template: apiUrl, resource: apiUrl, channel: 'mcp' }, { method: 'GET', template: apiUrl, resource: apiUrl, channel: 'mcp' }, { method: 'DELETE', template: apiUrl, resource: apiUrl, channel: 'mcp' });
+                }
+                else if (api.type === 'openapi') {
+                    const spec = await read(apiUrl);
+                    requirePap(typeof spec.openapi === 'string' && spec.openapi.startsWith('3.'), 'unsupported_profile');
+                    const servers = spec.servers === undefined ? [{ url: new URL(apiUrl).origin }] : spec.servers;
+                    requirePap(Array.isArray(servers) && servers.length > 0 && servers.length <= 16, 'discovery_failed');
+                    const paths = object(spec.paths);
+                    if (spec.components !== undefined) {
+                        const schemes = object(spec.components).securitySchemes;
+                        if (schemes !== undefined)
+                            for (const scheme of Object.values(object(schemes))) {
+                                const entry = object(scheme);
+                                if (entry.type === 'oauth2' && entry.flows !== undefined)
+                                    for (const flow of Object.values(object(entry.flows))) {
+                                        const scopes = object(flow).scopes;
+                                        if (scopes !== undefined)
+                                            Object.keys(object(scopes)).forEach(value => discoveredScopes.add(value));
+                                    }
+                            }
+                    }
+                    for (const server of servers) {
+                        const base = httpsUrl(new URL(String(object(server).url), apiUrl).href);
+                        requirePap(!base.search && !base.hash, 'discovery_failed');
+                        const resource = await serviceResource(base.href.replace(/\/$/, ''));
+                        for (const [path, value] of Object.entries(paths)) {
+                            requirePap(path.startsWith('/') && !path.startsWith('//') && !/[?#\\]/.test(path), 'discovery_failed');
+                            const pathItem = object(value);
+                            requirePap(pathItem.servers === undefined, 'unsupported_profile');
+                            for (const [method, operation] of Object.entries(pathItem))
+                                if (['get', 'post', 'put', 'patch', 'delete', 'head', 'options'].includes(method)) {
+                                    requirePap(object(operation).servers === undefined, 'unsupported_profile');
+                                    const parameters = [];
+                                    for (const list of [pathItem.parameters, object(operation).parameters])
+                                        if (list !== undefined) {
+                                            requirePap(Array.isArray(list) && list.length <= 64, 'discovery_failed');
+                                            for (const raw of list) {
+                                                const parameter = object(raw);
+                                                // Unsupported references are not converted into a permissive tool parameter.
+                                                if (parameter.$ref !== undefined)
+                                                    continue;
+                                                if (parameter.in !== 'path' && parameter.in !== 'query')
+                                                    continue;
+                                                requirePap(typeof parameter.name === 'string' && /^[A-Za-z0-9_.-]{1,128}$/.test(parameter.name), 'discovery_failed');
+                                                const value = { name: parameter.name, in: parameter.in, required: parameter.required === true };
+                                                const index = parameters.findIndex(p => p.name === value.name && p.in === value.in);
+                                                if (index >= 0)
+                                                    parameters[index] = value;
+                                                else
+                                                    parameters.push(value);
+                                            }
+                                        }
+                                    routes.push({ method: method.toUpperCase(), template: `${base.href.replace(/\/$/, '')}${path}`, resource, parameters, channel: 'openapi' });
+                                }
+                        }
+                    }
+                }
+            }
+        }
+        const protocols = doc.agent === undefined ? [] : object(doc.agent).protocols;
+        if (Array.isArray(protocols))
+            for (const item of protocols) {
+                const protocol = object(item);
+                if (protocol.type === 'poppy') {
+                    const endpoint = httpsUrl(protocol.endpoint).href.replace(/\/$/, '');
+                    const resource = await serviceResource(endpoint);
+                    for (const [method, suffix] of [['POST', ''], ['GET', '/{id}'], ['GET', '/{id}/messages'], ['POST', '/{id}/messages'], ['POST', '/{id}/close']])
+                        routes.push({ method, template: endpoint + suffix, resource, channel: 'poppy' });
+                }
+            }
+        requirePap(routes.length > 0 && routes.length <= 2048, 'unsupported_profile');
+        const scopes = [...new Set([...(auth.scopes === undefined ? [] : Object.keys(object(auth.scopes))), ...discoveredScopes, ...advertisedScopes])];
+        return { ref: id('cmp'), domain: url.host.toLowerCase(), name: organization.name, companyId: issuer ?? origin, issuer,
+            authDisabled: auth.disabled === true, authMode: issuer ? auth.disabled === true ? 'disabled' : 'account' : 'no_as', metadata,
+            routes, scopes, metadataDigest: sha256Hex(JSON.stringify(sources)), sources, expiresAt: this.clock() + 300000, generation: 1 };
+    }
+}

package/lib/errors.d.ts

@@ -0,0 +1,14 @@
+export type PapErrorCode = 'discovery_failed' | 'unsupported_profile' | 'unsafe_destination' | 'namespace_changed' | 'permission_denied' | 'state_conflict' | 'state_corrupt' | 'credential_unavailable' | 'delegation_blocked' | 'invalid_session' | 'session_ended' | 'invalid_token' | 'reauthorization_required' | 'unsupported_sign_in' | 'invalid_authorization_response' | 'insufficient_scope' | 'unauthorized_client' | 'rate_limited' | 'request_uncertain' | 'redirect_blocked' | 'invalid_client' | 'invalid_dpop_proof' | 'invalid_scope' | 'invalid_target' | 'oauth_error' | 'disconnected' | 'revocation_pending' | 'not_configured' | 'credential_history_incomplete';
+export interface PapAuthHint {
+    readonly scheme: 'Bearer' | 'DPoP';
+    readonly scope?: readonly string[];
+    readonly resourceMetadataUrl?: string;
+}
+/** Errors are deliberately fixed text: no remote payloads or credentials. */
+export declare class PapError extends Error {
+    readonly code: PapErrorCode;
+    readonly retryAfterSeconds?: number | string | undefined;
+    readonly authHint?: PapAuthHint | undefined;
+    constructor(code: PapErrorCode, retryAfterSeconds?: number | string | undefined, authHint?: PapAuthHint | undefined);
+}
+export declare function requirePap(condition: unknown, code: PapErrorCode): asserts condition;

package/lib/errors.js

@@ -0,0 +1,17 @@
+/** Errors are deliberately fixed text: no remote payloads or credentials. */
+export class PapError extends Error {
+    code;
+    retryAfterSeconds;
+    authHint;
+    constructor(code, retryAfterSeconds, authHint) {
+        super(`PAP operation failed: ${code}`);
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.authHint = authHint;
+        this.name = 'PapError';
+    }
+}
+export function requirePap(condition, code) {
+    if (!condition)
+        throw new PapError(code);
+}

package/lib/file-secrets.d.ts

@@ -0,0 +1,14 @@
+import type { HostSecretStore } from './host.js';
+/** Flush directories where the OS supports opening them; Windows still flushes files. */
+export declare function syncDirectory(path: string): Promise<void>;
+/** File-backed PAP state encryption keys. Identity/signing keys remain in native custody. */
+export declare class FileSecretStore implements HostSecretStore {
+    readonly root: string;
+    constructor(root: string);
+    assertSeparateFrom(stateRoot: string): void;
+    private path;
+    private prepare;
+    private read;
+    getEncryptionKey(namespace: string): Promise<Uint8Array | undefined>;
+    getOrCreateEncryptionKey(namespace: string): Promise<Uint8Array>;
+}