zk-credits 0.2.4 → 0.2.7

package/dist/gateway-trial-status.js

@@ -0,0 +1,70 @@
+/**
+ * Freshness and readiness checks used by the separately registered adapter
+ * trial. Keep this gate fail-closed when a gateway omits a named check.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export const GATEWAY_READINESS_CHECK_NAMES = [
+    'launchControl',
+    'database',
+    'baseRoot',
+    'baseRpc',
+    'verifierAssets',
+    'provider',
+];
+const MAX_STATUS_AGE_MS = 120_000;
+const MAX_FUTURE_SKEW_MS = 30_000;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isGatewayStatusFresh(value, now = Date.now()) {
+    if (typeof value !== 'string')
+        return false;
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return false;
+    const age = now - timestamp;
+    return age <= MAX_STATUS_AGE_MS && age >= -MAX_FUTURE_SKEW_MS;
+}
+export function evaluateGatewayReadiness(status, body, now = Date.now()) {
+    const report = isRecord(body) ? body : undefined;
+    const checks = Array.isArray(report?.checks) ? report.checks : undefined;
+    const byName = new Map();
+    const failedChecks = [];
+    let checksValid = Boolean(checks);
+    for (const check of checks ?? []) {
+        if (!isRecord(check) || typeof check.name !== 'string' || byName.has(check.name)) {
+            checksValid = false;
+            continue;
+        }
+        byName.set(check.name, check);
+        if (!GATEWAY_READINESS_CHECK_NAMES.includes(check.name))
+            checksValid = false;
+    }
+    checksValid = checksValid
+        && byName.size === GATEWAY_READINESS_CHECK_NAMES.length
+        && GATEWAY_READINESS_CHECK_NAMES.every((name) => byName.has(name) && byName.get(name)?.ok === true);
+    for (const name of GATEWAY_READINESS_CHECK_NAMES) {
+        if (byName.get(name)?.ok !== true)
+            failedChecks.push(name);
+    }
+    if (!checksValid && failedChecks.length === 0)
+        failedChecks.push('checks');
+    if (report?.ready !== true)
+        failedChecks.push('ready');
+    if (report?.launchControl !== 'enabled' && !failedChecks.includes('launchControl')) {
+        failedChecks.push('launchControl');
+    }
+    const timestampFresh = isGatewayStatusFresh(report?.generatedAt, now);
+    if (!timestampFresh)
+        failedChecks.push('generatedAt');
+    return {
+        passed: status === 200
+            && report?.ready === true
+            && report.launchControl === 'enabled'
+            && checksValid
+            && timestampFresh,
+        failedChecks,
+        timestampFresh,
+    };
+}

package/dist/local-x402-agent.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Local runtime for an operator's own x402 agent.
+ *
+ * This loads the same encrypted credential, pinned proving artifacts, public
+ * Base witness source, proof coordinator, and local slot ledger used by the
+ * loopback sidecar. The returned client binds each actual HTTP method, URL,
+ * and body into its proof. A loopback-only authenticated metrics endpoint
+ * reports aggregate counters for the operator's evidence bundle.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { createBasePrepaidClient } from './base-sidecar.js';
+export interface LocalX402AgentOptions {
+    /** Decrypts the browser export in local memory. Never pass this through an environment variable. */
+    credentialPassword: string;
+    environment?: NodeJS.ProcessEnv;
+    homeDirectory?: string;
+    stateDirectory?: string;
+    port?: number;
+}
+export interface LocalX402Agent {
+    /** Request-aware client backed by local proving and the x402 adapter. */
+    client: ReturnType<typeof createBasePrepaidClient>['client'];
+    /** Local authenticated endpoint used only for aggregate activation metrics. */
+    metricsUrl: string;
+    close(): Promise<void>;
+}
+/**
+ * Starts the local proof engine for a participant's own agent integration.
+ * Call `client.fetch(url, init)` for each real request, then close the runtime
+ * when the agent exits. The local server serves only loopback and requires its
+ * owner-only token for the aggregate `/metrics` response.
+ */
+export declare function createLocalX402Agent(options: LocalX402AgentOptions): Promise<LocalX402Agent>;

package/dist/local-x402-agent.js

@@ -0,0 +1,130 @@
+/**
+ * Local runtime for an operator's own x402 agent.
+ *
+ * This loads the same encrypted credential, pinned proving artifacts, public
+ * Base witness source, proof coordinator, and local slot ledger used by the
+ * loopback sidecar. The returned client binds each actual HTTP method, URL,
+ * and body into its proof. A loopback-only authenticated metrics endpoint
+ * reports aggregate counters for the operator's evidence bundle.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { decryptAnyCredentialExport } from '@zk-credits/shared/base';
+import { BASE_SEPOLIA_NETWORK, createZkPrepaidLifecycleMetrics, } from '@zk-credits/x402-zk-prepaid';
+import { createBasePrepaidClient, createFileWitnessProvider, validateBaseCreditWitness, } from './base-sidecar.js';
+import { createBaseEventWitnessProvider } from './base-event-sync.js';
+import { createPinnedBaseProofGenerator } from './proof-coordinator.js';
+import { createBaseProofMetrics } from './proof-metrics.js';
+import { BaseSlotLedger } from './slot-ledger.js';
+import { readSetupConfig, applySetupConfig } from './setup-config.js';
+import { createSidecarServer } from './sidecar.js';
+import { createLoopbackToken, sidecarStatePaths } from './sidecar-config.js';
+import { writeLoopbackToken } from './sidecar-state.js';
+const DEFAULT_GATEWAY_URL = 'https://zk-credits-gateway.onrender.com';
+const DEFAULT_PORT = 3210;
+async function witnessProviderForSource(source, cachePath) {
+    if (source.kind === 'file') {
+        const value = JSON.parse(await readFile(source.path, 'utf8'));
+        return createFileWitnessProvider(value);
+    }
+    return createBaseEventWitnessProvider({
+        rpcUrl: source.rpcUrl,
+        contractAddress: source.contractAddress,
+        deploymentBlock: source.deploymentBlock === undefined ? undefined : BigInt(source.deploymentBlock),
+        confirmations: source.confirmations === undefined ? undefined : BigInt(source.confirmations),
+        cachePath,
+    });
+}
+async function readCredential(path, password) {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    if (parsed.format !== 'zk-credits-credential' || (parsed.version !== 1 && parsed.version !== 2)) {
+        throw new Error('Credential file is not a supported zk-credits export');
+    }
+    return decryptAnyCredentialExport(parsed, password);
+}
+/**
+ * Starts the local proof engine for a participant's own agent integration.
+ * Call `client.fetch(url, init)` for each real request, then close the runtime
+ * when the agent exits. The local server serves only loopback and requires its
+ * owner-only token for the aggregate `/metrics` response.
+ */
+export async function createLocalX402Agent(options) {
+    const environment = options.environment ?? process.env;
+    const homeDirectory = options.homeDirectory ?? homedir();
+    const stateDirectory = options.stateDirectory ?? environment.ZK_CREDITS_HOME ?? join(homeDirectory, '.zk-credits');
+    const credentialPath = environment.ZK_CREDITS_CREDENTIAL_PATH;
+    if (!credentialPath)
+        throw new Error('Set ZK_CREDITS_CREDENTIAL_PATH to the encrypted browser export');
+    const savedConfig = await readSetupConfig(join(stateDirectory, 'config.json'));
+    if (savedConfig)
+        applySetupConfig(environment, savedConfig);
+    const credential = await readCredential(credentialPath, options.credentialPassword);
+    const artifactDirectory = environment.ZK_CREDITS_ARTIFACT_DIR;
+    if (!artifactDirectory)
+        throw new Error('Run `zk-credits setup codex` first to install and verify the pinned proving bundle');
+    const witnessPath = environment.ZK_CREDITS_WITNESS_PATH;
+    const rpcUrl = environment.BASE_RPC_URL;
+    const contractAddress = environment.BASE_PRIVATE_CREDIT_BOND_ADDRESS;
+    const witnessProvider = witnessPath
+        ? await witnessProviderForSource({ kind: 'file', path: witnessPath }, join(stateDirectory, 'base-event-sync.json'))
+        : rpcUrl && contractAddress
+            ? await witnessProviderForSource({
+                kind: 'base-events',
+                rpcUrl,
+                contractAddress,
+                ...(environment.BASE_DEPLOYMENT_BLOCK && /^\d+$/u.test(environment.BASE_DEPLOYMENT_BLOCK)
+                    ? { deploymentBlock: environment.BASE_DEPLOYMENT_BLOCK }
+                    : {}),
+                ...(environment.BASE_CONFIRMATIONS && /^\d+$/u.test(environment.BASE_CONFIRMATIONS)
+                    ? { confirmations: environment.BASE_CONFIRMATIONS }
+                    : {}),
+            }, join(stateDirectory, 'base-event-sync.json'))
+            : (() => { throw new Error('Local setup is missing its Base witness source; rerun `zk-credits setup codex`'); })();
+    const proofMetrics = createBaseProofMetrics();
+    const exchangeMetrics = createZkPrepaidLifecycleMetrics();
+    const slotLedger = await BaseSlotLedger.open({ path: join(stateDirectory, 'base-slots.json') });
+    const prove = await createPinnedBaseProofGenerator({ artifactDirectory, metrics: proofMetrics });
+    validateBaseCreditWitness(await witnessProvider.witnessForCredential(credential));
+    if (credential.deploymentDomain !== '84532' || credential.expiry <= Math.floor(Date.now() / 1000)) {
+        throw new Error(`Credential is not active for ${BASE_SEPOLIA_NETWORK}`);
+    }
+    const prepaid = createBasePrepaidClient({
+        credential,
+        witnessProvider,
+        prove,
+        slotLedger,
+        lifecycle: exchangeMetrics.observe,
+    });
+    const localToken = createLoopbackToken();
+    const paths = sidecarStatePaths(stateDirectory);
+    const metrics = () => ({
+        ...proofMetrics.snapshot(),
+        exchange: exchangeMetrics.snapshot(),
+    });
+    const server = createSidecarServer({
+        localToken,
+        gatewayBaseUrl: environment.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL,
+        prepaidClient: prepaid.client,
+        metrics,
+    });
+    let baseUrl;
+    try {
+        const port = options.port ?? Number(environment.ZK_CREDITS_SIDECAR_PORT || DEFAULT_PORT);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error('Local metrics port is invalid');
+        baseUrl = await server.listen(port);
+        await writeLoopbackToken(paths.tokenPath, localToken);
+    }
+    catch (error) {
+        await server.close();
+        throw error;
+    }
+    return {
+        client: prepaid.client,
+        metricsUrl: `${baseUrl}/metrics`,
+        close: async () => server.close(),
+    };
+}

package/dist/responses-bridge.js

@@ -91,6 +91,21 @@ function responseTools(value) {
             tools.push({ type: 'function', function: definition });
             continue;
         }
+        // Codex sends its local freeform apply_patch tool with every Responses
+        // request. Chat Completions cannot execute that tool, so validate this
+        // known declaration and omit it from the provider request.
+        if (tool.type === 'custom') {
+            if (!hasOnlyKeys(tool, ['type', 'name', 'description', 'format'])
+                || tool.name !== 'apply_patch'
+                || (tool.description !== undefined && typeof tool.description !== 'string')
+                || !isRecord(tool.format)
+                || !hasOnlyKeys(tool.format, ['type', 'syntax', 'definition'])
+                || tool.format.type !== 'grammar'
+                || tool.format.syntax !== 'lark'
+                || typeof tool.format.definition !== 'string')
+                return undefined;
+            continue;
+        }
         // Codex includes these tool declarations in each Responses request. The
         // fixed service class has no web-search executor and accepts only direct
         // function tools, so validate their known shape and drop them.
@@ -188,8 +203,9 @@ export function translateResponsesRequest(body) {
         }
         chatRequest.max_completion_tokens = body.max_output_tokens;
     }
-    if (body.parallel_tool_calls !== undefined)
-        chatRequest.parallel_tool_calls = body.parallel_tool_calls;
+    // Codex sends this optional hint even when its model catalog disables the
+    // capability. The pinned provider does not advertise the parameter under
+    // the gateway's require_parameters route, so forwarding it prevents dispatch.
     for (const key of ['temperature', 'top_p', 'stop', 'seed', 'presence_penalty', 'frequency_penalty', 'logit_bias']) {
         if (body[key] !== undefined)
             chatRequest[key] = body[key];
@@ -250,8 +266,9 @@ export function responsesEventStream(chatValue, model) {
     if (text !== null && text !== undefined && typeof text !== 'string') {
         throw new Error('Gateway returned an unsupported chat content value');
     }
-    if (refusal !== undefined && typeof refusal !== 'string')
+    if (refusal !== undefined && refusal !== null && typeof refusal !== 'string') {
         throw new Error('Gateway returned an invalid refusal value');
+    }
     if (typeof text === 'string' || typeof refusal === 'string') {
         const itemId = `msg_${randomUUID().replaceAll('-', '')}`;
         const isRefusal = typeof refusal === 'string';

package/dist/sidecar.d.ts

@@ -15,6 +15,8 @@ export interface SidecarOptions {
     localToken: string;
     gatewayBaseUrl: string;
     prepaidClient: PrepaidTransport;
+    /** Limits this process to one authenticated, valid spend request for the internal trial. */
+    internalTrialOneProof?: boolean;
     /** Aggregate-only proof and exchange metrics served to the authenticated local operator. */
     metrics?: () => SidecarMetricsSnapshot;
 }

package/dist/sidecar.js

@@ -112,6 +112,7 @@ async function relayResponsesGatewayResponse(res, upstream, responseModel) {
 export function createSidecarServer(options) {
     const gatewayBaseUrl = options.gatewayBaseUrl.replace(/\/$/u, '');
     let server = null;
+    let internalTrialRequestClaimed = false;
     const inFlight = new Set();
     const handler = async (req, res) => {
         const pathname = new URL(req.url || '/', 'http://127.0.0.1').pathname;
@@ -173,6 +174,13 @@ export function createSidecarServer(options) {
                     return;
                 }
             }
+            if (options.internalTrialOneProof) {
+                if (internalTrialRequestClaimed) {
+                    sendJson(res, 409, { error: 'internal_trial_limit_reached' });
+                    return;
+                }
+                internalTrialRequestClaimed = true;
+            }
             const upstream = await options.prepaidClient.fetch(`${gatewayBaseUrl}/v1/chat/completions`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },