ribaunt 0.1.6 → 0.2.1

package/README.md

@@ -37,11 +37,14 @@ pnpm add ribaunt
 ## Quick Start
 
 Set a strong secret in your server environment. Keep this server-only.
+Ribaunt requires at least 32 UTF-8 bytes; generate a random value rather than a memorable password.
 
 ```env
 RIBAUNT_SECRET="replace-with-a-long-random-secret"
 ```
 
+> **Upgrading from v0.1:** `verifySolution()` now returns a structured result object, not a boolean. Always check `result.valid`; using the result object directly in an `if` condition is unsafe because JavaScript objects are truthy.
+
 Create two endpoints: one to issue challenges and one to verify solutions.
 
 ```ts
@@ -60,10 +63,10 @@ app.get('/api/captcha/challenge', (_req, res) => {
 
 app.post('/api/captcha/verify', async (req, res) => {
   const { tokens, solutions } = req.body;
-  const valid = await verifySolution(tokens, solutions);
+  const result = await verifySolution(tokens, solutions);
 
-  if (!valid) {
-    return res.status(400).json({ success: false, error: 'Invalid CAPTCHA solution' });
+  if (!result.valid) {
+    return res.status(400).json({ success: false, error: result.reason });
   }
 
   return res.json({ success: true });
@@ -140,12 +143,38 @@ const challenges = createChallenge(5, 4, 120);
 
 Validate user- or config-controlled values before passing them to `createChallenge()`. Invalid values throw.
 
+### `createChallenge({ difficulty: "auto", ... })`
+
+Creates adaptive challenge tokens from a server-bounded calibration hint. Calibration is untrusted and raise-only: it can increase work for fast clients, but it never lowers the server baseline.
+
+```ts
+const challenges = createChallenge({
+  difficulty: 'auto',
+  calibration: requestBody.calibration,
+  targetDurationMs: 750,
+  minDifficulty: 3,
+  maxDifficulty: 6,
+  minAmount: 1,
+  maxAmount: 8,
+  ttlSeconds: 60,
+});
+```
+
+For machine-to-machine checks, benchmark the Node client and send the same calibration shape:
+
+```ts
+import { calibrateNode } from 'ribaunt';
+
+const calibration = calibrateNode();
+```
+
 ### `verifySolution(tokens, solutions, options?)`
 
-Verifies submitted solutions and returns `Promise<boolean>`.
+Verifies submitted solutions and returns a structured result:
+`{ valid: true }` or `{ valid: false, reason, message }`.
 
 ```ts
-const valid = await verifySolution(tokens, solutions, {
+const result = await verifySolution(tokens, solutions, {
   onWarning: (warning) => {
     console.log('captcha warning', warning.reason, warning.message);
   },
@@ -155,7 +184,7 @@ const valid = await verifySolution(tokens, solutions, {
 Replay prevention defaults to `local`, which blocks token reuse in the current process. For serverless or horizontally scaled deployments, use `replayPrevention: 'remote'` with an atomic distributed store.
 
 ```ts
-const valid = await verifySolution(tokens, solutions, {
+const result = await verifySolution(tokens, solutions, {
   replayPrevention: 'remote',
   replayStore: {
     consume: async (jti, expiresAt) => {
@@ -184,6 +213,8 @@ const solutions = solveChallenge(challenges, {
   challenge-endpoint="/api/captcha/challenge"
   verify-endpoint="/api/captcha/verify"
   auto-verify="true"
+  challenge-method="POST"
+  calibrate="true"
   show-warning="false"
   warning-message="Verification may take longer on this device."
   solve-timeout="15000"
@@ -196,6 +227,8 @@ const solutions = solveChallenge(challenges, {
 | `challenge-endpoint` | `challengeEndpoint` | Endpoint that returns `{ challenges: string[] }`. |
 | `verify-endpoint` | `verifyEndpoint` | Endpoint that accepts `{ tokens, solutions }`. |
 | `auto-verify` | `autoVerify` | Starts verification when the widget loads. |
+| `challenge-method` | `challengeMethod` | Use `POST` when sending calibration to an auto-hardness endpoint. |
+| `calibrate` | `calibrate` | Benchmarks the browser and sends `{ calibration }` with POST challenge requests. |
 | `show-warning` | `showWarning` | Shows a warning banner. |
 | `warning-message` | `warningMessage` | Custom warning text. |
 | `solve-timeout` | `solveTimeout` | Optional solve timeout in milliseconds. |

package/dist/cjs/index.d.ts

@@ -3,22 +3,66 @@ export interface ChallengeSolution {
     nonce: string;
     hash: string;
 }
+export interface ClientCalibration {
+    iterations: number;
+    durationMs: number;
+}
+export interface WorkloadBounds {
+    minDifficulty?: number;
+    maxDifficulty?: number;
+    minAmount?: number;
+    maxAmount?: number;
+}
+export interface AdaptiveWorkloadOptions extends WorkloadBounds {
+    riskScore?: number;
+    targetDurationMs?: number;
+    calibration?: ClientCalibration;
+}
+export interface Workload {
+    difficulty: number;
+    amount: number;
+    estimatedAttempts: number;
+}
+export interface ChallengeOptions {
+    difficulty?: number | 'auto';
+    amount?: number;
+    ttlSeconds?: number;
+    context?: string;
+    workload?: Pick<Workload, 'difficulty' | 'amount'>;
+    riskScore?: number;
+    targetDurationMs?: number;
+    calibration?: ClientCalibration;
+    minDifficulty?: number;
+    maxDifficulty?: number;
+    minAmount?: number;
+    maxAmount?: number;
+}
 export interface ReplayStore {
     consume(jti: string, expiresAt: number): Promise<boolean>;
+    consumeMany?(jtis: string[], expiresAt: number): Promise<boolean>;
 }
 export type ReplayPreventionMode = 'disabled' | 'local' | 'remote';
 export interface VerifySolutionOptions {
     replayPrevention?: ReplayPreventionMode;
     replayStore?: ReplayStore;
+    context?: string;
     debug?: boolean;
     onWarning?: (warning: VerifyWarning) => void;
 }
-export type VerifyWarningReason = 'invalid-token' | 'expired-token' | 'invalid-solution' | 'replay-detected' | 'configuration-error';
+export type VerifyFailureReason = 'invalid-token' | 'expired-token' | 'invalid-solution' | 'context-mismatch' | 'replay-detected' | 'configuration-error';
+export type VerifyWarningReason = VerifyFailureReason;
 export interface VerifyWarning {
     reason: VerifyWarningReason;
     message: string;
     error?: unknown;
 }
+export type VerifySolutionResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: VerifyFailureReason;
+    message: string;
+};
 export interface SolveChallengeOptions {
     maxIterations?: number;
     maxDurationMs?: number;
@@ -26,34 +70,18 @@ export interface SolveChallengeOptions {
 export declare class LocalReplayStore implements ReplayStore {
     private usedTokens;
     consume(jti: string, expiresAt: number): Promise<boolean>;
+    consumeMany(jtis: string[], expiresAt: number): Promise<boolean>;
     private cleanup;
 }
 /**
- * Creates one or more PoW challenges and returns them as signed JWT tokens.
- *
- * @param difficulty - Number of leading zeros required in the hash (default 5)
- * @param amount - Number of challenges to create (default 4)
- * @param ttlSeconds - Time to live for each challenge in seconds (default 30)
- * @returns An array of JWT challenge tokens
+ * Selects bounded proof-of-work using a server-owned risk floor and untrusted timing calibration.
  */
+export declare function selectWorkload(options?: AdaptiveWorkloadOptions): Workload;
+export declare function calibrateNode(iterations?: number): ClientCalibration;
+export declare const calibrateClient: typeof calibrateNode;
 export declare function createChallenge(difficulty?: number, amount?: number, ttlSeconds?: number): ChallengeToken[];
-/**
- * Solves one or more PoW challenges encoded in JWT tokens.
- *
- * @param token - The JWT challenge token or an array of tokens
- * @param options - Optional guardrails for test/debug usage (`maxIterations`, `maxDurationMs`)
- * @returns The nonce/hash pair for single input or an array of them for multiple tokens
- */
-export declare function solveChallenge(token: ChallengeToken): ChallengeSolution | undefined;
+export declare function createChallenge(options: ChallengeOptions): ChallengeToken[];
 export declare function solveChallenge(token: ChallengeToken, options?: SolveChallengeOptions): ChallengeSolution | undefined;
-export declare function solveChallenge(token: ChallengeToken[]): ChallengeSolution[] | undefined;
 export declare function solveChallenge(token: ChallengeToken[], options?: SolveChallengeOptions): ChallengeSolution[] | undefined;
-/**
- * Verifies a PoW solution returned by the client.
- *
- * @param token - The original JWT issued as the challenge (single token or array of tokens)
- * @param nonce - The nonce/answer submitted by the client (single nonce, array of nonces, or array of solution objects)
- * @returns true only if every provided solution is valid; otherwise false
- */
-export declare function verifySolution(token: ChallengeToken | ChallengeToken[], nonce: number | string | Array<number | string> | ChallengeSolution | ChallengeSolution[], options?: VerifySolutionOptions): Promise<boolean>;
+export declare function verifySolution(token: ChallengeToken | ChallengeToken[], nonce: number | string | Array<number | string> | ChallengeSolution | ChallengeSolution[], options?: VerifySolutionOptions): Promise<VerifySolutionResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;IACxC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,eAAe,GACf,kBAAkB,GAClB,iBAAiB,GACjB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,UAAU,CAA6B;IAEzC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/D,OAAO,CAAC,OAAO;CAShB;AA0LD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,UAAU,GAAE,MAAU,EACtB,MAAM,GAAE,MAAU,EAClB,UAAU,GAAE,MAAW,GACtB,cAAc,EAAE,CAUlB;AA0FD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB,GAAG,SAAS,CAAC;AACrF,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,iBAAiB,GAAG,SAAS,CAAC;AACjC,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,GAAG,SAAS,CAAC;AACzF,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,iBAAiB,EAAE,GAAG,SAAS,CAAC;AAwBnC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,EACxC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,EACzF,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAuDlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}