capjs-core 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capjs-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Stateless server-side challenge generator and verifier for Cap, a lightweight, modern open-source CAPTCHA alternative. No storage, no filesystem - bring your own.",
   "keywords": [
     "anti-abuse",
@@ -42,6 +42,7 @@
     "src/instrumentation.js",
     "src/prng.js",
     "src/crypto.js",
+    "src/rsw.js",
     "README.md",
     "LICENSE"
   ],

package/src/index.d.ts

@@ -19,7 +19,36 @@ export interface GeneratedInstrumentation {
   instrumentation: string;
 }
 
+export type ProtocolName = "sha256-pow" | "rsw" | "instrumentation";
+
+export interface RswKeypair {
+  N: bigint;
+  p: bigint;
+  q: bigint;
+  bits?: number;
+}
+
+export interface SerializedRswKeypair {
+  N: string;
+  p: string;
+  q: string;
+  bits?: number | null;
+}
+
+export interface RswMinter {
+  N: bigint;
+  t: number;
+  g: bigint;
+  h: bigint;
+  modulusBytes: number;
+  N_hex: string;
+  g_hex: string;
+  h_hex: string;
+  mint(): { x_hex: string; y_hex: string };
+}
+
 export interface GenerateChallengeOptions {
+  // ── format-1 (default) ──
   challengeCount?: number;
   challengeSize?: number;
   challengeDifficulty?: number;
@@ -30,24 +59,64 @@ export interface GenerateChallengeOptions {
   instrumentationGenerator?: (
     opts: InstrumentationOptions,
   ) => Promise<GeneratedInstrumentation>;
+
+  // ── format-2 opt-in ──
+  format?: 2;
+  protocols?: ProtocolName[];
+  /** RSW keypair, either as raw BigInts (from `generateRswKeypair`) or as a
+   *  serialized JSON-friendly form (from `serializeRswKeypair`). cap-core
+   *  builds the minter on first call and memoizes it on this object. */
+  keypair?: RswKeypair | SerializedRswKeypair;
+  /** Number of sequential squarings the client must perform. Default 75_000. */
+  t?: number;
+  /** Alternative to `keypair`: pass a pre-built minter (advanced). */
+  rsw?: RswMinter;
 }
 
-export interface ChallengeResult {
+export interface Format2ChallengeEntry {
+  protocol: ProtocolName;
+  payload: Record<string, unknown>;
+}
+
+export interface Format1ChallengeResult {
   challenge: ChallengeSpec;
   token: string;
   expires: number;
   instrumentation?: string;
 }
 
+export interface Format2ChallengeResult {
+  token: string;
+  format: 2;
+  challenges: Format2ChallengeEntry[];
+  expires: number;
+}
+
+export type ChallengeResult = Format1ChallengeResult | Format2ChallengeResult;
+
 export interface InstrumentationPayload {
   i: string;
   state: Record<string, number>;
   ts?: number;
 }
 
+export interface Format2SolutionShaPow { nonce: number | string }
+export interface Format2SolutionRsw { y: string }
+export interface Format2SolutionInstrumentation {
+  instr?: InstrumentationPayload;
+  blocked?: boolean;
+  timeout?: boolean;
+}
+export type Format2Solution =
+  | Format2SolutionShaPow
+  | Format2SolutionRsw
+  | Format2SolutionInstrumentation;
+
 export interface ValidateChallengeBody {
   token: string;
-  solutions: number[];
+  /** Format-1: an array of nonces. Format-2: an array of protocol-specific
+   *  solution objects, in the same order as `challenges`. */
+  solutions: number[] | Format2Solution[];
   instr?: InstrumentationPayload;
   instr_blocked?: boolean;
   instr_timeout?: boolean;
@@ -97,3 +166,21 @@ export function validateChallenge(
   body: ValidateChallengeBody,
   opts?: ValidateChallengeOptions,
 ): Promise<ValidateChallengeResult>;
+
+// ─── RSW (format-2) helpers ────────────────────────────────────────────────
+/** Generates a fresh 2048-bit-by-default RSA-style modulus + factors. Expensive
+ *  (~700 ms to several seconds depending on prime-roll luck). Generate once
+ *  at boot and persist the result. */
+export function generateRswKeypair(bits?: number): RswKeypair;
+
+/** JSON-friendly form, safe to write to disk or env. */
+export function serializeRswKeypair(kp: RswKeypair): SerializedRswKeypair;
+export function deserializeRswKeypair(s: SerializedRswKeypair): RswKeypair;
+
+/** Build a minter for a specific squaring count `t`. Memoized when used via
+ *  `generateChallenge({ keypair, t })`; this direct API is for callers who
+ *  want full control. */
+export function buildRswMinter(
+  args: { N: bigint; p: bigint; q: bigint; t: number; g?: bigint },
+  opts?: { bits?: number },
+): RswMinter;

package/src/index.js

@@ -10,11 +10,58 @@ import {
   sha256Bytes,
   sha256Hex,
 } from "./crypto.js";
-import {
-  generateInstrumentation,
-  verifyInstrumentationResult,
-} from "./instrumentation.js";
+import { generateInstrumentation, verifyInstrumentationResult } from "./instrumentation.js";
 import { fnv1a, fnv1aResume, prngFromHash } from "./prng.js";
+import {
+  buildRswMinter as _buildRswMinter,
+  deserializeRswKeypair,
+  verifyRswSolution,
+} from "./rsw.js";
+
+export {
+  buildRswMinter,
+  generateRswKeypair,
+  serializeRswKeypair,
+  deserializeRswKeypair,
+} from "./rsw.js";
+
+const DEFAULT_RSW_T = 75_000;
+
+// Cache the minter on the keypair object identity, keyed by t. Callers who
+// pass the same `keypair` object back across requests get zero per-call
+// overhead beyond the mint itself.
+const _minterCache = new WeakMap(); // keypair → Map<t, minter>
+
+function resolveRswMinter(opts) {
+  // explicit minter takes precedence (existing API)
+  if (opts.rsw && typeof opts.rsw.mint === "function") return opts.rsw;
+
+  if (!opts.keypair) {
+    throw new Error(
+      "[capjs-core] format-2 with 'rsw' requires opts.keypair (from generateRswKeypair) or opts.rsw (from buildRswMinter).",
+    );
+  }
+
+  // Normalize: serialized (strings) → BigInt
+  const kp = typeof opts.keypair.N === "string"
+    ? deserializeRswKeypair(opts.keypair)
+    : opts.keypair;
+
+  // Memoize {keypair, t} → minter. Reuses the precomputed h across calls so
+  // the first request after boot is the only one that pays the ~5 ms setup.
+  const t = opts.t ?? DEFAULT_RSW_T;
+  let byT = _minterCache.get(opts.keypair);
+  if (!byT) {
+    byT = new Map();
+    _minterCache.set(opts.keypair, byT);
+  }
+  let minter = byT.get(t);
+  if (!minter) {
+    minter = _buildRswMinter({ ...kp, t });
+    byT.set(t, minter);
+  }
+  return minter;
+}
 
 const DEFAULT_CHALLENGE_COUNT = 50;
 const DEFAULT_CHALLENGE_SIZE = 32;
@@ -35,10 +82,7 @@ function assertSecret(secret) {
   if (typeof secret !== "string" && !Buffer.isBuffer(secret)) {
     throw new Error("[capjs-core] secret must be a string or Buffer");
   }
-  const len =
-    typeof secret === "string"
-      ? Buffer.byteLength(secret, "utf8")
-      : secret.length;
+  const len = typeof secret === "string" ? Buffer.byteLength(secret, "utf8") : secret.length;
   if (len < 16) {
     throw new Error("[capjs-core] secret must be at least 16 bytes for security");
   }
@@ -47,6 +91,10 @@ function assertSecret(secret) {
 export async function generateChallenge(secret, opts = {}) {
   assertSecret(secret);
 
+  if (opts.format === 2) {
+    return generateChallengeV2(secret, opts);
+  }
+
   const c = opts.challengeCount ?? DEFAULT_CHALLENGE_COUNT;
   const s = opts.challengeSize ?? DEFAULT_CHALLENGE_SIZE;
   const d = opts.challengeDifficulty ?? DEFAULT_CHALLENGE_DIFFICULTY;
@@ -82,8 +130,7 @@ export async function generateChallenge(secret, opts = {}) {
 
   let instrumentation;
   if (opts.instrumentation) {
-    const instrOpts =
-      typeof opts.instrumentation === "object" ? opts.instrumentation : {};
+    const instrOpts = typeof opts.instrumentation === "object" ? opts.instrumentation : {};
     const generator = opts.instrumentationGenerator || generateInstrumentation;
     const instr = await generator({ ...instrOpts, ttlMs });
     payload.ei = encryptGcm(
@@ -113,14 +160,17 @@ export async function validateChallenge(secret, body, opts = {}) {
   assertSecret(secret);
 
   if (!body || typeof body !== "object") return fail("invalid_body");
-  if (!body.token || typeof body.token !== "string")
-    return fail("missing_token");
+  if (!body.token || typeof body.token !== "string") return fail("missing_token");
   const solutions = body.solutions;
   if (!Array.isArray(solutions)) return fail("missing_solutions");
 
   const payload = jwtVerify(body.token, secret);
   if (!payload) return fail("invalid_token");
 
+  if (payload.f === 2) {
+    return validateChallengeV2(secret, body, payload, opts);
+  }
+
   if (opts.scope && payload.sk !== opts.scope) return fail("scope_mismatch");
 
   if (!payload.exp || payload.exp < Date.now()) return fail("expired");
@@ -177,8 +227,7 @@ export async function validateChallenge(secret, body, opts = {}) {
       return fail("instr_timeout", { instr_error: true });
     } else if (body.instr) {
       const r = verifyInstrumentationResult(instrMeta, body.instr);
-      if (!r.valid)
-        return fail(r.reason || "instr_failed", { instr_error: true });
+      if (!r.valid) return fail(r.reason || "instr_failed", { instr_error: true });
     } else {
       return fail("instr_missing", { instr_error: true });
     }
@@ -227,3 +276,174 @@ export async function validateChallenge(secret, body, opts = {}) {
     iat: payload.iat,
   };
 }
+
+async function generateChallengeV2(secret, opts) {
+  const protocols =
+    Array.isArray(opts.protocols) && opts.protocols.length ? opts.protocols : ["rsw"];
+  const ttlMs = opts.expiresMs ?? DEFAULT_CHALLENGE_TTL_MS;
+  const now = Date.now();
+  const exp = now + ttlMs;
+
+  const challenges = [];
+  const expected = [];
+
+  for (const proto of protocols) {
+    if (proto === "sha256-pow") {
+      const c = opts.challengeCount ?? DEFAULT_CHALLENGE_COUNT;
+      const s = opts.challengeSize ?? DEFAULT_CHALLENGE_SIZE;
+      const d = opts.challengeDifficulty ?? DEFAULT_CHALLENGE_DIFFICULTY;
+      if (
+        !Number.isInteger(c) ||
+        c < 1 ||
+        c > MAX_CHALLENGE_COUNT ||
+        !Number.isInteger(s) ||
+        s < 1 ||
+        s > MAX_CHALLENGE_SIZE ||
+        !Number.isInteger(d) ||
+        d < 1 ||
+        d > MAX_CHALLENGE_DIFFICULTY
+      ) {
+        throw new Error(
+          `[capjs-core] invalid params: c≤${MAX_CHALLENGE_COUNT}, s≤${MAX_CHALLENGE_SIZE}, d∈[1,${MAX_CHALLENGE_DIFFICULTY}]`,
+        );
+      }
+      const target = "0".repeat(d);
+      for (let i = 0; i < c; i++) {
+        const salt = randomHex(s);
+        challenges.push({ protocol: "sha256-pow", payload: { salt, target } });
+        expected.push({ protocol: "sha256-pow", salt, target });
+      }
+    } else if (proto === "rsw") {
+      const minter = resolveRswMinter(opts);
+      const { x_hex, y_hex } = minter.mint();
+      challenges.push({
+        protocol: "rsw",
+        payload: { N: minter.N_hex, x: x_hex, t: minter.t },
+      });
+      expected.push({ protocol: "rsw", y: y_hex });
+    } else if (proto === "instrumentation") {
+      const instrOpts =
+        typeof opts.instrumentation === "object" && opts.instrumentation !== null
+          ? opts.instrumentation
+          : {};
+      const generator = opts.instrumentationGenerator || generateInstrumentation;
+      const instr = await generator({ ...instrOpts, ttlMs });
+      challenges.push({ protocol: "instrumentation", payload: { blob: instr.instrumentation } });
+      expected.push({
+        protocol: "instrumentation",
+        instrMeta: {
+          id: instr.id,
+          expectedVals: instr.expectedVals,
+          vars: instr.vars,
+          blockAutomatedBrowsers: instr.blockAutomatedBrowsers,
+          expires: exp,
+        },
+      });
+    } else {
+      throw new Error(`[capjs-core] unknown protocol '${proto}'`);
+    }
+  }
+
+  const tokenPayload = {
+    f: 2,
+    n: randomHex(16),
+    exp,
+    iat: now,
+    ev: encryptGcm({ expected }, secret, "cap:fmt2-v1"),
+  };
+  if (opts.scope) tokenPayload.sk = String(opts.scope);
+  if (opts.extra && typeof opts.extra === "object") tokenPayload.x = opts.extra;
+
+  const token = jwtSign(tokenPayload, secret);
+  return { token, format: 2, challenges, expires: exp };
+}
+
+async function validateChallengeV2(secret, body, payload, opts = {}) {
+  if (opts.scope && payload.sk !== opts.scope) return fail("scope_mismatch");
+  if (!payload.exp || payload.exp < Date.now()) return fail("expired");
+
+  const decrypted = decryptGcm(payload.ev, secret, "cap:fmt2-v1");
+  if (!decrypted || !Array.isArray(decrypted.expected)) return fail("invalid_token");
+  const expected = decrypted.expected;
+  const solutions = body.solutions;
+
+  if (solutions.length !== expected.length) return fail("invalid_solutions");
+
+  for (let i = 0; i < expected.length; i++) {
+    const e = expected[i];
+    const s = solutions[i];
+    if (!s || typeof s !== "object") return fail("invalid_solution");
+
+    if (e.protocol === "sha256-pow") {
+      const nonce = s.nonce;
+      if (typeof nonce !== "number" && typeof nonce !== "string") return fail("invalid_solution");
+      const hash = sha256Bytes(e.salt + nonce);
+      if (!powMatchesPrefix(hash, parseHexPrefix(e.target))) return fail("invalid_solution");
+    } else if (e.protocol === "rsw") {
+      if (!verifyRswSolution(e.y, s.y)) return fail("invalid_solution");
+    } else if (e.protocol === "instrumentation") {
+      const meta = e.instrMeta;
+      if (!meta) return fail("instr_corrupted", { instr_error: true });
+      if (meta.expires && Date.now() > meta.expires) {
+        return fail("instr_expired", { instr_error: true });
+      }
+      if (s.blocked === true) {
+        if (meta.blockAutomatedBrowsers) {
+          return fail("instr_automated_browser", { instr_error: true });
+        }
+      } else if (s.timeout === true) {
+        return fail("instr_timeout", { instr_error: true });
+      } else if (s.instr) {
+        const r = verifyInstrumentationResult(meta, s.instr);
+        if (!r.valid) return fail(r.reason || "instr_failed", { instr_error: true });
+      } else {
+        return fail("instr_missing", { instr_error: true });
+      }
+    } else {
+      return fail("invalid_solution");
+    }
+  }
+
+  if (typeof opts.consumeNonce === "function") {
+    const sig = jwtSigHex(body.token);
+    if (!sig) return fail("invalid_token");
+    const ttlMs = Math.max(1, payload.exp - Date.now());
+    let claimed;
+    try {
+      claimed = await opts.consumeNonce(sig, ttlMs);
+    } catch (err) {
+      return fail("nonce_store_error", { error: String(err?.message || err) });
+    }
+    if (!claimed) return fail("already_redeemed");
+  }
+
+  const tokenTtlMs = opts.tokenTtlMs ?? DEFAULT_TOKEN_TTL_MS;
+  const tokenExpires = Date.now() + tokenTtlMs;
+
+  if (typeof opts.signToken === "function") {
+    const signed = await opts.signToken({
+      scope: payload.sk ?? null,
+      expires: tokenExpires,
+      iat: payload.iat,
+    });
+    return {
+      success: true,
+      token: signed,
+      expires: tokenExpires,
+      scope: payload.sk ?? null,
+      iat: payload.iat,
+    };
+  }
+
+  const id = randomHex(8);
+  const verToken = randomHex(15);
+  const tokenHash = sha256Hex(verToken);
+  return {
+    success: true,
+    token: `${id}:${verToken}`,
+    tokenKey: `${id}:${tokenHash}`,
+    expires: tokenExpires,
+    scope: payload.sk ?? null,
+    iat: payload.iat,
+  };
+}

package/src/rsw.js

@@ -0,0 +1,167 @@
+import { randomBytes } from "node:crypto";
+
+function bigintFromBuf(buf) {
+  let x = 0n;
+  for (const b of buf) x = (x << 8n) | BigInt(b);
+  return x;
+}
+
+function modpow(b, e, m) {
+  let r = 1n;
+  b %= m;
+  if (b < 0n) b += m;
+  while (e > 0n) {
+    if (e & 1n) r = (r * b) % m;
+    e >>= 1n;
+    b = (b * b) % m;
+  }
+  return r;
+}
+
+function modinv(a, m) {
+  let [old_r, r] = [a % m, m];
+  let [old_s, s] = [1n, 0n];
+  if (old_r < 0n) old_r += m;
+  while (r !== 0n) {
+    const q = old_r / r;
+    [old_r, r] = [r, old_r - q * r];
+    [old_s, s] = [s, old_s - q * s];
+  }
+  return ((old_s % m) + m) % m;
+}
+
+function isProbablePrime(n, k = 4) {
+  if (n < 2n) return false;
+  for (const p of [2n, 3n, 5n, 7n, 11n, 13n, 17n, 19n, 23n, 29n, 31n]) {
+    if (n === p) return true;
+    if (n % p === 0n) return false;
+  }
+  let d = n - 1n;
+  let r = 0n;
+  while ((d & 1n) === 0n) {
+    d >>= 1n;
+    r++;
+  }
+  const bits = n.toString(2).length;
+  const byteLen = (bits + 7) >> 3;
+  outer: for (let i = 0; i < k; i++) {
+    let a = 0n;
+    do {
+      a = bigintFromBuf(randomBytes(byteLen)) % (n - 3n);
+    } while (a < 2n);
+    let x = modpow(a, d, n);
+    if (x === 1n || x === n - 1n) continue;
+    for (let j = 0n; j < r - 1n; j++) {
+      x = (x * x) % n;
+      if (x === n - 1n) continue outer;
+    }
+    return false;
+  }
+  return true;
+}
+
+function randomPrime(bits) {
+  const byteLen = (bits + 7) >> 3;
+  for (;;) {
+    let x = bigintFromBuf(randomBytes(byteLen));
+    x |= 1n;
+    x |= 1n << BigInt(bits - 1);
+    x |= 1n << BigInt(bits - 2);
+    x &= (1n << BigInt(bits)) - 1n;
+    if (isProbablePrime(x, 4)) return x;
+  }
+}
+
+function hexOf(bi, byteLen) {
+  let s = bi.toString(16);
+  if (byteLen != null) {
+    const target = byteLen * 2;
+    if (s.length < target) s = "0".repeat(target - s.length) + s;
+  }
+  return s;
+}
+
+// generation is expensive (~700 ms for 2048-bit on a modern CPU); persist the result.
+export function generateRswKeypair(bits = 2048) {
+  if (bits % 2 !== 0) throw new Error("rsw bits must be even");
+  const p = randomPrime(bits >> 1);
+  let q = randomPrime(bits >> 1);
+  while (q === p) q = randomPrime(bits >> 1);
+  const N = p * q;
+  return { N, p, q, bits };
+}
+
+export function serializeRswKeypair(kp) {
+  return { N: kp.N.toString(), p: kp.p.toString(), q: kp.q.toString(), bits: kp.bits ?? null };
+}
+export function deserializeRswKeypair(s) {
+  if (!s || typeof s !== "object") throw new Error("invalid serialized rsw keypair");
+  const N = typeof s.N === "string" ? BigInt(s.N) : s.N;
+  const p = typeof s.p === "string" ? BigInt(s.p) : s.p;
+  const q = typeof s.q === "string" ? BigInt(s.q) : s.q;
+  if (typeof N !== "bigint" || typeof p !== "bigint" || typeof q !== "bigint") {
+    throw new Error("rsw keypair fields must be bigint or string-encoded bigint");
+  }
+  return { N, p, q, bits: s.bits ?? N.toString(2).length };
+}
+
+export function buildRswMinter({ N, p, q, t, g }, opts = {}) {
+  if (!N || !p || !q || !t) throw new Error("rsw minter needs {N, p, q, t}");
+  const bits = opts.bits ?? N.toString(2).length;
+  const modulusBytes = Math.ceil(bits / 8);
+  const G = g ?? (bigintFromBuf(randomBytes(modulusBytes)) % (N - 3n)) + 2n;
+
+  const pm1 = p - 1n;
+  const qm1 = q - 1n;
+  const e_p = modpow(2n, BigInt(t), pm1);
+  const e_q = modpow(2n, BigInt(t), qm1);
+
+  const hp = modpow(G % p, e_p, p);
+  const hq = modpow(G % q, e_q, q);
+  const qinv_p = modinv(q % p, p);
+  const crtCombine = (ap, aq) => {
+    let s = (((ap - aq) % p) + p) % p;
+    s = (s * qinv_p) % p;
+    return aq + q * s;
+  };
+  const h = crtCombine(hp, hq);
+
+  const gp = G % p;
+  const gq = G % q;
+
+  function mintFromR(r) {
+    const rp = r % pm1;
+    const rq = r % qm1;
+    const xp = modpow(gp, rp, p);
+    const xq = modpow(gq, rq, q);
+    const yp = modpow(hp, rp, p);
+    const yq = modpow(hq, rq, q);
+    return { x: crtCombine(xp, xq), y: crtCombine(yp, yq) };
+  }
+
+  return {
+    N,
+    t,
+    g: G,
+    h,
+    modulusBytes,
+    N_hex: hexOf(N, modulusBytes),
+    g_hex: hexOf(G, modulusBytes),
+    h_hex: hexOf(h, modulusBytes),
+
+    mint() {
+      const r = bigintFromBuf(randomBytes(32));
+      const { x, y } = mintFromR(r);
+      return {
+        x_hex: hexOf(x, modulusBytes),
+        y_hex: hexOf(y, modulusBytes),
+      };
+    },
+  };
+}
+
+export function verifyRswSolution(expectedYHex, claimedYHex) {
+  if (typeof claimedYHex !== "string" || typeof expectedYHex !== "string") return false;
+  const norm = (s) => s.replace(/^0x/, "").toLowerCase().replace(/^0+/, "");
+  return norm(expectedYHex) === norm(claimedYHex);
+}