@awiki/dsh-pap 0.0.0-stage → 0.1.0

package/lib/plugin.d.ts

@@ -0,0 +1,75 @@
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { HttpTransport, IdentityRef } from './types.js';
+import type { HostSecretStore } from './host.js';
+import { type ProductResult } from './product-api.js';
+export interface PapPluginConfig {
+    /** Explicit opt-in; loading an unconfigured bundle performs no discovery or signing. */
+    enabled?: boolean;
+    stateRoot?: string;
+    keyringService?: string;
+    /** Explicit local storage selection; no automatic fallback between backends. */
+    secretStore?: 'keyring' | 'local-file';
+    /** Absolute key directory, separate from stateRoot. Required for local-file. */
+    secretsRoot?: string;
+    /** Approved C policy chosen by Host configuration, never by a Remote or model. */
+    policyRef?: string;
+    identityRef?: IdentityRef;
+}
+/** Optional OS-specific Host provider. It never supplies Agent keys or device credentials. */
+export interface PapHostServices {
+    secrets: HostSecretStore;
+    transport?: HttpTransport;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        pap: PapService;
+        papHost: PapHostServices;
+    }
+}
+export declare const name = "@awiki/dsh-pap/plugin";
+export declare const inject: string[];
+/** Arbitrary provider/network descriptions never cross a public boundary. */
+export declare function publicResult(operation: () => Promise<unknown>): Promise<ProductResult>;
+/** Actual installed F Host. Engine, C targets and callback capabilities remain in this process. */
+export declare class PapService extends Service {
+    private readonly config;
+    private readonly installedContext;
+    private client?;
+    private hostConsumer?;
+    private selected?;
+    private binding?;
+    private stopped;
+    private lastError?;
+    private readonly ready;
+    private readonly authHints;
+    private readonly credentialHistory;
+    private changing;
+    constructor(ctx: Context, config?: PapPluginConfig);
+    private assertInstalled;
+    private consumer;
+    private restore;
+    private persistSelection;
+    private select;
+    private engine;
+    private runPublic;
+    private publicValue;
+    private assertCurrentEngine;
+    private catalog;
+    start(): Promise<void>;
+    stop(): void;
+    getStatus(includeManagementHints?: boolean): Promise<object>;
+    /** The installed user-only Typert manager receives the management facade. */
+    acquireManagement(context: Context): {
+        status(): Promise<ProductResult>;
+        operations(): Promise<ProductResult>;
+        execute(input: unknown): Promise<ProductResult>;
+    };
+    /** Agent capability contains only approved local operation references. */
+    acquireTools(context: Context): {
+        status(): Promise<ProductResult>;
+        operations(): Promise<ProductResult>;
+        request(input: unknown, signal?: AbortSignal): Promise<ProductResult>;
+    };
+    private manage;
+}
+export declare function apply(ctx: Context, config?: PapPluginConfig): PapService;

package/lib/plugin.js

@@ -0,0 +1,473 @@
+import { Service } from '@deepseek-ai/cordis';
+import { isAbsolute, join, resolve } from 'node:path';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { PapClient } from './client.js';
+import { ProtocolIdentityHost } from './protocol-adapter.js';
+import { SafeHttpsTransport } from './network.js';
+import { PapError, requirePap } from './errors.js';
+import { KeyringSecretStore } from './keyring.js';
+import { FileSecretStore, syncDirectory } from './file-secrets.js';
+import { DeviceCallbackHandoff } from './callback-handoff.js';
+import { PAP_CONSUMER, PAP_MANAGER, PAP_TOOLS, identityReferenceSchema, managementRequestSchema, operationRequestSchema } from './product-api.js';
+import { assertApproval, findOperation, prepareOperation, privateValues, publicOperations, publicResponse, sanitizePublicValue } from './product-operations.js';
+import { httpsUrl, id, sha256 } from './util.js';
+import { strictJson } from './strict-json.js';
+import { CredentialHistory } from './credential-history.js';
+export const name = PAP_CONSUMER;
+export const inject = ['anpIdentity'];
+const fiberOf = (fiber) => fiber?.ctx?.fiber ?? fiber;
+/** Arbitrary provider/network descriptions never cross a public boundary. */
+export async function publicResult(operation) {
+    try {
+        return { ok: true, value: await operation() };
+    }
+    catch (error) {
+        if (error instanceof PapError)
+            return { ok: false, error: { code: error.code, ...(error.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: error.retryAfterSeconds }) } };
+        const code = error?.code;
+        if (typeof code === 'string' && ['callback_not_ready', 'callback_claimed', 'callback_expired', 'callback_conflict', 'callback_unavailable', 'callback_limit', 'management_auth_required', 'not_published', 'client_id_conflict', 'idempotency_conflict', 'provider_unavailable', 'provider_disposed', 'consumer_forbidden'].includes(code))
+            return { ok: false, error: { code } };
+        return { ok: false, error: { code: 'permission_denied' } };
+    }
+}
+/** Actual installed F Host. Engine, C targets and callback capabilities remain in this process. */
+export class PapService extends Service {
+    config;
+    installedContext;
+    client;
+    hostConsumer;
+    selected;
+    binding;
+    stopped = false;
+    lastError;
+    ready;
+    authHints = new Map();
+    credentialHistory = new CredentialHistory();
+    changing = false;
+    constructor(ctx, config = {}) {
+        super(ctx, 'pap');
+        this.config = config;
+        // Cordis service access can associate this.ctx with a caller. C must always
+        // receive the original installed F Context, never the manager/tool caller.
+        this.installedContext = ctx;
+        ctx.effect(() => () => this.stop());
+        this.ready = Promise.resolve().then(() => this.restore());
+    }
+    assertInstalled(context, expected) {
+        requirePap(!this.stopped, 'disconnected');
+        const loader = this.installedContext.get('loader');
+        const entry = loader?.entries && [...loader.entries()].find(value => fiberOf(value.fiber) === fiberOf(context.fiber));
+        requirePap(entry && !entry.disabled && entry.options.name === expected && entry.fiber && [1, 2].includes(entry.fiber.state), 'permission_denied');
+    }
+    async consumer() {
+        requirePap(!this.stopped, 'disconnected');
+        requirePap(this.config.enabled === true && typeof this.config.stateRoot === 'string' && isAbsolute(this.config.stateRoot) && Boolean(this.config.policyRef), 'not_configured');
+        if (!this.hostConsumer) {
+            const identity = this.installedContext.get('anpIdentity');
+            requirePap(typeof identity?.bindPapHostConsumer === 'function', 'permission_denied');
+            this.hostConsumer = identity.bindPapHostConsumer(this.installedContext);
+        }
+        await this.hostConsumer.assertActive();
+        return this.hostConsumer;
+    }
+    async restore() {
+        if (this.config.enabled !== true)
+            return;
+        if (typeof this.config.stateRoot !== 'string' || !isAbsolute(this.config.stateRoot) || !this.config.policyRef) {
+            this.lastError = 'not_configured';
+            return;
+        }
+        try {
+            let reference = this.config.identityRef;
+            try {
+                reference = identityReferenceSchema.parse(strictJson(await readFile(join(this.config.stateRoot, 'selected-identity.json')), 4096));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw new PapError('state_corrupt');
+            }
+            if (reference)
+                await this.select(reference, false);
+        }
+        catch (error) {
+            this.lastError = error instanceof PapError ? error.code : 'permission_denied';
+        }
+    }
+    async persistSelection(reference) {
+        const root = this.config.stateRoot;
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const temporary = join(root, `.${id('selection')}.tmp`);
+        try {
+            const file = await open(temporary, 'wx', 0o600);
+            try {
+                await file.writeFile(JSON.stringify(reference));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await rename(temporary, join(root, 'selected-identity.json'));
+            await syncDirectory(root);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async select(reference, persist) {
+        requirePap(!this.changing && !this.stopped, 'state_conflict');
+        this.changing = true;
+        let next;
+        try {
+            // A disposed C facade never revives. Only an explicit user selection (or
+            // plugin reload) reacquires current authority from the installed Context.
+            if (persist) {
+                this.hostConsumer?.dispose();
+                this.hostConsumer = undefined;
+            }
+            const consumer = await this.consumer();
+            const resolved = await consumer.resolveBinding(reference, this.config.policyRef, 'pap_session');
+            const identityRef = resolved.binding.identityRef;
+            requirePap(identityRef.storeId === reference.storeId && identityRef.identityId === reference.identityId && identityRef.did === reference.did && typeof resolved.binding.ownerRef === 'string' && resolved.binding.ownerRef.length > 0, 'permission_denied');
+            const binding = { identityRef: { storeId: identityRef.storeId, identityId: identityRef.identityId, did: identityRef.did }, ownerRef: resolved.binding.ownerRef, clientId: resolved.binding.clientId };
+            httpsUrl(binding.clientId);
+            const identity = this.installedContext.get('anpIdentity');
+            requirePap(typeof identity.bindProtocolConsumer === 'function', 'permission_denied');
+            const protocolHost = new ProtocolIdentityHost(identity.bindProtocolConsumer(this.installedContext), this.config.policyRef);
+            const host = this.installedContext.get('papHost');
+            requirePap(this.config.secretStore === undefined || ['keyring', 'local-file'].includes(this.config.secretStore), 'not_configured');
+            let protectedSecrets;
+            if (this.config.secretStore === 'local-file') {
+                requirePap(typeof this.config.secretsRoot === 'string' && isAbsolute(this.config.secretsRoot), 'not_configured');
+                protectedSecrets = new FileSecretStore(this.config.secretsRoot);
+            }
+            else if (this.config.secretStore === 'keyring') {
+                protectedSecrets = new KeyringSecretStore(this.config.keyringService ?? 'org.agentconnect.dsh-pap', join(this.config.stateRoot, 'keyring-locks'));
+            }
+            else {
+                protectedSecrets = host?.secrets ?? new KeyringSecretStore(this.config.keyringService ?? 'org.agentconnect.dsh-pap', join(this.config.stateRoot, 'keyring-locks'));
+            }
+            if (protectedSecrets instanceof FileSecretStore)
+                protectedSecrets.assertSeparateFrom(this.config.stateRoot);
+            const profileNamespace = `dsh-pap/profile/${sha256(resolve(this.config.stateRoot))}/`;
+            const secrets = {
+                getEncryptionKey: namespace => protectedSecrets.getEncryptionKey(profileNamespace + namespace),
+                getOrCreateEncryptionKey: namespace => protectedSecrets.getOrCreateEncryptionKey(profileNamespace + namespace),
+            };
+            const management = async (transactionId, callbackRef) => {
+                await consumer.assertActive();
+                let state = await next.store.read();
+                let tx = transactionId ? state.transactions[transactionId] : Object.values(state.transactions).find(value => value.callbackRef === callbackRef);
+                requirePap(tx && tx.status === 'pending' && tx.expiresAt > Date.now(), 'invalid_authorization_response');
+                let subject = state.subjects[tx.subjectRef];
+                let company = subject && state.companies[subject.companyRef];
+                requirePap(company && company.issuer === tx.issuer && tx.clientId === binding.clientId, 'permission_denied');
+                if (company.expiresAt <= Date.now()) {
+                    await next.resolvePapCompany(company.domain);
+                    await consumer.assertActive();
+                    state = await next.store.read();
+                    tx = transactionId ? state.transactions[transactionId] : Object.values(state.transactions).find(value => value.callbackRef === callbackRef);
+                    requirePap(tx && tx.status === 'pending' && tx.expiresAt > Date.now(), 'invalid_authorization_response');
+                    subject = state.subjects[tx.subjectRef];
+                    company = subject && state.companies[subject.companyRef];
+                    requirePap(company && company.issuer === tx.issuer && tx.clientId === binding.clientId, 'permission_denied');
+                }
+                const latest = Object.values(state.companies).filter(value => value.domain === company.domain).sort((left, right) => right.generation - left.generation)[0];
+                requirePap(latest?.companyId === company.companyId && latest.issuer === tx.issuer, 'namespace_changed');
+                const target = await protocolHost.acquire(binding, company, 'pap_account', tx.resource, undefined, tx.scope);
+                requirePap(target.targetRef, 'permission_denied');
+                return consumer.callbackManagementFor({ identityRef: reference, policyRef: this.config.policyRef, targetRef: target.targetRef });
+            };
+            const handoff = {
+                register: async (input) => { const driver = await management(input.transactionId); try {
+                    return await new DeviceCallbackHandoff(driver).register(input);
+                }
+                finally {
+                    driver.dispose();
+                } },
+                collect: async (callbackRef) => { const driver = await management(undefined, callbackRef); try {
+                    return await new DeviceCallbackHandoff(driver).collect(callbackRef);
+                }
+                finally {
+                    driver.dispose();
+                } },
+            };
+            next = new PapClient({ stateRoot: join(this.config.stateRoot, `identity-${sha256(JSON.stringify(binding))}`), binding, identityHost: protocolHost, secretStore: secrets, callbackHandoff: handoff, observeCredentials: credentials => this.credentialHistory.observe(credentials) }, host?.transport ?? new SafeHttpsTransport());
+            await next.recover();
+            await consumer.assertActive();
+            requirePap(!this.stopped, 'disconnected');
+            if (persist)
+                await this.persistSelection(reference);
+            await consumer.assertActive();
+            requirePap(!this.stopped, 'disconnected');
+            this.client?.close();
+            this.authHints.clear();
+            this.client = next;
+            this.binding = binding;
+            this.selected = structuredClone(reference);
+            this.lastError = undefined;
+        }
+        catch (error) {
+            next?.close();
+            this.lastError = error instanceof PapError ? error.code : 'permission_denied';
+            throw error;
+        }
+        finally {
+            this.changing = false;
+        }
+    }
+    async engine() {
+        await this.ready;
+        requirePap(!this.stopped, 'disconnected');
+        requirePap(this.client, 'not_configured');
+        await (await this.consumer()).assertActive();
+        return this.client;
+    }
+    async runPublic(operation) {
+        const result = await publicResult(operation);
+        if (this.stopped)
+            return { ok: false, error: { code: 'disconnected' } };
+        try {
+            return sanitizePublicValue(result, this.credentialHistory.values());
+        }
+        catch {
+            return { ok: false, error: { code: 'credential_unavailable' } };
+        }
+    }
+    publicValue(state, value, userAuthorizationUrl = false) {
+        requirePap(state.credentialVault?.completeness === 'complete', 'credential_history_incomplete');
+        this.credentialHistory.restore(state);
+        const tokens = this.credentialHistory.values();
+        const sanitized = sanitizePublicValue(value, [...tokens, ...privateValues(state)]);
+        if (userAuthorizationUrl && value && typeof value === 'object' && !Array.isArray(value) && typeof value.authorizationUrl === 'string') {
+            // Only this explicit user result may carry the AS-bound state/challenge.
+            sanitized.authorizationUrl = sanitizePublicValue(value.authorizationUrl, [...tokens, ...privateValues(state, false)]);
+        }
+        return sanitized;
+    }
+    assertCurrentEngine(engine) { requirePap(!this.stopped, 'disconnected'); requirePap(!this.changing && this.client === engine, 'state_conflict'); }
+    async catalog(enabledOnly, check) {
+        check();
+        const engine = await this.engine();
+        const state = await engine.store.read();
+        check();
+        this.assertCurrentEngine(engine);
+        await (await this.consumer()).assertActive();
+        check();
+        this.assertCurrentEngine(engine);
+        return this.publicValue(state, publicOperations(state, enabledOnly));
+    }
+    async start() { await this.ready; }
+    stop() { if (this.stopped)
+        return; this.stopped = true; this.client?.close(); this.hostConsumer?.dispose(); this.credentialHistory.dispose(); }
+    async getStatus(includeManagementHints = false) {
+        await this.ready;
+        requirePap(!this.stopped, 'disconnected');
+        if (this.config.enabled !== true)
+            return { state: 'disabled' };
+        if (!this.client)
+            return { state: this.lastError === 'credential_unavailable' ? 'credential_unavailable' : 'unconfigured', ...(this.lastError ? { error: this.lastError } : {}) };
+        const engine = this.client;
+        await (await this.consumer()).assertActive();
+        const state = await engine.store.read();
+        this.assertCurrentEngine(engine);
+        await (await this.consumer()).assertActive();
+        this.assertCurrentEngine(engine);
+        if (state.credentialVault?.completeness !== 'complete' || state.credentialVault.blocked) {
+            if (!includeManagementHints)
+                throw new PapError(state.credentialVault?.completeness !== 'complete' ? 'credential_history_incomplete' : 'credential_unavailable');
+            return { state: state.credentialVault?.completeness !== 'complete' ? 'migration_required' : 'credential_unavailable', error: state.credentialVault?.completeness !== 'complete' ? 'credential_history_incomplete' : 'credential_unavailable',
+                accounts: [...new Map([...Object.values(state.grants).map(value => [value.accountSlot, { accountSlot: value.accountSlot, status: value.status, scopes: [] }]), ...Object.values(state.transactions).map(value => [value.accountSlot, { accountSlot: value.accountSlot, status: 'pending_login', scopes: [] }])]).values()] };
+        }
+        return this.publicValue(state, { state: 'ready', identity: this.selected, supportedSignIn: ['direct'],
+            ...(includeManagementHints ? { authenticationHints: [...this.authHints].map(([operationRef, hint]) => ({ operationRef, ...hint })),
+                pendingSignIns: Object.values(state.transactions).filter(value => value.status === 'pending' && value.expiresAt > Date.now()).map(value => ({ transactionRef: value.ref, accountSlot: value.accountSlot, ...(state.subjects[value.subjectRef] ? { companyRef: state.subjects[value.subjectRef].companyRef } : {}), expiresAt: value.expiresAt })) } : {}),
+            companies: Object.values(state.companies).map(value => ({ companyRef: value.ref, name: value.name, authMode: value.authMode, scopes: value.scopes })),
+            sessions: Object.values(state.sessions).map(value => ({ sessionRef: value.ref, ...(state.subjects[value.subjectRef] ? { companyRef: state.subjects[value.subjectRef].companyRef } : {}), connected: value.connected, account: Boolean(value.accountSlot), ...(value.accountSlot ? { accountSlot: value.accountSlot } : {}) })),
+            accounts: Object.values(state.grants).map(value => ({ accountSlot: value.accountSlot, ...(state.subjects[value.subjectRef] ? { companyRef: state.subjects[value.subjectRef].companyRef } : {}), status: value.status, scopes: value.scope, canRefresh: value.status === 'active' && Boolean(value.refreshToken) })),
+        });
+    }
+    /** The installed user-only Typert manager receives the management facade. */
+    acquireManagement(context) {
+        this.assertInstalled(context, PAP_MANAGER);
+        const check = () => this.assertInstalled(context, PAP_MANAGER);
+        return Object.freeze({
+            status: () => this.runPublic(async () => { check(); const result = await this.getStatus(true); check(); return result; }),
+            operations: () => this.runPublic(() => this.catalog(false, check)),
+            execute: input => this.runPublic(async () => {
+                check();
+                const parsed = managementRequestSchema.safeParse(input);
+                requirePap(parsed.success, 'permission_denied');
+                const previous = this.client;
+                const result = await this.manage(parsed.data, check);
+                check();
+                if (parsed.data.action !== 'identity/select' && previous) {
+                    this.assertCurrentEngine(previous);
+                    await (await this.consumer()).assertActive();
+                    check();
+                    this.assertCurrentEngine(previous);
+                }
+                const current = this.client;
+                if (!current)
+                    return result;
+                const state = await current.store.read();
+                check();
+                this.assertCurrentEngine(current);
+                await (await this.consumer()).assertActive();
+                check();
+                this.assertCurrentEngine(current);
+                if (parsed.data.action === 'account/sign-out' && state.credentialVault?.completeness !== 'complete')
+                    return result;
+                if (parsed.data.action === 'identity/select' && state.credentialVault?.completeness !== 'complete')
+                    return result;
+                return this.publicValue(state, result, parsed.data.action === 'account/sign-in');
+            }),
+        });
+    }
+    /** Agent capability contains only approved local operation references. */
+    acquireTools(context) {
+        this.assertInstalled(context, PAP_TOOLS);
+        const check = () => this.assertInstalled(context, PAP_TOOLS);
+        return Object.freeze({
+            status: () => this.runPublic(async () => { check(); const result = await this.getStatus(); check(); return result; }),
+            operations: () => this.runPublic(() => this.catalog(true, check)),
+            request: (input, signal) => this.runPublic(async () => {
+                check();
+                const parsed = operationRequestSchema.safeParse(input);
+                requirePap(parsed.success, 'permission_denied');
+                const engine = await this.engine();
+                const pin = this.credentialHistory.begin();
+                try {
+                    const snapshot = await engine.store.read();
+                    requirePap(snapshot.credentialVault?.completeness === 'complete', 'credential_history_incomplete');
+                    const prepared = prepareOperation(snapshot, parsed.data);
+                    this.credentialHistory.restore(snapshot);
+                    for (const grant of Object.values(snapshot.grants)) {
+                        this.credentialHistory.rememberIfAbsent(grant.accessToken);
+                        if (grant.refreshToken)
+                            this.credentialHistory.rememberIfAbsent(grant.refreshToken);
+                    }
+                    const checkRequest = () => { check(); this.assertCurrentEngine(engine); };
+                    checkRequest();
+                    this.credentialHistory.assertUsable();
+                    const sentSecrets = new Set(privateValues(snapshot));
+                    try {
+                        const response = await engine.dispatchPap(prepared.approval.sessionRef, prepared.operation, { signal,
+                            assertAllowed: state => { checkRequest(); this.credentialHistory.assertUsable(); assertApproval(state, parsed.data.operationRef, prepared.approval); },
+                            captureSecrets: (values, credentials) => { for (const value of values)
+                                sentSecrets.add(value); if (credentials)
+                                this.credentialHistory.observe(credentials); this.credentialHistory.assertUsable(); },
+                        });
+                        checkRequest();
+                        await (await this.consumer()).assertActive();
+                        checkRequest();
+                        const current = await engine.store.read();
+                        assertApproval(current, parsed.data.operationRef, prepared.approval);
+                        this.credentialHistory.restore(current);
+                        const secrets = [...sentSecrets, ...privateValues(current), ...this.credentialHistory.values()];
+                        checkRequest();
+                        await (await this.consumer()).assertActive();
+                        checkRequest();
+                        this.authHints.delete(parsed.data.operationRef);
+                        return publicResponse(response, secrets);
+                    }
+                    catch (error) {
+                        if (this.client === engine && !this.changing && error instanceof PapError && error.authHint) {
+                            if (this.authHints.size >= 32)
+                                this.authHints.delete(this.authHints.keys().next().value);
+                            this.authHints.set(parsed.data.operationRef, error.authHint);
+                        }
+                        throw error;
+                    }
+                }
+                finally {
+                    this.credentialHistory.end(pin);
+                }
+            }),
+        });
+    }
+    async manage(input, check) {
+        await this.ready;
+        check();
+        if (input.action === 'identity/select') {
+            await this.select(input.reference, true);
+            check();
+            return this.getStatus(true);
+        }
+        const engine = await this.engine();
+        check();
+        if (input.action !== 'account/sign-out')
+            requirePap((await engine.store.read()).credentialVault?.completeness === 'complete', 'credential_history_incomplete');
+        if (input.action === 'company/discover')
+            return engine.resolvePapCompany(input.domain);
+        if (input.action === 'session/connect') {
+            const subject = await engine.getOrCreatePapUser(input.companyRef, input.mode ?? 'regular', true);
+            check();
+            return { ...subject, ...(await engine.openPapSession(subject.subjectRef, input.accountSlot)) };
+        }
+        if (input.action === 'session/disconnect') {
+            await engine.disconnectPap(input.sessionRef);
+            return null;
+        }
+        if (input.action === 'operation/disable') {
+            await engine.store.transaction(state => { check(); if (state.product)
+                delete state.product.operations[input.operationRef]; });
+            return null;
+        }
+        if (input.action === 'operation/enable')
+            return engine.store.transaction(state => {
+                check();
+                const { company, route } = findOperation(state, input.operationRef);
+                const session = state.sessions[input.sessionRef];
+                requirePap(session?.connected && state.subjects[session.subjectRef]?.companyRef === company.ref, 'permission_denied');
+                const scopes = [...new Set(input.scopes ?? [])].sort();
+                requirePap(scopes.every(scope => company.scopes.includes(scope)) && (session.accountSlot || scopes.length === 0), 'insufficient_scope');
+                state.product ??= { operations: {} };
+                state.product.operations[input.operationRef] = { companyRef: company.ref, method: route.method, template: route.template, resource: route.resource, sessionRef: input.sessionRef, scopes, generation: state.generation + 1 };
+                return { operationRef: input.operationRef, enabled: true };
+            });
+        if (input.action === 'account/sign-in') {
+            const state = await engine.store.read();
+            const { company, route } = findOperation(state, input.operationRef);
+            const session = state.sessions[input.sessionRef];
+            requirePap(session?.connected && state.subjects[session.subjectRef]?.companyRef === company.ref, 'permission_denied');
+            const resolved = await (await this.consumer()).resolveBinding(this.selected, this.config.policyRef, 'pap_account');
+            const current = this.binding;
+            const candidate = resolved.binding;
+            requirePap(candidate.clientId === current.clientId && candidate.ownerRef === current.ownerRef && candidate.identityRef.storeId === current.identityRef.storeId && candidate.identityRef.identityId === current.identityRef.identityId && candidate.identityRef.did === current.identityRef.did && resolved.redirectUri, 'unsupported_sign_in');
+            httpsUrl(resolved.redirectUri);
+            check();
+            return engine.startSignIn(session.subjectRef, { scopes: input.scopes, resource: route.resource, redirectUri: resolved.redirectUri, callbackMode: 'handoff', method: 'direct' });
+        }
+        if (input.action === 'account/collect')
+            return engine.collectSignIn(input.transactionRef);
+        const state = await engine.store.read();
+        const account = Object.values(state.grants).find(value => value.accountSlot === input.accountSlot) ?? Object.values(state.transactions).find(value => value.accountSlot === input.accountSlot);
+        requirePap(account, 'reauthorization_required');
+        if (input.action === 'account/refresh') {
+            const grant = state.grants[account.ref];
+            requirePap(grant?.status === 'active' && grant.refreshToken, 'reauthorization_required');
+            const subject = state.subjects[grant.subjectRef];
+            const company = subject && state.companies[subject.companyRef];
+            const slot = state.accountSlots[input.accountSlot];
+            requirePap(subject && company && company.companyId === subject.companyId && grant.issuer === company.issuer && grant.clientId === this.binding?.clientId && JSON.stringify(subject.binding) === JSON.stringify(this.binding) && company.routes.some(route => route.resource === grant.resource), 'permission_denied');
+            requirePap(slot && !slot.signedOut && slot.epoch === grant.accountEpoch, 'reauthorization_required');
+            const sessions = Object.values(state.sessions).filter(session => session.connected && session.accountSlot === input.accountSlot).map(session => ({ ref: session.ref, generation: session.generation }));
+            check();
+            this.assertCurrentEngine(engine);
+            await (await this.consumer()).assertActive();
+            check();
+            await engine.refreshAccountGrant(grant.ref);
+            const current = await engine.store.read();
+            check();
+            this.assertCurrentEngine(engine);
+            await (await this.consumer()).assertActive();
+            check();
+            this.assertCurrentEngine(engine);
+            requirePap(current.accountSlots[input.accountSlot]?.epoch === slot.epoch && !current.accountSlots[input.accountSlot]?.signedOut && current.grants[grant.ref]?.status === 'active', 'reauthorization_required');
+            requirePap(current.companies[subject.companyRef]?.companyId === company.companyId && current.companies[subject.companyRef]?.issuer === company.issuer && sessions.every(session => current.sessions[session.ref]?.connected && current.sessions[session.ref]?.generation === session.generation && current.sessions[session.ref]?.accountSlot === input.accountSlot), 'state_conflict');
+            return { status: 'active' };
+        }
+        return engine.signOutAccount(account.subjectRef, input.accountSlot);
+    }
+}
+export function apply(ctx, config = {}) { return new PapService(ctx, config); }

package/lib/product-api.d.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import type { Binding, IdentityRef } from './types.js';
+import type { DeviceManagementOperations } from './callback-handoff.js';
+export declare const PAP_CONSUMER = "@awiki/dsh-pap/plugin";
+export declare const PAP_MANAGER = "@awiki/dsh-pap/management-remote";
+export declare const PAP_TOOLS = "@awiki/dsh-pap/tools";
+/** C-owned capability. The caller is the actual installed F Context, never a wire name. */
+export interface PapHostConsumer {
+    resolveBinding(identityRef: IdentityRef, policyRef: string, profile: 'pap_session' | 'pap_account'): Promise<{
+        binding: Binding;
+        redirectUri?: string;
+    }>;
+    callbackManagementFor(input: {
+        identityRef: IdentityRef;
+        policyRef: string;
+        targetRef: object;
+    }): Promise<DeviceManagementOperations & {
+        dispose(): void;
+    }>;
+    assertActive(): void | Promise<void>;
+    dispose(): void;
+}
+export declare const identityReferenceSchema: z.ZodObject<{
+    storeId: z.ZodString;
+    identityId: z.ZodString;
+    did: z.ZodString;
+}, z.core.$strict>;
+export declare const managementRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"identity/select">;
+    reference: z.ZodObject<{
+        storeId: z.ZodString;
+        identityId: z.ZodString;
+        did: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"company/discover">;
+    domain: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"session/connect">;
+    companyRef: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<{
+        regular: "regular";
+        anonymous: "anonymous";
+    }>>;
+    accountSlot: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"session/disconnect">;
+    sessionRef: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"operation/enable">;
+    operationRef: z.ZodString;
+    sessionRef: z.ZodString;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"operation/disable">;
+    operationRef: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"account/sign-in">;
+    sessionRef: z.ZodString;
+    operationRef: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"account/collect">;
+    transactionRef: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"account/sign-out">;
+    accountSlot: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"account/refresh">;
+    accountSlot: z.ZodString;
+}, z.core.$strict>], "action">;
+export type PapManagementRequest = z.infer<typeof managementRequestSchema>;
+export declare const operationRequestSchema: z.ZodObject<{
+    operationRef: z.ZodString;
+    path: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodJSONSchema>;
+}, z.core.$strict>;
+export type PapOperationRequest = z.infer<typeof operationRequestSchema>;
+export type ProductResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        retryAfterSeconds?: number | string;
+    };
+};

package/lib/product-api.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export const PAP_CONSUMER = '@awiki/dsh-pap/plugin';
+export const PAP_MANAGER = '@awiki/dsh-pap/management-remote';
+export const PAP_TOOLS = '@awiki/dsh-pap/tools';
+const ref = z.string().min(1).max(256);
+export const identityReferenceSchema = z.object({ storeId: ref, identityId: ref, did: ref }).strict();
+const scope = z.string().min(1).max(256).regex(/^[\x21\x23-\x5b\x5d-\x7e]+$/);
+export const managementRequestSchema = z.discriminatedUnion('action', [
+    z.object({ action: z.literal('identity/select'), reference: identityReferenceSchema }).strict(),
+    z.object({ action: z.literal('company/discover'), domain: z.string().min(1).max(253) }).strict(),
+    z.object({ action: z.literal('session/connect'), companyRef: ref, mode: z.enum(['regular', 'anonymous']).optional(), accountSlot: ref.optional() }).strict(),
+    z.object({ action: z.literal('session/disconnect'), sessionRef: ref }).strict(),
+    z.object({ action: z.literal('operation/enable'), operationRef: ref, sessionRef: ref, scopes: z.array(scope).max(64).optional() }).strict(),
+    z.object({ action: z.literal('operation/disable'), operationRef: ref }).strict(),
+    z.object({ action: z.literal('account/sign-in'), sessionRef: ref, operationRef: ref, scopes: z.array(scope).min(1).max(64) }).strict(),
+    z.object({ action: z.literal('account/collect'), transactionRef: ref }).strict(),
+    z.object({ action: z.literal('account/sign-out'), accountSlot: ref }).strict(),
+    z.object({ action: z.literal('account/refresh'), accountSlot: ref }).strict(),
+]);
+export const operationRequestSchema = z.object({
+    operationRef: ref,
+    path: z.record(z.string(), z.string().max(1024)).optional(),
+    query: z.record(z.string(), z.string().max(4096)).optional(),
+    body: z.json().optional(),
+}).strict();