@nawa-captcha/server 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @nawa-captcha/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Nawa Captcha** — a self-hosted, privacy-friendly and accessible puzzle CAPTCHA. A drop-in alternative to reCAPTCHA, hCaptcha and Turnstile with no third-party tracking: your server issues the challenge and verifies the answer.
+
+This package: Node.js server: issue and verify challenges, Express middleware.
+
+- 🧩 38 challenge types you choose from (one, two or many, per action): slider jigsaws, rotate, drag to the shadow, jigsaw, hold, icon/colour/clock/symmetry grids, match pairs, tap in order, spell, order and story tiles, connect the dots, maze, math, dice, invisible proof-of-work, an accessible text question and an audio challenge — [see them live](https://oriebalzyuot96.github.io/nawa-captcha/#playground)
+- 🔒 Answers are sealed (AES-256-GCM) and never reach the browser; pass tokens are signed and single-use
+- ♿ Keyboard, touch and screen-reader friendly (text question and audio challenge); Arabic and English; RTL
+- 🎨 Premium 3D design, six themes in light and dark plus high contrast (WCAG 2.2 AA), Pelagic UI tokens, optional sound effects
+- 🖥️ Backends: Node.js / Express and ASP.NET Core (`NawaCaptcha.AspNetCore`, coming to NuGet)
+
+## Install
+
+> **Coming to npm.** `@nawa-captcha/server` is published once the `@nawa-captcha` npm organisation exists. Until then, build it from the [repository](https://github.com/oriebalzyuot96/nawa-captcha) (`npm install && npm run build`, then `npm pack -w @nawa-captcha/server`).
+
+```bash
+npm i @nawa-captcha/server
+# or
+yarn add @nawa-captcha/server
+# or
+pnpm add @nawa-captcha/server
+```
+
+## Usage
+
+```js
+import express from 'express';
+import { createNawaCaptcha } from '@nawa-captcha/server';
+import { nawaCaptchaExpress, requireCaptcha } from '@nawa-captcha/server/express';
+
+const guard = createNawaCaptcha({
+  secret: process.env.NAWA_CAPTCHA_SECRET, // ≥ 32 chars, never sent to browsers
+  siteKeys: ['main'],
+  actions: ['login'],
+});
+
+const app = express();
+// POST /captcha/challenge and POST /captcha/verify
+app.use('/captcha', express.json({ limit: '32kb' }), nawaCaptchaExpress(guard));
+// Protect a route: the token comes from the X-Nawa-Captcha-Token header or the nawa-captcha-token field
+app.post('/login', express.urlencoded({ extended: false }),
+  requireCaptcha(guard, { expectedAction: 'login', maxAgeSec: 300 }),
+  (req, res) => res.send('ok'));
+```
+
+## Choosing puzzles
+
+```js
+const guard = createNawaCaptcha({
+  secret: process.env.NAWA_CAPTCHA_SECRET,
+  types: ['slider', 'rotate-object', 'pairs', 'maze'], // allow-list: one, two or many
+  mode: 'random',                                      // 'random' | 'sequence' | 'adaptive' (default)
+  weights: { maze: 2 },
+  perAction: { login: ['pow', 'slider'], signup: { types: ['maze', 'spell'], steps: 2 } },
+});
+// Routes can demand more: requireCaptcha(guard, { expectedAction: 'signup', allowedTypes: ['maze', 'spell'], minSteps: 2 })
+```
+
+The browser can narrow the list (`<nawa-captcha types="slider,maze">`) but never widen it. With `steps` > 1, `POST /verify` returns `{ next }` until the last puzzle; the pass token then lists every solved type in `stp`. Every type, its keyboard operation and its blind-guess rate are in the [main README](https://github.com/oriebalzyuot96/nawa-captcha#puzzle-types).
+
+Then verify on your backend before trusting the request — see the [full guide](https://github.com/oriebalzyuot96/nawa-captcha#readme).
+
+📖 Docs: https://oriebalzyuot96.github.io/nawa-captcha/ · 💻 Source: https://github.com/oriebalzyuot96/nawa-captcha
+
+MIT © oriebalzyuot96

package/dist/binding.d.ts

@@ -0,0 +1,22 @@
+/** Which client attributes a token is bound to. Encoded in the token as `cbm`. */
+export type BindMode = 'none' | 'ip' | 'ua' | 'ip+ua';
+export declare const BIND_MODES: readonly BindMode[];
+export interface ClientInfo {
+    readonly ip?: string | undefined;
+    readonly userAgent?: string | undefined;
+}
+/** `::ffff:1.2.3.4` and `1.2.3.4` are the same client; IPv6 is compared lower-case. */
+export declare function normalizeIp(ip: string | undefined): string;
+export declare function normalizeUa(ua: string | undefined): string;
+/**
+ * The exact string hashed into `cb`. Mirrored byte-for-byte by the .NET verifier:
+ *   ip mode:    "ip=<ip>"
+ *   ua mode:    "ua=<ua>"
+ *   ip+ua mode: "ip=<ip>\nua=<ua>"
+ */
+export declare function bindingMaterial(mode: BindMode, client: ClientInfo): string | undefined;
+/** Returns base64url(HMAC-SHA256(K_bind, material)), or undefined when the client info is missing. */
+export declare function bindingHash(key: Uint8Array, mode: BindMode, client: ClientInfo): string | undefined;
+/** Pseudonymous per-client key for counters (rate limits, adaptive difficulty). Never stores raw IPs. */
+export declare function clientKey(key: Uint8Array, client: ClientInfo): string;
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC;AACtD,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAAkC,CAAC;AAE7E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAID,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK1D;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAatF;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGnG;AAED,yGAAyG;AACzG,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAGrE"}

package/dist/binding.js

@@ -0,0 +1,46 @@
+import { b64url, hmac } from './crypto.js';
+export const BIND_MODES = ['none', 'ip', 'ua', 'ip+ua'];
+const MAX_UA = 512;
+/** `::ffff:1.2.3.4` and `1.2.3.4` are the same client; IPv6 is compared lower-case. */
+export function normalizeIp(ip) {
+    if (!ip)
+        return '';
+    let value = ip.trim().toLowerCase();
+    if (value.startsWith('::ffff:') && value.includes('.'))
+        value = value.slice(7);
+    return value;
+}
+export function normalizeUa(ua) {
+    return (ua ?? '').trim().slice(0, MAX_UA);
+}
+/**
+ * The exact string hashed into `cb`. Mirrored byte-for-byte by the .NET verifier:
+ *   ip mode:    "ip=<ip>"
+ *   ua mode:    "ua=<ua>"
+ *   ip+ua mode: "ip=<ip>\nua=<ua>"
+ */
+export function bindingMaterial(mode, client) {
+    const ip = normalizeIp(client.ip);
+    const ua = normalizeUa(client.userAgent);
+    switch (mode) {
+        case 'none':
+            return undefined;
+        case 'ip':
+            return ip ? `ip=${ip}` : undefined;
+        case 'ua':
+            return ua ? `ua=${ua}` : undefined;
+        case 'ip+ua':
+            return ip && ua ? `ip=${ip}\nua=${ua}` : undefined;
+    }
+}
+/** Returns base64url(HMAC-SHA256(K_bind, material)), or undefined when the client info is missing. */
+export function bindingHash(key, mode, client) {
+    const material = bindingMaterial(mode, client);
+    return material === undefined ? undefined : b64url(hmac(key, material));
+}
+/** Pseudonymous per-client key for counters (rate limits, adaptive difficulty). Never stores raw IPs. */
+export function clientKey(key, client) {
+    const ip = normalizeIp(client.ip);
+    return b64url(hmac(key, `ck=${ip || 'unknown'}`)).slice(0, 22);
+}
+//# sourceMappingURL=binding.js.map

package/dist/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAI3C,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAO7E,MAAM,MAAM,GAAG,GAAG,CAAC;AAEnB,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,EAAsB;IAChD,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IACnB,IAAI,KAAK,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,EAAsB;IAChD,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAc,EAAE,MAAkB;IAChE,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACzC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,SAAS,CAAC;QACnB,KAAK,IAAI;YACP,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACrC,KAAK,IAAI;YACP,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACrC,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACvD,CAAC;AACH,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,WAAW,CAAC,GAAe,EAAE,IAAc,EAAE,MAAkB;IAC7E,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/C,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,SAAS,CAAC,GAAe,EAAE,MAAkB;IAC3D,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACjE,CAAC"}

package/dist/catalog.d.ts

@@ -0,0 +1,12 @@
+import type { ChallengeType } from './types.js';
+export type TypeFamily = 'drag' | 'select' | 'tap' | 'order' | 'draw' | 'type' | 'invisible';
+export interface TypeInfo {
+    readonly family: TypeFamily;
+    readonly en: string;
+    readonly ar: string;
+    /** Rough chance that a blind guess passes one attempt (documentation; see README). */
+    readonly guess: string;
+}
+/** Human-readable names for docs, galleries and playgrounds. */
+export declare const TYPE_INFO: Readonly<Record<ChallengeType, TypeInfo>>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7F,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,gEAAgE;AAChE,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAuC/D,CAAC"}

package/dist/catalog.js

@@ -0,0 +1,42 @@
+/** Human-readable names for docs, galleries and playgrounds. */
+export const TYPE_INFO = {
+    slider: { family: 'drag', en: 'Slider jigsaw', ar: 'لغز السحب', guess: '≈ 8%' },
+    'slide-unlock': { family: 'drag', en: 'Slide to the target', ar: 'اسحب إلى الهدف', guess: '≈ 7%' },
+    'shadow-drag': { family: 'drag', en: 'Drag to the shadow', ar: 'اسحب إلى الظل', guess: '< 2%' },
+    jigsaw: { family: 'drag', en: 'Jigsaw (4 pieces)', ar: 'أحجية من 4 قطع', guess: '1 in 23' },
+    rotate: { family: 'drag', en: 'Rotate the scene', ar: 'تدوير المشهد', guess: '≈ 7%' },
+    'rotate-object': { family: 'drag', en: 'Rotate the object', ar: 'تدوير الشيء', guess: '≈ 7%' },
+    'rotate-match': { family: 'drag', en: 'Align the inner circle', ar: 'محاذاة الدائرة الداخلية', guess: '≈ 7%' },
+    hold: { family: 'drag', en: 'Hold and release', ar: 'اضغط ثم أفلت', guess: '≈ 1 in 4' },
+    icons: { family: 'select', en: 'Select matching shapes', ar: 'اختيار الأشكال المطابقة', guess: '< 1%' },
+    'icons-weather': { family: 'select', en: 'Select weather icons', ar: 'اختيار رموز الطقس', guess: '< 1%' },
+    'icons-objects': { family: 'select', en: 'Select everyday objects', ar: 'اختيار الأشياء', guess: '< 1%' },
+    'odd-one-out': { family: 'select', en: 'Odd one out', ar: 'المختلف', guess: '1 in 9' },
+    'odd-rotation': { family: 'select', en: 'Find the mirrored letter', ar: 'الحرف المعكوس', guess: '1 in 6' },
+    'color-name': { family: 'select', en: 'Colour by name + pattern', ar: 'اللون بالاسم والنقش', guess: '< 1%' },
+    biggest: { family: 'select', en: 'Largest / smallest', ar: 'الأكبر / الأصغر', guess: '1 in 9' },
+    'find-shape': { family: 'select', en: 'Find the shape', ar: 'ابحث عن الشكل', guess: '< 1%' },
+    'shadow-pick': { family: 'select', en: 'Pick the shadow', ar: 'اختر الظل', guess: '1 in 6' },
+    pattern: { family: 'select', en: 'What comes next', ar: 'ما التالي', guess: '1 in 6' },
+    clock: { family: 'select', en: 'Read the clock', ar: 'قراءة الساعة', guess: '1 in 6' },
+    'math-compare': { family: 'select', en: 'Compare sums', ar: 'مقارنة النواتج', guess: '1 in 62' },
+    symmetry: { family: 'select', en: 'Complete the mirror', ar: 'أكمل التماثل', guess: '< 0.1%' },
+    pairs: { family: 'select', en: 'Match pairs', ar: 'مطابقة الأزواج', guess: '1 in 105' },
+    'tap-order': { family: 'tap', en: 'Tap numbers in order', ar: 'انقر الأرقام بالترتيب', guess: '< 0.1%' },
+    spell: { family: 'tap', en: 'Spell the word', ar: 'تهجئة الكلمة', guess: '< 0.1%' },
+    order: { family: 'order', en: 'Order dots / bars', ar: 'ترتيب النقاط والأعمدة', guess: '1 in 24' },
+    'order-size': { family: 'order', en: 'Order by size', ar: 'الترتيب حسب الحجم', guess: '1 in 24' },
+    'order-numbers': { family: 'order', en: 'Order numbers', ar: 'ترتيب الأعداد', guess: '1 in 24' },
+    'order-time': { family: 'order', en: 'Order clock times', ar: 'ترتيب الأوقات', guess: '1 in 24' },
+    story: { family: 'order', en: 'Picture story', ar: 'قصة مصورة', guess: '1 in 6–24' },
+    trace: { family: 'draw', en: 'Connect the dots', ar: 'توصيل النقاط', guess: '< 0.1%' },
+    'trace-letters': { family: 'draw', en: 'Connect A–E', ar: 'توصيل الحروف', guess: '< 0.1%' },
+    maze: { family: 'draw', en: 'Maze', ar: 'متاهة', guess: '< 0.1%' },
+    math: { family: 'type', en: 'Math image', ar: 'عملية حسابية', guess: '≈ 10%' },
+    count: { family: 'type', en: 'Count the objects', ar: 'عدّ الأشياء', guess: '≈ 1 in 5' },
+    dice: { family: 'type', en: 'Dice total', ar: 'مجموع النرد', guess: '≈ 1 in 6' },
+    pow: { family: 'invisible', en: 'Invisible proof-of-work', ar: 'إثبات عمل غير مرئي', guess: 'n/a (CPU cost)' },
+    accessible: { family: 'invisible', en: 'Accessible text question', ar: 'سؤال نصي ميسّر', guess: 'machine-readable' },
+    audio: { family: 'invisible', en: 'Audio challenge (digits / beeps)', ar: 'تحدٍّ صوتي (أرقام / نغمات)', guess: '1 in 10,000 (digits) · ≈ 1 in 6 (beeps)' },
+};
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/crypto.d.ts

@@ -0,0 +1,44 @@
+/** HKDF salt shared by every Nawa Captcha implementation (Node, .NET). Changing it breaks interop. */
+export declare const HKDF_SALT = "nawa-guard/v1";
+export type KeyPurpose = 'challenge-token' | 'pass-token' | 'client-binding';
+export interface SecretEntry {
+    /** Key id embedded in every token so secrets can be rotated. 1-16 chars of [A-Za-z0-9_-]. */
+    readonly kid: string;
+    /** High-entropy secret, at least 32 characters. Never ship it to a browser. */
+    readonly secret: string;
+}
+export interface Keyring {
+    /** The kid used for new tokens (first entry). */
+    readonly activeKid: string;
+    key(kid: string, purpose: KeyPurpose): Uint8Array | undefined;
+}
+export declare const MIN_SECRET_LENGTH = 32;
+export declare const utf8: (text: string) => Uint8Array;
+export declare function fromUtf8(bytes: Uint8Array): string | undefined;
+export declare function deriveKey(secret: string, purpose: KeyPurpose): Uint8Array;
+/**
+ * Builds a keyring from one or more secrets. The first entry signs/seals new tokens; all entries
+ * are accepted when opening/verifying, which is what makes zero-downtime rotation possible.
+ */
+export declare function createKeyring(secrets: string | readonly SecretEntry[]): Keyring;
+export declare function isValidKid(kid: string): boolean;
+export declare function b64url(buf: Uint8Array): string;
+export declare function fromB64url(text: string): Uint8Array | undefined;
+export declare function randomId(bytes?: number): string;
+export declare function hmac(key: Uint8Array, data: string): Uint8Array;
+export declare function sha256(data: string | Uint8Array): Uint8Array;
+/** Constant-time equality that is also safe for inputs of different lengths. */
+export declare function safeEqual(a: Uint8Array | string, b: Uint8Array | string): boolean;
+/** AES-256-GCM seal: returns iv(12) and ciphertext||tag(16). */
+export declare function seal(key: Uint8Array, plaintext: string, aad: string): {
+    iv: Uint8Array;
+    data: Uint8Array;
+};
+export declare function open(key: Uint8Array, iv: Uint8Array, data: Uint8Array, aad: string): string | undefined;
+/** Uniform integer in [min, maxExclusive); fractional bounds are rounded inward. */
+export declare const randInt: (min: number, maxExclusive: number) => number;
+export declare const randFloat: (min?: number, max?: number) => number;
+export declare const pick: <T>(items: readonly T[]) => T;
+export declare const shuffle: <T>(items: T[]) => T[];
+export declare const sample: <T>(items: readonly T[], count: number) => T[];
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAGA,sGAAsG;AACtG,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAE7E,MAAM,WAAW,WAAW;IAC1B,6FAA6F;IAC7F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;CAC/D;AAGD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAKpC,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,KAAG,UAAkC,CAAC;AACvE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAM9D;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,UAAU,CAEzE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,GAAG,OAAO,CAyB/E;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAE9C;AAID,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAQ/D;AAED,wBAAgB,QAAQ,CAAC,KAAK,SAAK,GAAG,MAAM,CAE3C;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAE9D;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAE5D;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CASjF;AAED,gEAAgE;AAChE,wBAAgB,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAG1G;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIvG;AAID,oFAAoF;AACpF,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,cAAc,MAAM,KAAG,MAA0C,CAAC;AACvG,eAAO,MAAM,SAAS,GAAI,YAAO,EAAE,YAAO,KAAG,MAAmC,CAAC;AACjF,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,SAAS,CAAC,EAAE,KAAG,CAA0B,CAAC;AACzE,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,KAAG,CAAC,EAA8B,CAAC;AACxE,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,OAAO,SAAS,CAAC,EAAE,EAAE,OAAO,MAAM,KAAG,CAAC,EAAoC,CAAC"}

package/dist/crypto.js

@@ -0,0 +1,108 @@
+import { aesGcmDecrypt, aesGcmEncrypt, fromBase64, hkdfSha256, hmacSha256, randomBytes, sha256 as sha256Bytes, timingSafeEqual } from './primitives.js';
+import { bytesToB64url, cryptoRng } from './rng.js';
+/** HKDF salt shared by every Nawa Captcha implementation (Node, .NET). Changing it breaks interop. */
+export const HKDF_SALT = 'nawa-guard/v1';
+const KID_RE = /^[A-Za-z0-9_-]{1,16}$/;
+export const MIN_SECRET_LENGTH = 32;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+export const utf8 = (text) => encoder.encode(text);
+export function fromUtf8(bytes) {
+    try {
+        return decoder.decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function deriveKey(secret, purpose) {
+    return hkdfSha256(utf8(secret), utf8(HKDF_SALT), utf8(purpose), 32);
+}
+/**
+ * Builds a keyring from one or more secrets. The first entry signs/seals new tokens; all entries
+ * are accepted when opening/verifying, which is what makes zero-downtime rotation possible.
+ */
+export function createKeyring(secrets) {
+    const list = typeof secrets === 'string' ? [{ kid: 'k1', secret: secrets }] : secrets;
+    if (list.length === 0)
+        throw new Error('nawa-captcha: at least one secret is required');
+    const keys = new Map();
+    for (const { kid, secret } of list) {
+        if (!KID_RE.test(kid))
+            throw new Error(`nawa-captcha: invalid kid "${kid}" (1-16 chars of A-Z a-z 0-9 _ -)`);
+        if (typeof secret !== 'string' || secret.length < MIN_SECRET_LENGTH) {
+            throw new Error(`nawa-captcha: secret for kid "${kid}" must be at least ${MIN_SECRET_LENGTH} characters`);
+        }
+        if (keys.has(kid))
+            throw new Error(`nawa-captcha: duplicate kid "${kid}"`);
+        keys.set(kid, new Map([
+            ['challenge-token', deriveKey(secret, 'challenge-token')],
+            ['pass-token', deriveKey(secret, 'pass-token')],
+            ['client-binding', deriveKey(secret, 'client-binding')],
+        ]));
+    }
+    const first = list[0];
+    if (!first)
+        throw new Error('nawa-captcha: at least one secret is required');
+    return {
+        activeKid: first.kid,
+        key: (kid, purpose) => keys.get(kid)?.get(purpose),
+    };
+}
+export function isValidKid(kid) {
+    return KID_RE.test(kid);
+}
+export function b64url(buf) {
+    return bytesToB64url(buf);
+}
+const B64URL_RE = /^[A-Za-z0-9_-]*$/;
+export function fromB64url(text) {
+    if (!B64URL_RE.test(text) || text.length % 4 === 1)
+        return undefined;
+    const b64 = text.replace(/-/g, '+').replace(/_/g, '/');
+    try {
+        return fromBase64(b64 + '='.repeat((4 - (b64.length % 4)) % 4));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function randomId(bytes = 16) {
+    return b64url(randomBytes(bytes));
+}
+export function hmac(key, data) {
+    return hmacSha256(key, utf8(data));
+}
+export function sha256(data) {
+    return sha256Bytes(typeof data === 'string' ? utf8(data) : data);
+}
+/** Constant-time equality that is also safe for inputs of different lengths. */
+export function safeEqual(a, b) {
+    const left = typeof a === 'string' ? utf8(a) : a;
+    const right = typeof b === 'string' ? utf8(b) : b;
+    if (left.length !== right.length) {
+        // Still burn a comparison so the timing does not reveal the length mismatch early.
+        timingSafeEqual(left, left);
+        return false;
+    }
+    return timingSafeEqual(left, right);
+}
+/** AES-256-GCM seal: returns iv(12) and ciphertext||tag(16). */
+export function seal(key, plaintext, aad) {
+    const iv = randomBytes(12);
+    return { iv, data: aesGcmEncrypt(key, iv, utf8(plaintext), utf8(aad)) };
+}
+export function open(key, iv, data, aad) {
+    if (iv.length !== 12 || data.length < 17)
+        return undefined;
+    const plain = aesGcmDecrypt(key, iv, data, utf8(aad));
+    return plain ? fromUtf8(plain) : undefined;
+}
+// ---------------------------------------------------------------- randomness helpers (CSPRNG only)
+/** Uniform integer in [min, maxExclusive); fractional bounds are rounded inward. */
+export const randInt = (min, maxExclusive) => cryptoRng.int(min, maxExclusive);
+export const randFloat = (min = 0, max = 1) => cryptoRng.float(min, max);
+export const pick = (items) => cryptoRng.pick(items);
+export const shuffle = (items) => cryptoRng.shuffle(items);
+export const sample = (items, count) => cryptoRng.sample(items, count);
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,245 @@
+import { type BindMode, type ClientInfo } from './binding.js';
+import { type Keyring, type SecretEntry } from './crypto.js';
+import { type ActionPolicy, type ResolvedPolicy, type SelectionMode } from './selection.js';
+import { type NawaCaptchaStore } from './store.js';
+import { type PassTokenClaims } from './tokens.js';
+import { type ChallengeType, type CheckFailure, type Lang, type ViewKind } from './types.js';
+export type { ActionPolicy, SelectionMode } from './selection.js';
+export type RateLimitHook = (ctx: {
+    kind: 'challenge' | 'verify';
+    clientKey: string;
+    client: ClientInfo;
+}) => boolean | Promise<boolean>;
+export interface RateLimitOptions {
+    readonly windowSec: number;
+    /** Challenges per client per window. */
+    readonly challenge: number;
+    /** Verify calls per client per window. */
+    readonly verify: number;
+}
+export interface AdaptiveOptions {
+    /** How long failures are remembered. */
+    readonly windowSec: number;
+    /** Failures that raise the difficulty one level. */
+    readonly failuresPerLevel: number;
+    readonly maxLevel: number;
+}
+export type GuardEvent = {
+    type: 'challenge-issued';
+    challengeType: ChallengeType;
+    level: number;
+    clientKey: string;
+    action: string;
+    step?: number;
+    steps?: number;
+} | {
+    type: 'step-solved';
+    challengeType: ChallengeType;
+    level: number;
+    clientKey: string;
+    action: string;
+    step: number;
+    steps: number;
+    solveMs: number;
+} | {
+    type: 'verify-success';
+    challengeType: ChallengeType;
+    level: number;
+    clientKey: string;
+    action: string;
+    solveMs: number;
+    solvedTypes?: readonly ChallengeType[];
+} | {
+    type: 'verify-failed';
+    challengeType?: ChallengeType;
+    reason: VerifyFailure;
+    detail?: string;
+    clientKey: string;
+} | {
+    type: 'rate-limited';
+    kind: 'challenge' | 'verify';
+    clientKey: string;
+};
+export interface NawaCaptchaOptions {
+    /** Server secret (≥32 chars), or a list of `{ kid, secret }` for rotation (first one signs). */
+    readonly secret: string | readonly SecretEntry[];
+    /** Allowed public site keys. When omitted any well-formed site key is accepted. */
+    readonly siteKeys?: readonly string[];
+    /** Allowed action names. When omitted any well-formed action is accepted. */
+    readonly actions?: readonly string[];
+    readonly store?: NawaCaptchaStore;
+    readonly challengeTtlSec?: number;
+    readonly passTtlSec?: number;
+    /** Bind tokens to the client's IP and/or User-Agent. Default `ip+ua`. */
+    readonly bind?: BindMode;
+    /**
+     * Allow-list of challenge types the server may issue (one, two or many). Default: all types for
+     * `adaptive` (filtered by the ladder), every visual type for `random`/`sequence`. The browser
+     * can only narrow this list, never widen it.
+     */
+    readonly types?: readonly ChallengeType[];
+    /** Relative weights for random picks (default 1 each; 0 disables a type). */
+    readonly weights?: Partial<Record<ChallengeType, number>>;
+    /** How a type is picked from the allowed ones. Default `adaptive`. */
+    readonly mode?: SelectionMode;
+    /** Puzzles to solve in a row (each a different type when possible) before a pass token. Default 1, max 3. */
+    readonly steps?: number;
+    /** Per-action overrides, e.g. `{ login: ['pow', 'slider'], signup: { types: [...], steps: 2 } }`. */
+    readonly perAction?: Readonly<Record<string, readonly ChallengeType[] | ActionPolicy>>;
+    /** Honour the browser's `types` narrowing hint (`<nawa-captcha types="…">`). Default true. */
+    readonly clientNarrowing?: boolean;
+    /** Type pools by difficulty level (index = level), for `adaptive`. */
+    readonly ladder?: readonly (readonly ChallengeType[])[];
+    /** Start every client at an invisible proof-of-work; visible puzzles only after failures/risk. */
+    readonly invisibleFirst?: boolean;
+    /** Base proof-of-work difficulty in leading zero bits (each level adds 2). Default 16. */
+    readonly powBits?: number;
+    /** Let the browser pick one exact puzzle type from the allow-list (demos, galleries). */
+    readonly allowClientType?: boolean;
+    /** The accessible alternatives (text question, audio) can always be requested, even when not in `types`. Default true. */
+    readonly allowAccessible?: boolean;
+    readonly maxAttempts?: Partial<Record<ChallengeType, number>>;
+    readonly minSolveMs?: Partial<Record<ChallengeType, number>>;
+    readonly rateLimit?: false | RateLimitOptions | RateLimitHook;
+    readonly adaptive?: false | AdaptiveOptions;
+    /** Extra levels from your own risk signals (e.g. failed logins for this account). */
+    readonly assessRisk?: (ctx: {
+        client: ClientInfo;
+        action: string;
+        clientKey: string;
+    }) => number | Promise<number>;
+    readonly onEvent?: (event: GuardEvent) => void;
+    readonly defaultLang?: Lang;
+    readonly now?: () => number;
+}
+export interface ChallengeRequest {
+    readonly siteKey?: unknown;
+    readonly action?: unknown;
+    readonly lang?: unknown;
+    /** One exact type (only honoured with `allowClientType`, except `accessible`). */
+    readonly type?: unknown;
+    /** Narrowing hint: an array (or comma-separated string) of types. Never widens the allow-list. */
+    readonly types?: unknown;
+    readonly client: ClientInfo;
+}
+export interface ChallengeResponse {
+    readonly token: string;
+    readonly type: ChallengeType;
+    /** The widget view that renders this type. */
+    readonly view: ViewKind;
+    readonly lang: Lang;
+    readonly prompt: string;
+    readonly data: unknown;
+    readonly level: number;
+    /** Multi-step: this step (1-based) and the total. Both 1 for single puzzles. */
+    readonly step: number;
+    readonly steps: number;
+    /** Unix ms. */
+    readonly expiresAt: number;
+    /** Lifetime in ms (relative, so browsers with a skewed clock still refresh on time). */
+    readonly expiresInMs: number;
+}
+export type ChallengeError = 'invalid-input' | 'rate-limited';
+export type VerifyFailure = 'invalid-input' | 'invalid-token' | 'expired' | 'client-mismatch' | 'replayed' | 'attempts-exceeded' | 'too-fast' | 'rate-limited' | CheckFailure;
+/** What the browser is told. Deliberately coarser than {@link VerifyFailure} (no tuning oracle for bots). */
+export type PublicVerifyError = 'invalid-input' | 'invalid-token' | 'expired' | 'failed' | 'rate-limited';
+export type VerifyResult = {
+    ok: true;
+    passToken: string;
+    expiresAt: number;
+    expiresInMs: number;
+    type: ChallengeType;
+    solvedTypes: readonly ChallengeType[];
+    next?: undefined;
+}
+/** Multi-step: this step was solved; the next challenge must be solved before a pass token is issued. */
+ | {
+    ok: true;
+    next: ChallengeResponse;
+    passToken?: undefined;
+} | {
+    ok: false;
+    error: PublicVerifyError;
+    reason: VerifyFailure;
+    detail?: string;
+    retry: boolean;
+};
+export interface VerifyRequest {
+    readonly token: unknown;
+    readonly answer: unknown;
+    readonly client: ClientInfo;
+}
+export type PassTokenError = 'missing-token' | 'malformed' | 'unknown-key' | 'bad-signature' | 'expired' | 'not-yet-valid' | 'too-old' | 'action-mismatch' | 'site-mismatch' | 'type-not-allowed' | 'too-few-steps' | 'client-mismatch' | 'replayed';
+export type PassTokenResult = {
+    ok: true;
+    claims: PassTokenClaims;
+} | {
+    ok: false;
+    error: PassTokenError;
+};
+export interface VerifyPassTokenOptions {
+    /** Same secret(s) as the issuing server; pass a list to accept rotated keys. */
+    readonly secret: string | readonly SecretEntry[] | Keyring;
+    /** The action the protected route expects (e.g. "login"). Required: tokens are not interchangeable across actions. */
+    readonly expectedAction: string | readonly string[];
+    readonly expectedSiteKey?: string;
+    /** Reject tokens issued longer ago than this, even if not yet expired. */
+    readonly maxAgeSec?: number;
+    /** Shared store for single-use enforcement. Defaults to a process-wide in-memory store. */
+    readonly store?: NawaCaptchaStore;
+    /** The request's client info; required when the token is client-bound. */
+    readonly client?: ClientInfo;
+    /**
+     * Restrict which challenge types are acceptable for this route (e.g. exclude 'pow'). For a
+     * multi-step token, at least one solved step must be of an allowed type.
+     */
+    readonly allowedTypes?: readonly ChallengeType[];
+    /** Require at least this many solved puzzles (multi-step tokens). Default 1. */
+    readonly minSteps?: number;
+    readonly clockSkewSec?: number;
+    readonly now?: () => number;
+}
+export declare class NawaCaptcha {
+    readonly options: NawaCaptchaOptions;
+    readonly keys: Keyring;
+    readonly store: NawaCaptchaStore;
+    private readonly registry;
+    private readonly powByBits;
+    private readonly base;
+    private readonly explicitTypes;
+    private readonly policies;
+    private readonly bind;
+    private readonly now;
+    constructor(options: NawaCaptchaOptions);
+    /** The effective selection policy for an action (global options merged with `perAction`). */
+    policy(action: string): ResolvedPolicy;
+    private emit;
+    private clientKeyOf;
+    private allowed;
+    private levelFor;
+    private definition;
+    private maxAttempts;
+    private minSolveMs;
+    /** Picks a type from `pool` according to the policy, avoiding `exclude` when possible. */
+    private choose;
+    private issue;
+    createChallenge(req: ChallengeRequest): Promise<{
+        ok: true;
+        challenge: ChallengeResponse;
+    } | {
+        ok: false;
+        error: ChallengeError;
+    }>;
+    verify(req: VerifyRequest): Promise<VerifyResult>;
+    /** Server-side pass-token check using this instance's secrets and store. */
+    verifyPassToken(token: unknown, opts: Omit<VerifyPassTokenOptions, 'secret' | 'store'> & {
+        store?: NawaCaptchaStore;
+    }): Promise<PassTokenResult>;
+}
+export declare function createNawaCaptcha(options: NawaCaptchaOptions): NawaCaptcha;
+/**
+ * Verifies a pass token on your backend (the equivalent of reCAPTCHA siteverify, but local):
+ * signature, expiry, max age, action, site key, allowed types, steps, client binding, and single use.
+ */
+export declare function verifyPassToken(token: unknown, opts: VerifyPassTokenOptions): Promise<PassTokenResult>;
+//# sourceMappingURL=engine.d.ts.map