@oleary-labs/signet-sdk 0.1.0

package/src/request.ts

@@ -0,0 +1,174 @@
+/**
+ * Session-authenticated request signing.
+ *
+ * After auth, every keygen/sign request must include a signature
+ * over the canonical request hash, produced with the session private key.
+ *
+ * Canonical hash: SHA256(groupID ":" keyID ":" nonce ":" timestamp_8BE [":" messageHash])
+ * Signature: 64-byte [R || S] secp256k1 ECDSA (no recovery byte)
+ */
+
+import type { SessionKeypair, IdTokenClaims } from "./types";
+import { bytesToHex } from "./session";
+
+/** Signed request ready to POST to a node. */
+export interface SignedRequest {
+  group_id: string;
+  key_suffix?: string;
+  session_pub: string;
+  request_sig: string;
+  nonce: string;
+  timestamp: number;
+}
+
+/** Signed request with message_hash for /v1/sign. */
+export interface SignedSignRequest extends SignedRequest {
+  message_hash: string;
+}
+
+/**
+ * Derive the key ID that the node will resolve for this session.
+ *
+ * For OAuth sessions: iss:sub or iss:sub:suffix
+ * e.g. https://accounts.google.com:114810956681671373980
+ */
+export function deriveKeyId(claims: IdTokenClaims, keySuffix?: string, identity?: string): string {
+  const base = identity ?? `${claims.iss}:${claims.sub}`;
+  return keySuffix ? `${base}:${keySuffix}` : base;
+}
+
+/**
+ * Build and sign a keygen request.
+ *
+ * @param identity - For auth key cert sessions, pass the identity string.
+ *   The key ID becomes `identity[:suffix]` instead of `iss:sub[:suffix]`.
+ */
+export async function signKeygenRequest(
+  keypair: SessionKeypair,
+  claims: IdTokenClaims,
+  groupId: string,
+  keySuffix?: string,
+  identity?: string,
+): Promise<SignedRequest> {
+  const normalizedGroupId = groupId.toLowerCase();
+  const keyId = deriveKeyId(claims, keySuffix, identity);
+  const nonce = generateNonce();
+  const timestamp = Math.floor(Date.now() / 1000);
+
+  const hash = await canonicalRequestHash(normalizedGroupId, keyId, nonce, timestamp);
+  const sig = await signHash(keypair.privateKey, hash);
+
+  return {
+    group_id: normalizedGroupId,
+    key_suffix: keySuffix,
+    session_pub: keypair.publicKeyHex,
+    request_sig: bytesToHex(sig),
+    nonce,
+    timestamp,
+  };
+}
+
+/**
+ * Build and sign a threshold signing request.
+ */
+export async function signSignRequest(
+  keypair: SessionKeypair,
+  claims: IdTokenClaims,
+  groupId: string,
+  messageHash: Uint8Array,
+  keySuffix?: string,
+  identity?: string,
+): Promise<SignedSignRequest> {
+  const normalizedGroupId = groupId.toLowerCase();
+  const keyId = deriveKeyId(claims, keySuffix, identity);
+  const nonce = generateNonce();
+  const timestamp = Math.floor(Date.now() / 1000);
+
+  const hash = await canonicalRequestHash(
+    normalizedGroupId,
+    keyId,
+    nonce,
+    timestamp,
+    messageHash
+  );
+  const sig = await signHash(keypair.privateKey, hash);
+
+  return {
+    group_id: normalizedGroupId,
+    key_suffix: keySuffix,
+    session_pub: keypair.publicKeyHex,
+    request_sig: bytesToHex(sig),
+    nonce,
+    timestamp,
+    message_hash: bytesToHex(messageHash),
+  };
+}
+
+/**
+ * Compute the canonical request hash matching the Go node's format.
+ *
+ * SHA256(groupID ":" keyID ":" nonce ":" timestamp_8BE [":" messageHash])
+ */
+async function canonicalRequestHash(
+  groupId: string,
+  keyId: string,
+  nonce: string,
+  timestamp: number,
+  messageHash?: Uint8Array
+): Promise<Uint8Array> {
+  const parts: Uint8Array[] = [];
+  const enc = new TextEncoder();
+
+  parts.push(enc.encode(groupId));
+  parts.push(enc.encode(":"));
+  parts.push(enc.encode(keyId));
+  parts.push(enc.encode(":"));
+  parts.push(enc.encode(nonce));
+  parts.push(enc.encode(":"));
+
+  // timestamp as 8-byte big-endian
+  const tsBuf = new ArrayBuffer(8);
+  const view = new DataView(tsBuf);
+  view.setBigUint64(0, BigInt(timestamp));
+  parts.push(new Uint8Array(tsBuf));
+
+  if (messageHash && messageHash.length > 0) {
+    parts.push(enc.encode(":"));
+    parts.push(messageHash);
+  }
+
+  // Concatenate
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const buf = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    buf.set(p, offset);
+    offset += p.length;
+  }
+
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return new Uint8Array(digest);
+}
+
+/**
+ * Sign a 32-byte hash with the session private key.
+ * Returns 64-byte [R || S] signature (no recovery byte).
+ *
+ * Uses signAsync which works without configuring hashes.sha256.
+ * lowS: true to match go-ethereum's crypto.VerifySignature.
+ */
+async function signHash(
+  privateKey: Uint8Array,
+  hash: Uint8Array
+): Promise<Uint8Array> {
+  const { signAsync } = await import("@noble/secp256k1");
+  // prehash: false — our input is already SHA-256'd, don't hash again
+  const sig = await signAsync(hash, privateKey, { lowS: true, prehash: false });
+  return new Uint8Array(sig);
+}
+
+function generateNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return bytesToHex(bytes);
+}

package/src/scopedSign.ts

@@ -0,0 +1,184 @@
+/**
+ * Structured EIP-712 signing for scoped keys.
+ *
+ * Scoped keys reject raw hash signing — the caller must provide a
+ * structured payload that the node verifies against the key's scope
+ * before computing the hash and signing.
+ */
+
+import type { SessionKeypair, IdTokenClaims } from "./types";
+import { signKeygenRequest } from "./request";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EIP712Domain {
+  name?: string;
+  version?: string;
+  chainId: number;
+  verifyingContract: string;
+}
+
+export interface EIP712TypedData {
+  domain: EIP712Domain;
+  types: Record<string, Array<{ name: string; type: string }>>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}
+
+export interface ScopedSignResult {
+  signature: string;       // raw signature hex
+  ecdsaSignature: string;  // ECDSA-formatted (r, s, v)
+  curve: string;
+}
+
+// ---------------------------------------------------------------------------
+// Scope construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an EIP-712 domain scope (scheme 0x03).
+ *
+ * Format: 0x03 | chainId (8 bytes, uint64 BE) | verifyingContract (20 bytes)
+ * Total: 29 bytes.
+ */
+export function buildEIP712Scope(chainId: number, verifyingContract: string): string {
+  const buf = new Uint8Array(29);
+  buf[0] = 0x03;
+
+  // chainId as 8-byte big-endian
+  const view = new DataView(buf.buffer);
+  view.setBigUint64(1, BigInt(chainId));
+
+  // verifyingContract as 20 bytes
+  const addr = verifyingContract.startsWith("0x")
+    ? verifyingContract.slice(2)
+    : verifyingContract;
+  for (let i = 0; i < 20; i++) {
+    buf[9 + i] = parseInt(addr.slice(i * 2, i * 2 + 2), 16);
+  }
+
+  return "0x" + Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// ---------------------------------------------------------------------------
+// Structured signing
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign a structured EIP-712 payload with a scoped key.
+ *
+ * The node extracts the domain from the typed data, verifies it matches
+ * the key's scope, computes hashTypedData, and threshold-signs.
+ *
+ * @param nodeUrl - Target group node URL
+ * @param proxyEndpoint - CORS proxy URL
+ * @param groupId - Group contract address
+ * @param keyId - The scoped sub-key to sign with
+ * @param curve - Key curve (e.g. "ecdsa_secp256k1")
+ * @param typedData - Full EIP-712 typed data structure
+ * @param sessionKeypair - Active session keypair
+ * @param claims - OAuth/identity claims for session auth
+ * @param identity - For auth key cert sessions
+ */
+export async function signTypedData(
+  nodeUrl: string,
+  proxyEndpoint: string,
+  groupId: string,
+  keyId: string,
+  curve: string,
+  typedData: EIP712TypedData,
+  sessionKeypair: SessionKeypair,
+  claims: IdTokenClaims,
+  identity?: string,
+): Promise<ScopedSignResult> {
+  // Build session-authenticated request (no message hash — payload is sent separately)
+  // The canonical hash must use the full sub-key ID (identity + suffix).
+  // Extract suffix from keyId: "oauth:iss:sub:suffix" → suffix is last segment
+  // The identity param is "iss:sub", so we need to add the suffix.
+  const keyParts = keyId.split(":");
+  const keySuffix = keyParts.length > 1 ? keyParts[keyParts.length - 1] : undefined;
+
+  const signReq = await signKeygenRequest(
+    sessionKeypair,
+    claims,
+    groupId,
+    keySuffix,
+    identity,
+  );
+
+  const res = await fetch(proxyEndpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-node-url": nodeUrl,
+      "x-node-path": "/v1/sign",
+    },
+    body: JSON.stringify({
+      group_id: groupId.toLowerCase(),
+      key_id: keyId,
+      key_suffix: keySuffix,
+      curve,
+      payload: {
+        scheme: "eip712",
+        typed_data: typedData,
+      },
+      session_pub: signReq.session_pub,
+      request_sig: signReq.request_sig,
+      nonce: signReq.nonce,
+      timestamp: signReq.timestamp,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Scoped sign failed: ${res.status} — ${body}`);
+  }
+
+  const data = await res.json();
+  return {
+    signature: data.signature,
+    ecdsaSignature: data.ecdsa_signature,
+    curve: data.curve ?? curve,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+export const CHAIN_PRESETS = [
+  {
+    label: "USDC on Base",
+    chainId: 8453,
+    contractName: "USDC",
+    verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    eip712Name: "USD Coin",
+    eip712Version: "2",
+  },
+  {
+    label: "USDC on Base Sepolia",
+    chainId: 84532,
+    contractName: "USDC",
+    verifyingContract: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    eip712Name: "USD Coin",
+    eip712Version: "2",
+  },
+  {
+    label: "USDC on Ethereum",
+    chainId: 1,
+    contractName: "USDC",
+    verifyingContract: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    eip712Name: "USD Coin",
+    eip712Version: "2",
+  },
+  {
+    label: "USDC on Sepolia",
+    chainId: 11155111,
+    contractName: "USDC",
+    verifyingContract: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    eip712Name: "USD Coin",
+    eip712Version: "2",
+  },
+] as const;

package/src/server-prover.ts

@@ -0,0 +1,76 @@
+/**
+ * Server-side ZK proof generation via the bundler's /v1/prove endpoint.
+ *
+ * Delegates JWT proof generation to the bundler instead of running
+ * noir + bb.js client-side via WASM. Faster (~2-3s vs 2-7s) and
+ * avoids shipping heavy WASM binaries to the browser.
+ *
+ * The returned proof + claims + modulus are everything needed to
+ * call authenticateWithBootstrap.
+ */
+
+export interface ServerProofResult {
+  proof: Uint8Array;
+  sub: string;
+  iss: string;
+  exp: number;
+  aud: string;
+  azp: string;
+  jwksModulus: Uint8Array;
+  sessionPub: string;
+}
+
+/**
+ * Generate a ZK proof of a JWT via the bundler's server-side prover.
+ *
+ * @param bundlerProxyUrl - URL of the bundler proxy (e.g. "/api/bundler")
+ * @param jwt - Raw JWT from OAuth provider
+ * @param sessionPubHex - 33-byte compressed secp256k1 public key, hex-encoded
+ */
+export async function generateServerProof(
+  bundlerProxyUrl: string,
+  jwt: string,
+  sessionPubHex: string,
+  apiKey?: string,
+): Promise<ServerProofResult> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "x-bundler-path": "/v1/prove",
+  };
+  if (apiKey) headers["X-API-Key"] = apiKey;
+
+  const res = await fetch(bundlerProxyUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ jwt, session_pub: sessionPubHex }),
+  });
+
+  const result = await res.json();
+
+  if (!res.ok) {
+    const msg = result.error ?? JSON.stringify(result);
+    throw new Error(`Server proof generation failed: ${res.status} — ${msg}`);
+  }
+  if (result.error) {
+    const msg = typeof result.error === "string" ? result.error : JSON.stringify(result.error);
+    throw new Error(`Server proof generation failed: ${msg}`);
+  }
+
+  return {
+    proof: hexToBytes(result.proof),
+    sub: result.sub,
+    iss: result.iss,
+    exp: result.exp,
+    aud: result.aud,
+    azp: result.azp,
+    jwksModulus: hexToBytes(result.jwks_modulus),
+    sessionPub: result.session_pub,
+  };
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  return new Uint8Array(
+    (clean.match(/.{2}/g) ?? []).map((b) => parseInt(b, 16))
+  );
+}

package/src/session.ts

@@ -0,0 +1,33 @@
+/**
+ * Session keypair management (secp256k1).
+ *
+ * Generates an ephemeral keypair for authenticating with bootstrap nodes.
+ * The private key is held in memory only — never persisted.
+ */
+
+import type { SessionKeypair } from "./types";
+
+/**
+ * Generate a new ephemeral secp256k1 session keypair.
+ */
+export async function generateSessionKeypair(): Promise<SessionKeypair> {
+  const { utils, getPublicKey } = await import("@noble/secp256k1");
+  const privateKey = utils.randomSecretKey();
+  const publicKeyBytes = getPublicKey(privateKey, true); // compressed
+  const publicKeyHex = bytesToHex(publicKeyBytes);
+  return { privateKey, publicKeyHex };
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}

package/src/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared types for the Signet SDK.
+ */
+
+/** Decoded Google ID token claims. */
+export interface IdTokenClaims {
+  iss: string; // "https://accounts.google.com"
+  sub: string; // stable numeric user ID
+  email: string;
+  name?: string;
+  picture?: string;
+  azp: string; // OAuth client ID
+  aud: string;
+  exp: number; // unix timestamp
+  iat: number;
+}
+
+/** RSA public key from JWKS. */
+export interface JWKSKey {
+  kid: string;
+  kty: string;
+  alg: string;
+  n: string; // base64url-encoded modulus
+  e: string; // base64url-encoded exponent
+}
+
+/** Session keypair (secp256k1). */
+export interface SessionKeypair {
+  privateKey: Uint8Array;
+  publicKeyHex: string; // 33-byte compressed, hex-encoded
+}
+
+/** Witness inputs for the jwt_auth noir circuit. */
+export interface CircuitWitness {
+  // Private witness
+  data: number[]; // JWT signed data bytes, padded to 1024
+  dataLen: number; // actual length of signed data
+  base64DecodeOffset: number; // header length + 1
+  redcParamsLimbs: string[]; // 18 limbs, decimal strings
+  signatureLimbs: string[]; // 18 limbs, decimal strings
+
+  // Public inputs
+  pubkeyModulusLimbs: string[]; // 18 limbs, decimal strings
+  iss: string;
+  sub: string;
+  exp: number;
+  aud: string;
+  azp: string;
+  sessionPub: number[]; // 33 bytes
+}
+
+/** Auth request body for bootstrap node /v1/auth (OAuth/ZK path). */
+export interface NodeAuthRequest {
+  group_id: string;
+  session_pub: string; // hex
+  proof: string; // hex
+  sub: string;
+  iss: string;
+  exp: number;
+  aud: string;
+  azp: string;
+  jwks_modulus: string; // hex
+}