Types

type ChallengeToken = string; // A signed JWT challenge token

interface ChallengeSolution {
  nonce: string; // The nonce that satisfies the PoW condition
  hash: string;  // The hash (hex) produced by nonce
}

type PowAlgorithm = 'sha256' | 'argon2id';

type ArgonProfile = 'mobile' | 'standard';

const HARD_MAX = { m: 32768, t: 3, p: 1, hashLen: 32 } as const;

interface ChallengeOptions {
  difficulty?: number | 'auto';
  amount?: number;
  ttlSeconds?: number;
  context?: string;
  workload?: Pick<Workload, 'difficulty' | 'amount'>;

  // Only used when difficulty === 'auto':
  targetDurationMs?: number;   // default 750
  riskScore?: number;          // 0–100, default 50
  calibration?: ClientCalibration;
  minDifficulty?: number;      // default 3
  maxDifficulty?: number;      // default 6
  minAmount?: number;          // default 1
  maxAmount?: number;          // default 8

  // Algorithm selection:
  algorithm?: PowAlgorithm;    // default 'sha256'
  argonProfile?: ArgonProfile; // only with algorithm: 'argon2id'

  // Extension hooks:
  rateLimiter?: RateLimiter;
  onEvent?: (event: RibauntEvent) => void;
}

interface ClientCalibration {
  iterations: number;
  durationMs: number;
}

interface AdaptiveWorkloadOptions extends WorkloadBounds {
  riskScore?: number;
  targetDurationMs?: number;
  calibration?: ClientCalibration;
  algorithm?: PowAlgorithm;    // default 'sha256'
  argonProfile?: ArgonProfile; // only with algorithm: 'argon2id'
}

interface Workload {
  difficulty: number;
  amount: number;
  estimatedAttempts: number;
  algorithm: PowAlgorithm;
  argon?: { m: number; t: number; p: number; hashLen: number }; // present for 'argon2id'
}

interface RiskSignals {
  ip?: string;
  userAgent?: string;
  accountAgeSeconds?: number;
  requestVelocity?: number;
  [key: string]: unknown;
}

interface RiskScorer {
  score(signals: RiskSignals): number | Promise<number>;
}

interface RiskThresholds {
  challenge: number; // risk < challenge            -> allow
  block: number;     // challenge <= risk < block   -> challenge
}                    // risk >= block               -> block

const DEFAULT_RISK_THRESHOLDS: RiskThresholds = { challenge: 40, block: 80 };

interface AssessWorkloadOptions extends WorkloadBounds {
  targetDurationMs?: number;
  calibration?: ClientCalibration;
}

interface AssessOptions {
  signals: RiskSignals;
  scorer?: RiskScorer;
  thresholds?: RiskThresholds;
  workload?: AssessWorkloadOptions;
}

interface RiskAssessment {
  risk: number;                            // 0–100, finite
  action: 'allow' | 'challenge' | 'block';
  workload?: Workload;
}

interface ReplayStore {
  consume(jti: string, expiresAt: number): Promise<boolean>;
  consumeMany?(jtis: string[], expiresAt: number): Promise<boolean>;
}

class LocalReplayStore implements ReplayStore {
  async consume(jti: string, expiresAt: number): Promise<boolean>;
  async consumeMany(jtis: string[], expiresAt: number): Promise<boolean>;
}

import { LocalReplayStore } from 'ribaunt';

const store = new LocalReplayStore();

const result = await verifySolution(tokens, solutions, {
  replayPrevention: 'remote',
  replayStore: store,
});

type ReplayPreventionMode = 'disabled' | 'local' | 'remote';

interface VerifySolutionOptions {
  replayPrevention?: ReplayPreventionMode; // default: 'local'
  replayStore?: ReplayStore;               // required when replayPrevention is 'remote'
  context?: string;                        // optional challenge scope
  debug?: boolean;                         // default: true in development
  onWarning?: (warning: VerifyWarning) => void;
  rateLimiter?: RateLimiter;
  onEvent?: (event: RibauntEvent) => void;
}

interface RateLimiter {
  check(key?: string): Promise<boolean>;
}

class RateLimitedError extends Error {
  readonly code: 'rate-limited';
  readonly name: 'RateLimitedError';
}

import { verifySolution, RateLimitedError } from 'ribaunt';

try {
  const result = await verifySolution(tokens, solutions, { rateLimiter });
  // ...
} catch (error) {
  if (error instanceof RateLimitedError) {
    return res.status(429).json({ error: error.message });
  }
  throw error;
}

type RibauntEvent =
  | { type: 'challenge-issued'; difficulty: number; amount: number; algorithm?: PowAlgorithm }
  | { type: 'verify-success' }
  | { type: 'verify-failure'; reason: VerifyFailureReason; message: string };

type VerifySolutionResult =
  | { valid: true }
  | { valid: false; reason: VerifyFailureReason; message: string };

interface VerifyWarning {
  reason: VerifyWarningReason;
  message: string;
  error?: unknown;
}

type VerifyFailureReason =
  | 'invalid-token'
  | 'expired-token'
  | 'invalid-solution'
  | 'context-mismatch'
  | 'replay-detected'
  | 'replay-store-unavailable'
  | 'configuration-error';

type VerifyWarningReason = VerifyFailureReason;

interface SolveChallengeOptions {
  maxIterations?: number; // hard cap on nonce attempts
  maxDurationMs?: number; // default: 30000 ms
}

type WidgetState = 'initial' | 'fetching' | 'solving' | 'verifying' | 'done' | 'error';

type WidgetErrorCode =
  | 'timeout'
  | 'aborted'
  | 'challenge-fetch-failed'
  | 'invalid-challenge'
  | 'solve-failed'
  | 'verification-failed'
  | 'worker-unavailable'
  | 'unknown';

class WidgetError extends Error {
  readonly code: WidgetErrorCode;
  readonly name: 'WidgetError';
}

interface RibauntWidgetHandle {
  reset(): void;
  getState(): WidgetState | '';
  startVerification(): void;
}