@bolyra/sdk 0.2.0

package/src/identity.ts

@@ -0,0 +1,114 @@
+import { HumanIdentity, AgentCredential, Permission } from './types';
+import { poseidon2, poseidon5, eddsaSign, derivePublicKey, derivePublicKeyScalar } from './utils';
+import { InvalidPermissionError } from './errors';
+
+/**
+ * Create a human identity (EdDSA keypair + commitment).
+ * Compatible with Semaphore v4 identity scheme.
+ *
+ * @param secret - A secret value (random bigint or derived from a seed phrase).
+ *                 KEEP THIS PRIVATE — it is the human's authentication key.
+ * @returns HumanIdentity with secret, publicKey, and commitment
+ *
+ * @example
+ * ```ts
+ * const identity = await createHumanIdentity(BigInt(crypto.getRandomValues(new Uint8Array(32)).reduce((a, b) => a * 256n + BigInt(b), 0n)));
+ * console.log(identity.commitment); // Poseidon2(Ax, Ay) — enroll this in humanTree
+ * ```
+ */
+export async function createHumanIdentity(
+  secret: bigint,
+): Promise<HumanIdentity> {
+  // HumanUniqueness circuit uses BabyPbk (direct scalar multiply),
+  // NOT EdDSA prv2pub. Use derivePublicKeyScalar here.
+  const publicKey = await derivePublicKeyScalar(secret);
+  const commitment = await poseidon2(publicKey.x, publicKey.y);
+  return { secret, publicKey, commitment };
+}
+
+/**
+ * Create an AI agent credential signed by the operator.
+ *
+ * @param modelHash - Hash of the model identifier (e.g., sha256("gpt-4o"))
+ * @param operatorPrivateKey - Operator's EdDSA private key (signs the credential)
+ * @param permissions - Array of Permission flags (cumulative encoding enforced)
+ * @param expiryTimestamp - Unix timestamp when the credential expires
+ * @returns AgentCredential with all fields + operator signature + commitment
+ *
+ * @example
+ * ```ts
+ * const credential = await createAgentCredential(
+ *   hashModel("gpt-4o"),
+ *   operatorKey,
+ *   [Permission.READ_DATA, Permission.WRITE_DATA, Permission.FINANCIAL_SMALL],
+ *   BigInt(Math.floor(Date.now() / 1000) + 86400) // +1 day
+ * );
+ * console.log(credential.commitment); // enroll this in agentTree
+ * ```
+ */
+export async function createAgentCredential(
+  modelHash: bigint,
+  operatorPrivateKey: bigint | Buffer,
+  permissions: Permission[],
+  expiryTimestamp: bigint,
+): Promise<AgentCredential> {
+  const bitmask = permissionsToBitmask(permissions);
+  validateCumulativeBitEncoding(bitmask);
+
+  const operatorPublicKey = await derivePublicKey(
+    typeof operatorPrivateKey === 'bigint'
+      ? operatorPrivateKey
+      : BigInt('0x' + operatorPrivateKey.toString('hex')),
+  );
+
+  const commitment = await poseidon5(
+    modelHash,
+    operatorPublicKey.x,
+    operatorPublicKey.y,
+    bitmask,
+    expiryTimestamp,
+  );
+
+  const signature = await eddsaSign(operatorPrivateKey, commitment);
+
+  return {
+    modelHash,
+    operatorPublicKey,
+    permissionBitmask: bitmask,
+    expiryTimestamp,
+    signature,
+    commitment,
+  };
+}
+
+/** Convert an array of Permission flags to a 64-bit bitmask */
+export function permissionsToBitmask(permissions: Permission[]): bigint {
+  let bitmask = 0n;
+  for (const p of permissions) {
+    bitmask |= 1n << BigInt(p);
+  }
+  return bitmask;
+}
+
+/** Validate cumulative bit encoding: bit 4 implies 2+3, bit 3 implies 2 */
+export function validateCumulativeBitEncoding(bitmask: bigint): void {
+  const bit2 = (bitmask >> 2n) & 1n;
+  const bit3 = (bitmask >> 3n) & 1n;
+  const bit4 = (bitmask >> 4n) & 1n;
+
+  if (bit4 && !bit3) {
+    throw new InvalidPermissionError(
+      'FINANCIAL_UNLIMITED (bit 4) requires FINANCIAL_MEDIUM (bit 3)',
+    );
+  }
+  if (bit4 && !bit2) {
+    throw new InvalidPermissionError(
+      'FINANCIAL_UNLIMITED (bit 4) requires FINANCIAL_SMALL (bit 2)',
+    );
+  }
+  if (bit3 && !bit2) {
+    throw new InvalidPermissionError(
+      'FINANCIAL_MEDIUM (bit 3) requires FINANCIAL_SMALL (bit 2)',
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// Core types
+export type {
+  HumanIdentity,
+  AgentCredential,
+  HandshakeResult,
+  DelegationResult,
+  Proof,
+  BolyraConfig,
+} from './types';
+
+// Permission enum
+export { Permission } from './types';
+
+// Identity creation
+export {
+  createHumanIdentity,
+  createAgentCredential,
+  permissionsToBitmask,
+  validateCumulativeBitEncoding,
+} from './identity';
+
+// Handshake (v0.2 — real proof generation via snarkjs)
+export { proveHandshake, verifyHandshake } from './handshake';
+
+// Delegation (stubs — coming in v0.3)
+export { delegate, verifyDelegation } from './delegation';
+
+// Errors
+export {
+  BolyraError,
+  ProofGenerationError,
+  VerificationError,
+  InvalidPermissionError,
+  ExpiredCredentialError,
+  ScopeEscalationError,
+  StaleProofError,
+} from './errors';

package/src/snarkjs.d.ts

@@ -0,0 +1,26 @@
+declare module 'snarkjs' {
+  export namespace groth16 {
+    function fullProve(
+      input: any,
+      wasmPath: string,
+      zkeyPath: string,
+    ): Promise<{ proof: any; publicSignals: string[] }>;
+    function verify(
+      vkey: any,
+      publicSignals: string[],
+      proof: any,
+    ): Promise<boolean>;
+  }
+  export namespace plonk {
+    function fullProve(
+      input: any,
+      wasmPath: string,
+      zkeyPath: string,
+    ): Promise<{ proof: any; publicSignals: string[] }>;
+    function verify(
+      vkey: any,
+      publicSignals: string[],
+      proof: any,
+    ): Promise<boolean>;
+  }
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+/** 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 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; // snarkjs proof object
+  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;
+}

package/src/utils.ts

@@ -0,0 +1,97 @@
+/**
+ * Lazy-initialized crypto primitives.
+ * circomlibjs requires async factory calls; we cache them on first use.
+ */
+
+let _poseidon: any = null;
+let _eddsa: any = null;
+let _babyJub: any = null;
+let _F: any = null;
+
+async function ensureCrypto(): Promise<void> {
+  if (_poseidon) return;
+  const circomlibjs = await import('circomlibjs');
+  _poseidon = await circomlibjs.buildPoseidon();
+  _eddsa = await circomlibjs.buildEddsa();
+  _babyJub = await circomlibjs.buildBabyjub();
+  _F = _poseidon.F;
+}
+
+/** Poseidon hash with 2 inputs. Returns a bigint. */
+export async function poseidon2(a: bigint, b: bigint): Promise<bigint> {
+  await ensureCrypto();
+  const hash = _poseidon([a, b]);
+  return _F.toObject(hash);
+}
+
+/** Poseidon hash with 5 inputs. Returns a bigint. */
+export async function poseidon5(
+  a: bigint,
+  b: bigint,
+  c: bigint,
+  d: bigint,
+  e: bigint,
+): Promise<bigint> {
+  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.
+ */
+export async function derivePublicKey(
+  secret: bigint | Buffer,
+): Promise<{ x: bigint; y: bigint }> {
+  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.
+ */
+export async function derivePublicKeyScalar(
+  secret: bigint,
+): Promise<{ x: bigint; y: bigint }> {
+  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. */
+export async function eddsaSign(
+  privateKey: bigint | Buffer,
+  message: bigint,
+): Promise<{ R8: { x: bigint; y: bigint }; S: bigint }> {
+  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,
+  };
+}