ribaunt 0.2.4 → 0.2.6

package/dist/cjs/index.js

@@ -1,19 +1,65 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.calibrateClient = exports.LocalReplayStore = exports.RateLimitedError = exports.DEFAULT_RISK_THRESHOLDS = void 0;
+exports.calibrateArgonClient = exports.calibrateClient = exports.LocalReplayStore = exports.RateLimitedError = exports.ARGON_PROFILES = exports.HARD_MAX = exports.DEFAULT_RISK_THRESHOLDS = void 0;
 exports.selectWorkload = selectWorkload;
 exports.assess = assess;
 exports.calibrateNode = calibrateNode;
+exports.calibrateArgonNode = calibrateArgonNode;
+exports.__resetArgonForTesting = __resetArgonForTesting;
 exports.createChallenge = createChallenge;
 exports.solveChallenge = solveChallenge;
+exports.solveChallengeAsync = solveChallengeAsync;
 exports.verifySolution = verifySolution;
 const crypto_1 = __importDefault(require("crypto"));
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const risk_js_1 = require("./risk.js");
 Object.defineProperty(exports, "DEFAULT_RISK_THRESHOLDS", { enumerable: true, get: function () { return risk_js_1.DEFAULT_RISK_THRESHOLDS; } });
+exports.HARD_MAX = {
+    m: 32 * 1024,
+    t: 3,
+    p: 1,
+    hashLen: 32,
+};
+exports.ARGON_PROFILES = {
+    mobile: { m: 8 * 1024, t: 1, p: 1, hashLen: 32 },
+    standard: { m: 8 * 1024, t: 1, p: 1, hashLen: 32 },
+};
 class RateLimitedError extends Error {
     constructor(message = 'Rate limit exceeded') {
         super(message);
@@ -56,9 +102,69 @@ const DEFAULT_BOUNDS = {
     minAmount: 1,
     maxAmount: 8,
 };
+const DEFAULT_BOUNDS_SHA = DEFAULT_BOUNDS;
+const DEFAULT_BOUNDS_ARGON = {
+    minDifficulty: 1,
+    maxDifficulty: 2,
+    minAmount: 1,
+    maxAmount: 8,
+};
 const MAX_WORKLOAD_DIFFICULTY = 64;
+const MAX_WORKLOAD_ARGON_DIFFICULTY = 8;
 const MAX_WORKLOAD_AMOUNT = 64;
 const MAX_WORKLOAD_CANDIDATES = 10000;
+let cachedArgon2id = null;
+let argon2idLoadPromise = null;
+async function getArgon2idFn() {
+    if (cachedArgon2id)
+        return cachedArgon2id;
+    if (argon2idLoadPromise)
+        return argon2idLoadPromise;
+    argon2idLoadPromise = (async () => {
+        // hash-wasm is CJS; handle both default and named interop
+        const mod = await Promise.resolve().then(() => __importStar(require('hash-wasm')));
+        const pkg = mod.default ?? mod;
+        const fn = pkg.argon2id;
+        if (typeof fn !== 'function')
+            throw new Error('hash-wasm argon2id not available');
+        cachedArgon2id = fn;
+        return fn;
+    })();
+    return argon2idLoadPromise;
+}
+function padSalt(challenge) {
+    if (challenge.length >= 16)
+        return challenge.slice(0, 16);
+    return challenge.padEnd(16, '0');
+}
+function resolveArgonParams(profile) {
+    const normalized = profile ?? 'mobile';
+    if (normalized !== 'mobile' && normalized !== 'standard') {
+        throw new Error('argonProfile must be "mobile" or "standard"');
+    }
+    return exports.ARGON_PROFILES[normalized];
+}
+async function argon2idHash(challenge, nonce, params) {
+    const argon2id = await getArgon2idFn();
+    const salt = padSalt(challenge);
+    const password = `${challenge}${String(nonce)}`;
+    return argon2id({
+        password,
+        salt,
+        parallelism: params.p,
+        iterations: params.t,
+        memorySize: params.m,
+        hashLength: params.hashLen,
+        outputType: 'hex',
+    });
+}
+function assertAlgorithm(value) {
+    if (value === undefined)
+        return 'sha256';
+    if (value === 'sha256' || value === 'argon2id')
+        return value;
+    throw new Error('algorithm must be "sha256" or "argon2id"');
+}
 function assertFiniteInteger(value, name, minimum) {
     if (!Number.isFinite(value))
         throw new Error(`${name} must be a finite number`);
@@ -71,17 +177,40 @@ function isValidPayload(payload) {
     if (!payload || typeof payload !== 'object')
         return false;
     const value = payload;
-    return typeof value.challenge === 'string'
-        && value.challenge.length > 0
-        && typeof value.difficulty === 'number'
-        && Number.isInteger(value.difficulty)
-        && value.difficulty >= 1
-        && value.difficulty <= 64
-        && typeof value.expires === 'number'
-        && Number.isInteger(value.expires)
-        && typeof value.jti === 'string'
-        && value.jti.length > 0
-        && (value.contextHash === undefined || /^[a-f0-9]{64}$/.test(value.contextHash));
+    if (typeof value.challenge !== 'string' || value.challenge.length === 0)
+        return false;
+    if (typeof value.difficulty !== 'number' || !Number.isInteger(value.difficulty) || value.difficulty < 1)
+        return false;
+    const alg = (value.alg ?? 'sha256');
+    if (alg === 'argon2id') {
+        if (value.difficulty > MAX_WORKLOAD_ARGON_DIFFICULTY)
+            return false;
+        if (typeof value.m !== 'number' || !Number.isInteger(value.m) || value.m < 8 || value.m > exports.HARD_MAX.m)
+            return false;
+        if (typeof value.t !== 'number' || !Number.isInteger(value.t) || value.t < 1 || value.t > exports.HARD_MAX.t)
+            return false;
+        if (typeof value.p !== 'number' || !Number.isInteger(value.p) || value.p < 1 || value.p > exports.HARD_MAX.p)
+            return false;
+        if (value.hashLen !== undefined && value.hashLen !== 32)
+            return false;
+        // enforce at least pow of two? not needed
+    }
+    else if (alg === 'sha256') {
+        if (value.difficulty > MAX_WORKLOAD_DIFFICULTY)
+            return false;
+        if (value.m !== undefined || value.t !== undefined || value.p !== undefined || value.hashLen !== undefined)
+            return false;
+    }
+    else {
+        return false;
+    }
+    if (typeof value.expires !== 'number' || !Number.isInteger(value.expires))
+        return false;
+    if (typeof value.jti !== 'string' || value.jti.length === 0)
+        return false;
+    if (value.contextHash !== undefined && !/^[a-f0-9]{64}$/.test(value.contextHash))
+        return false;
+    return true;
 }
 function assertRange(value, name, minimum, maximum) {
     if (!Number.isFinite(value) || value < minimum || value > maximum) {
@@ -89,20 +218,32 @@ function assertRange(value, name, minimum, maximum) {
     }
     return value;
 }
+function getDefaultBounds(algorithm) {
+    return algorithm === 'argon2id' ? DEFAULT_BOUNDS_ARGON : DEFAULT_BOUNDS_SHA;
+}
+function getMaxDifficulty(algorithm) {
+    return algorithm === 'argon2id' ? MAX_WORKLOAD_ARGON_DIFFICULTY : MAX_WORKLOAD_DIFFICULTY;
+}
 function normalizeBounds(options) {
-    const minDifficulty = assertFiniteInteger(options.minDifficulty ?? DEFAULT_BOUNDS.minDifficulty, 'Minimum difficulty', 1);
-    if (minDifficulty > MAX_WORKLOAD_DIFFICULTY) {
-        throw new Error(`Minimum difficulty must be at most ${MAX_WORKLOAD_DIFFICULTY}`);
-    }
-    const maxDifficulty = assertFiniteInteger(options.maxDifficulty ?? DEFAULT_BOUNDS.maxDifficulty, 'Maximum difficulty', minDifficulty);
-    if (maxDifficulty > MAX_WORKLOAD_DIFFICULTY) {
-        throw new Error(`Maximum difficulty must be at most ${MAX_WORKLOAD_DIFFICULTY}`);
-    }
-    const minAmount = assertFiniteInteger(options.minAmount ?? DEFAULT_BOUNDS.minAmount, 'Minimum amount', 1);
+    const algorithm = assertAlgorithm(options.algorithm);
+    return normalizeBoundsInternal(options, algorithm);
+}
+function normalizeBoundsInternal(options, algorithm = 'sha256') {
+    const defaults = getDefaultBounds(algorithm);
+    const maxDiff = getMaxDifficulty(algorithm);
+    const minDifficulty = assertFiniteInteger(options.minDifficulty ?? defaults.minDifficulty, 'Minimum difficulty', 1);
+    if (minDifficulty > maxDiff) {
+        throw new Error(`Minimum difficulty must be at most ${maxDiff}`);
+    }
+    const maxDifficulty = assertFiniteInteger(options.maxDifficulty ?? defaults.maxDifficulty, 'Maximum difficulty', minDifficulty);
+    if (maxDifficulty > maxDiff) {
+        throw new Error(`Maximum difficulty must be at most ${maxDiff}`);
+    }
+    const minAmount = assertFiniteInteger(options.minAmount ?? defaults.minAmount, 'Minimum amount', 1);
     if (minAmount > MAX_WORKLOAD_AMOUNT) {
         throw new Error(`Minimum amount must be at most ${MAX_WORKLOAD_AMOUNT}`);
     }
-    const maxAmount = assertFiniteInteger(options.maxAmount ?? DEFAULT_BOUNDS.maxAmount, 'Maximum amount', minAmount);
+    const maxAmount = assertFiniteInteger(options.maxAmount ?? defaults.maxAmount, 'Maximum amount', minAmount);
     if (maxAmount > MAX_WORKLOAD_AMOUNT) {
         throw new Error(`Maximum amount must be at most ${MAX_WORKLOAD_AMOUNT}`);
     }
@@ -110,18 +251,25 @@ function normalizeBounds(options) {
     if (candidateCount > MAX_WORKLOAD_CANDIDATES) {
         throw new Error(`Workload bounds too large: candidate count ${candidateCount} exceeds ${MAX_WORKLOAD_CANDIDATES}`);
     }
-    return { minDifficulty, maxDifficulty, minAmount, maxAmount };
+    return { minDifficulty, maxDifficulty, minAmount, maxAmount, algorithm };
 }
 function closestWorkload(targetAttempts, bounds) {
     let best;
     let bestDistance = Number.POSITIVE_INFINITY;
+    const algorithm = bounds.algorithm ?? 'sha256';
+    const argon = algorithm === 'argon2id' ? resolveArgonParams(bounds.argonProfile) : undefined;
     for (let difficulty = bounds.minDifficulty; difficulty <= bounds.maxDifficulty; difficulty++) {
         for (let amount = bounds.minAmount; amount <= bounds.maxAmount; amount++) {
             const estimatedAttempts = (16 ** difficulty) * amount;
             const distance = Math.abs(Math.log(estimatedAttempts / targetAttempts));
             if (distance < bestDistance) {
                 bestDistance = distance;
-                best = { difficulty, amount, estimatedAttempts };
+                if (algorithm === 'argon2id') {
+                    best = { difficulty, amount, estimatedAttempts, algorithm, argon: argon };
+                }
+                else {
+                    best = { difficulty, amount, estimatedAttempts, algorithm };
+                }
             }
         }
     }
@@ -129,9 +277,28 @@ function closestWorkload(targetAttempts, bounds) {
 }
 /**
  * Selects bounded proof-of-work using a server-owned risk floor and untrusted timing calibration.
+ * For `algorithm:'argon2id'` difficulty is capped to the argon max (default 2) and the returned
+ * workload carries `argon:{m,t,p}` derived from `argonProfile` so the device can comfortably solve it.
  */
 function selectWorkload(options = {}) {
-    const bounds = normalizeBounds(options);
+    const algorithm = assertAlgorithm(options.algorithm);
+    if (options.argonProfile !== undefined) {
+        if (algorithm !== 'argon2id')
+            throw new Error('argonProfile is only valid when algorithm is "argon2id"');
+        if (options.argonProfile !== 'mobile' && options.argonProfile !== 'standard') {
+            throw new Error('argonProfile must be "mobile" or "standard"');
+        }
+    }
+    // Validate argonProfile early
+    if (algorithm === 'argon2id') {
+        // Trigger validation (defaults to mobile when undefined)
+        resolveArgonParams(options.argonProfile);
+    }
+    const bounds = normalizeBounds({ ...options, algorithm });
+    // Carry argonProfile through bounds object for closestWorkload to consume (without polluting validation)
+    if (algorithm === 'argon2id' && options.argonProfile !== undefined) {
+        bounds.argonProfile = options.argonProfile;
+    }
     const riskScore = assertRange(options.riskScore ?? 50, 'Risk score', 0, 100);
     const targetDurationMs = assertFiniteInteger(options.targetDurationMs ?? 750, 'Target duration', 1);
     const minimumAttempts = 16 ** bounds.minDifficulty
@@ -145,33 +312,54 @@ function selectWorkload(options = {}) {
         targetAttempts = Math.max(minimumAttempts, calibratedAttempts);
     }
     const maximumAttempts = (16 ** bounds.maxDifficulty) * bounds.maxAmount;
-    return closestWorkload(Math.min(targetAttempts, maximumAttempts), bounds);
+    const workload = closestWorkload(Math.min(targetAttempts, maximumAttempts), bounds);
+    // Ensure argon carries profile-resolved params if not already via closestWorkload
+    if (algorithm === 'argon2id' && !workload.argon) {
+        workload.argon = resolveArgonParams(options.argonProfile);
+    }
+    return workload;
 }
 function validateAssessWorkloadOptions(workload) {
+    const alg = assertAlgorithm(workload.algorithm);
+    const defaults = getDefaultBounds(alg);
+    const maxDiffForAlg = getMaxDifficulty(alg);
     // Reuse same validation messages as normalizeBounds / selectWorkload for regression safety
     if (workload.minDifficulty !== undefined) {
         assertFiniteInteger(workload.minDifficulty, 'Minimum difficulty', 1);
+        if (Math.floor(workload.minDifficulty) > maxDiffForAlg) {
+            throw new Error(`Minimum difficulty must be at most ${maxDiffForAlg}`);
+        }
     }
     if (workload.maxDifficulty !== undefined) {
         // Need to ensure we validate max >= min (using resolved min)
-        const min = workload.minDifficulty !== undefined ? Math.floor(workload.minDifficulty) : DEFAULT_BOUNDS.minDifficulty;
+        const min = workload.minDifficulty !== undefined ? Math.floor(workload.minDifficulty) : defaults.minDifficulty;
         assertFiniteInteger(workload.maxDifficulty, 'Maximum difficulty', min);
+        if (Math.floor(workload.maxDifficulty) > maxDiffForAlg) {
+            throw new Error(`Maximum difficulty must be at most ${maxDiffForAlg}`);
+        }
     }
     else if (workload.minDifficulty !== undefined) {
         // If only minDifficulty provided, still need to ensure default max >= min
-        if (DEFAULT_BOUNDS.maxDifficulty < Math.floor(workload.minDifficulty)) {
+        if (defaults.maxDifficulty < Math.floor(workload.minDifficulty)) {
             throw new Error(`Maximum difficulty must be at least ${Math.floor(workload.minDifficulty)}`);
         }
     }
+    if (workload.argonProfile !== undefined) {
+        const p = workload.argonProfile;
+        if (alg !== 'argon2id')
+            throw new Error('argonProfile is only valid when algorithm is "argon2id"');
+        if (p !== 'mobile' && p !== 'standard')
+            throw new Error('argonProfile must be "mobile" or "standard"');
+    }
     if (workload.minAmount !== undefined) {
         assertFiniteInteger(workload.minAmount, 'Minimum amount', 1);
     }
     if (workload.maxAmount !== undefined) {
-        const minAmt = workload.minAmount !== undefined ? Math.floor(workload.minAmount) : DEFAULT_BOUNDS.minAmount;
+        const minAmt = workload.minAmount !== undefined ? Math.floor(workload.minAmount) : defaults.minAmount;
         assertFiniteInteger(workload.maxAmount, 'Maximum amount', minAmt);
     }
     else if (workload.minAmount !== undefined) {
-        if (DEFAULT_BOUNDS.maxAmount < Math.floor(workload.minAmount)) {
+        if (defaults.maxAmount < Math.floor(workload.minAmount)) {
             throw new Error(`Maximum amount must be at least ${Math.floor(workload.minAmount)}`);
         }
     }
@@ -196,9 +384,14 @@ function validateAssessWorkloadOptions(workload) {
     if (workload.minDifficulty !== undefined ||
         workload.maxDifficulty !== undefined ||
         workload.minAmount !== undefined ||
-        workload.maxAmount !== undefined) {
+        workload.maxAmount !== undefined ||
+        workload.algorithm !== undefined ||
+        workload.argonProfile !== undefined) {
         normalizeBounds(workload);
     }
+    if (workload.algorithm !== undefined) {
+        assertAlgorithm(workload.algorithm);
+    }
 }
 /**
  * Programmable risk-assessment subsystem.
@@ -272,6 +465,13 @@ async function assess(options) {
     }
     return { risk, action };
 }
+/**
+ * Measures SHA-256 hashing speed on Node.js to calibrate adaptive workload selection.
+ * Runs a small benchmark to estimate device performance.
+ *
+ * @param iterations - Number of SHA-256 hashes to run (default: 128)
+ * @returns Calibration object with iterations and measured duration
+ */
 function calibrateNode(iterations = 128) {
     if (!Number.isFinite(iterations) || iterations < 1) {
         throw new Error('Calibration iterations must be at least 1');
@@ -286,7 +486,71 @@ function calibrateNode(iterations = 128) {
         durationMs: Math.max(1, Math.round(performance.now() - startedAt)),
     };
 }
+/**
+ * Alias for calibrateNode - measures device hashing speed for adaptive workload.
+ */
 exports.calibrateClient = calibrateNode;
+let cachedArgonCalibrationWarmup = null;
+async function ensureArgonWarmup() {
+    if (cachedArgonCalibrationWarmup)
+        return cachedArgonCalibrationWarmup;
+    // Warm up WASM once (first argon hash triggers compilation)
+    cachedArgonCalibrationWarmup = (async () => {
+        try {
+            await getArgon2idFn();
+            // tiny probe to force WASM compile — one hash at mobile params
+            const argon = await getArgon2idFn();
+            await argon({
+                password: 'ribaunt-warmup',
+                salt: 'ribaunt-warmup-16b',
+                parallelism: 1,
+                iterations: 1,
+                memorySize: 8 * 1024,
+                hashLength: 32,
+                outputType: 'hex',
+            });
+        }
+        catch {
+            // warmup best-effort; calibration will still surface errors
+        }
+    })();
+    return cachedArgonCalibrationWarmup;
+}
+/**
+ * Calibrate Argon2id on Node — measures device speed for the memory-hard algorithm.
+ * Uses a smaller iteration default (16) because each hash is ~6ms (mobile) vs microseconds for SHA.
+ * The returned shape is identical to `calibrateNode()` so `selectWorkload({calibration, algorithm:'argon2id'})` can consume it.
+ * Keep SHA `calibrateNode()` for `algorithm:'sha256'` — mismatched calibration will over/under-estimate.
+ */
+async function calibrateArgonNode(iterations = 16) {
+    if (!Number.isFinite(iterations) || iterations < 1) {
+        throw new Error('Calibration iterations must be at least 1');
+    }
+    const normalizedIterations = Math.floor(iterations);
+    await ensureArgonWarmup();
+    const profile = resolveArgonParams('mobile');
+    const startedAt = performance.now();
+    for (let index = 0; index < normalizedIterations; index++) {
+        await argon2idHash(`ribaunt-calibration:${index}`, '0', profile);
+    }
+    return {
+        iterations: normalizedIterations,
+        durationMs: Math.max(1, Math.round(performance.now() - startedAt)),
+    };
+}
+/**
+ * Alias for calibrateArgonNode - measures Argon2id performance for adaptive workload.
+ */
+exports.calibrateArgonClient = calibrateArgonNode;
+/**
+ * Resets Argon2id module cache for testing purposes.
+ * Should not be called in production code.
+ */
+function __resetArgonForTesting() {
+    cachedArgon2id = null;
+    argon2idLoadPromise = null;
+    cachedArgonCalibrationWarmup = null;
+}
 function generateChallenge(length = 8) {
     return crypto_1.default.randomBytes(length).toString('base64url').slice(0, length);
 }
@@ -308,7 +572,7 @@ function getSecret() {
     }
     return secret;
 }
-function createSingleChallenge(difficulty, ttlSeconds, context) {
+function createSingleChallenge(difficulty, ttlSeconds, context, algorithm = 'sha256', argonParams) {
     const jti = crypto_1.default.randomUUID();
     const payload = {
         challenge: generateChallenge(),
@@ -316,6 +580,22 @@ function createSingleChallenge(difficulty, ttlSeconds, context) {
         expires: Math.floor(Date.now() / 1000) + ttlSeconds,
         jti,
     };
+    if (algorithm === 'argon2id') {
+        payload.alg = 'argon2id';
+        const p = argonParams ?? resolveArgonParams('mobile');
+        payload.m = p.m;
+        payload.t = p.t;
+        payload.p = p.p;
+        payload.hashLen = p.hashLen;
+        if (difficulty < 1 || difficulty > MAX_WORKLOAD_ARGON_DIFFICULTY) {
+            throw new Error(`Challenge difficulty must be between 1 and ${MAX_WORKLOAD_ARGON_DIFFICULTY} for argon2id`);
+        }
+    }
+    else {
+        if (difficulty < 1 || difficulty > MAX_WORKLOAD_DIFFICULTY) {
+            throw new Error(`Challenge difficulty must be at most ${MAX_WORKLOAD_DIFFICULTY}`);
+        }
+    }
     if (context !== undefined)
         payload.contextHash = hashContext(context, jti);
     return jsonwebtoken_1.default.sign(payload, getSecret(), { algorithm: 'HS256' });
@@ -332,13 +612,51 @@ function emitEvent(options, event) {
 }
 async function createChallenge(difficultyOrOptions = 5, amount = 4, ttlSeconds = 30) {
     const options = typeof difficultyOrOptions === 'object' ? difficultyOrOptions : undefined;
-    const selectedWorkload = options?.workload
-        ?? (options?.difficulty === 'auto' ? selectWorkload(options) : undefined);
+    const algorithm = assertAlgorithm(options?.algorithm);
+    if (options?.argonProfile !== undefined && algorithm !== 'argon2id') {
+        throw new Error('argonProfile is only valid when algorithm is "argon2id"');
+    }
+    let selectedWorkload;
+    if (options?.workload) {
+        const w = options.workload;
+        const wDiff = assertFiniteInteger(w.difficulty, 'Challenge difficulty', 1);
+        const maxForAlg = getMaxDifficulty(algorithm);
+        if (wDiff > maxForAlg)
+            throw new Error(`Challenge difficulty must be at most ${maxForAlg} for ${algorithm}`);
+        const wAmount = assertFiniteInteger(w.amount, 'Challenge amount', 1);
+        selectedWorkload = {
+            difficulty: wDiff,
+            amount: wAmount,
+            estimatedAttempts: (16 ** wDiff) * wAmount,
+            algorithm,
+            ...(algorithm === 'argon2id' ? { argon: resolveArgonParams(options.argonProfile) } : {}),
+        };
+    }
+    else if (options?.difficulty === 'auto') {
+        const workloadInput = {
+            ...options,
+            algorithm,
+            ...(options.argonProfile !== undefined ? { argonProfile: options.argonProfile } : {}),
+        };
+        selectedWorkload = selectWorkload(workloadInput);
+    }
+    // When algorithm is argon2id and workload was explicit or auto, resolve argon params for token
+    let workloadArgon;
+    if (algorithm === 'argon2id') {
+        if (selectedWorkload?.argon) {
+            workloadArgon = selectedWorkload.argon;
+        }
+        else {
+            workloadArgon = resolveArgonParams(options?.argonProfile);
+        }
+    }
     const configuredDifficulty = options?.difficulty === 'auto' ? undefined : options?.difficulty;
-    const difficulty = assertFiniteInteger(selectedWorkload?.difficulty ?? configuredDifficulty
-        ?? (typeof difficultyOrOptions === 'number' ? difficultyOrOptions : 5), 'Challenge difficulty', 1);
-    if (difficulty > 64)
-        throw new Error('Challenge difficulty must be at most 64');
+    const difficultyRaw = selectedWorkload?.difficulty ?? configuredDifficulty
+        ?? (typeof difficultyOrOptions === 'number' ? difficultyOrOptions : 5);
+    const difficulty = assertFiniteInteger(difficultyRaw, 'Challenge difficulty', 1);
+    const maxForAlg = getMaxDifficulty(algorithm);
+    if (difficulty > maxForAlg)
+        throw new Error(`Challenge difficulty must be at most ${maxForAlg} for ${algorithm}`);
     const normalizedAmount = assertFiniteInteger(selectedWorkload?.amount ?? options?.amount ?? (options ? 1 : amount), 'Challenge amount', 1);
     const ttlValue = options?.ttlSeconds ?? (options ? 30 : ttlSeconds);
     if (Number.isFinite(ttlValue) && Math.floor(ttlValue) < 1) {
@@ -350,8 +668,13 @@ async function createChallenge(difficultyOrOptions = 5, amount = 4, ttlSeconds =
         if (!allowed)
             throw new RateLimitedError('Challenge issuance rate limited');
     }
-    const challenges = Array.from({ length: normalizedAmount }, () => createSingleChallenge(difficulty, normalizedTtl, options?.context));
-    emitEvent(options, { type: 'challenge-issued', difficulty, amount: normalizedAmount });
+    const challenges = Array.from({ length: normalizedAmount }, () => createSingleChallenge(difficulty, normalizedTtl, options?.context, algorithm, workloadArgon));
+    if (algorithm === 'argon2id') {
+        emitEvent(options, { type: 'challenge-issued', difficulty, amount: normalizedAmount, algorithm });
+    }
+    else {
+        emitEvent(options, { type: 'challenge-issued', difficulty, amount: normalizedAmount });
+    }
     return challenges;
 }
 function normalizeMaxIterations(options) {
@@ -370,6 +693,10 @@ function solveSingleChallenge(token, options) {
         const payload = jsonwebtoken_1.default.decode(token);
         if (!payload)
             return undefined;
+        // Sync solver only supports sha256; argon2id requires async path
+        const alg = payload.alg ?? 'sha256';
+        if (alg === 'argon2id')
+            return undefined;
         const prefix = '0'.repeat(payload.difficulty);
         const maxIterations = normalizeMaxIterations(options);
         const maxDurationMs = normalizeMaxDurationMs(options);
@@ -401,6 +728,68 @@ function solveChallenge(token, options) {
     }
     return solveSingleChallenge(token, options);
 }
+async function solveSingleChallengeAsync(token, options) {
+    try {
+        const payload = jsonwebtoken_1.default.decode(token);
+        if (!payload)
+            return undefined;
+        const alg = payload.alg ?? 'sha256';
+        const prefix = '0'.repeat(payload.difficulty);
+        const maxIterations = normalizeMaxIterations(options);
+        const maxDurationMs = normalizeMaxDurationMs(options);
+        const startedAt = Date.now();
+        if (alg === 'argon2id') {
+            const params = {
+                m: payload.m ?? exports.HARD_MAX.m,
+                t: payload.t ?? 1,
+                p: payload.p ?? 1,
+                hashLen: payload.hashLen ?? 32,
+            };
+            // Validate params match token (already validated by isValidPayload, but double-check)
+            if (params.m > exports.HARD_MAX.m || params.t > exports.HARD_MAX.t || params.p > exports.HARD_MAX.p)
+                return undefined;
+            for (let nonce = 0;; nonce++) {
+                if (maxIterations !== undefined && nonce >= maxIterations)
+                    return undefined;
+                if (Date.now() - startedAt >= maxDurationMs)
+                    return undefined;
+                const hash = await argon2idHash(payload.challenge, nonce, params);
+                if (hash.startsWith(prefix))
+                    return { nonce: String(nonce), hash };
+                // Cooperative yield every 1 iteration for argon (hash is already ~6ms, but allow abort checks)
+                if (nonce % 1 === 0)
+                    await new Promise(r => setTimeout(r, 0));
+            }
+        }
+        else {
+            for (let nonce = 0;; nonce++) {
+                if (maxIterations !== undefined && nonce >= maxIterations)
+                    return undefined;
+                if (Date.now() - startedAt >= maxDurationMs)
+                    return undefined;
+                const hash = crypto_1.default.createHash('sha256').update(`${payload.challenge}${nonce}`).digest('hex');
+                if (hash.startsWith(prefix))
+                    return { nonce: String(nonce), hash };
+            }
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+async function solveChallengeAsync(token, options) {
+    if (Array.isArray(token)) {
+        const solutions = [];
+        for (const item of token) {
+            const solution = await solveSingleChallengeAsync(item, options);
+            if (!solution)
+                return undefined;
+            solutions.push(solution);
+        }
+        return solutions;
+    }
+    return solveSingleChallengeAsync(token, options);
+}
 function shouldDebug(options) {
     return options?.debug ?? process.env.NODE_ENV === 'development';
 }
@@ -451,6 +840,22 @@ function contextMatches(payload, suppliedContext) {
     const actual = Buffer.from(hashContext(suppliedContext, payload.jti), 'hex');
     return expected.length === actual.length && crypto_1.default.timingSafeEqual(expected, actual);
 }
+/**
+ * Verifies that a proof-of-work solution correctly solves the challenge token(s).
+ *
+ * Validation steps:
+ * 1. JWT signature and expiration check
+ * 2. Hash verification (recomputed hash matches difficulty)
+ * 3. Context binding check (if context was provided)
+ * 4. Replay prevention (via ReplayStore if configured)
+ *
+ * Supports batch verification with atomic replay detection.
+ *
+ * @param token - Challenge token(s) to verify
+ * @param nonce - Solution nonce(s) or ChallengeSolution object(s)
+ * @param options - Verification options (replay prevention, context, rate limiting)
+ * @returns Result indicating validity or specific failure reason
+ */
 async function verifySolution(token, nonce, options) {
     if (options?.rateLimiter) {
         const allowed = await options.rateLimiter.check(options?.context);
@@ -498,10 +903,27 @@ async function verifySolution(token, nonce, options) {
             if (!contextMatches(payload, options?.context)) {
                 return warn('context-mismatch', 'verifySolution rejected a mismatched challenge context', options);
             }
-            const hash = crypto_1.default
-                .createHash('sha256')
-                .update(`${payload.challenge}${String(currentNonce)}`)
-                .digest('hex');
+            const alg = payload.alg ?? 'sha256';
+            let hash;
+            if (alg === 'argon2id') {
+                const params = {
+                    m: payload.m ?? exports.HARD_MAX.m,
+                    t: payload.t ?? 1,
+                    p: payload.p ?? 1,
+                    hashLen: payload.hashLen ?? 32,
+                };
+                // Strict validation — tokens with out-of-bounds params already rejected by isValidPayload, but double-check for safety
+                if (params.m < 8 || params.m > exports.HARD_MAX.m || params.t < 1 || params.t > exports.HARD_MAX.t || params.p < 1 || params.p > exports.HARD_MAX.p) {
+                    return warn('invalid-token', 'verifySolution rejected an invalid argon2id token', options);
+                }
+                hash = await argon2idHash(payload.challenge, currentNonce, params);
+            }
+            else {
+                hash = crypto_1.default
+                    .createHash('sha256')
+                    .update(`${payload.challenge}${String(currentNonce)}`)
+                    .digest('hex');
+            }
             if (!hash.startsWith('0'.repeat(payload.difficulty))) {
                 return warn('invalid-solution', 'verifySolution rejected an invalid nonce', options);
             }