zk-credits 0.1.0

package/circuits/manifest.json

@@ -0,0 +1,16 @@
+{
+  "artifacts": [
+    {
+      "file": "rln_nullifier.wasm",
+      "sha256": "38370baebbafb76562d5c94e15354c04152c388bffe1bf85faeeb4dd221538c1"
+    },
+    {
+      "file": "rln_nullifier_final.zkey",
+      "sha256": "11cd9e881437283701dcebd75be469d57ec7428de3495d229268eb75f2413cc8"
+    },
+    {
+      "file": "verification_key_rln.json",
+      "sha256": "9a521e0e19dc272c281f1a41abf79571bb0094cda653c890bdd95aa5b4c5f1ee"
+    }
+  ]
+}

package/circuits/verification_key_rln.json

@@ -0,0 +1,109 @@
+{
+ "protocol": "groth16",
+ "curve": "bls12381",
+ "nPublic": 4,
+ "vk_alpha_1": [
+  "1244916799719111115985824406146514200983043647072123709622583920496525002856764215221448931962172516669612006664011",
+  "674184716755852549412886332979972587855277846527799005000484605021468038416766675025743003205822498453235045691476",
+  "1"
+ ],
+ "vk_beta_2": [
+  [
+   "2455251836070541788489529793762142346199398025992507018540619039036086814384951975176756650000846004361344070161304",
+   "2937824279562491013596404255358969138585343050874888399768103071899950746606483895876569409026151415551079740037761"
+  ],
+  [
+   "446083790294330119881832403473761928440559063068309621037545623082473144505427418093982114100409901098317111775821",
+   "3785055939750926364236474492083690801000055773112847122159407366123504713227708230770664301332755836784284502908712"
+  ],
+  [
+   "1",
+   "0"
+  ]
+ ],
+ "vk_gamma_2": [
+  [
+   "352701069587466618187139116011060144890029952792775240219908644239793785735715026873347600343865175952761926303160",
+   "3059144344244213709971259814753781636986470325476647558659373206291635324768958432433509563104347017837885763365758"
+  ],
+  [
+   "1985150602287291935568054521177171638300868978215655730859378665066344726373823718423869104263333984641494340347905",
+   "927553665492332455747201965776037880757740193453592970025027978793976877002675564980949289727957565575433344219582"
+  ],
+  [
+   "1",
+   "0"
+  ]
+ ],
+ "vk_delta_2": [
+  [
+   "815903917344004787967184712590545096236532819656388622025249611089881028477817865557111876667504441704194684680307",
+   "670418350436737966704976106638632654750417626321542221556129023573394146719830978038172500968777166806783233326358"
+  ],
+  [
+   "132242538892870542023564177985854902449332198072826003671372574646963034098929452508380735176272713149086113864544",
+   "1295474109123148911958332787357286834151182410719136962183460732527817478371821937388205172048254642287772006009264"
+  ],
+  [
+   "1",
+   "0"
+  ]
+ ],
+ "vk_alphabeta_12": [
+  [
+   [
+    "2148218340318415560785282432131639593244917611573725139848778170535434244212026178066037788310472564349970250282392",
+    "3886099966455474325354315497186064113709942495020874416427588084988203169653116890509783720642066036079024288318367"
+   ],
+   [
+    "2147733873846352773264547871382924081657868204207859655073999707937942259125041863315023713461664906836183909349427",
+    "3300509236653870608433795081198008200257706137874605155741973379043673218059121533531885971135301481641148990288908"
+   ],
+   [
+    "1457040979867014527178278917296122843565121729489643303266593330575329991280167715824060993604767796096686114833558",
+    "522202240083044464005146299554446710117064086086358260623118384301631920417346027196182771281895994950369033642655"
+   ]
+  ],
+  [
+   [
+    "2143490186396385444016488966037949777514548881502140436891739250424332358613767373363354273246538302735780964291134",
+    "992359013426272838367672158158652816958223156384535853564383892165623437873615951263884124498691885172712210460870"
+   ],
+   [
+    "2930464239864002107991444247101178291833963173368894752425555503421946405791467731459004456083402426838355238725274",
+    "1641122466550679068287562812263191357777988622153078979652004605642842424522164600037157683230157584394685025158128"
+   ],
+   [
+    "3713193058400064755185876715564152409762918217604594177751650270255812088538785420914214301101967016069607286158727",
+    "3330823746424537451818547927613235469316182723960266221891897980402198103295396404876595659434703874739812673040531"
+   ]
+  ]
+ ],
+ "IC": [
+  [
+   "2619981925219799044925292874804472181322403305042960540267007572554148292764967234794422060297405328360757510836410",
+   "1671878666008695368264725089725176391458488012496484085432493950640398385781945148513326456164087180642228352857154",
+   "1"
+  ],
+  [
+   "2962167839060010823612043197241393772530852323612584445859764903692967795672028163825735615820801435857580681916666",
+   "149941004408393200420344522245393435122492041086792788867727881494885562834027422806934271879564707675908925017073",
+   "1"
+  ],
+  [
+   "2827687415023160826278720364233374930905679736186024874228420390555381619909205688587633404816747958873736490833250",
+   "1158462108537411797695075524175255149628850521698164664688681863659381326196535473842851262539366227662015891009304",
+   "1"
+  ],
+  [
+   "529262520578754285118871536040905446947891826400031106172291657766477328537381420544111896054250568733141121144894",
+   "76786170645685285882188204133787783442160455050559729010717405837827594403467807550443285025529284869053889709362",
+   "1"
+  ],
+  [
+   "532817504610992030868130360294801571860447285842057982753015098208520483232734639607596289339602237219420675894443",
+   "3537860490759685255700833399282272211830248347533426758099162862063308826090393262829666104619743494237271770797411",
+   "1"
+  ]
+ ]
+}

package/dist/artifact-manifest.d.ts

@@ -0,0 +1,8 @@
+export interface CircuitArtifact {
+    file: string;
+    sha256: string;
+}
+/** Version-pinned contents of the circuits directory shipped in this package. */
+export declare const CIRCUIT_MANIFEST: readonly CircuitArtifact[];
+/** Refuses to prove when an installed circuit differs from the pinned release. */
+export declare function verifyArtifactManifest(artifactDirectory: string, manifest?: readonly CircuitArtifact[]): Promise<readonly CircuitArtifact[]>;

package/dist/artifact-manifest.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Version-pinned contents of the circuits directory shipped in this package. */
+export const CIRCUIT_MANIFEST = [
+    {
+        file: 'rln_nullifier.wasm',
+        sha256: '38370baebbafb76562d5c94e15354c04152c388bffe1bf85faeeb4dd221538c1',
+    },
+    {
+        file: 'rln_nullifier_final.zkey',
+        sha256: '11cd9e881437283701dcebd75be469d57ec7428de3495d229268eb75f2413cc8',
+    },
+    {
+        file: 'verification_key_rln.json',
+        sha256: '9a521e0e19dc272c281f1a41abf79571bb0094cda653c890bdd95aa5b4c5f1ee',
+    },
+];
+/** Refuses to prove when an installed circuit differs from the pinned release. */
+export async function verifyArtifactManifest(artifactDirectory, manifest = CIRCUIT_MANIFEST) {
+    for (const artifact of manifest) {
+        const content = await readFile(join(artifactDirectory, artifact.file));
+        const digest = createHash('sha256').update(content).digest('hex');
+        if (digest !== artifact.sha256) {
+            throw new Error(`Circuit artifact hash mismatch: ${artifact.file}`);
+        }
+    }
+    return manifest;
+}

package/dist/cli-runtime.d.ts

@@ -0,0 +1,15 @@
+export interface CliCommandDependencies {
+    loopbackBaseUrl: string;
+    readToken(): Promise<string>;
+    importMnemonic(mnemonic: string): Promise<void>;
+    readMnemonic(): Promise<string>;
+    write(line: string): void;
+    isIdentityConfigured(): Promise<boolean>;
+    configureCodex(model?: string): Promise<void>;
+    ensureSidecar(): Promise<string>;
+    isCodexProfileInstalled(): Promise<boolean>;
+    isSidecarHealthy(): Promise<boolean>;
+    launchCodex(args: readonly string[]): Promise<number>;
+}
+/** Handles the non-server CLI commands independently from terminal I/O. */
+export declare function runCliCommand(args: readonly string[], dependencies: CliCommandDependencies): Promise<number>;

package/dist/cli-runtime.js

@@ -0,0 +1,55 @@
+import { formatOpenAiEnvironment } from './sidecar-config.js';
+function setupModel(args) {
+    if (args[1] !== 'codex')
+        throw new Error('Usage: zk-credits setup codex [--model <model>]');
+    if (args.length === 2)
+        return undefined;
+    if (args.length === 4 && args[2] === '--model' && args[3]?.trim())
+        return args[3];
+    throw new Error('Usage: zk-credits setup codex [--model <model>]');
+}
+/** Handles the non-server CLI commands independently from terminal I/O. */
+export async function runCliCommand(args, dependencies) {
+    switch (args[0]) {
+        case 'env': {
+            dependencies.write(formatOpenAiEnvironment(dependencies.loopbackBaseUrl, await dependencies.readToken()));
+            return 0;
+        }
+        case 'import-mnemonic': {
+            await dependencies.importMnemonic(await dependencies.readMnemonic());
+            dependencies.write('ZK Credits identity imported into the system credential store.');
+            return 0;
+        }
+        case 'setup': {
+            const model = setupModel(args);
+            if (!await dependencies.isIdentityConfigured()) {
+                await dependencies.importMnemonic(await dependencies.readMnemonic());
+                dependencies.write('ZK Credits identity imported into the system credential store.');
+            }
+            await dependencies.configureCodex(model);
+            await dependencies.ensureSidecar();
+            dependencies.write('ZK Credits is ready for Codex.');
+            dependencies.write('Run: zk-credits codex');
+            return 0;
+        }
+        case 'token': {
+            dependencies.write(await dependencies.ensureSidecar());
+            return 0;
+        }
+        case 'status': {
+            dependencies.write(`Identity: ${await dependencies.isIdentityConfigured() ? 'configured' : 'missing'}`);
+            dependencies.write(`Codex profile: ${await dependencies.isCodexProfileInstalled() ? 'installed' : 'missing'}`);
+            dependencies.write(`Sidecar: ${await dependencies.isSidecarHealthy() ? 'running' : 'stopped'}`);
+            return 0;
+        }
+        case 'codex': {
+            if (!await dependencies.isCodexProfileInstalled()) {
+                throw new Error('Run zk-credits setup codex first');
+            }
+            await dependencies.ensureSidecar();
+            return dependencies.launchCodex(args.slice(1));
+        }
+        default:
+            throw new Error('Usage: zk-credits <setup codex|codex|status|token|import-mnemonic|serve|env>');
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { launchCodexProcess } from './codex-launcher.js';
+import { isCodexProfileInstalled, resolveCodexHome, writeCodexProfile, } from './codex-profile.js';
+import { IdentityStore } from './identity.js';
+import { createLocalProofGenerator } from './local-prover.js';
+import { MembershipClient } from './membership-client.js';
+import { runCliCommand } from './cli-runtime.js';
+import { createNodeSidecarLifecycle } from './node-sidecar-lifecycle.js';
+import { activateSidecarServer } from './server-startup.js';
+import { createLoopbackToken, sidecarStatePaths } from './sidecar-config.js';
+import { ensureSidecarReady } from './sidecar-lifecycle.js';
+import { readLoopbackToken, writeLoopbackToken } from './sidecar-state.js';
+import { createSidecarServer } from './sidecar.js';
+import { TicketLedger } from './ticket-ledger.js';
+const DEFAULT_GATEWAY_URL = 'https://zk-credits-gateway.onrender.com';
+const DEFAULT_PORT = 3210;
+function stateDirectory() {
+    return process.env.ZK_CREDITS_HOME || join(homedir(), '.zk-credits');
+}
+function loopbackBaseUrl() {
+    const port = Number(process.env.ZK_CREDITS_SIDECAR_PORT || DEFAULT_PORT);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error('ZK_CREDITS_SIDECAR_PORT must be a port between 1 and 65535');
+    }
+    return `http://127.0.0.1:${port}`;
+}
+function readPort(args) {
+    const portIndex = args.indexOf('--port');
+    if (portIndex === -1)
+        return Number(new URL(loopbackBaseUrl()).port);
+    const parsed = Number(args[portIndex + 1]);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error('--port must be a port between 1 and 65535');
+    }
+    return parsed;
+}
+/** Reads a recovery phrase from a TTY without terminal echo or shell history. */
+async function readHiddenMnemonic() {
+    if (!process.stdin.isTTY || !process.stdin.setRawMode) {
+        throw new Error('import-mnemonic requires an interactive terminal');
+    }
+    process.stdout.write('Enter your 24-word recovery phrase: ');
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    return new Promise((resolve, reject) => {
+        let value = '';
+        const done = (error) => {
+            process.stdin.off('data', onData);
+            process.stdin.setRawMode(false);
+            process.stdout.write('\n');
+            if (error)
+                reject(error);
+            else
+                resolve(value.trim());
+        };
+        const onData = (chunk) => {
+            for (const byte of chunk) {
+                if (byte === 3) {
+                    done(new Error('Mnemonic import cancelled'));
+                    return;
+                }
+                if (byte === 13 || byte === 10) {
+                    done();
+                    return;
+                }
+                if (byte === 127 || byte === 8) {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                value += String.fromCharCode(byte);
+            }
+        };
+        process.stdin.on('data', onData);
+    });
+}
+function printHelp() {
+    console.log(`Usage:
+  zk-credits setup codex [--model <model>]
+  zk-credits codex [codex arguments...]
+  zk-credits status
+  zk-credits import-mnemonic
+  zk-credits serve [--port <port>]
+  eval "$(zk-credits env)"
+
+The Codex setup starts the loopback sidecar automatically; daily use is
+"zk-credits codex". serve/env remain available for other OpenAI-compatible
+clients. Set ZK_CREDITS_MNEMONIC only for a headless process; it is not
+persisted by that path.`);
+}
+async function serve(args) {
+    const port = readPort(args);
+    const statePaths = sidecarStatePaths(stateDirectory());
+    const localToken = createLoopbackToken();
+    const identities = new IdentityStore();
+    const secretK = await identities.loadSecretK({ headlessMnemonic: process.env.ZK_CREDITS_MNEMONIC });
+    const gatewayBaseUrl = process.env.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL;
+    const proofGenerator = await createLocalProofGenerator({
+        secretK,
+        membershipClient: new MembershipClient(gatewayBaseUrl),
+    });
+    const sidecar = createSidecarServer({
+        localToken,
+        gatewayBaseUrl,
+        compatibilityKey: process.env.ZK_CREDITS_COMPATIBILITY_KEY || 'sk-zk-local-demo',
+        ledger: new TicketLedger(statePaths.ledgerPath),
+        proofGenerator,
+    });
+    let address;
+    try {
+        address = await activateSidecarServer({
+            listen: () => sidecar.listen(port),
+            publishToken: () => writeLoopbackToken(statePaths.tokenPath, localToken),
+        });
+    }
+    catch (error) {
+        await sidecar.close();
+        throw error;
+    }
+    console.log(`ZK Credits sidecar listening on ${address}/v1`);
+    console.log('Run eval "$(zk-credits env)" in the client shell.');
+    const shutdown = async () => {
+        await sidecar.close();
+        process.exit(0);
+    };
+    process.once('SIGINT', () => { void shutdown(); });
+    process.once('SIGTERM', () => { void shutdown(); });
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args[0] === '--help' || args[0] === '-h' || !args[0]) {
+        printHelp();
+        return;
+    }
+    if (args[0] === 'serve') {
+        await serve(args.slice(1));
+        return;
+    }
+    const identities = new IdentityStore();
+    const sidecarHome = stateDirectory();
+    const statePaths = sidecarStatePaths(sidecarHome);
+    const codexHome = resolveCodexHome(process.env, homedir());
+    const cliEntryPath = process.argv[1];
+    if (!cliEntryPath)
+        throw new Error('Unable to resolve the zk-credits executable path');
+    const lifecycle = createNodeSidecarLifecycle({
+        loopbackBaseUrl: loopbackBaseUrl(),
+        stateDirectory: sidecarHome,
+        tokenPath: statePaths.tokenPath,
+        logPath: statePaths.logPath,
+        cliEntryPath,
+    });
+    const exitCode = await runCliCommand(args, {
+        loopbackBaseUrl: loopbackBaseUrl(),
+        readToken: () => readLoopbackToken(statePaths.tokenPath),
+        importMnemonic: async (mnemonic) => { await identities.importMnemonic(mnemonic); },
+        readMnemonic: readHiddenMnemonic,
+        write: (line) => console.log(line),
+        isIdentityConfigured: () => identities.hasIdentity(),
+        configureCodex: async (model) => {
+            await writeCodexProfile({ codexHome, loopbackBaseUrl: loopbackBaseUrl(), model });
+        },
+        ensureSidecar: () => ensureSidecarReady(lifecycle),
+        isCodexProfileInstalled: () => isCodexProfileInstalled(codexHome),
+        isSidecarHealthy: () => lifecycle.isHealthy(),
+        launchCodex: (codexArgs) => launchCodexProcess(codexArgs),
+    });
+    if (exitCode !== 0)
+        process.exitCode = exitCode;
+}
+void main().catch((error) => {
+    console.error(error instanceof Error ? error.message : 'zk-credits failed');
+    process.exitCode = 1;
+});

package/dist/codex-launcher.d.ts

@@ -0,0 +1,10 @@
+interface SpawnedProcess {
+    once(event: 'error', listener: (error: NodeJS.ErrnoException) => void): this;
+    once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+}
+export type SpawnCommand = (command: string, args: readonly string[], options: {
+    stdio: 'inherit';
+}) => SpawnedProcess;
+/** Launches interactive Codex with the isolated ZK Credits provider profile. */
+export declare function launchCodexProcess(args: readonly string[], spawnImpl?: SpawnCommand): Promise<number>;
+export {};

package/dist/codex-launcher.js

@@ -0,0 +1,17 @@
+import { spawn } from 'node:child_process';
+import { CODEX_PROFILE_NAME } from './codex-profile.js';
+const spawnCommand = (command, args, options) => spawn(command, args, options);
+/** Launches interactive Codex with the isolated ZK Credits provider profile. */
+export async function launchCodexProcess(args, spawnImpl = spawnCommand) {
+    const child = spawnImpl('codex', ['--profile', CODEX_PROFILE_NAME, ...args], { stdio: 'inherit' });
+    return new Promise((resolve, reject) => {
+        child.once('error', (error) => {
+            if (error.code === 'ENOENT') {
+                reject(new Error('Codex CLI was not found; install it before running zk-credits codex'));
+                return;
+            }
+            reject(error);
+        });
+        child.once('exit', (code) => resolve(code ?? 1));
+    });
+}

package/dist/codex-profile.d.ts

@@ -0,0 +1,16 @@
+export declare const CODEX_PROFILE_NAME = "zk-credits";
+export declare const DEFAULT_CODEX_MODEL = "openai/gpt-4o-mini";
+export interface CodexProfileOptions {
+    loopbackBaseUrl: string;
+    model?: string;
+}
+export interface WriteCodexProfileOptions extends CodexProfileOptions {
+    codexHome: string;
+}
+export declare function resolveCodexHome(environment: NodeJS.ProcessEnv, userHome: string): string;
+export declare function codexProfilePath(codexHome: string): string;
+export declare function renderCodexProfile(options: CodexProfileOptions): string;
+/** Returns the Codex-specific model catalog served by its `/v1/models` probe. */
+export declare function codexModelsResponse(): object;
+export declare function writeCodexProfile(options: WriteCodexProfileOptions): Promise<string>;
+export declare function isCodexProfileInstalled(codexHome: string): Promise<boolean>;

package/dist/codex-profile.js

@@ -0,0 +1,103 @@
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, rename, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const CODEX_PROFILE_NAME = 'zk-credits';
+export const DEFAULT_CODEX_MODEL = 'openai/gpt-4o-mini';
+export function resolveCodexHome(environment, userHome) {
+    return environment.CODEX_HOME || join(userHome, '.codex');
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function providerBaseUrl(loopbackBaseUrl) {
+    const url = new URL(loopbackBaseUrl);
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1') {
+        throw new Error('Codex provider must use a 127.0.0.1 HTTP sidecar URL');
+    }
+    return `${url.origin}/v1`;
+}
+export function codexProfilePath(codexHome) {
+    return join(codexHome, `${CODEX_PROFILE_NAME}.config.toml`);
+}
+export function renderCodexProfile(options) {
+    const model = options.model?.trim() || DEFAULT_CODEX_MODEL;
+    return [
+        `model = ${tomlString(model)}`,
+        'model_provider = "zk_credits"',
+        '',
+        '[model_providers.zk_credits]',
+        'name = "ZK Credits"',
+        `base_url = ${tomlString(providerBaseUrl(options.loopbackBaseUrl))}`,
+        'wire_api = "responses"',
+        '',
+        '[model_providers.zk_credits.auth]',
+        'command = "zk-credits"',
+        'args = ["token"]',
+        'refresh_interval_ms = 0',
+        '',
+    ].join('\n');
+}
+/** Returns the Codex-specific model catalog served by its `/v1/models` probe. */
+export function codexModelsResponse() {
+    return {
+        models: [{
+                slug: DEFAULT_CODEX_MODEL,
+                display_name: 'GPT-4o Mini (ZK Credits)',
+                description: 'OpenRouter coding model paid with private ZK Credits tickets.',
+                default_reasoning_level: null,
+                supported_reasoning_levels: [],
+                shell_type: 'shell_command',
+                visibility: 'list',
+                supported_in_api: true,
+                priority: 1,
+                additional_speed_tiers: [],
+                service_tiers: [],
+                default_service_tier: null,
+                availability_nux: null,
+                upgrade: null,
+                base_instructions: [
+                    'You are Codex, a coding agent. Follow the user\'s instructions carefully.',
+                    'Use the provided tools when needed, preserve existing work, and verify changes before claiming completion.',
+                ].join(' '),
+                include_skills_usage_instructions: true,
+                include_plugin_usage_instructions: true,
+                include_apps_usage_instructions: true,
+                supports_reasoning_summary_parameter: false,
+                default_reasoning_summary: 'none',
+                support_verbosity: false,
+                default_verbosity: null,
+                apply_patch_tool_type: 'freeform',
+                web_search_tool_type: 'text',
+                truncation_policy: { mode: 'tokens', limit: 10_000 },
+                supports_parallel_tool_calls: true,
+                supports_image_detail_original: false,
+                context_window: 128_000,
+                max_context_window: 128_000,
+                experimental_supported_tools: [],
+                input_modalities: ['text', 'image'],
+                supports_search_tool: false,
+                use_responses_lite: false,
+                tool_mode: 'direct',
+            }],
+    };
+}
+export async function writeCodexProfile(options) {
+    await mkdir(options.codexHome, { recursive: true, mode: 0o700 });
+    const profilePath = codexProfilePath(options.codexHome);
+    const temporaryPath = `${profilePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    await writeFile(temporaryPath, renderCodexProfile(options), { encoding: 'utf8', mode: 0o600 });
+    await chmod(temporaryPath, 0o600);
+    await rename(temporaryPath, profilePath);
+    await chmod(profilePath, 0o600);
+    return profilePath;
+}
+export async function isCodexProfileInstalled(codexHome) {
+    try {
+        return (await stat(codexProfilePath(codexHome))).isFile();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,18 @@
+export interface CredentialStore {
+    getPassword(service: string, account: string): Promise<string | null>;
+    setPassword(service: string, account: string, password: string): Promise<void>;
+}
+/**
+ * Owns the local private identity. The recovery phrase is converted to the
+ * 32-byte secret before persistence, so neither the phrase nor a local bearer
+ * ever reaches the gateway or ticket ledger.
+ */
+export declare class IdentityStore {
+    private readonly credentials;
+    constructor(credentials?: CredentialStore);
+    hasIdentity(): Promise<boolean>;
+    importMnemonic(mnemonic: string): Promise<Uint8Array>;
+    loadSecretK(options?: {
+        headlessMnemonic?: string;
+    }): Promise<Uint8Array>;
+}

package/dist/identity.js

@@ -0,0 +1,48 @@
+import * as keytar from 'keytar';
+import { recoverSecretK } from '@zk-credits/shared';
+const SERVICE = 'zk-credits-sidecar';
+const ACCOUNT = 'secret-k-v1';
+function secretToHex(secretK) {
+    if (secretK.length !== 32)
+        throw new Error('Expected a 32-byte ZK Credits secret');
+    return Array.from(secretK, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+function hexToSecret(value) {
+    if (!/^[a-f0-9]{64}$/i.test(value)) {
+        throw new Error('Stored ZK Credits credential is malformed; re-import the mnemonic');
+    }
+    return new Uint8Array(value.match(/.{2}/g).map((pair) => Number.parseInt(pair, 16)));
+}
+/**
+ * Owns the local private identity. The recovery phrase is converted to the
+ * 32-byte secret before persistence, so neither the phrase nor a local bearer
+ * ever reaches the gateway or ticket ledger.
+ */
+export class IdentityStore {
+    credentials;
+    constructor(credentials = keytar) {
+        this.credentials = credentials;
+    }
+    async hasIdentity() {
+        return await this.credentials.getPassword(SERVICE, ACCOUNT) !== null;
+    }
+    async importMnemonic(mnemonic) {
+        const secretK = recoverSecretK(mnemonic);
+        if (secretK.length !== 32)
+            throw new Error('Recovery phrase must encode a 32-byte secret');
+        await this.credentials.setPassword(SERVICE, ACCOUNT, secretToHex(secretK));
+        return secretK;
+    }
+    async loadSecretK(options = {}) {
+        const stored = await this.credentials.getPassword(SERVICE, ACCOUNT);
+        if (stored !== null)
+            return hexToSecret(stored);
+        if (options.headlessMnemonic) {
+            const secretK = recoverSecretK(options.headlessMnemonic);
+            if (secretK.length !== 32)
+                throw new Error('Recovery phrase must encode a 32-byte secret');
+            return secretK;
+        }
+        throw new Error('No ZK Credits identity found; run zk-credits import-mnemonic first');
+    }
+}

package/dist/local-prover.d.ts

@@ -0,0 +1,18 @@
+import { type RlnCircuitResources, type RlnProofInput, type RlnProofResult } from '@zk-credits/shared';
+import { MembershipClient } from './membership-client.js';
+import type { ProofGenerator } from './sidecar.js';
+export interface MembershipWitnessReader {
+    witnessForSecret(secretK: Uint8Array): ReturnType<MembershipClient['witnessForSecret']>;
+}
+export type SelfVerifyingRlnProver = (input: RlnProofInput, resources: RlnCircuitResources) => Promise<Pick<RlnProofResult, 'proof' | 'publicSignals'>>;
+export interface LocalProofGeneratorOptions {
+    secretK: Uint8Array;
+    membershipClient: MembershipWitnessReader;
+    artifactDirectory?: string;
+    prove?: SelfVerifyingRlnProver;
+}
+/**
+ * Builds the sidecar's local prover after checking every installed circuit
+ * byte against its release manifest. No proving asset is fetched at runtime.
+ */
+export declare function createLocalProofGenerator(options: LocalProofGeneratorOptions): Promise<ProofGenerator>;