ribaunt 0.2.4 → 0.2.6

package/dist/index.js

@@ -2,6 +2,16 @@ import crypto from 'crypto';
 import jwt from 'jsonwebtoken';
 import { DEFAULT_RISK_THRESHOLDS, defaultScorer, validateRiskThresholds, validateScorerOutput, } from './risk.js';
 export { DEFAULT_RISK_THRESHOLDS };
+export const HARD_MAX = {
+    m: 32 * 1024,
+    t: 3,
+    p: 1,
+    hashLen: 32,
+};
+export const ARGON_PROFILES = {
+    mobile: { m: 8 * 1024, t: 1, p: 1, hashLen: 32 },
+    standard: { m: 8 * 1024, t: 1, p: 1, hashLen: 32 },
+};
 export class RateLimitedError extends Error {
     constructor(message = 'Rate limit exceeded') {
         super(message);
@@ -42,9 +52,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 import('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 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`);
@@ -57,17 +127,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 > HARD_MAX.m)
+            return false;
+        if (typeof value.t !== 'number' || !Number.isInteger(value.t) || value.t < 1 || value.t > HARD_MAX.t)
+            return false;
+        if (typeof value.p !== 'number' || !Number.isInteger(value.p) || value.p < 1 || value.p > 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) {
@@ -75,20 +168,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}`);
     }
@@ -96,18 +201,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 };
+                }
             }
         }
     }
@@ -115,9 +227,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.
  */
 export 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
@@ -131,33 +262,54 @@ export 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)}`);
         }
     }
@@ -182,9 +334,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.
@@ -258,6 +415,13 @@ export 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
+ */
 export function calibrateNode(iterations = 128) {
     if (!Number.isFinite(iterations) || iterations < 1) {
         throw new Error('Calibration iterations must be at least 1');
@@ -272,7 +436,71 @@ export function calibrateNode(iterations = 128) {
         durationMs: Math.max(1, Math.round(performance.now() - startedAt)),
     };
 }
+/**
+ * Alias for calibrateNode - measures device hashing speed for adaptive workload.
+ */
 export const 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.
+ */
+export 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.
+ */
+export const calibrateArgonClient = calibrateArgonNode;
+/**
+ * Resets Argon2id module cache for testing purposes.
+ * Should not be called in production code.
+ */
+export function __resetArgonForTesting() {
+    cachedArgon2id = null;
+    argon2idLoadPromise = null;
+    cachedArgonCalibrationWarmup = null;
+}
 function generateChallenge(length = 8) {
     return crypto.randomBytes(length).toString('base64url').slice(0, length);
 }
@@ -294,7 +522,7 @@ function getSecret() {
     }
     return secret;
 }
-function createSingleChallenge(difficulty, ttlSeconds, context) {
+function createSingleChallenge(difficulty, ttlSeconds, context, algorithm = 'sha256', argonParams) {
     const jti = crypto.randomUUID();
     const payload = {
         challenge: generateChallenge(),
@@ -302,6 +530,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 jwt.sign(payload, getSecret(), { algorithm: 'HS256' });
@@ -318,13 +562,51 @@ function emitEvent(options, event) {
 }
 export 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) {
@@ -336,8 +618,13 @@ export async function createChallenge(difficultyOrOptions = 5, amount = 4, ttlSe
         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) {
@@ -356,6 +643,10 @@ function solveSingleChallenge(token, options) {
         const payload = jwt.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);
@@ -387,6 +678,68 @@ export function solveChallenge(token, options) {
     }
     return solveSingleChallenge(token, options);
 }
+async function solveSingleChallengeAsync(token, options) {
+    try {
+        const payload = jwt.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 ?? 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 > HARD_MAX.m || params.t > HARD_MAX.t || params.p > 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.createHash('sha256').update(`${payload.challenge}${nonce}`).digest('hex');
+                if (hash.startsWith(prefix))
+                    return { nonce: String(nonce), hash };
+            }
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export 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';
 }
@@ -437,6 +790,22 @@ function contextMatches(payload, suppliedContext) {
     const actual = Buffer.from(hashContext(suppliedContext, payload.jti), 'hex');
     return expected.length === actual.length && crypto.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
+ */
 export async function verifySolution(token, nonce, options) {
     if (options?.rateLimiter) {
         const allowed = await options.rateLimiter.check(options?.context);
@@ -484,10 +853,27 @@ export 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
-                .createHash('sha256')
-                .update(`${payload.challenge}${String(currentNonce)}`)
-                .digest('hex');
+            const alg = payload.alg ?? 'sha256';
+            let hash;
+            if (alg === 'argon2id') {
+                const params = {
+                    m: payload.m ?? 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 > HARD_MAX.m || params.t < 1 || params.t > HARD_MAX.t || params.p < 1 || params.p > HARD_MAX.p) {
+                    return warn('invalid-token', 'verifySolution rejected an invalid argon2id token', options);
+                }
+                hash = await argon2idHash(payload.challenge, currentNonce, params);
+            }
+            else {
+                hash = crypto
+                    .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);
             }