@oleary-labs/signet-sdk 0.1.0

package/src/jwks.ts

@@ -0,0 +1,92 @@
+/**
+ * JWKS (JSON Web Key Set) fetcher.
+ *
+ * Fetches RSA public keys from any OIDC-compliant issuer and extracts
+ * the modulus needed for the ZK proof witness. Supports Google, Clerk,
+ * and any issuer with a standard JWKS endpoint.
+ */
+
+import type { JWKSKey } from "./types";
+
+const GOOGLE_JWKS_URI = "https://www.googleapis.com/oauth2/v3/certs";
+
+// Cache per issuer URI
+const cache = new Map<string, { keys: JWKSKey[]; expiry: number }>();
+const CACHE_TTL = 3600_000; // 1 hour
+
+/**
+ * Derive the JWKS URI from a JWT issuer.
+ * Google uses a non-standard path; all other OIDC issuers use /.well-known/jwks.json.
+ */
+function jwksUriForIssuer(issuer: string): string {
+  if (issuer === "https://accounts.google.com") {
+    return GOOGLE_JWKS_URI;
+  }
+  // Standard OIDC convention
+  const base = issuer.endsWith("/") ? issuer.slice(0, -1) : issuer;
+  return `${base}/.well-known/jwks.json`;
+}
+
+/**
+ * Fetch JWKS keys for an issuer.
+ */
+export async function fetchJWKS(issuer?: string): Promise<JWKSKey[]> {
+  const uri = jwksUriForIssuer(issuer ?? "https://accounts.google.com");
+  const cached = cache.get(uri);
+  if (cached && Date.now() < cached.expiry) {
+    return cached.keys;
+  }
+
+  const res = await fetch(uri);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch JWKS from ${uri}: ${res.status}`);
+  }
+
+  const data = await res.json();
+  const keys = data.keys as JWKSKey[];
+  cache.set(uri, { keys, expiry: Date.now() + CACHE_TTL });
+  return keys;
+}
+
+/** @deprecated Use fetchJWKS() instead */
+export const fetchGoogleJWKS = () => fetchJWKS("https://accounts.google.com");
+
+/**
+ * Find the RSA key matching a JWT's kid.
+ * If issuer is provided, fetches from that issuer's JWKS endpoint.
+ */
+export async function getJWKSKeyForKid(kid: string, issuer?: string): Promise<JWKSKey> {
+  const keys = await fetchJWKS(issuer);
+  const key = keys.find((k) => k.kid === kid);
+  if (!key) {
+    throw new Error(`No JWKS key found for kid: ${kid}`);
+  }
+  if (key.kty !== "RSA") {
+    throw new Error(`Expected RSA key, got ${key.kty}`);
+  }
+  return key;
+}
+
+/**
+ * Decode a base64url-encoded JWKS modulus to a BigInt.
+ */
+export function decodeModulus(base64url: string): bigint {
+  const binary = atob(base64url.replace(/-/g, "+").replace(/_/g, "/"));
+  let hex = "";
+  for (let i = 0; i < binary.length; i++) {
+    hex += binary.charCodeAt(i).toString(16).padStart(2, "0");
+  }
+  return BigInt("0x" + hex);
+}
+
+/**
+ * Decode a base64url-encoded JWKS modulus to raw bytes.
+ */
+export function decodeModulusBytes(base64url: string): Uint8Array {
+  const binary = atob(base64url.replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/jwt.ts

@@ -0,0 +1,74 @@
+/**
+ * JWT parsing utilities for ZK proof witness construction.
+ *
+ * Extracts the components needed by the noir jwt_auth circuit:
+ * - Signed data (header.payload as raw bytes)
+ * - RSA signature (decoded from base64url)
+ * - Key ID (kid) from the header for JWKS lookup
+ */
+
+import type { IdTokenClaims } from "./types";
+
+/** Parsed JWT components needed for proof generation. */
+export interface ParsedJWT {
+  /** Raw signed data: base64(header) + "." + base64(payload) as bytes */
+  signedData: Uint8Array;
+  /** Base64-decoded RSA signature bytes */
+  signatureBytes: Uint8Array;
+  /** Key ID from the JWT header — used to find the right JWKS key */
+  kid: string;
+  /** Decoded payload claims */
+  claims: IdTokenClaims;
+  /** Offset where base64-encoded payload starts (header length + 1 for the dot) */
+  base64DecodeOffset: number;
+}
+
+/**
+ * Parse a JWT into its components for ZK proof generation.
+ */
+export function parseJWT(jwt: string): ParsedJWT {
+  const parts = jwt.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid JWT: expected 3 parts");
+  }
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // Decode header to get kid
+  const header = JSON.parse(base64urlDecode(headerB64));
+  if (header.alg !== "RS256") {
+    throw new Error(`Unsupported JWT algorithm: ${header.alg}`);
+  }
+
+  // Signed data is the raw ASCII bytes of "header.payload"
+  const signedDataStr = `${headerB64}.${payloadB64}`;
+  const signedData = new TextEncoder().encode(signedDataStr);
+
+  // Decode the RSA signature
+  const signatureBytes = base64urlDecodeBytes(signatureB64);
+
+  // Decode claims
+  const claims = JSON.parse(base64urlDecode(payloadB64)) as IdTokenClaims;
+
+  return {
+    signedData,
+    signatureBytes,
+    kid: header.kid,
+    claims,
+    base64DecodeOffset: headerB64.length + 1,
+  };
+}
+
+function base64urlDecode(s: string): string {
+  const padded = s.replace(/-/g, "+").replace(/_/g, "/");
+  return atob(padded);
+}
+
+function base64urlDecodeBytes(s: string): Uint8Array {
+  const decoded = base64urlDecode(s);
+  const bytes = new Uint8Array(decoded.length);
+  for (let i = 0; i < decoded.length; i++) {
+    bytes[i] = decoded.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/keygen.ts

@@ -0,0 +1,89 @@
+/**
+ * Distributed key generation via bootstrap nodes.
+ *
+ * After auth, call keygen to create a key shard for the session identity.
+ * 409 (key already exists) is treated as success — the key was already created
+ * in a previous session.
+ */
+
+import type { SessionKeypair, IdTokenClaims } from "./types";
+import { signKeygenRequest } from "./request";
+
+export interface KeygenConfig {
+  nodeUrls: string[];
+  groupId: string;
+  /** Proxy endpoint for CORS */
+  proxyEndpoint?: string;
+}
+
+export interface KeygenResult {
+  keyId: string;
+  ethereumAddress: string;
+  groupPublicKey: string;
+  alreadyExisted: boolean;
+}
+
+/**
+ * Trigger keygen on a bootstrap node.
+ * If the key already exists (409), returns success with alreadyExisted=true.
+ */
+export async function keygen(
+  config: KeygenConfig,
+  keypair: SessionKeypair,
+  claims: IdTokenClaims,
+  keySuffix?: string,
+  identity?: string,
+  curve?: string,
+  scope?: string,
+): Promise<KeygenResult> {
+  const req = await signKeygenRequest(keypair, claims, config.groupId, keySuffix, identity);
+
+  // Try the first node (keygen only needs to be initiated on one node)
+  const nodeUrl = config.nodeUrls[0];
+  const url = config.proxyEndpoint
+    ? config.proxyEndpoint
+    : `${nodeUrl}/v1/keygen`;
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (config.proxyEndpoint) {
+    headers["x-node-url"] = nodeUrl;
+    headers["x-node-path"] = "/v1/keygen";
+  }
+
+  // Add optional curve and scope to the request body
+  const body: Record<string, unknown> = { ...req };
+  if (curve) body.curve = curve;
+  if (scope) body.scope = scope;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  if (res.status === 409) {
+    // Key already exists — node now returns full key info on 409
+    const data = await res.json();
+    return {
+      keyId: data.key_id ?? `${claims.iss}:${claims.sub}${keySuffix ? `:${keySuffix}` : ""}`,
+      ethereumAddress: data.ethereum_address ?? "",
+      groupPublicKey: data.public_key ?? "",
+      alreadyExisted: true,
+    };
+  }
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Keygen failed: ${res.status} — ${body}`);
+  }
+
+  const data = await res.json();
+  return {
+    keyId: data.key_id,
+    ethereumAddress: data.ethereum_address,
+    groupPublicKey: data.public_key,
+    alreadyExisted: false,
+  };
+}

package/src/oauth.ts

@@ -0,0 +1,157 @@
+/**
+ * Google OAuth PKCE flow.
+ *
+ * Framework-agnostic — uses browser APIs only (sessionStorage, crypto, location).
+ * The token exchange itself is delegated to a caller-provided endpoint
+ * so the client_secret stays server-side.
+ */
+
+import type { IdTokenClaims } from "./types";
+
+function base64urlEncode(buf: ArrayBuffer | Uint8Array): string {
+  return btoa(String.fromCharCode(...new Uint8Array(buf)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+}
+
+function generateVerifier(): string {
+  const buf = new Uint8Array(32);
+  crypto.getRandomValues(buf);
+  return base64urlEncode(buf);
+}
+
+async function generateChallenge(verifier: string): Promise<string> {
+  const data = new TextEncoder().encode(verifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return base64urlEncode(digest);
+}
+
+export interface OAuthConfig {
+  clientId: string;
+  callbackPath?: string; // defaults to "/auth/callback"
+}
+
+/**
+ * Kick off the Google OAuth PKCE flow.
+ * Stores PKCE state in sessionStorage and redirects to Google.
+ */
+export async function startGoogleOAuth(
+  config: OAuthConfig,
+  returnTo?: string
+): Promise<void> {
+  if (!config.clientId) {
+    throw new Error("Google Client ID not configured");
+  }
+
+  const verifier = generateVerifier();
+  const challenge = await generateChallenge(verifier);
+  const state = base64urlEncode(
+    crypto.getRandomValues(new Uint8Array(16))
+  );
+
+  sessionStorage.setItem("signet_oauth_verifier", verifier);
+  sessionStorage.setItem("signet_oauth_state", state);
+  sessionStorage.setItem(
+    "signet_oauth_return_to",
+    returnTo ?? window.location.pathname
+  );
+
+  const callbackPath = config.callbackPath ?? "/auth/callback";
+  const redirectUri = `${window.location.origin}${callbackPath}`;
+
+  const params = new URLSearchParams({
+    client_id: config.clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: "openid profile email",
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    state,
+  });
+
+  window.location.href = `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
+}
+
+/**
+ * Handle the OAuth callback: validate state, exchange code for tokens.
+ *
+ * @param tokenEndpoint — URL of the server-side token exchange endpoint
+ * @returns The raw JWT id_token string, or throws on error.
+ */
+export async function handleOAuthCallback(
+  tokenEndpoint: string
+): Promise<string> {
+  const params = new URLSearchParams(window.location.search);
+  const code = params.get("code");
+  const state = params.get("state");
+  const error = params.get("error");
+
+  if (error) {
+    throw new Error(
+      `Google OAuth error: ${error} — ${params.get("error_description") ?? ""}`
+    );
+  }
+
+  if (!code) {
+    throw new Error("No authorization code received");
+  }
+
+  const savedState = sessionStorage.getItem("signet_oauth_state");
+  if (state !== savedState) {
+    throw new Error("State mismatch — possible CSRF attack");
+  }
+
+  const verifier = sessionStorage.getItem("signet_oauth_verifier");
+  const callbackUri = window.location.origin + window.location.pathname;
+
+  // Clean up PKCE state
+  sessionStorage.removeItem("signet_oauth_state");
+  sessionStorage.removeItem("signet_oauth_verifier");
+
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      code,
+      code_verifier: verifier,
+      redirect_uri: callbackUri,
+    }),
+  });
+
+  const data = await res.json();
+
+  if (data.error) {
+    throw new Error(
+      `Token exchange failed: ${data.error} — ${data.error_description ?? ""}`
+    );
+  }
+
+  return data.id_token;
+}
+
+/**
+ * Decode a JWT payload without verification.
+ * Signature verification happens via ZK proof.
+ */
+export function decodeIdToken(jwt: string): IdTokenClaims {
+  const payload = jwt.split(".")[1];
+  const decoded = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+  const claims = JSON.parse(decoded);
+  // Preserve original aud/azp presence for ZK proof public input matching.
+  // If the JWT doesn't have aud or azp, keep them empty so the prover
+  // and verifier agree on the same (empty) public inputs.
+  if (claims.aud === undefined) claims.aud = "";
+  if (claims.azp === undefined) claims.azp = "";
+  if (claims.email === undefined) claims.email = "";
+  return claims;
+}
+
+/**
+ * Get the return-to path stored before the OAuth redirect.
+ */
+export function getOAuthReturnTo(): string {
+  const returnTo = sessionStorage.getItem("signet_oauth_return_to") ?? "/";
+  sessionStorage.removeItem("signet_oauth_return_to");
+  return returnTo;
+}

package/src/partial-sha.ts

@@ -0,0 +1,99 @@
+// Returns the intermediate SHA256 hash of the data
+export async function generatePartialSHA256(data: Uint8Array, hashUntilIndex: number) {
+  if (typeof data === 'string') {
+    const encoder = new TextEncoder();
+    data = encoder.encode(data); // Convert string to Uint8Array
+  }
+
+  const blockSize = 64; // 512 bits
+  const blockIndex = Math.floor(hashUntilIndex / blockSize);
+  const H = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+    0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19
+  ]);
+
+  for (let i = 0; i < blockIndex; i++) {
+    if (i * blockSize >= data.length) {
+      throw new Error('Block index out of range.');
+    }
+
+    const block = new Uint8Array(blockSize);
+    block.set(data.slice(i * blockSize, (i + 1) * blockSize));
+    sha256Block(H, block);
+  }
+
+  // Get the intermediate digest (this is **not** the final hash)
+  return {
+    partialHash: H,
+    remainingData: data.slice(blockIndex * blockSize)
+  }
+}
+
+/**
+ * SHA-256 constants (first 32 bits of fractional parts of cube roots of primes)
+ */
+const K = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+];
+
+/**
+* Rotate right function (SHA-256 bitwise operations)
+*/
+function rotr(n: number, x: number) {
+  return (x >>> n) | (x << (32 - n));
+}
+
+/**
+* SHA-256 Compression Function (Processes 64-byte blocks)
+*/
+function sha256Block(H: Uint32Array, block: Uint8Array) {
+  let w = new Uint32Array(64);
+  let a = H[0], b = H[1], c = H[2], d = H[3];
+  let e = H[4], f = H[5], g = H[6], h = H[7];
+
+  // Convert block into 32-bit words
+  for (let i = 0; i < 16; i++) {
+    w[i] = (block[i * 4] << 24) | (block[i * 4 + 1] << 16) | (block[i * 4 + 2] << 8) | block[i * 4 + 3];
+  }
+  for (let i = 16; i < 64; i++) {
+    const s0 = rotr(7, w[i - 15]) ^ rotr(18, w[i - 15]) ^ (w[i - 15] >>> 3);
+    const s1 = rotr(17, w[i - 2]) ^ rotr(19, w[i - 2]) ^ (w[i - 2] >>> 10);
+    w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+  }
+
+  // Main compression loop
+  for (let i = 0; i < 64; i++) {
+    const S1 = rotr(6, e) ^ rotr(11, e) ^ rotr(25, e);
+    const ch = (e & f) ^ (~e & g);
+    const temp1 = (h + S1 + ch + K[i] + w[i]) >>> 0;
+    const S0 = rotr(2, a) ^ rotr(13, a) ^ rotr(22, a);
+    const maj = (a & b) ^ (a & c) ^ (b & c);
+    const temp2 = (S0 + maj) >>> 0;
+
+    h = g;
+    g = f;
+    f = e;
+    e = (d + temp1) >>> 0;
+    d = c;
+    c = b;
+    b = a;
+    a = (temp1 + temp2) >>> 0;
+  }
+
+  // Update intermediate hash values
+  H[0] = (H[0] + a) >>> 0;
+  H[1] = (H[1] + b) >>> 0;
+  H[2] = (H[2] + c) >>> 0;
+  H[3] = (H[3] + d) >>> 0;
+  H[4] = (H[4] + e) >>> 0;
+  H[5] = (H[5] + f) >>> 0;
+  H[6] = (H[6] + g) >>> 0;
+  H[7] = (H[7] + h) >>> 0;
+}

package/src/proof.ts

@@ -0,0 +1,99 @@
+/**
+ * Client-side ZK proof generation for JWT authentication.
+ *
+ * Runs entirely in the browser:
+ * 1. Parse JWT + fetch JWKS → build circuit witness
+ * 2. @noir-lang/noir_js → generate ACIR witness from compiled circuit
+ * 3. @aztec/bb.js → generate UltraHonk proof via WASM
+ *
+ * Expected time: ~2-7 seconds in a modern browser.
+ */
+
+import { Noir } from "@noir-lang/noir_js";
+import { UltraHonkBackend } from "@aztec/bb.js";
+import { jwt as jwtArtifacts, assertBbJsVersion } from "@oleary-labs/signet-circuits";
+import { decodeIdToken } from "./oauth";
+import { getJWKSKeyForKid, decodeModulusBytes } from "./jwks";
+import { buildFullWitness } from "./witness";
+import { hexToBytes } from "./session";
+import type { IdTokenClaims } from "./types";
+
+/** Proof generation result. */
+export interface ProofResult {
+  proof: Uint8Array;
+  publicInputs: string[];
+  claims: IdTokenClaims;
+}
+
+// Circuit artifact from @signet/circuits — embedded at build time.
+const circuit = jwtArtifacts.circuit;
+
+/**
+ * Generate a ZK proof that a JWT is valid — entirely client-side.
+ *
+ * @param jwt — raw JWT string (header.payload.signature)
+ * @param sessionPubHex — 33-byte compressed secp256k1 session public key (hex)
+ * @returns proof bytes, public inputs, and decoded claims
+ */
+export async function generateJWTProof(
+  jwt: string,
+  sessionPubHex: string
+): Promise<ProofResult> {
+  // 1. Parse JWT and decode claims
+  const parts = jwt.split(".");
+  const headerB64 = parts[0];
+  const header = JSON.parse(
+    atob(headerB64.replace(/-/g, "+").replace(/_/g, "/"))
+  );
+  const claims = decodeIdToken(jwt);
+
+  // 2. Fetch the RSA key from the issuer's JWKS
+  const jwksKey = await getJWKSKeyForKid(header.kid, claims.iss);
+  const jsonWebKey: JsonWebKey = {
+    kty: jwksKey.kty,
+    n: jwksKey.n,
+    e: jwksKey.e,
+    alg: jwksKey.alg,
+  };
+
+  // 3. Build full circuit witness
+  const sessionPubBytes = Array.from(hexToBytes(sessionPubHex));
+  const witness = await buildFullWitness(jwt, jsonWebKey, claims, sessionPubBytes);
+
+  // 4. Version check — fail fast if bb.js doesn't match the circuit artifacts.
+  await assertBbJsVersion();
+
+  // 5. Generate ACIR witness from compiled circuit
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const noir = new Noir(circuit as any);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const { witness: acirWitness } = await noir.execute(witness as any);
+
+  // 6. Generate UltraHonk proof via bb.js WASM
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const backend = new UltraHonkBackend((circuit as any).bytecode);
+  const proofData = await backend.generateProof(acirWitness);
+
+  await backend.destroy();
+
+  return {
+    proof: proofData.proof,
+    publicInputs: proofData.publicInputs,
+    claims,
+  };
+}
+
+/**
+ * Get the RSA modulus bytes for a JWT (for the node auth request).
+ */
+export async function getJWTModulusBytes(jwt: string): Promise<Uint8Array> {
+  const parts = jwt.split(".");
+  const header = JSON.parse(
+    atob(parts[0].replace(/-/g, "+").replace(/_/g, "/"))
+  );
+  const claims = JSON.parse(
+    atob(parts[1].replace(/-/g, "+").replace(/_/g, "/"))
+  );
+  const jwksKey = await getJWKSKeyForKid(header.kid, claims.iss);
+  return decodeModulusBytes(jwksKey.n);
+}