@awiki/dsh-pap 0.0.0-stage → 0.1.0

package/lib/product-operations.d.ts

@@ -0,0 +1,16 @@
+import type { Company, HttpResponse, Operation, PapState, ProductOperationApproval, Route } from './types.js';
+import type { PapOperationRequest } from './product-api.js';
+export declare function operationRef(company: Company, route: Route): string;
+export declare function findOperation(state: PapState, reference: string): {
+    company: Company;
+    route: Route;
+};
+export declare function publicOperations(state: PapState, enabledOnly?: boolean): object[];
+export declare function assertApproval(state: PapState, reference: string, expected: ProductOperationApproval): void;
+export declare function prepareOperation(state: PapState, input: PapOperationRequest): {
+    operation: Operation;
+    approval: ProductOperationApproval;
+};
+export declare function privateValues(state: PapState, includeOAuthState?: boolean): string[];
+export declare function sanitizePublicValue(value: unknown, secrets: readonly string[]): unknown;
+export declare function publicResponse(response: HttpResponse, secrets?: readonly string[]): object;

package/lib/product-operations.js

@@ -0,0 +1,120 @@
+import { PapError, requirePap } from './errors.js';
+import { httpsUrl, htu, sha256 } from './util.js';
+import { strictJson } from './strict-json.js';
+export function operationRef(company, route) {
+    return `op_${sha256(JSON.stringify([company.ref, route.method, route.template, route.resource, route.parameters ?? [], route.channel]))}`;
+}
+function supported(company, route) {
+    const reserved = [...company.sources.map(x => x.url), company.metadata?.token_endpoint, company.metadata?.authorization_endpoint, company.metadata?.revocation_endpoint].filter((value) => Boolean(value));
+    return route.channel !== 'mcp' && !reserved.some(value => htu(value) === htu(route.template.replace(/\{[^{}]+\}/g, '__parameter__')));
+}
+export function findOperation(state, reference) {
+    for (const company of Object.values(state.companies))
+        for (const route of company.routes) {
+            if (operationRef(company, route) === reference && supported(company, route))
+                return { company, route };
+        }
+    throw new PapError('unsafe_destination');
+}
+export function publicOperations(state, enabledOnly = false) {
+    const entries = [];
+    for (const company of Object.values(state.companies))
+        for (const route of company.routes) {
+            if (!supported(company, route))
+                continue;
+            const reference = operationRef(company, route);
+            const approval = state.product?.operations[reference];
+            if (enabledOnly && !approval)
+                continue;
+            entries.push({ operationRef: reference, companyRef: company.ref, method: route.method, path: new URL(route.template).pathname.replace(/%7b/gi, '{').replace(/%7d/gi, '}'),
+                pathParameters: [...route.template.matchAll(/\{([A-Za-z0-9_.-]+)\}/g)].map(x => x[1]),
+                queryParameters: (route.parameters ?? []).filter(x => x.in === 'query').map(x => ({ name: x.name, required: x.required })),
+                enabled: Boolean(approval), account: approval ? Boolean(state.sessions[approval.sessionRef]?.accountSlot) : false });
+        }
+    return entries;
+}
+export function assertApproval(state, reference, expected) {
+    const current = state.product?.operations[reference];
+    requirePap(current && JSON.stringify(current) === JSON.stringify(expected), 'permission_denied');
+    const { company, route } = findOperation(state, reference);
+    requirePap(company.ref === current.companyRef && route.method === current.method && route.template === current.template && route.resource === current.resource, 'permission_denied');
+    const session = state.sessions[current.sessionRef];
+    const subject = session && state.subjects[session.subjectRef];
+    requirePap(session?.connected && subject?.companyRef === company.ref, 'disconnected');
+}
+export function prepareOperation(state, input) {
+    const approval = state.product?.operations[input.operationRef];
+    requirePap(approval, 'permission_denied');
+    assertApproval(state, input.operationRef, approval);
+    const { route } = findOperation(state, input.operationRef);
+    const pathNames = [...route.template.matchAll(/\{([A-Za-z0-9_.-]+)\}/g)].map(x => x[1]);
+    const path = input.path ?? {};
+    const query = input.query ?? {};
+    requirePap(Object.keys(path).every(key => pathNames.includes(key)) && pathNames.every(key => typeof path[key] === 'string'), 'unsafe_destination');
+    let destination = route.template.replace(/\{([A-Za-z0-9_.-]+)\}/g, (_all, key) => {
+        const value = path[key];
+        requirePap(value.length > 0 && value !== '.' && value !== '..' && !/[\/%\\\x00-\x20\x7f]/.test(value), 'unsafe_destination');
+        return encodeURIComponent(value);
+    });
+    requirePap(!/[{}]/.test(destination), 'unsupported_profile');
+    const url = httpsUrl(destination);
+    requirePap(!url.search, 'unsafe_destination');
+    const allowedQuery = (route.parameters ?? []).filter(x => x.in === 'query');
+    requirePap(Object.keys(query).every(key => allowedQuery.some(x => x.name === key)) && allowedQuery.filter(x => x.required).every(x => query[x.name] !== undefined), 'unsafe_destination');
+    for (const [key, value] of Object.entries(query)) {
+        requirePap(!/[\x00-\x1f\x7f]/.test(value), 'unsafe_destination');
+        url.searchParams.set(key, value);
+    }
+    requirePap(url.href.length <= 8192, 'unsafe_destination');
+    const body = input.body === undefined ? undefined : JSON.stringify(input.body);
+    requirePap(body === undefined || ['POST', 'PUT', 'PATCH', 'DELETE'].includes(route.method) && Buffer.byteLength(body) <= 65536, 'permission_denied');
+    return { approval: structuredClone(approval), operation: { url: url.href, method: route.method, resource: route.resource, scopes: [...approval.scopes],
+            ...(body === undefined ? {} : { body, headers: { 'content-type': 'application/json' } }) } };
+}
+const privateFields = /^(?:token|access[_-]?token|refresh[_-]?token|id[_-]?token|authorization|proxy[_-]?authorization|dpop|poppy[_-]?session|private[_-]?key|client[_-]?secret|client[_-]?assertion|code[_-]?verifier|claim[_-]?secret|callbackRef)$/i;
+export function privateValues(state, includeOAuthState = true) {
+    const values = [];
+    for (const grant of Object.values(state.grants))
+        values.push(grant.accessToken, grant.refreshToken, grant.dpopKey?.handle);
+    for (const subject of Object.values(state.subjects))
+        values.push(subject.userId, subject.agentId);
+    for (const session of Object.values(state.sessions))
+        values.push(session.sid);
+    for (const delegation of Object.values(state.delegations))
+        values.push(delegation.compact, delegation.key.handle);
+    for (const tx of Object.values(state.transactions)) {
+        values.push(includeOAuthState ? tx.state : undefined, tx.verifier, tx.callbackRef, tx.dpopKey?.handle);
+        if (tx.callbackRef)
+            try {
+                const claim = JSON.parse(tx.callbackRef);
+                if (typeof claim.claimSecret === 'string')
+                    values.push(claim.claimSecret);
+            }
+            catch { /* No cleartext fallback for an unknown callback reference. */ }
+    }
+    return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+export function sanitizePublicValue(value, secrets) { return redact(value, secrets); }
+/** Only business JSON crosses the tool boundary. Protocol headers and credential-shaped fields do not. */
+function redact(value, secrets, depth = 0) {
+    requirePap(depth <= 32, 'unsupported_profile');
+    const sensitive = (text) => secrets.some(secret => text.includes(secret)) || /(?:^|\s)(?:Bearer|DPoP)\s+\S+|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/.test(text);
+    if (typeof value === 'string' && sensitive(value))
+        return '[redacted]';
+    if (Array.isArray(value))
+        return value.map(item => redact(item, secrets, depth + 1));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [sensitive(key) ? '[redacted]' : key, privateFields.test(key) ? '[redacted]' : redact(item, secrets, depth + 1)]));
+    return value;
+}
+export function publicResponse(response, secrets = []) {
+    const type = response.headers['content-type']?.split(';')[0]?.trim().toLowerCase();
+    if (type !== 'application/json' && type !== 'application/problem+json')
+        return { status: response.status, bodyAvailable: false };
+    try {
+        return { status: response.status, body: redact(strictJson(response.body, 65536), secrets) };
+    }
+    catch {
+        return { status: response.status, bodyAvailable: false };
+    }
+}

package/lib/protocol-adapter.d.ts

@@ -0,0 +1,90 @@
+import type { PapIdentityHost, PapSigningLease } from './host.js';
+import type { Binding, Company, PublicJwk } from './types.js';
+/** Structural subset of C's real ./protocol-client API. No native or generic signer fallback. */
+export interface ProtocolKeyReference {
+    keyRef: object;
+    handle: string;
+    purpose: 'pap_session' | 'pap_dpop';
+    generation: number;
+    publicJwk: PublicJwk;
+    thumbprint: string;
+}
+export interface ProtocolSignerLease {
+    readonly targetRef: object;
+    getOAuthClientIdentity(): Promise<{
+        clientId: string;
+        keyId: string;
+        algorithm: 'ES256';
+        publicJwk: PublicJwk;
+        redirectUris?: string[];
+    }>;
+    assertActive(): Promise<void>;
+    signOAuthClientAssertion(targetRef: object): Promise<string>;
+    bindPapScope(input: {
+        userId: string;
+        accountSlot?: string;
+    }): object;
+    createDelegatedKey(scopeRef: object, operationId: string): Promise<ProtocolKeyReference>;
+    createDpopKey(scopeRef: object, operationId: string): Promise<ProtocolKeyReference>;
+    restorePapKey(scopeRef: object, input: {
+        handle: string;
+        generation: number;
+        purpose: 'pap_session' | 'pap_dpop';
+    }): Promise<ProtocolKeyReference>;
+    issuePapDelegation(scopeRef: object, input: {
+        keyRef: object;
+        ttlSeconds: number;
+    }): Promise<string>;
+    signPapSessionRequest(scopeRef: object, input: {
+        keyRef: object;
+        delegation: string;
+        clientId: string;
+        sid: string;
+        sub: string;
+        agentId?: string;
+        httpMethod: string;
+        httpUri: string;
+        accessToken?: string;
+    }): Promise<string>;
+    signDpopProof(scopeRef: object, input: {
+        keyRef: object;
+        httpMethod: string;
+        httpUri: string;
+        accessToken?: string;
+        nonce?: string;
+    }): Promise<string>;
+    retireTemporaryKey(scopeRef: object, keyRef: object): Promise<void>;
+    dispose(): void;
+}
+export interface ProtocolIdentityClient {
+    registerValidatedTarget(input: {
+        identityRef: Binding['identityRef'];
+        policyRef: string;
+        discovery: {
+            profile: 'pap_session' | 'pap_account';
+            issuer: string;
+            resource: string;
+            tokenEndpoint?: string;
+            revocationEndpoint?: string;
+            companyId: string;
+            metadataDigest: string;
+            expiresAt: number;
+            allowedEndpoints?: string[];
+            sources: {
+                resource: string;
+                authorizationServer: string;
+            };
+        };
+        requestedScopes: string[];
+    }): Promise<ProtocolSignerLease>;
+}
+/** Bind to C from the installed Host Context; persist only the native handle and public descriptor. */
+export declare class ProtocolIdentityHost implements PapIdentityHost {
+    private readonly client;
+    private readonly policyRef;
+    private readonly rawLeases;
+    private readonly leases;
+    constructor(client: ProtocolIdentityClient, policyRef: string);
+    dispose(): void;
+    acquire(binding: Binding, company: Company, purpose: 'pap_session' | 'pap_account', resource: string, destination?: string, requestedScopes?: readonly string[]): Promise<PapSigningLease>;
+}

package/lib/protocol-adapter.js

@@ -0,0 +1,75 @@
+import { requirePap } from './errors.js';
+import { htu } from './util.js';
+const serializable = (key) => ({ handle: key.handle, purpose: key.purpose, generation: key.generation, public_jwk: key.publicJwk, thumbprint: key.thumbprint });
+/** Bind to C from the installed Host Context; persist only the native handle and public descriptor. */
+export class ProtocolIdentityHost {
+    client;
+    policyRef;
+    rawLeases = new Set();
+    leases = new Map();
+    constructor(client, policyRef) {
+        this.client = client;
+        this.policyRef = policyRef;
+    }
+    dispose() { for (const lease of this.rawLeases)
+        lease.dispose(); this.rawLeases.clear(); this.leases.clear(); }
+    async acquire(binding, company, purpose, resource, destination, requestedScopes = []) {
+        const key = JSON.stringify([binding.identityRef, company.ref, company.generation, purpose, resource, destination, [...requestedScopes].sort()]);
+        const existing = this.leases.get(key);
+        if (existing) {
+            await existing.assertActive();
+            return existing;
+        }
+        const discoveryUrl = company.sources[0].url;
+        const raw = await this.client.registerValidatedTarget({ identityRef: binding.identityRef, policyRef: this.policyRef, discovery: {
+                profile: purpose, issuer: company.issuer ?? company.companyId, companyId: company.companyId, resource,
+                tokenEndpoint: company.metadata?.token_endpoint, revocationEndpoint: company.metadata?.revocation_endpoint,
+                metadataDigest: company.metadataDigest, expiresAt: company.expiresAt,
+                // Dynamic path parameters are authorized by registering the exact operation URL below.
+                allowedEndpoints: [...company.routes.filter(x => !x.template.includes('{')).map(x => htu(x.template)), ...(destination ? [htu(destination)] : [])],
+                sources: { resource: discoveryUrl, authorizationServer: company.sources.find(x => x.url.includes('/.well-known/oauth-authorization-server'))?.url ?? discoveryUrl },
+            }, requestedScopes: [...requestedScopes] });
+        this.rawLeases.add(raw);
+        const scopes = new Map();
+        const keys = new Map();
+        const scopeRef = (scope) => {
+            requirePap(scope.company_id === company.companyId && scope.owner === binding.ownerRef, 'permission_denied');
+            const cacheKey = JSON.stringify(scope);
+            let ref = scopes.get(cacheKey);
+            if (!ref) {
+                ref = raw.bindPapScope({ userId: scope.user_id, accountSlot: scope.account_slot });
+                scopes.set(cacheKey, ref);
+            }
+            return ref;
+        };
+        const restored = async (scope, key) => {
+            const cacheKey = JSON.stringify([scope, key.handle, key.generation]);
+            let ref = keys.get(cacheKey);
+            if (!ref) {
+                ref = await raw.restorePapKey(scopeRef(scope), { handle: key.handle, generation: key.generation, purpose: key.purpose });
+                keys.set(cacheKey, ref);
+            }
+            requirePap(ref.thumbprint === key.thumbprint && ref.purpose === key.purpose && ref.generation === key.generation, 'credential_unavailable');
+            return ref;
+        };
+        const create = async (scope, operationId, purpose) => {
+            const key = await (purpose === 'pap_session' ? raw.createDelegatedKey(scopeRef(scope), operationId) : raw.createDpopKey(scopeRef(scope), operationId));
+            keys.set(JSON.stringify([scope, key.handle, key.generation]), key);
+            return serializable(key);
+        };
+        const lease = {
+            targetRef: raw.targetRef,
+            getOAuthClientIdentity: async () => { const identity = await raw.getOAuthClientIdentity(); return { clientId: identity.clientId, alg: identity.algorithm, kid: identity.keyId, publicJwk: identity.publicJwk, redirectUris: identity.redirectUris }; },
+            assertActive: () => raw.assertActive(),
+            createDelegatedKey: (scope, operationId) => create(scope, operationId, 'pap_session'),
+            createDpopKey: (scope, operationId) => create(scope, operationId, 'pap_dpop'),
+            issuePapDelegation: async (key, scope, ttlSeconds) => raw.issuePapDelegation(scopeRef(scope), { keyRef: (await restored(scope, key)).keyRef, ttlSeconds }),
+            signPapSessionRequest: async (input) => { const { key, scope, ...request } = input; return raw.signPapSessionRequest(scopeRef(scope), { ...request, keyRef: (await restored(scope, key)).keyRef }); },
+            signDpopProof: async (input) => { const { key, scope, ...request } = input; return raw.signDpopProof(scopeRef(scope), { ...request, keyRef: (await restored(scope, key)).keyRef }); },
+            signOAuthClientAssertion: () => raw.signOAuthClientAssertion(raw.targetRef),
+            retireTemporaryKey: async (key, scope) => raw.retireTemporaryKey(scopeRef(scope), (await restored(scope, key)).keyRef),
+        };
+        this.leases.set(key, lease);
+        return lease;
+    }
+}

package/lib/remote.d.ts

@@ -0,0 +1,3 @@
+import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+declare const contribution: TypertRemoteContribution;
+export default contribution;

package/lib/remote.js

@@ -0,0 +1,17 @@
+/** User-only Typert contract. It is not included in model tools. */
+import { z } from 'zod';
+import { managementRequestSchema } from './product-api.js';
+const result = z.discriminatedUnion('ok', [
+    z.object({ ok: z.literal(true), value: z.json().nullable() }).strict(),
+    z.object({ ok: z.literal(false), error: z.object({ code: z.string(), retryAfterSeconds: z.union([z.number(), z.string()]).optional() }).strict() }).strict(),
+]);
+const methods = ['status', 'operations', 'manage'];
+const contribution = {
+    package: '@awiki/dsh-pap',
+    descriptors: methods.map(method => ({
+        id: `@awiki/dsh-pap#papManager/${method}`, service: 'papManager', namespace: 'papManager', method, invocation: { kind: 'direct' },
+        parameters: method === 'manage' ? [{ name: 'input', wire: 'input', source: 'json', codec: { mode: 'strict', typeSymbol: 'dsh-pap/manager#Request', create: () => managementRequestSchema } }] : [],
+        result: { mode: 'strict', typeSymbol: 'dsh-pap/manager#Result', create: () => result },
+    })),
+};
+export default contribution;

package/lib/store.d.ts

@@ -0,0 +1,14 @@
+import type { HostSecretStore } from './host.js';
+import type { PapState } from './types.js';
+/** Encrypted, cross-process serialized transactions. The master key stays in Host secret storage. */
+export declare class PapStore {
+    readonly root: string;
+    private readonly secrets;
+    private readonly namespace;
+    private readonly path;
+    constructor(root: string, secrets: HostSecretStore, namespace: string);
+    private key;
+    transaction<T>(fn: (state: PapState) => T | Promise<T>): Promise<T>;
+    read(): Promise<PapState>;
+    recover(): Promise<void>;
+}

package/lib/store.js

@@ -0,0 +1,128 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import lockfile from 'proper-lockfile';
+import { PapError, requirePap } from './errors.js';
+import { syncDirectory } from './file-secrets.js';
+import { ensureCredentialVault } from './credential-history.js';
+const empty = () => ({ schemaVersion: 1, generation: 0, companies: {}, subjects: {}, sessions: {}, delegations: {}, grants: {}, transactions: {}, nonces: {}, cooldowns: {}, retirements: {}, accountSlots: {}, delegationAttempts: {}, credentialVault: { version: 1, completeness: 'complete', entries: {}, blocked: false } });
+/** Encrypted, cross-process serialized transactions. The master key stays in Host secret storage. */
+export class PapStore {
+    root;
+    secrets;
+    namespace;
+    path;
+    constructor(root, secrets, namespace) {
+        this.root = root;
+        this.secrets = secrets;
+        this.namespace = namespace;
+        this.path = join(root, 'pap-state.enc');
+    }
+    async key(existing) {
+        try {
+            const material = existing ? await this.secrets.getEncryptionKey(`pap/${this.namespace}`) : await this.secrets.getOrCreateEncryptionKey(`pap/${this.namespace}`);
+            requirePap(material, 'credential_unavailable');
+            const key = Buffer.from(material);
+            requirePap(key.length === 32, 'credential_unavailable');
+            return key;
+        }
+        catch {
+            throw new PapError('credential_unavailable');
+        }
+    }
+    async transaction(fn) {
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        const release = await lockfile.lock(this.root, { realpath: true, stale: 30000, update: 5000, retries: { retries: 80, minTimeout: 10, maxTimeout: 100 } });
+        let key;
+        try {
+            let bytes;
+            try {
+                bytes = await readFile(this.path);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw new PapError('state_corrupt');
+            }
+            key = await this.key(bytes !== undefined);
+            let state;
+            try {
+                if (!bytes)
+                    state = empty();
+                else {
+                    requirePap(bytes.length > 33 && bytes.subarray(0, 5).toString() === 'PAP01', 'state_corrupt');
+                    const decipher = createDecipheriv('aes-256-gcm', key, bytes.subarray(5, 17));
+                    decipher.setAAD(Buffer.from(`pap-state/1/${this.namespace}`));
+                    decipher.setAuthTag(bytes.subarray(17, 33));
+                    state = JSON.parse(Buffer.concat([decipher.update(bytes.subarray(33)), decipher.final()]).toString());
+                    requirePap(state.schemaVersion === 1 && Number.isSafeInteger(state.generation) && state.companies && state.subjects && state.sessions && state.delegations && state.grants && state.transactions && state.nonces && state.retirements, 'state_corrupt');
+                    // Additive migration of the first private candidate; closed slots stay closed.
+                    state.accountSlots ??= {};
+                    state.delegationAttempts ??= {};
+                    state.cooldowns ??= {};
+                    for (const grant of Object.values(state.grants)) {
+                        grant.accountEpoch ??= 1;
+                        const slot = state.accountSlots[grant.accountSlot] ??= { subjectRef: grant.subjectRef, epoch: grant.accountEpoch, signedOut: false };
+                        if (['signed_out', 'revocation_pending'].includes(grant.status))
+                            slot.signedOut = true;
+                    }
+                    for (const tx of Object.values(state.transactions)) {
+                        tx.accountEpoch ??= 1;
+                        const slot = state.accountSlots[tx.accountSlot] ??= { subjectRef: tx.subjectRef, epoch: tx.accountEpoch, signedOut: false };
+                        if (slot.signedOut) {
+                            tx.status = 'cancelled';
+                            tx.verifier = '';
+                            delete tx.callbackRef;
+                        }
+                    }
+                    ensureCredentialVault(state);
+                }
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    state = empty();
+                else
+                    throw new PapError('state_corrupt');
+            }
+            const result = await fn(state);
+            state.generation++;
+            const iv = randomBytes(12);
+            const cipher = createCipheriv('aes-256-gcm', key, iv);
+            cipher.setAAD(Buffer.from(`pap-state/1/${this.namespace}`));
+            const encrypted = Buffer.concat([cipher.update(JSON.stringify(state)), cipher.final()]);
+            const temp = join(this.root, `.pap-${randomBytes(12).toString('hex')}.tmp`);
+            try {
+                const file = await open(temp, 'wx', 0o600);
+                try {
+                    await file.writeFile(Buffer.concat([Buffer.from('PAP01'), iv, cipher.getAuthTag(), encrypted]));
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await rename(temp, this.path);
+                await syncDirectory(this.root);
+            }
+            finally {
+                await rm(temp, { force: true });
+            }
+            return structuredClone(result);
+        }
+        finally {
+            key?.fill(0);
+            await release();
+        }
+    }
+    async read() { return this.transaction(state => state); }
+    async recover() {
+        await this.transaction(state => {
+            for (const grant of Object.values(state.grants))
+                if (grant.status === 'refreshing') {
+                    grant.status = 'uncertain';
+                    grant.generation++;
+                }
+            for (const tx of Object.values(state.transactions))
+                if (tx.status === 'exchanging')
+                    tx.status = 'failed';
+        });
+    }
+}

package/lib/strict-json.d.ts

@@ -0,0 +1,2 @@
+/** Bounded RFC 8259 parser: fatal UTF-8 and duplicate object member rejection. */
+export declare function strictJson(bytes: Uint8Array, maxBytes?: number): unknown;

package/lib/strict-json.js

@@ -0,0 +1,111 @@
+/** Bounded RFC 8259 parser: fatal UTF-8 and duplicate object member rejection. */
+export function strictJson(bytes, maxBytes = 1024 * 1024) {
+    if (bytes.length > maxBytes)
+        throw new Error('Invalid JSON');
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    let at = 0;
+    let nodes = 0;
+    const fail = () => { throw new Error('Invalid JSON'); };
+    const ws = () => { while (at < text.length && /[\x20\t\r\n]/.test(text[at]))
+        at++; };
+    const string = () => {
+        if (text[at] !== '"')
+            return fail();
+        const start = at++;
+        for (;;) {
+            if (at >= text.length)
+                return fail();
+            const char = text.charCodeAt(at++);
+            if (char === 0x22) {
+                // JSON.parse validates string escapes and control characters, after token boundaries are fixed.
+                return JSON.parse(text.slice(start, at));
+            }
+            if (char < 0x20)
+                return fail();
+            if (char === 0x5c) {
+                if (at >= text.length)
+                    return fail();
+                const escape = text[at++];
+                if (escape === 'u') {
+                    if (!/^[a-fA-F0-9]{4}$/.test(text.slice(at, at + 4)))
+                        return fail();
+                    at += 4;
+                }
+                else if (!'"\\/bfnrt'.includes(escape))
+                    return fail();
+            }
+        }
+    };
+    const value = (depth) => {
+        if (++nodes > 65536 || depth > 32)
+            return fail();
+        ws();
+        const char = text[at];
+        if (char === '"')
+            return string();
+        if (char === '{') {
+            at++;
+            ws();
+            const result = Object.create(null);
+            const seen = new Set();
+            if (text[at] === '}') {
+                at++;
+                return result;
+            }
+            for (;;) {
+                ws();
+                const key = string();
+                if (seen.has(key))
+                    return fail();
+                seen.add(key);
+                ws();
+                if (text[at++] !== ':')
+                    return fail();
+                result[key] = value(depth + 1);
+                ws();
+                const end = text[at++];
+                if (end === '}')
+                    return result;
+                if (end !== ',')
+                    return fail();
+            }
+        }
+        if (char === '[') {
+            at++;
+            ws();
+            const result = [];
+            if (text[at] === ']') {
+                at++;
+                return result;
+            }
+            for (;;) {
+                result.push(value(depth + 1));
+                ws();
+                const end = text[at++];
+                if (end === ']')
+                    return result;
+                if (end !== ',')
+                    return fail();
+            }
+        }
+        for (const [literal, parsed] of [['true', true], ['false', false], ['null', null]]) {
+            if (text.startsWith(literal, at)) {
+                at += literal.length;
+                return parsed;
+            }
+        }
+        const number = text.slice(at).match(/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/);
+        if (!number)
+            return fail();
+        at += number[0].length;
+        const parsed = Number(number[0]);
+        if (!Number.isFinite(parsed))
+            return fail();
+        return parsed;
+    };
+    const parsed = value(0);
+    ws();
+    if (at !== text.length)
+        return fail();
+    return parsed;
+}

package/lib/tools.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "@awiki/dsh-pap/tools";
+export declare const inject: string[];
+/** No tools for identity selection, discovery, browser sign-in, callback collection or sign-out. */
+export declare function apply(ctx: Context): void;

package/lib/tools.js

@@ -0,0 +1,29 @@
+import { PAP_TOOLS } from './product-api.js';
+import { requirePap } from './errors.js';
+export const name = PAP_TOOLS;
+export const inject = ['pap', 'tools'];
+const output = {
+    schema: { type: 'object', additionalProperties: true },
+    render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+};
+/** No tools for identity selection, discovery, browser sign-in, callback collection or sign-out. */
+export function apply(ctx) {
+    const facade = ctx.pap.acquireTools(ctx);
+    const registry = ctx.get('tools');
+    requirePap(typeof registry?.register === 'function', 'permission_denied');
+    const register = (tool) => { registry.register(tool); };
+    const empty = { type: 'object', properties: {}, additionalProperties: false };
+    const agent = (execution) => requirePap(execution.agent && !execution.signal?.aborted, 'permission_denied');
+    register({ name: 'pap_status', description: 'Read PAP connection and account status. Ask the user to configure PAP or sign in when required.', parameters: empty, output,
+        execute: async (_args, execution) => { agent(execution); return facade.status(); } });
+    register({ name: 'pap_operations', description: 'List Company operations explicitly enabled by the user. Use their opaque operationRef with pap_request.', parameters: empty, output,
+        execute: async (_args, execution) => { agent(execution); return facade.operations(); } });
+    register({ name: 'pap_request', description: 'Invoke one user-enabled Company operation. Supply its operationRef and only declared path/query parameters and optional JSON body. Account sign-in is a separate user action.',
+        parameters: { type: 'object', additionalProperties: false, required: ['operationRef'], properties: {
+                operationRef: { type: 'string' },
+                path: { type: 'object', additionalProperties: true },
+                query: { type: 'object', additionalProperties: true },
+                body: {},
+            } }, output,
+        execute: async (args, execution) => { agent(execution); return facade.request(args, execution.signal); } });
+}