@bolyra/sdk 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/** EdDSA identity for a human participant */
+export interface HumanIdentity {
+    /** EdDSA secret scalar (KEEP PRIVATE) */
+    secret: bigint;
+    /** Baby Jubjub public key coordinates */
+    publicKey: {
+        x: bigint;
+        y: bigint;
+    };
+    /** Poseidon2(Ax, Ay) — leaf in humanTree */
+    commitment: bigint;
+}
+/** AI agent credential */
+export interface AgentCredential {
+    modelHash: bigint;
+    operatorPublicKey: {
+        x: bigint;
+        y: bigint;
+    };
+    permissionBitmask: bigint;
+    expiryTimestamp: bigint;
+    /** EdDSA signature of operator over credential commitment */
+    signature: {
+        R8: {
+            x: bigint;
+            y: bigint;
+        };
+        S: bigint;
+    };
+    /** Poseidon5(modelHash, Ax, Ay, bitmask, expiry) — leaf in agentTree */
+    commitment: bigint;
+}
+/** Permission bits (cumulative encoding) */
+export declare enum Permission {
+    READ_DATA = 0,
+    WRITE_DATA = 1,
+    FINANCIAL_SMALL = 2,// < $100
+    FINANCIAL_MEDIUM = 3,// < $10,000 (implies SMALL)
+    FINANCIAL_UNLIMITED = 4,// unlimited (implies MEDIUM + SMALL)
+    SIGN_ON_BEHALF = 5,
+    SUB_DELEGATE = 6,
+    ACCESS_PII = 7
+}
+/** Result of a mutual handshake verification */
+export interface HandshakeResult {
+    /** Human's nullifier (unique per scope) */
+    humanNullifier: bigint;
+    /** Agent's nullifier (unique per session) */
+    agentNullifier: bigint;
+    /** Session nonce used */
+    sessionNonce: bigint;
+    /** Agent's scope commitment (chain seed for delegation) */
+    scopeCommitment: bigint;
+    /** Whether the handshake was verified on-chain */
+    verified: boolean;
+}
+/** Result of a delegation */
+export interface DelegationResult {
+    /** New scope commitment for the next hop */
+    newScopeCommitment: bigint;
+    /** Delegation nullifier (unique per delegation per session) */
+    delegationNullifier: bigint;
+    /** Hop number in the chain (0-indexed) */
+    hopIndex: number;
+}
+/** Proof with public signals ready for on-chain verification */
+export interface Proof {
+    proof: any;
+    publicSignals: string[];
+}
+/** Configuration for the SDK */
+export interface BolyraConfig {
+    /** RPC URL for the target chain (default: Base Sepolia) */
+    rpcUrl?: string;
+    /** Address of the IdentityRegistry contract */
+    registryAddress?: string;
+    /** Path to circuit WASM files (default: bundled) */
+    circuitDir?: string;
+    /** Path to zkey files (default: bundled) */
+    zkeyDir?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,SAAS,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,0BAA0B;AAC1B,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,SAAS,EAAE;QAAE,EAAE,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4CAA4C;AAC5C,oBAAY,UAAU;IACpB,SAAS,IAAI;IACb,UAAU,IAAI;IACd,eAAe,IAAI,CAAM,SAAS;IAClC,gBAAgB,IAAI,CAAK,4BAA4B;IACrD,mBAAmB,IAAI,CAAE,qCAAqC;IAC9D,cAAc,IAAI;IAClB,YAAY,IAAI;IAChB,UAAU,IAAI;CACf;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gEAAgE;AAChE,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,GAAG,CAAC;IACX,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Permission = void 0;
+/** Permission bits (cumulative encoding) */
+var Permission;
+(function (Permission) {
+    Permission[Permission["READ_DATA"] = 0] = "READ_DATA";
+    Permission[Permission["WRITE_DATA"] = 1] = "WRITE_DATA";
+    Permission[Permission["FINANCIAL_SMALL"] = 2] = "FINANCIAL_SMALL";
+    Permission[Permission["FINANCIAL_MEDIUM"] = 3] = "FINANCIAL_MEDIUM";
+    Permission[Permission["FINANCIAL_UNLIMITED"] = 4] = "FINANCIAL_UNLIMITED";
+    Permission[Permission["SIGN_ON_BEHALF"] = 5] = "SIGN_ON_BEHALF";
+    Permission[Permission["SUB_DELEGATE"] = 6] = "SUB_DELEGATE";
+    Permission[Permission["ACCESS_PII"] = 7] = "ACCESS_PII";
+})(Permission || (exports.Permission = Permission = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAsBA,4CAA4C;AAC5C,IAAY,UASX;AATD,WAAY,UAAU;IACpB,qDAAa,CAAA;IACb,uDAAc,CAAA;IACd,iEAAmB,CAAA;IACnB,mEAAoB,CAAA;IACpB,yEAAuB,CAAA;IACvB,+DAAkB,CAAA;IAClB,2DAAgB,CAAA;IAChB,uDAAc,CAAA;AAChB,CAAC,EATW,UAAU,0BAAV,UAAU,QASrB"}

package/dist/utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lazy-initialized crypto primitives.
+ * circomlibjs requires async factory calls; we cache them on first use.
+ */
+/** Poseidon hash with 2 inputs. Returns a bigint. */
+export declare function poseidon2(a: bigint, b: bigint): Promise<bigint>;
+/** Poseidon hash with 5 inputs. Returns a bigint. */
+export declare function poseidon5(a: bigint, b: bigint, c: bigint, d: bigint, e: bigint): Promise<bigint>;
+/**
+ * Derive EdDSA public key from a private key buffer (Baby Jubjub).
+ * Uses eddsa.prv2pub which matches what EdDSAPoseidonVerifier expects:
+ * hash the key, clamp bits per RFC 8032, then multiply base point.
+ *
+ * IMPORTANT: This is NOT the same as babyJub.mulPointEscalar(Base8, scalar).
+ * The HumanUniqueness circuit uses BabyPbk (direct scalar multiply) for
+ * the human identity. The AgentPolicy circuit uses EdDSAPoseidonVerifier
+ * which expects prv2pub-derived keys. Use the right function for each.
+ */
+export declare function derivePublicKey(secret: bigint | Buffer): Promise<{
+    x: bigint;
+    y: bigint;
+}>;
+/**
+ * Derive public key via direct scalar multiplication (Baby Jubjub).
+ * Used by HumanUniqueness circuit's BabyPbk component.
+ */
+export declare function derivePublicKeyScalar(secret: bigint): Promise<{
+    x: bigint;
+    y: bigint;
+}>;
+/** Sign a message (field element) with EdDSA. */
+export declare function eddsaSign(privateKey: bigint | Buffer, message: bigint): Promise<{
+    R8: {
+        x: bigint;
+        y: bigint;
+    };
+    S: bigint;
+}>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH,qDAAqD;AACrD,wBAAsB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIrE;AAED,qDAAqD;AACrD,wBAAsB,SAAS,CAC7B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,OAAO,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAYnC;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAOnC;AAED,iDAAiD;AACjD,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,EAAE,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAYtD"}

package/dist/utils.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Lazy-initialized crypto primitives.
+ * circomlibjs requires async factory calls; we cache them on first use.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.poseidon2 = poseidon2;
+exports.poseidon5 = poseidon5;
+exports.derivePublicKey = derivePublicKey;
+exports.derivePublicKeyScalar = derivePublicKeyScalar;
+exports.eddsaSign = eddsaSign;
+let _poseidon = null;
+let _eddsa = null;
+let _babyJub = null;
+let _F = null;
+async function ensureCrypto() {
+    if (_poseidon)
+        return;
+    const circomlibjs = await Promise.resolve().then(() => __importStar(require('circomlibjs')));
+    _poseidon = await circomlibjs.buildPoseidon();
+    _eddsa = await circomlibjs.buildEddsa();
+    _babyJub = await circomlibjs.buildBabyjub();
+    _F = _poseidon.F;
+}
+/** Poseidon hash with 2 inputs. Returns a bigint. */
+async function poseidon2(a, b) {
+    await ensureCrypto();
+    const hash = _poseidon([a, b]);
+    return _F.toObject(hash);
+}
+/** Poseidon hash with 5 inputs. Returns a bigint. */
+async function poseidon5(a, b, c, d, e) {
+    await ensureCrypto();
+    const hash = _poseidon([a, b, c, d, e]);
+    return _F.toObject(hash);
+}
+/**
+ * Derive EdDSA public key from a private key buffer (Baby Jubjub).
+ * Uses eddsa.prv2pub which matches what EdDSAPoseidonVerifier expects:
+ * hash the key, clamp bits per RFC 8032, then multiply base point.
+ *
+ * IMPORTANT: This is NOT the same as babyJub.mulPointEscalar(Base8, scalar).
+ * The HumanUniqueness circuit uses BabyPbk (direct scalar multiply) for
+ * the human identity. The AgentPolicy circuit uses EdDSAPoseidonVerifier
+ * which expects prv2pub-derived keys. Use the right function for each.
+ */
+async function derivePublicKey(secret) {
+    await ensureCrypto();
+    const key = typeof secret === 'bigint'
+        ? Buffer.from(secret.toString(16).padStart(64, '0'), 'hex')
+        : secret;
+    // Use eddsa.prv2pub which matches EdDSAPoseidonVerifier's key derivation
+    const pubKey = _eddsa.prv2pub(key);
+    return {
+        x: _F.toObject(pubKey[0]),
+        y: _F.toObject(pubKey[1]),
+    };
+}
+/**
+ * Derive public key via direct scalar multiplication (Baby Jubjub).
+ * Used by HumanUniqueness circuit's BabyPbk component.
+ */
+async function derivePublicKeyScalar(secret) {
+    await ensureCrypto();
+    const pubKey = _babyJub.mulPointEscalar(_babyJub.Base8, secret);
+    return {
+        x: _F.toObject(pubKey[0]),
+        y: _F.toObject(pubKey[1]),
+    };
+}
+/** Sign a message (field element) with EdDSA. */
+async function eddsaSign(privateKey, message) {
+    await ensureCrypto();
+    const key = typeof privateKey === 'bigint'
+        ? Buffer.from(privateKey.toString(16).padStart(64, '0'), 'hex')
+        : privateKey;
+    const msgFe = _F.e(message);
+    const sig = _eddsa.signPoseidon(key, msgFe);
+    return {
+        R8: { x: _F.toObject(sig.R8[0]), y: _F.toObject(sig.R8[1]) },
+        S: sig.S,
+    };
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@bolyra/sdk",
+  "version": "0.2.0",
+  "description": "TypeScript SDK for Bolyra — mutual ZKP authentication for humans and AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@semaphore-protocol/core": "^4.14.0",
+    "snarkjs": "^0.7.4",
+    "circomlibjs": "^0.1.7",
+    "ethers": "^6.13.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "@types/jest": "^29.5.0"
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bolyra/bolyra"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/circomlibjs.d.ts

@@ -0,0 +1,5 @@
+declare module 'circomlibjs' {
+  export function buildPoseidon(): Promise<any>;
+  export function buildEddsa(): Promise<any>;
+  export function buildBabyjub(): Promise<any>;
+}

package/src/delegation.ts

@@ -0,0 +1,45 @@
+import { BolyraError } from './errors';
+import { DelegationResult, Proof, BolyraConfig, AgentCredential } from './types';
+
+/**
+ * Delegate scoped permissions to another agent.
+ * Currently a stub -- full implementation requires the delegation circuit zkey.
+ *
+ * @param delegator - The delegating agent's credential
+ * @param delegatee - The receiving agent's credential
+ * @param parentScopeCommitment - Scope commitment from the parent handshake or delegation
+ * @param hopIndex - Current hop index in the delegation chain (0-indexed)
+ * @param config - SDK configuration
+ * @returns Delegation proof ready for on-chain verification
+ */
+export async function delegate(
+  _delegator: AgentCredential,
+  _delegatee: AgentCredential,
+  _parentScopeCommitment: bigint,
+  _hopIndex: number,
+  _config?: BolyraConfig,
+): Promise<{ proof: Proof; result: DelegationResult }> {
+  throw new BolyraError(
+    'delegate() coming in @bolyra/sdk v0.3 — delegation circuit integration.',
+    'NOT_IMPLEMENTED',
+  );
+}
+
+/**
+ * Verify a delegation proof on-chain.
+ *
+ * @param proof - The delegation ZK proof
+ * @param parentScopeCommitment - Expected parent scope commitment
+ * @param config - SDK configuration
+ * @returns DelegationResult with new scope commitment and hop index
+ */
+export async function verifyDelegation(
+  _proof: Proof,
+  _parentScopeCommitment: bigint,
+  _config?: BolyraConfig,
+): Promise<DelegationResult> {
+  throw new BolyraError(
+    'verifyDelegation() coming in @bolyra/sdk v0.3.',
+    'NOT_IMPLEMENTED',
+  );
+}

package/src/errors.ts

@@ -0,0 +1,69 @@
+export class BolyraError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'BolyraError';
+  }
+}
+
+export class ProofGenerationError extends BolyraError {
+  constructor(circuit: string, reason: string) {
+    super(
+      `Failed to generate ${circuit} proof: ${reason}`,
+      'PROOF_GENERATION_FAILED',
+      { circuit, reason }
+    );
+  }
+}
+
+export class VerificationError extends BolyraError {
+  constructor(reason: string) {
+    super(
+      `On-chain verification failed: ${reason}`,
+      'VERIFICATION_FAILED',
+      { reason }
+    );
+  }
+}
+
+export class InvalidPermissionError extends BolyraError {
+  constructor(message: string) {
+    super(message, 'INVALID_PERMISSION');
+  }
+}
+
+export class ExpiredCredentialError extends BolyraError {
+  constructor(expiryTimestamp: bigint) {
+    super(
+      `Agent credential expired at ${expiryTimestamp}`,
+      'CREDENTIAL_EXPIRED',
+      { expiryTimestamp: expiryTimestamp.toString() }
+    );
+  }
+}
+
+export class ScopeEscalationError extends BolyraError {
+  constructor(delegatorScope: bigint, requestedScope: bigint) {
+    super(
+      `Delegation scope escalation: delegatee scope (${requestedScope}) is not a subset of delegator scope (${delegatorScope})`,
+      'SCOPE_ESCALATION',
+      {
+        delegatorScope: delegatorScope.toString(),
+        requestedScope: requestedScope.toString(),
+      }
+    );
+  }
+}
+
+export class StaleProofError extends BolyraError {
+  constructor(rootType: 'human' | 'agent') {
+    super(
+      `${rootType} Merkle root is stale — the tree was updated after proof generation. Regenerate the proof.`,
+      'STALE_MERKLE_ROOT',
+      { rootType }
+    );
+  }
+}

package/src/handshake.ts

@@ -0,0 +1,186 @@
+import * as snarkjs from 'snarkjs';
+import * as path from 'path';
+import {
+  HumanIdentity,
+  AgentCredential,
+  HandshakeResult,
+  Proof,
+  BolyraConfig,
+} from './types';
+import { ProofGenerationError } from './errors';
+
+// Default paths to circuit artifacts (relative to package root)
+const DEFAULT_CIRCUIT_DIR = path.join(__dirname, '../../circuits/build');
+
+/**
+ * Generate a mutual handshake proof (human + agent).
+ * Both proofs can be generated in parallel for wall-clock optimization.
+ *
+ * @param human - The human's identity (secret + publicKey + commitment)
+ * @param agent - The agent's credential (signed by operator)
+ * @param options - Optional scope, nonce override, and SDK config
+ * @returns Both proofs and the session nonce
+ *
+ * @example
+ * ```ts
+ * const { humanProof, agentProof, nonce } = await proveHandshake(
+ *   humanIdentity,
+ *   agentCredential,
+ *   { scope: 1n }
+ * );
+ * // Submit both proofs to IdentityRegistry.verifyHandshake()
+ * ```
+ */
+export async function proveHandshake(
+  human: HumanIdentity,
+  agent: AgentCredential,
+  options?: {
+    scope?: bigint;
+    nonce?: bigint;
+    config?: BolyraConfig;
+  },
+): Promise<{ humanProof: Proof; agentProof: Proof; nonce: bigint }> {
+  const scope = options?.scope ?? 1n;
+  const nonce = options?.nonce ?? BigInt(Date.now());
+  const circuitDir = options?.config?.circuitDir ?? DEFAULT_CIRCUIT_DIR;
+
+  // Generate both proofs in parallel
+  const [humanProof, agentProof] = await Promise.all([
+    generateHumanProof(human, scope, nonce, circuitDir),
+    generateAgentProof(agent, nonce, circuitDir),
+  ]);
+
+  return { humanProof, agentProof, nonce };
+}
+
+async function generateHumanProof(
+  human: HumanIdentity,
+  scope: bigint,
+  nonce: bigint,
+  circuitDir: string,
+): Promise<Proof> {
+  const wasmPath = path.join(
+    circuitDir,
+    'HumanUniqueness_js/HumanUniqueness.wasm',
+  );
+  const zkeyPath = path.join(circuitDir, 'HumanUniqueness_final.zkey');
+
+  // Build Merkle proof inputs (single leaf: depth 0, padded to 20)
+  const siblings = new Array(20).fill('0');
+
+  const input = {
+    secret: human.secret.toString(),
+    merkleProofLength: '0', // depth 0 for single-leaf tree
+    merkleProofIndex: '0',
+    merkleProofSiblings: siblings,
+    scope: scope.toString(),
+    sessionNonce: nonce.toString(),
+  };
+
+  try {
+    const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+      input,
+      wasmPath,
+      zkeyPath,
+    );
+    return { proof, publicSignals };
+  } catch (err: any) {
+    throw new ProofGenerationError(
+      'HumanUniqueness',
+      err.message ?? String(err),
+    );
+  }
+}
+
+async function generateAgentProof(
+  agent: AgentCredential,
+  nonce: bigint,
+  circuitDir: string,
+): Promise<Proof> {
+  const wasmPath = path.join(
+    circuitDir,
+    'AgentPolicy_js/AgentPolicy.wasm',
+  );
+  const zkeyPath = path.join(circuitDir, 'AgentPolicy_plonk.zkey');
+
+  const currentTimestamp = BigInt(Math.floor(Date.now() / 1000));
+  const requiredScopeMask = 0n; // no required scope for basic handshake
+
+  const siblings = new Array(20).fill('0');
+
+  const input = {
+    modelHash: agent.modelHash.toString(),
+    operatorPubkeyAx: agent.operatorPublicKey.x.toString(),
+    operatorPubkeyAy: agent.operatorPublicKey.y.toString(),
+    permissionBitmask: agent.permissionBitmask.toString(),
+    expiryTimestamp: agent.expiryTimestamp.toString(),
+    sigR8x: agent.signature.R8.x.toString(),
+    sigR8y: agent.signature.R8.y.toString(),
+    sigS: agent.signature.S.toString(),
+    merkleProofLength: '0',
+    merkleProofIndex: '0',
+    merkleProofSiblings: siblings,
+    requiredScopeMask: requiredScopeMask.toString(),
+    currentTimestamp: currentTimestamp.toString(),
+    sessionNonce: nonce.toString(),
+  };
+
+  try {
+    const { proof, publicSignals } = await snarkjs.plonk.fullProve(
+      input,
+      wasmPath,
+      zkeyPath,
+    );
+    return { proof, publicSignals };
+  } catch (err: any) {
+    throw new ProofGenerationError(
+      'AgentPolicy',
+      err.message ?? String(err),
+    );
+  }
+}
+
+/**
+ * Verify a handshake result (check proof validity without on-chain submission).
+ * For on-chain verification, submit proofs to IdentityRegistry.verifyHandshake().
+ *
+ * @param humanProof - The human's ZK proof
+ * @param agentProof - The agent's ZK proof
+ * @param nonce - The session nonce used during proof generation
+ * @param config - SDK configuration (circuitDir for vkey paths)
+ * @returns HandshakeResult with nullifiers and verification status
+ */
+export async function verifyHandshake(
+  humanProof: Proof,
+  agentProof: Proof,
+  nonce: bigint,
+  config?: BolyraConfig,
+): Promise<HandshakeResult> {
+  const circuitDir = config?.circuitDir ?? DEFAULT_CIRCUIT_DIR;
+
+  // Verify human proof (Groth16)
+  const humanVkeyPath = path.join(circuitDir, 'HumanUniqueness_vkey.json');
+  const humanVkey = require(humanVkeyPath);
+  const humanValid = await snarkjs.groth16.verify(
+    humanVkey,
+    humanProof.publicSignals,
+    humanProof.proof,
+  );
+
+  // Verify agent proof (PLONK)
+  const agentVkeyPath = path.join(circuitDir, 'AgentPolicy_vkey.json');
+  const agentVkey = require(agentVkeyPath);
+  const agentValid = await snarkjs.plonk.verify(
+    agentVkey,
+    agentProof.publicSignals,
+    agentProof.proof,
+  );
+
+  return {
+    humanNullifier: BigInt(humanProof.publicSignals[1]),
+    agentNullifier: BigInt(agentProof.publicSignals[1]),
+    sessionNonce: nonce,
+    scopeCommitment: BigInt(agentProof.publicSignals[2]),
+    verified: humanValid && agentValid,
+  };
+}