@oleary-labs/signet-sdk 0.1.0

package/src/admin.ts

@@ -0,0 +1,178 @@
+/**
+ * Admin API authentication for Signet group management.
+ *
+ * Admin auth is stateless: sign SHA256(group_id : nonce : timestamp_BE)
+ * with a trusted auth key. For Schnorr auth keys (prefix 0x01), the
+ * signature is produced via FROST threshold signing through the bootstrap
+ * group.
+ */
+
+import type { SessionKeypair, IdTokenClaims } from "./types";
+import { signSignRequest } from "./request";
+import { bytesToHex } from "./session";
+
+export interface AdminAuthConfig {
+  nodeProxyUrl: string;
+  bootstrapGroup: string;
+  bootstrapNodes: string[];
+}
+
+export interface AdminAuth {
+  group_id: string;
+  auth_key_pub: string;
+  signature: string;
+  nonce: string;
+  timestamp: number;
+}
+
+/**
+ * Build an admin auth payload by threshold-signing the admin hash
+ * via the bootstrap group.
+ *
+ * The admin hash is: SHA256(group_id + ":" + nonce + ":" + timestamp_8BE)
+ * The signature is a 65-byte FROST Schnorr signature.
+ */
+export async function buildAdminAuth(
+  config: AdminAuthConfig,
+  groupId: string,
+  authKeyPub: string,
+  sessionKeypair: SessionKeypair,
+  claims: IdTokenClaims,
+): Promise<AdminAuth> {
+  const normalizedGroupId = groupId.toLowerCase();
+  const nonce = generateNonce();
+  const timestamp = Math.floor(Date.now() / 1000);
+
+  // Build the admin hash: SHA256(group_id + ":" + nonce + ":" + timestamp_8BE)
+  const adminHash = await computeAdminHash(normalizedGroupId, nonce, timestamp);
+
+  // Threshold-sign the hash via bootstrap group
+  const signReq = await signSignRequest(
+    sessionKeypair,
+    claims,
+    config.bootstrapGroup,
+    adminHash,
+  );
+
+  const signRes = await fetch(config.nodeProxyUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-node-url": config.bootstrapNodes[0],
+      "x-node-path": "/v1/sign",
+    },
+    body: JSON.stringify(signReq),
+  });
+
+  if (!signRes.ok) {
+    const body = await signRes.text();
+    throw new Error(`Admin signing failed: ${signRes.status} — ${body}`);
+  }
+
+  const { ethereum_signature } = await signRes.json();
+
+  return {
+    group_id: normalizedGroupId,
+    auth_key_pub: authKeyPub,
+    signature: ethereum_signature,
+    nonce,
+    timestamp,
+  };
+}
+
+/**
+ * Call an admin endpoint with auth.
+ *
+ * If the signing request fails with a 401 "session not found" error and
+ * a reauthenticate callback is provided, re-establishes the node session
+ * and retries once.
+ */
+export async function adminRequest<T>(
+  config: AdminAuthConfig,
+  nodeUrl: string,
+  path: string,
+  groupId: string,
+  authKeyPub: string,
+  sessionKeypair: SessionKeypair,
+  claims: IdTokenClaims,
+  extraBody?: Record<string, unknown>,
+  reauthenticate?: () => Promise<void>,
+): Promise<T> {
+  try {
+    return await adminRequestInner<T>(config, nodeUrl, path, groupId, authKeyPub, sessionKeypair, claims, extraBody);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (reauthenticate && /session not found/i.test(msg)) {
+      await reauthenticate();
+      return await adminRequestInner<T>(config, nodeUrl, path, groupId, authKeyPub, sessionKeypair, claims, extraBody);
+    }
+    throw err;
+  }
+}
+
+async function adminRequestInner<T>(
+  config: AdminAuthConfig,
+  nodeUrl: string,
+  path: string,
+  groupId: string,
+  authKeyPub: string,
+  sessionKeypair: SessionKeypair,
+  claims: IdTokenClaims,
+  extraBody?: Record<string, unknown>,
+): Promise<T> {
+  const auth = await buildAdminAuth(config, groupId, authKeyPub, sessionKeypair, claims);
+
+  const res = await fetch(config.nodeProxyUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-node-url": nodeUrl,
+      "x-node-path": path,
+    },
+    body: JSON.stringify({ ...auth, ...extraBody }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Admin ${path} failed: ${res.status} — ${body}`);
+  }
+
+  return res.json();
+}
+
+async function computeAdminHash(
+  groupId: string,
+  nonce: string,
+  timestamp: number
+): Promise<Uint8Array> {
+  const enc = new TextEncoder();
+  const parts: Uint8Array[] = [];
+
+  parts.push(enc.encode(groupId));
+  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));
+
+  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);
+}
+
+function generateNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return bytesToHex(bytes);
+}

package/src/authkey-session.ts

@@ -0,0 +1,241 @@
+/**
+ * Auth key certificate session flow.
+ *
+ * Creates a node session using an ECDSA auth key certificate instead of
+ * an OAuth/ZK proof. This enables keygen and signing without user login —
+ * useful for backend services, AI agents, or any programmatic access.
+ *
+ * Flow:
+ * 1. Sign a certificate binding an identity + session pub to the auth key
+ * 2. POST /v1/auth with the certificate to establish a session
+ * 3. Use the session key for subsequent keygen/sign requests (same as OAuth flow)
+ *
+ * The identity becomes the key namespace: keys are stored as "authkey:<identity>"
+ * (or "authkey:<identity>:<suffix>" with key_suffix).
+ */
+
+import type { SessionKeypair } from "./types";
+import { bytesToHex } from "./session";
+
+export interface AuthKeyCertConfig {
+  /** Base URL or proxy URL for the node */
+  nodeUrl: string;
+  /** If set, requests go through this proxy (for CORS) */
+  proxyEndpoint?: string;
+}
+
+export interface AuthKeyCertResult {
+  identity: string;
+  expiresAt: number;
+}
+
+/**
+ * Authenticate with a node using an auth key certificate.
+ *
+ * @param config - Node URL / proxy config
+ * @param groupId - Group contract address
+ * @param authPrivateKey - 32-byte ECDSA private key (matches an on-chain auth key)
+ * @param identity - Logical identity string (e.g. "my-backend", "agent-1")
+ * @param sessionKeypair - Ephemeral session keypair for subsequent requests
+ * @param expiry - Certificate expiry (unix seconds). Default: 1 hour from now.
+ */
+export async function authenticateWithAuthKey(
+  config: AuthKeyCertConfig,
+  groupId: string,
+  authPrivateKey: Uint8Array,
+  identity: string,
+  sessionKeypair: SessionKeypair,
+  expiry?: number,
+): Promise<AuthKeyCertResult> {
+  const { getPublicKey, signAsync } = await import("@noble/secp256k1");
+
+  const normalizedGroupId = groupId.toLowerCase();
+  const certExpiry = expiry ?? Math.floor(Date.now() / 1000) + 3600;
+
+  // Derive the auth key public key (with ECDSA prefix 0x00)
+  const authPubBytes = getPublicKey(authPrivateKey, true);
+  const authKeyPub = `0x00${bytesToHex(authPubBytes)}`;
+
+  // Sign certificate: SHA256(identity + ":" + group_id + ":" + session_pub_hex + ":" + expiry_8BE)
+  const certHash = await computeCertHash(
+    identity,
+    normalizedGroupId,
+    sessionKeypair.publicKeyHex,
+    certExpiry,
+  );
+  const certSig = await signAsync(certHash, authPrivateKey, {
+    lowS: true,
+    prehash: false,
+  });
+  const certSigHex = bytesToHex(new Uint8Array(certSig));
+
+  // POST /v1/auth with certificate
+  const url = config.proxyEndpoint ?? `${config.nodeUrl}/v1/auth`;
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (config.proxyEndpoint) {
+    headers["x-node-url"] = config.nodeUrl;
+    headers["x-node-path"] = "/v1/auth";
+  }
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      group_id: normalizedGroupId,
+      session_pub: sessionKeypair.publicKeyHex,
+      certificate: {
+        identity,
+        expiry: certExpiry,
+        auth_key_pub: authKeyPub,
+        signature: certSigHex,
+      },
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Auth key auth failed: ${res.status} — ${body}`);
+  }
+
+  const data = await res.json();
+  return {
+    identity: data.identity ?? identity,
+    expiresAt: data.expires_at ?? certExpiry,
+  };
+}
+
+/**
+ * Authenticate with a node using a Schnorr auth key certificate.
+ *
+ * The certificate hash is threshold-signed via the bootstrap group (FROST),
+ * producing a 65-byte Schnorr signature. This works for auth keys registered
+ * on-chain with the 0x01 (Schnorr) prefix.
+ *
+ * @param config - Bootstrap group config for threshold signing
+ * @param targetNodeUrl - The target group node to authenticate with
+ * @param proxyEndpoint - CORS proxy URL
+ * @param targetGroupId - The target group contract address
+ * @param authKeyPub - Auth key with 0x01 prefix (e.g. "0x0103d767f7...")
+ * @param identity - Logical identity string (e.g. "key-tester")
+ * @param sessionKeypair - Session keypair for the target group node
+ * @param bootstrapSessionKeypair - Session keypair for the bootstrap group (already authed)
+ * @param claims - OAuth claims for signing requests to the bootstrap group
+ * @param expiry - Certificate expiry (unix seconds). Default: 1 hour from now.
+ */
+export async function authenticateWithSchnorrAuthKey(
+  config: {
+    bootstrapGroup: string;
+    bootstrapNodes: string[];
+    nodeProxyUrl: string;
+  },
+  targetNodeUrl: string,
+  proxyEndpoint: string,
+  targetGroupId: string,
+  authKeyPub: string,
+  identity: string,
+  sessionKeypair: SessionKeypair,
+  bootstrapSessionKeypair: SessionKeypair,
+  claims: { iss: string; sub: string },
+  expiry?: number,
+): Promise<AuthKeyCertResult> {
+  const { signSignRequest } = await import("./request");
+
+  const normalizedGroupId = targetGroupId.toLowerCase();
+  const certExpiry = expiry ?? Math.floor(Date.now() / 1000) + 3600;
+
+  // Compute certificate hash
+  const certHash = await computeCertHash(
+    identity,
+    normalizedGroupId,
+    sessionKeypair.publicKeyHex,
+    certExpiry,
+  );
+
+  // Threshold-sign the cert hash via bootstrap group
+  const signReq = await signSignRequest(
+    bootstrapSessionKeypair,
+    claims as unknown as import("./types").IdTokenClaims,
+    config.bootstrapGroup,
+    certHash,
+  );
+
+  const signRes = await fetch(config.nodeProxyUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-node-url": config.bootstrapNodes[0],
+      "x-node-path": "/v1/sign",
+    },
+    body: JSON.stringify(signReq),
+  });
+
+  if (!signRes.ok) {
+    const body = await signRes.text();
+    throw new Error(`Schnorr cert signing failed: ${signRes.status} — ${body}`);
+  }
+
+  const { ethereum_signature } = await signRes.json();
+
+  // POST /v1/auth on the target group node with the Schnorr-signed certificate
+  const res = await fetch(proxyEndpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-node-url": targetNodeUrl,
+      "x-node-path": "/v1/auth",
+    },
+    body: JSON.stringify({
+      group_id: normalizedGroupId,
+      session_pub: sessionKeypair.publicKeyHex,
+      certificate: {
+        identity,
+        expiry: certExpiry,
+        auth_key_pub: authKeyPub,
+        signature: ethereum_signature,
+      },
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Schnorr auth key auth failed: ${res.status} — ${body}`);
+  }
+
+  const data = await res.json();
+  return {
+    identity: data.identity ?? identity,
+    expiresAt: data.expires_at ?? certExpiry,
+  };
+}
+
+async function computeCertHash(
+  identity: string,
+  groupId: string,
+  sessionPubHex: string,
+  expiry: number,
+): Promise<Uint8Array> {
+  const enc = new TextEncoder();
+  const expiryBuf = new ArrayBuffer(8);
+  new DataView(expiryBuf).setBigUint64(0, BigInt(expiry));
+
+  const parts: Uint8Array[] = [
+    enc.encode(identity),
+    enc.encode(":"),
+    enc.encode(groupId),
+    enc.encode(":"),
+    enc.encode(sessionPubHex),
+    enc.encode(":"),
+    new Uint8Array(expiryBuf),
+  ];
+
+  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);
+}

package/src/bootstrap.ts

@@ -0,0 +1,106 @@
+/**
+ * Bootstrap group node authentication.
+ *
+ * After generating a ZK proof of the JWT, POST it to each
+ * bootstrap node to register the session key.
+ */
+
+import type { NodeAuthRequest } from "./types";
+import { bytesToHex } from "./session";
+
+export interface BootstrapConfig {
+  groupId: string; // bootstrap group contract address
+  nodeUrls: string[]; // bootstrap node API URLs
+  /** Proxy endpoint for CORS — if set, requests go through this instead of directly to nodes */
+  proxyEndpoint?: string;
+}
+
+export interface AuthResult {
+  identity: string;
+  expiresAt: number;
+}
+
+/**
+ * Authenticate with all bootstrap nodes.
+ *
+ * Posts the ZK proof + session public key to each node's /v1/auth.
+ * All nodes must accept the session for signing to work.
+ */
+export async function authenticateWithBootstrap(
+  config: BootstrapConfig,
+  proof: Uint8Array,
+  sessionPubHex: string,
+  claims: { iss: string; sub: string; exp: number; aud: string; azp: string },
+  jwksModulusBytes: Uint8Array
+): Promise<AuthResult> {
+  const request: NodeAuthRequest = {
+    group_id: config.groupId,
+    session_pub: sessionPubHex,
+    proof: bytesToHex(proof),
+    sub: claims.sub,
+    iss: claims.iss,
+    exp: claims.exp,
+    aud: claims.aud,
+    azp: claims.azp,
+    jwks_modulus: bytesToHex(jwksModulusBytes),
+  };
+
+  // Auth with all nodes in parallel
+  const results = await Promise.allSettled(
+    config.nodeUrls.map((url) =>
+      authWithNode(url, request, config.proxyEndpoint)
+    )
+  );
+
+  // Check that at least one succeeded
+  const successes = results.filter(
+    (r): r is PromiseFulfilledResult<AuthResult> => r.status === "fulfilled"
+  );
+  const failures = results.filter(
+    (r): r is PromiseRejectedResult => r.status === "rejected"
+  );
+
+  if (successes.length === 0) {
+    const reasons = failures.map((f) => f.reason?.message ?? String(f.reason));
+    throw new Error(
+      `All bootstrap nodes rejected auth: ${reasons.join("; ")}`
+    );
+  }
+
+  if (failures.length > 0) {
+    console.warn(
+      `${failures.length}/${config.nodeUrls.length} bootstrap nodes failed auth:`,
+      failures.map((f) => f.reason?.message)
+    );
+  }
+
+  return successes[0].value;
+}
+
+async function authWithNode(
+  baseUrl: string,
+  request: NodeAuthRequest,
+  proxyEndpoint?: string
+): Promise<AuthResult> {
+  const url = proxyEndpoint ?? `${baseUrl}/v1/auth`;
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (proxyEndpoint) {
+    headers["x-node-url"] = baseUrl;
+    headers["x-node-path"] = "/v1/auth";
+  }
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(request),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`${baseUrl}: ${res.status} — ${body}`);
+  }
+
+  return res.json();
+}