zk-credits 0.1.0

package/dist/local-prover.js

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { generateRlnProofSelfVerified, requestDigestToField, skToField, } from '@zk-credits/shared';
+import { verifyArtifactManifest } from './artifact-manifest.js';
+/**
+ * Builds the sidecar's local prover after checking every installed circuit
+ * byte against its release manifest. No proving asset is fetched at runtime.
+ */
+export async function createLocalProofGenerator(options) {
+    const artifactDirectory = options.artifactDirectory ?? resolve(import.meta.dirname, '..', 'circuits');
+    await verifyArtifactManifest(artifactDirectory);
+    const verificationKey = JSON.parse(await readFile(resolve(artifactDirectory, 'verification_key_rln.json'), 'utf8'));
+    const prove = options.prove ?? generateRlnProofSelfVerified;
+    return async ({ ticketIndex, request }) => {
+        const [requestDigest, witness] = await Promise.all([
+            requestDigestToField(request),
+            options.membershipClient.witnessForSecret(options.secretK),
+        ]);
+        const result = await prove({
+            secret_k: skToField(options.secretK),
+            ticket_index: ticketIndex.toString(),
+            request_digest: requestDigest.field,
+            merkle_path_elements: witness.merklePathElements,
+            merkle_path_indices: witness.merklePathIndices,
+        }, {
+            rlnWasm: resolve(artifactDirectory, 'rln_nullifier.wasm'),
+            rlnZkey: resolve(artifactDirectory, 'rln_nullifier_final.zkey'),
+            rlnVk: verificationKey,
+        });
+        return { proof: result.proof, pubSignals: result.publicSignals };
+    };
+}

package/dist/membership-client.d.ts

@@ -0,0 +1,14 @@
+import { type MembershipWitness } from '@zk-credits/shared';
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Reads only public gateway state. The user's commitment is located locally
+ * in the complete snapshot and is never sent in a path or query parameter.
+ */
+export declare class MembershipClient {
+    private readonly fetcher;
+    private readonly baseUrl;
+    constructor(gatewayBaseUrl: string, fetcher?: FetchLike);
+    witnessForSecret(secretK: Uint8Array): Promise<MembershipWitness>;
+    private getCurrentChainRoot;
+    private getSnapshot;
+}

package/dist/membership-client.js

@@ -0,0 +1,66 @@
+import { deriveMembershipWitness, mimcHash, skToField, } from '@zk-credits/shared';
+const MAX_SNAPSHOT_AGE_MS = 60_000;
+function parseSnapshot(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('Membership snapshot is malformed');
+    const snapshot = value;
+    if (typeof snapshot.root !== 'string'
+        || typeof snapshot.depth !== 'number'
+        || !Array.isArray(snapshot.leaves)
+        || !snapshot.leaves.every((leaf) => typeof leaf === 'string')
+        || !Array.isArray(snapshot.layers)
+        || !snapshot.layers.every((layer) => Array.isArray(layer) && layer.every((node) => typeof node === 'string'))
+        || typeof snapshot.generatedAt !== 'string') {
+        throw new Error('Membership snapshot is malformed');
+    }
+    const generatedAt = Date.parse(snapshot.generatedAt);
+    if (!Number.isFinite(generatedAt) || Date.now() - generatedAt > MAX_SNAPSHOT_AGE_MS || generatedAt - Date.now() > 5_000) {
+        throw new Error('Membership snapshot is stale');
+    }
+    return {
+        root: snapshot.root,
+        depth: snapshot.depth,
+        leaves: snapshot.leaves,
+        layers: snapshot.layers,
+        generatedAt: snapshot.generatedAt,
+    };
+}
+/**
+ * Reads only public gateway state. The user's commitment is located locally
+ * in the complete snapshot and is never sent in a path or query parameter.
+ */
+export class MembershipClient {
+    fetcher;
+    baseUrl;
+    constructor(gatewayBaseUrl, fetcher = fetch) {
+        this.fetcher = fetcher;
+        this.baseUrl = gatewayBaseUrl.replace(/\/$/, '');
+    }
+    async witnessForSecret(secretK) {
+        const [chainRoot, snapshot] = await Promise.all([
+            this.getCurrentChainRoot(),
+            this.getSnapshot(),
+        ]);
+        if (snapshot.root !== chainRoot) {
+            throw new Error('Membership snapshot does not match the current chain root');
+        }
+        const commitment = await mimcHash([BigInt(skToField(secretK))]);
+        return deriveMembershipWitness(commitment, snapshot);
+    }
+    async getCurrentChainRoot() {
+        const response = await this.fetcher(`${this.baseUrl}/v1/contract-status`, { cache: 'no-store' });
+        if (!response.ok)
+            throw new Error('Current chain root could not be loaded');
+        const payload = await response.json();
+        if (!payload || typeof payload !== 'object' || typeof payload.currentRoot !== 'string') {
+            throw new Error('Current chain root is unavailable');
+        }
+        return payload.currentRoot;
+    }
+    async getSnapshot() {
+        const response = await this.fetcher(`${this.baseUrl}/v1/membership-tree`, { cache: 'no-store' });
+        if (!response.ok)
+            throw new Error('Membership snapshot could not be loaded');
+        return parseSnapshot(await response.json());
+    }
+}

package/dist/node-sidecar-lifecycle.d.ts

@@ -0,0 +1,21 @@
+import type { SidecarLifecycleDependencies } from './sidecar-lifecycle.js';
+export interface DetachedSidecarProcess {
+    executable: string;
+    args: readonly string[];
+    env: NodeJS.ProcessEnv;
+    logPath: string;
+}
+export interface NodeSidecarLifecycleOptions {
+    loopbackBaseUrl: string;
+    stateDirectory: string;
+    tokenPath: string;
+    logPath: string;
+    cliEntryPath: string;
+}
+export interface NodeSidecarLifecycleRuntime {
+    fetchHealth(url: string): Promise<Response>;
+    startDetachedProcess(specification: DetachedSidecarProcess): Promise<void>;
+    wait(milliseconds: number): Promise<void>;
+}
+/** Connects lifecycle orchestration to Node fetch, process, and file APIs. */
+export declare function createNodeSidecarLifecycle(options: NodeSidecarLifecycleOptions, runtime?: NodeSidecarLifecycleRuntime): SidecarLifecycleDependencies;

package/dist/node-sidecar-lifecycle.js

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+import { chmod, mkdir, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { readLoopbackToken } from './sidecar-state.js';
+async function startDetachedProcess(specification) {
+    await mkdir(dirname(specification.logPath), { recursive: true, mode: 0o700 });
+    const log = await open(specification.logPath, 'a', 0o600);
+    await chmod(specification.logPath, 0o600);
+    try {
+        const child = spawn(specification.executable, specification.args, {
+            detached: true,
+            env: specification.env,
+            stdio: ['ignore', log.fd, log.fd],
+        });
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', reject);
+        });
+        child.unref();
+    }
+    finally {
+        await log.close();
+    }
+}
+const defaultRuntime = {
+    fetchHealth: async (url) => fetch(url, { signal: AbortSignal.timeout(500) }),
+    startDetachedProcess,
+    wait: async (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+};
+/** Connects lifecycle orchestration to Node fetch, process, and file APIs. */
+export function createNodeSidecarLifecycle(options, runtime = defaultRuntime) {
+    const url = new URL(options.loopbackBaseUrl);
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port) {
+        throw new Error('Sidecar lifecycle requires a 127.0.0.1 HTTP URL with an explicit port');
+    }
+    return {
+        logPath: options.logPath,
+        async isHealthy() {
+            try {
+                const response = await runtime.fetchHealth(`${url.origin}/health`);
+                if (!response.ok)
+                    return false;
+                const body = await response.json();
+                return body.service === 'zk-credits-sidecar' && body.status === 'ok';
+            }
+            catch {
+                return false;
+            }
+        },
+        async startDetached() {
+            await runtime.startDetachedProcess({
+                executable: process.execPath,
+                args: [options.cliEntryPath, 'serve', '--port', url.port],
+                env: {
+                    ...process.env,
+                    ZK_CREDITS_HOME: options.stateDirectory,
+                    ZK_CREDITS_SIDECAR_PORT: url.port,
+                },
+                logPath: options.logPath,
+            });
+        },
+        readToken: () => readLoopbackToken(options.tokenPath),
+        wait: runtime.wait,
+    };
+}

package/dist/server-startup.d.ts

@@ -0,0 +1,6 @@
+export interface SidecarServerActivation {
+    listen(): Promise<string>;
+    publishToken(): Promise<void>;
+}
+/** Makes the bearer discoverable only after this process owns the port. */
+export declare function activateSidecarServer(activation: SidecarServerActivation): Promise<string>;

package/dist/server-startup.js

@@ -0,0 +1,6 @@
+/** Makes the bearer discoverable only after this process owns the port. */
+export async function activateSidecarServer(activation) {
+    const address = await activation.listen();
+    await activation.publishToken();
+    return address;
+}

package/dist/sidecar-config.d.ts

@@ -0,0 +1,9 @@
+export interface SidecarStatePaths {
+    ledgerPath: string;
+    tokenPath: string;
+    logPath: string;
+}
+export declare function createLoopbackToken(): string;
+export declare function sidecarStatePaths(stateDirectory: string): SidecarStatePaths;
+/** Shell-safe environment lines for clients with OpenAI-compatible settings. */
+export declare function formatOpenAiEnvironment(loopbackBaseUrl: string, localToken: string): string;

package/dist/sidecar-config.js

@@ -0,0 +1,23 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+export function createLoopbackToken() {
+    return randomBytes(32).toString('base64url');
+}
+export function sidecarStatePaths(stateDirectory) {
+    return {
+        ledgerPath: join(stateDirectory, 'tickets.json'),
+        tokenPath: join(stateDirectory, 'loopback-token'),
+        logPath: join(stateDirectory, 'sidecar.log'),
+    };
+}
+/** Shell-safe environment lines for clients with OpenAI-compatible settings. */
+export function formatOpenAiEnvironment(loopbackBaseUrl, localToken) {
+    const url = new URL(loopbackBaseUrl);
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !/^[A-Za-z0-9_-]+$/.test(localToken)) {
+        throw new Error('Sidecar environment must use a valid 127.0.0.1 URL and local token');
+    }
+    return [
+        `export OPENAI_BASE_URL=${url.origin}/v1`,
+        `export OPENAI_API_KEY=${localToken}`,
+    ].join('\n');
+}

package/dist/sidecar-lifecycle.d.ts

@@ -0,0 +1,13 @@
+export interface SidecarLifecycleDependencies {
+    isHealthy(): Promise<boolean>;
+    startDetached(): Promise<void>;
+    readToken(): Promise<string>;
+    wait(milliseconds: number): Promise<void>;
+    logPath: string;
+}
+export interface SidecarReadinessOptions {
+    attempts?: number;
+    intervalMs?: number;
+}
+/** Ensures one loopback sidecar is ready before exposing its local bearer. */
+export declare function ensureSidecarReady(dependencies: SidecarLifecycleDependencies, options?: SidecarReadinessOptions): Promise<string>;

package/dist/sidecar-lifecycle.js

@@ -0,0 +1,14 @@
+/** Ensures one loopback sidecar is ready before exposing its local bearer. */
+export async function ensureSidecarReady(dependencies, options = {}) {
+    if (await dependencies.isHealthy())
+        return dependencies.readToken();
+    await dependencies.startDetached();
+    const attempts = options.attempts ?? 50;
+    const intervalMs = options.intervalMs ?? 100;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        await dependencies.wait(intervalMs);
+        if (await dependencies.isHealthy())
+            return dependencies.readToken();
+    }
+    throw new Error(`ZK Credits sidecar did not become ready; inspect ${dependencies.logPath}`);
+}

package/dist/sidecar-state.d.ts

@@ -0,0 +1,2 @@
+export declare function writeLoopbackToken(tokenPath: string, token: string): Promise<void>;
+export declare function readLoopbackToken(tokenPath: string): Promise<string>;

package/dist/sidecar-state.js

@@ -0,0 +1,18 @@
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export async function writeLoopbackToken(tokenPath, token) {
+    if (!token)
+        throw new Error('Loopback token is required');
+    await mkdir(dirname(tokenPath), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${tokenPath}.tmp`;
+    await writeFile(temporaryPath, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+    await chmod(temporaryPath, 0o600);
+    await rename(temporaryPath, tokenPath);
+    await chmod(tokenPath, 0o600);
+}
+export async function readLoopbackToken(tokenPath) {
+    const token = (await readFile(tokenPath, 'utf8')).trim();
+    if (!token)
+        throw new Error('No active ZK Credits sidecar token; start zk-credits serve first');
+    return token;
+}

package/dist/sidecar.d.ts

@@ -0,0 +1,27 @@
+import { TicketLedger } from './ticket-ledger.js';
+export interface ProofGeneratorInput {
+    ticketIndex: number;
+    request: unknown;
+}
+export type ProofGenerator = (input: ProofGeneratorInput) => Promise<{
+    proof: object;
+    pubSignals: string[];
+}>;
+export type GatewayFetch = (input: string, init: RequestInit) => Promise<Response>;
+export interface SidecarOptions {
+    localToken: string;
+    gatewayBaseUrl: string;
+    compatibilityKey: string;
+    ledger: TicketLedger;
+    proofGenerator: ProofGenerator;
+    gatewayFetch?: GatewayFetch;
+}
+export interface RunningSidecar {
+    listen(port?: number): Promise<string>;
+    close(): Promise<void>;
+}
+/**
+ * Creates a loopback-only OpenAI-compatible proxy. The local bearer never
+ * reaches Render; only the shared compatibility bearer and a fresh proof do.
+ */
+export declare function createSidecarServer(options: SidecarOptions): RunningSidecar;

package/dist/sidecar.js

@@ -0,0 +1,153 @@
+import { createServer } from 'node:http';
+import { codexModelsResponse } from './codex-profile.js';
+const MAX_REQUEST_BYTES = 2_000_000;
+function isLoopbackAddress(address) {
+    return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += bytes.length;
+        if (total > MAX_REQUEST_BYTES)
+            throw new Error('OpenAI request exceeds the loopback size limit');
+        chunks.push(bytes);
+    }
+    const raw = Buffer.concat(chunks).toString('utf8');
+    if (!raw)
+        throw new Error('OpenAI request body is required');
+    try {
+        return { raw, parsed: JSON.parse(raw) };
+    }
+    catch {
+        throw new Error('OpenAI request body must be valid JSON');
+    }
+}
+async function relayGatewayResponse(res, upstream) {
+    const contentType = upstream.headers.get('content-type') || 'application/json; charset=utf-8';
+    res.writeHead(upstream.status, { 'Content-Type': contentType });
+    if (!upstream.body) {
+        res.end();
+        return;
+    }
+    const reader = upstream.body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            res.write(Buffer.from(value));
+        }
+        res.end();
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function proofHeader(proof) {
+    return Buffer.from(JSON.stringify(proof)).toString('base64');
+}
+/**
+ * Creates a loopback-only OpenAI-compatible proxy. The local bearer never
+ * reaches Render; only the shared compatibility bearer and a fresh proof do.
+ */
+export function createSidecarServer(options) {
+    const gatewayBaseUrl = options.gatewayBaseUrl.replace(/\/$/, '');
+    const gatewayFetch = options.gatewayFetch ?? fetch;
+    let server = null;
+    const inFlight = new Set();
+    const handler = async (req, res) => {
+        const pathname = new URL(req.url || '/', 'http://127.0.0.1').pathname;
+        if (!isLoopbackAddress(req.socket.remoteAddress)) {
+            sendJson(res, 403, { error: 'loopback_only' });
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/health') {
+            sendJson(res, 200, { service: 'zk-credits-sidecar', status: 'ok' });
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/v1/models') {
+            if (req.headers.authorization !== `Bearer ${options.localToken}`) {
+                sendJson(res, 401, { error: 'invalid_local_token' });
+                return;
+            }
+            sendJson(res, 200, codexModelsResponse());
+            return;
+        }
+        if (req.method !== 'POST' || (pathname !== '/v1/chat/completions' && pathname !== '/v1/responses')) {
+            sendJson(res, 404, { error: 'unsupported_openai_path' });
+            return;
+        }
+        if (req.headers.authorization !== `Bearer ${options.localToken}`) {
+            sendJson(res, 401, { error: 'invalid_local_token' });
+            return;
+        }
+        try {
+            const body = await readJsonBody(req);
+            const reservation = await options.ledger.reserve(body.parsed);
+            const proof = await options.proofGenerator({
+                ticketIndex: reservation.index,
+                request: body.parsed,
+            });
+            const upstream = await gatewayFetch(`${gatewayBaseUrl}${pathname}`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${options.compatibilityKey}`,
+                    'Content-Type': 'application/json',
+                    'X-ZK-Proof': proofHeader(proof),
+                },
+                body: body.raw,
+            });
+            await relayGatewayResponse(res, upstream);
+            if (upstream.status >= 200 && upstream.status < 300) {
+                await options.ledger.consume(reservation.requestDigest);
+            }
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                const message = error instanceof Error ? error.message : 'Loopback request failed';
+                sendJson(res, 502, { error: 'sidecar_request_failed', message });
+            }
+            else if (!res.writableEnded) {
+                res.end();
+            }
+        }
+    };
+    return {
+        async listen(port = 0) {
+            if (server)
+                throw new Error('ZK Credits sidecar is already running');
+            server = createServer((req, res) => {
+                const request = handler(req, res).finally(() => inFlight.delete(request));
+                inFlight.add(request);
+            });
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(port, '127.0.0.1', () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+            const address = server.address();
+            return `http://127.0.0.1:${address.port}`;
+        },
+        async close() {
+            if (!server)
+                return;
+            const activeServer = server;
+            server = null;
+            await new Promise((resolve, reject) => activeServer.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            }));
+            await Promise.all(inFlight);
+        },
+    };
+}

package/dist/ticket-ledger.d.ts

@@ -0,0 +1,22 @@
+export type TicketState = 'reserved' | 'consumed';
+export interface TicketReservation {
+    index: number;
+    requestDigest: string;
+    state: TicketState;
+}
+/**
+ * Durable, serialized local ticket allocation. It never reassigns a ticket
+ * after an ambiguous request: only an exact canonical request digest may
+ * reuse its prior reservation for gateway idempotency.
+ */
+export declare class TicketLedger {
+    private readonly filePath;
+    private readonly capacity;
+    private queue;
+    constructor(filePath: string, capacity?: number);
+    reserve(request: unknown): Promise<TicketReservation>;
+    consume(requestDigest: string): Promise<void>;
+    private serialized;
+    private read;
+    private write;
+}

package/dist/ticket-ledger.js

@@ -0,0 +1,91 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { requestDigestToField } from '@zk-credits/shared';
+function parseLedger(raw) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.entries)) {
+        throw new Error('Sidecar ticket ledger is malformed');
+    }
+    const entries = parsed.entries.map((entry) => {
+        if (!entry || typeof entry !== 'object'
+            || !Number.isInteger(entry.index)
+            || typeof entry.requestDigest !== 'string'
+            || !['reserved', 'consumed'].includes(entry.state)) {
+            throw new Error('Sidecar ticket ledger is malformed');
+        }
+        return entry;
+    });
+    return { entries };
+}
+/**
+ * Durable, serialized local ticket allocation. It never reassigns a ticket
+ * after an ambiguous request: only an exact canonical request digest may
+ * reuse its prior reservation for gateway idempotency.
+ */
+export class TicketLedger {
+    filePath;
+    capacity;
+    queue = Promise.resolve();
+    constructor(filePath, capacity = 100) {
+        this.filePath = filePath;
+        this.capacity = capacity;
+    }
+    async reserve(request) {
+        const digest = (await requestDigestToField(request)).digest;
+        return this.serialized(async () => {
+            const ledger = await this.read();
+            const existing = ledger.entries.find((entry) => entry.requestDigest === digest);
+            if (existing)
+                return { ...existing };
+            const used = new Set(ledger.entries.map((entry) => entry.index));
+            const index = Array.from({ length: this.capacity }, (_, candidate) => candidate)
+                .find((candidate) => !used.has(candidate));
+            if (index === undefined)
+                throw new Error('All ZK Credit tickets have been reserved');
+            const reservation = { index, requestDigest: digest, state: 'reserved' };
+            ledger.entries.push(reservation);
+            await this.write(ledger);
+            return reservation;
+        });
+    }
+    async consume(requestDigest) {
+        await this.serialized(async () => {
+            const ledger = await this.read();
+            const entry = ledger.entries.find((candidate) => candidate.requestDigest === requestDigest);
+            if (!entry)
+                throw new Error('Unknown sidecar ticket reservation');
+            entry.state = 'consumed';
+            await this.write(ledger);
+        });
+    }
+    async serialized(operation) {
+        const previous = this.queue;
+        let release;
+        this.queue = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    async read() {
+        try {
+            return parseLedger(await readFile(this.filePath, 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { entries: [] };
+            throw error;
+        }
+    }
+    async write(ledger) {
+        await mkdir(dirname(this.filePath), { recursive: true, mode: 0o700 });
+        const temporaryPath = `${this.filePath}.tmp`;
+        await writeFile(temporaryPath, JSON.stringify(ledger), { encoding: 'utf8', mode: 0o600 });
+        await rename(temporaryPath, this.filePath);
+    }
+}