@affix-io/sdk 2.0.0

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+import type { SdkConfig } from "./types.js";
+export type ApiResponse<T> = {
+    ok: boolean;
+    status: number;
+    data: T;
+};
+export declare class AffixApiClient {
+    private readonly config;
+    constructor(config: SdkConfig);
+    private headers;
+    health(): Promise<Record<string, unknown>>;
+    listCircuits(): Promise<Record<string, unknown>>;
+    prepareWitness(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    prove(circuitId: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    verify(circuitId: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    merkleAudit(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    merkleRoot(): Promise<Record<string, unknown>>;
+    private get;
+    private post;
+    private parse;
+}

package/dist/client.js

@@ -0,0 +1,72 @@
+import { requestJson } from "./http.js";
+export class AffixApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    headers() {
+        return {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "X-API-Key": this.config.apiKey,
+            "User-Agent": "AffixIO-SDK-Web/2.0",
+        };
+    }
+    async health() {
+        return this.get("/api/health");
+    }
+    async listCircuits() {
+        return this.get("/v1/circuits");
+    }
+    async prepareWitness(body) {
+        return this.post("/v1/witness/prepare", body);
+    }
+    async prove(circuitId, body) {
+        return this.post(`/v1/circuits/${encodeURIComponent(circuitId)}/prove`, body);
+    }
+    async verify(circuitId, body) {
+        return this.post(`/v1/circuits/${encodeURIComponent(circuitId)}/verify`, body);
+    }
+    async merkleAudit(body) {
+        return this.post("/v1/merkle/audit", body);
+    }
+    async merkleRoot() {
+        return this.get("/v1/merkle/root");
+    }
+    async get(path) {
+        const res = await requestJson(`${this.config.apiBase}${path}`, {
+            method: "GET",
+            headers: this.headers(),
+            timeoutMs: this.config.timeoutMs ?? 120_000,
+        });
+        return this.parse(res);
+    }
+    async post(path, body) {
+        const res = await requestJson(`${this.config.apiBase}${path}`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+            timeoutMs: this.config.timeoutMs ?? 120_000,
+        });
+        return this.parse(res);
+    }
+    async parse(res) {
+        let data = {};
+        try {
+            data = (await res.json());
+        }
+        catch {
+            data = { error: "invalid_json" };
+        }
+        if (!res.ok) {
+            const message = typeof data.message === "string"
+                ? data.message
+                : typeof data.error === "string"
+                    ? data.error
+                    : `http_${res.status}`;
+            throw new Error(message);
+        }
+        return data;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { SdkConfig } from "./types.js";
+export declare function resolveConfig(partial: Partial<SdkConfig> & {
+    apiKey?: string;
+}): SdkConfig;

package/dist/config.js

@@ -0,0 +1,17 @@
+import { loadEnv } from "./env.js";
+export function resolveConfig(partial) {
+    loadEnv();
+    const apiKey = partial.apiKey ?? process.env.AFFIX_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error("api_key_required: set AFFIX_API_KEY in .env or pass apiKey to AffixSDK");
+    }
+    return {
+        apiBase: partial.apiBase ?? process.env.AFFIX_API_BASE ?? "https://api.affix-io.com",
+        apiKey,
+        requestAttestation: partial.requestAttestation ?? true,
+        sector: partial.sector,
+        offlineQueuePath: partial.offlineQueuePath ?? ".affix/offline-queue.json",
+        proofStorePath: partial.proofStorePath ?? ".affix/proofs.json",
+        timeoutMs: partial.timeoutMs ?? 120_000,
+    };
+}

package/dist/credential-normalize.d.ts

@@ -0,0 +1,3 @@
+import type { AffixCredential } from "./types.js";
+/** Noir witness inputs need field elements; hash string labels the same way the API does. */
+export declare function normalizeCredential(credential: AffixCredential): AffixCredential;

package/dist/credential-normalize.js

@@ -0,0 +1,10 @@
+import { fieldInputHex } from "./field-input.js";
+/** Noir witness inputs need field elements; hash string labels the same way the API does. */
+export function normalizeCredential(credential) {
+    return {
+        ...credential,
+        schema_id: fieldInputHex(credential.schema_id),
+        issuer_pubkey_hash: fieldInputHex(credential.issuer_pubkey_hash),
+        credential_id: fieldInputHex(credential.credential_id),
+    };
+}

package/dist/env.d.ts

@@ -0,0 +1,12 @@
+export declare const ENV_FILE_PATH: string;
+/** Load variables from this package's .env (does not override existing process.env). */
+export declare function loadEnv(): void;
+export declare function maskApiKey(key: string): string;
+export type EnvStatus = {
+    env_file: string;
+    env_file_exists: boolean;
+    api_key_set: boolean;
+    api_key_preview: string | null;
+    api_base: string;
+};
+export declare function envStatus(): EnvStatus;

package/dist/env.js

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const ENV_FILE_PATH = join(packageRoot, ".env");
+let loaded = false;
+function parseEnvLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0)
+        return null;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return [key, value];
+}
+/** Load variables from this package's .env (does not override existing process.env). */
+export function loadEnv() {
+    if (loaded)
+        return;
+    loaded = true;
+    if (!existsSync(ENV_FILE_PATH))
+        return;
+    const text = readFileSync(ENV_FILE_PATH, "utf8");
+    for (const line of text.split("\n")) {
+        const parsed = parseEnvLine(line);
+        if (!parsed)
+            continue;
+        const [key, value] = parsed;
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}
+export function maskApiKey(key) {
+    if (key.length <= 8)
+        return "****";
+    return `${key.slice(0, 4)}…${key.slice(-4)}`;
+}
+export function envStatus() {
+    loadEnv();
+    const apiKey = process.env.AFFIX_API_KEY?.trim() ?? "";
+    return {
+        env_file: ENV_FILE_PATH,
+        env_file_exists: existsSync(ENV_FILE_PATH),
+        api_key_set: apiKey.length > 0,
+        api_key_preview: apiKey ? maskApiKey(apiKey) : null,
+        api_base: process.env.AFFIX_API_BASE ?? "https://api.affix-io.com",
+    };
+}

package/dist/field-input.d.ts

@@ -0,0 +1,2 @@
+/** Map labels or hex to BN254 field elements (matches api.affix-io.com encoding). */
+export declare function fieldInputHex(value: string | number | bigint): string;

package/dist/field-input.js

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+const FR_MODULUS = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+function reduceField(value) {
+    return ((value % FR_MODULUS) + FR_MODULUS) % FR_MODULUS;
+}
+function bytesToField(bytes) {
+    let acc = 0n;
+    for (const byte of bytes) {
+        acc = (acc << 8n) + BigInt(byte);
+    }
+    return reduceField(acc);
+}
+function fieldToBigInt(value) {
+    if (typeof value === "bigint")
+        return reduceField(value);
+    if (typeof value === "number")
+        return reduceField(BigInt(value));
+    const raw = String(value).trim();
+    if (!raw)
+        return 0n;
+    if (raw.startsWith("0x") || raw.startsWith("0X")) {
+        return reduceField(BigInt(raw));
+    }
+    if (/^[0-9]+$/.test(raw)) {
+        return reduceField(BigInt(raw));
+    }
+    return bytesToField(createHash("sha256").update(raw, "utf8").digest());
+}
+function fieldToHex(value) {
+    return `0x${reduceField(value).toString(16)}`;
+}
+/** Map labels or hex to BN254 field elements (matches api.affix-io.com encoding). */
+export function fieldInputHex(value) {
+    return fieldToHex(fieldToBigInt(value));
+}

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+export type HttpResponse = {
+    status: number;
+    ok: boolean;
+    json(): Promise<Record<string, unknown>>;
+};
+export declare function requestJson(url: string, options: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+}): Promise<HttpResponse>;

package/dist/http.js

@@ -0,0 +1,62 @@
+import { readFileSync, existsSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import tls from "node:tls";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const EXTRA_CA_PATH = join(packageRoot, "certs", "sectigo-r36.pem");
+let caBundle;
+function getCaBundle() {
+    if (caBundle)
+        return caBundle;
+    caBundle = [...tls.rootCertificates];
+    if (existsSync(EXTRA_CA_PATH)) {
+        caBundle.push(readFileSync(EXTRA_CA_PATH, "utf8"));
+    }
+    return caBundle;
+}
+export async function requestJson(url, options) {
+    const parsed = new URL(url);
+    const isHttps = parsed.protocol === "https:";
+    const lib = isHttps ? https : http;
+    return new Promise((resolve, reject) => {
+        const req = lib.request({
+            protocol: parsed.protocol,
+            hostname: parsed.hostname,
+            port: parsed.port || (isHttps ? 443 : 80),
+            path: `${parsed.pathname}${parsed.search}`,
+            method: options.method ?? "GET",
+            headers: options.headers,
+            ca: isHttps ? getCaBundle() : undefined,
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+            res.on("end", () => {
+                const text = Buffer.concat(chunks).toString("utf8");
+                const status = res.statusCode ?? 0;
+                resolve({
+                    status,
+                    ok: status >= 200 && status < 300,
+                    async json() {
+                        try {
+                            return JSON.parse(text);
+                        }
+                        catch {
+                            return { error: "invalid_json", raw: text };
+                        }
+                    },
+                });
+            });
+        });
+        req.on("error", reject);
+        if (options.timeoutMs) {
+            req.setTimeout(options.timeoutMs, () => {
+                req.destroy(new Error("request_timeout"));
+            });
+        }
+        if (options.body)
+            req.write(options.body);
+        req.end();
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { AffixApiClient } from "./client.js";
+import type { AffixCredential, ProveResult, SdkConfig, VerifyResult, WitnessContext, WitnessPackage } from "./types.js";
+export type ProveInput = {
+    circuitId: string;
+    credential?: AffixCredential;
+    context?: WitnessContext;
+    witness?: WitnessPackage;
+    fields?: Record<string, string | number | boolean>;
+    sector?: string;
+    requestAttestation?: boolean;
+    queueOnFailure?: boolean;
+};
+export declare class AffixSDK {
+    readonly client: AffixApiClient;
+    private readonly queue;
+    private readonly store;
+    constructor(config?: Partial<SdkConfig> & {
+        apiKey?: string;
+    });
+    private readonly config;
+    isOnline(): Promise<boolean>;
+    buildWitness(circuitId: string, credential: AffixCredential, context?: Partial<WitnessContext>): Promise<WitnessPackage>;
+    prove(input: ProveInput): Promise<ProveResult>;
+    verify(circuitId: string, proof: string, requestAttestation?: boolean): Promise<VerifyResult>;
+    proveAndVerify(input: ProveInput): Promise<{
+        prove: ProveResult;
+        verify: VerifyResult;
+    }>;
+    flushOfflineQueue(): Promise<ProveResult[]>;
+    listQueuedJobs(): import("./types.js").QueuedProveJob[];
+    listStoredProofs(): import("./types.js").StoredProof[];
+    private mapProveResult;
+}
+export { AffixApiClient } from "./client.js";
+export { ENV_FILE_PATH, envStatus, loadEnv, maskApiKey } from "./env.js";
+export type { EnvStatus } from "./env.js";
+export { defaultContext, prepareWitness, randomFieldHex, witnessFromInputs } from "./witness.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,154 @@
+import { randomUUID } from "node:crypto";
+import { AffixApiClient } from "./client.js";
+import { resolveConfig } from "./config.js";
+import { OfflineQueue } from "./offline-queue.js";
+import { ProofStore } from "./proof-store.js";
+import { normalizeCredential } from "./credential-normalize.js";
+import { redactProveBodyForQueue } from "./queue-body.js";
+import { defaultContext, prepareWitness } from "./witness.js";
+export class AffixSDK {
+    client;
+    queue;
+    store;
+    constructor(config = {}) {
+        const resolved = resolveConfig(config);
+        this.client = new AffixApiClient(resolved);
+        this.queue = new OfflineQueue(resolved.offlineQueuePath);
+        this.store = new ProofStore(resolved.proofStorePath);
+        this.config = resolved;
+    }
+    config;
+    async isOnline() {
+        try {
+            const health = await this.client.health();
+            return health.status === "ok";
+        }
+        catch {
+            return false;
+        }
+    }
+    async buildWitness(circuitId, credential, context) {
+        return prepareWitness(this.client, circuitId, credential, defaultContext(context));
+    }
+    async prove(input) {
+        const body = {
+            requestAttestation: input.requestAttestation ?? this.config.requestAttestation,
+            sector: input.sector ?? this.config.sector,
+        };
+        if (input.witness) {
+            body.witness = input.witness;
+        }
+        else if (input.credential) {
+            body.credential = normalizeCredential(input.credential);
+            body.context = defaultContext(input.context);
+        }
+        else if (input.fields) {
+            body.fields = input.fields;
+        }
+        else {
+            throw new Error("prove_requires_witness_or_credential_or_fields");
+        }
+        try {
+            const data = await this.client.prove(input.circuitId, body);
+            const result = this.mapProveResult(input.circuitId, data, input.witness);
+            this.store.save({
+                proof_id: result.proof_id,
+                circuit_id: result.circuit_id,
+                proof: result.proof,
+                proof_digest: result.proof_digest,
+                valid: result.valid,
+                created_at: new Date().toISOString(),
+                synced: Boolean(result.merkle_root),
+                merkle_root: result.merkle_root,
+            });
+            return result;
+        }
+        catch (err) {
+            if (input.queueOnFailure !== false) {
+                this.queue.enqueue({
+                    id: randomUUID(),
+                    circuit_id: input.circuitId,
+                    body: await redactProveBodyForQueue(input.circuitId, {
+                        ...body,
+                        circuit_id: input.circuitId,
+                    }),
+                });
+            }
+            throw err;
+        }
+    }
+    async verify(circuitId, proof, requestAttestation = true) {
+        const data = await this.client.verify(circuitId, {
+            proof,
+            requestAttestation,
+            sector: this.config.sector,
+        });
+        return {
+            proof_id: String(data.proof_id ?? ""),
+            valid: Boolean(data.valid),
+            verified: Boolean(data.verified ?? data.valid),
+            decision: data.decision === "yes" ? "yes" : "no",
+            circuit_id: circuitId,
+            proof_digest: String(data.proof_digest ?? ""),
+            merkle_root: typeof data.merkle_root === "string" ? data.merkle_root : undefined,
+            merkle_leaf_hash: typeof data.merkle_leaf_hash === "string" ? data.merkle_leaf_hash : undefined,
+            attestation: data.attestation,
+        };
+    }
+    async proveAndVerify(input) {
+        const prove = await this.prove(input);
+        const verify = await this.verify(input.circuitId, prove.proof, input.requestAttestation ?? true);
+        return { prove, verify };
+    }
+    async flushOfflineQueue() {
+        const results = [];
+        for (const job of this.queue.list()) {
+            try {
+                const data = await this.client.prove(job.circuit_id, job.body);
+                const result = this.mapProveResult(job.circuit_id, data);
+                this.store.save({
+                    proof_id: result.proof_id,
+                    circuit_id: result.circuit_id,
+                    proof: result.proof,
+                    proof_digest: result.proof_digest,
+                    valid: result.valid,
+                    created_at: new Date().toISOString(),
+                    synced: Boolean(result.merkle_root),
+                    merkle_root: result.merkle_root,
+                });
+                this.queue.remove(job.id);
+                results.push(result);
+            }
+            catch {
+                this.queue.bumpAttempt(job.id);
+            }
+        }
+        return results;
+    }
+    listQueuedJobs() {
+        return this.queue.list();
+    }
+    listStoredProofs() {
+        return this.store.list();
+    }
+    mapProveResult(circuitId, data, witness) {
+        return {
+            proof_id: String(data.proof_id ?? ""),
+            circuit_id: String(data.circuit_id ?? circuitId),
+            proof: String(data.proof ?? ""),
+            valid: Boolean(data.valid),
+            verified: typeof data.verified === "boolean" ? data.verified : Boolean(data.valid),
+            decision: data.decision === "yes" ? "yes" : "no",
+            proof_digest: String(data.proof_digest ?? ""),
+            return_value: typeof data.return_value === "string" ? data.return_value : undefined,
+            merkle_root: typeof data.merkle_root === "string" ? data.merkle_root : undefined,
+            merkle_leaf_hash: typeof data.merkle_leaf_hash === "string" ? data.merkle_leaf_hash : undefined,
+            attestation: data.attestation,
+            witness,
+        };
+    }
+}
+export { AffixApiClient } from "./client.js";
+export { ENV_FILE_PATH, envStatus, loadEnv, maskApiKey } from "./env.js";
+export { defaultContext, prepareWitness, randomFieldHex, witnessFromInputs } from "./witness.js";
+export * from "./types.js";

package/dist/offline-queue.d.ts

@@ -0,0 +1,11 @@
+import type { QueuedProveJob } from "./types.js";
+export declare class OfflineQueue {
+    private readonly path;
+    constructor(path: string);
+    private read;
+    private write;
+    enqueue(job: Omit<QueuedProveJob, "created_at" | "attempts">): QueuedProveJob;
+    list(): QueuedProveJob[];
+    remove(id: string): void;
+    bumpAttempt(id: string): void;
+}

package/dist/offline-queue.js

@@ -0,0 +1,52 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+export class OfflineQueue {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    read() {
+        if (!existsSync(this.path)) {
+            return { jobs: [] };
+        }
+        try {
+            const raw = JSON.parse(readFileSync(this.path, "utf8"));
+            return { jobs: raw.jobs ?? [] };
+        }
+        catch {
+            return { jobs: [] };
+        }
+    }
+    write(data) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(data, null, 2));
+    }
+    enqueue(job) {
+        const data = this.read();
+        const full = {
+            ...job,
+            created_at: new Date().toISOString(),
+            attempts: 0,
+        };
+        data.jobs.push(full);
+        this.write(data);
+        return full;
+    }
+    list() {
+        return this.read().jobs;
+    }
+    remove(id) {
+        const data = this.read();
+        data.jobs = data.jobs.filter((job) => job.id !== id);
+        this.write(data);
+    }
+    bumpAttempt(id) {
+        const data = this.read();
+        for (const job of data.jobs) {
+            if (job.id === id) {
+                job.attempts += 1;
+            }
+        }
+        this.write(data);
+    }
+}

package/dist/proof-store.d.ts

@@ -0,0 +1,10 @@
+import type { StoredProof } from "./types.js";
+export declare class ProofStore {
+    private readonly path;
+    constructor(path: string);
+    private read;
+    private write;
+    save(proof: StoredProof): void;
+    list(): StoredProof[];
+    markSynced(proof_id: string, merkle_root?: string): void;
+}

package/dist/proof-store.js

@@ -0,0 +1,44 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+export class ProofStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    read() {
+        if (!existsSync(this.path)) {
+            return { proofs: [] };
+        }
+        try {
+            return JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch {
+            return { proofs: [] };
+        }
+    }
+    write(data) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(data, null, 2));
+    }
+    save(proof) {
+        const data = this.read();
+        data.proofs.unshift(proof);
+        data.proofs = data.proofs.slice(0, 500);
+        this.write(data);
+    }
+    list() {
+        return this.read().proofs;
+    }
+    markSynced(proof_id, merkle_root) {
+        const data = this.read();
+        for (const proof of data.proofs) {
+            if (proof.proof_id === proof_id) {
+                proof.synced = true;
+                if (merkle_root) {
+                    proof.merkle_root = merkle_root;
+                }
+            }
+        }
+        this.write(data);
+    }
+}

package/dist/queue-body.d.ts

@@ -0,0 +1,2 @@
+/** Strip credential/context; persist witness-only bodies for offline resume. */
+export declare function redactProveBodyForQueue(circuitId: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;

package/dist/queue-body.js

@@ -0,0 +1,38 @@
+import { defaultContext } from "./witness.js";
+const WITNESS_PKG = "@affix-io/sdk-witness";
+async function loadWitnessBuilder() {
+    try {
+        const mod = await import(WITNESS_PKG);
+        if (typeof mod.buildLocalWitness !== "function") {
+            throw new Error("witness_export_missing");
+        }
+        return mod.buildLocalWitness;
+    }
+    catch {
+        throw new Error("offline_witness_unavailable: credential-based offline queue requires the private @affix-io/sdk-witness package. " +
+            "Install it from AffixIO, or pass witness/fields instead of credential, or set queueOnFailure: false.");
+    }
+}
+/** Strip credential/context; persist witness-only bodies for offline resume. */
+export async function redactProveBodyForQueue(circuitId, body) {
+    const out = {
+        requestAttestation: body.requestAttestation,
+        sector: body.sector,
+        circuit_id: body.circuit_id ?? circuitId,
+    };
+    if (body.witness && typeof body.witness === "object") {
+        out.witness = body.witness;
+        return out;
+    }
+    const credential = body.credential;
+    if (credential) {
+        const buildLocalWitness = await loadWitnessBuilder();
+        const context = defaultContext(body.context ?? {});
+        out.witness = buildLocalWitness(circuitId, credential, context);
+        return out;
+    }
+    if (body.fields) {
+        out.fields = body.fields;
+    }
+    return out;
+}