covara 0.11.2 → 0.13.0

package/README.md

@@ -88,6 +88,8 @@ function TodoList() {
 - **Security Headers** - HSTS, `X-Frame-Options`, MIME-sniffing protection, and more, auto-mounted by `createCovara`; opt-in CSP (so it never blocks your frontend)
 - **Authorization Scopes** - Row-level security with RSQL expressions, enforced across reads, writes, subscriptions, and search
 - **Field-level Read Masking** - `fields.readable` allowlist strips non-readable columns from every response and subscription event (cannot be bypassed via `?select=`)
+- **Abuse Protection** - A cost-weighted **token-bucket budget** with **proof of work as the overflow valve** via `abuseProtection({ budget, pow })`: within budget, requests are served and debited; over budget, the server issues a stateless, request-bound, one-time-use **428 challenge** that the **client library solves and retries transparently** (solving pays the overdraft). Difficulty is programmatically controllable via a trust hook; an endpoint can also *always* require PoW. Disable PoW for a hard 429 instead. KV-backed with in-memory fallback; works alongside the conventional `rateLimit`. See [docs](https://kahveciderin.github.io/covara/docs/tooling/abuse-protection)
+- **CAPTCHA** *(beta)* - Turnstile / hCaptcha / reCAPTCHA / custom providers as a per-endpoint gate (signup/login/…) or an alternative budget-overflow valve. The plain client surfaces a typed challenge; the React `<CovaraCaptcha/>` component renders the provider widget and retries transparently.
 
 ### File Storage
 - **Storage Adapters** - Local disk, S3, Cloudflare R2 (native binding or S3-compat), and in-memory behind one `StorageAdapter` interface
@@ -295,7 +297,8 @@ app.resource("/posts", postsTable, {
   // Optimistic locking (ETag / If-Match)
   etag: { versionField: "version" },
 
-  // Authorization scopes (row-level security via RSQL)
+  // Authorization scopes (row-level security via RSQL). Scopes can traverse a
+  // declared relation as a join, e.g. rsql`organization.members.userId==${user.id}`
   auth: {
     public: { read: true },
     update: async (user) => rsql`authorId==${user.id}`,

package/dist/abuse/budget.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Token-bucket budget store. Each identity class has a `capacity` and a
+ * `refillPerMinute`; operations deduct their declared cost. Exhaustion is a
+ * hard rejection (the caller raises 429). Backed by the global KV (or an
+ * injected store) with an in-process memory fallback, mirroring the rate-limit
+ * store's KV-or-memory pattern.
+ */
+import type { KVAdapter } from "../kv/index.js";
+import type { BudgetClassConfig } from "./config.js";
+export interface BudgetConsumeResult {
+    allowed: boolean;
+    remaining: number;
+    retryAfterMs: number;
+}
+export declare class BudgetStore {
+    private readonly injected?;
+    constructor(injected?: KVAdapter | undefined);
+    private get kv();
+    private load;
+    private save;
+    /**
+     * Inspect the bucket without deducting: report current (refilled) tokens,
+     * whether `cost` fits, the deficit, and the wait for a hard limit. Used to
+     * decide whether a request is within budget before any charge.
+     */
+    assess(key: string, cost: number, cfg: BudgetClassConfig, now?: number): Promise<BudgetConsumeResult & {
+        tokens: number;
+        sufficient: boolean;
+        deficit: number;
+    }>;
+    /**
+     * Debit `cost` from the bucket, flooring at zero (never negative). Used both
+     * for an in-budget charge and to settle the overdraft after a solved PoW
+     * challenge.
+     */
+    deduct(key: string, cost: number, cfg: BudgetClassConfig, now?: number): Promise<number>;
+    consume(key: string, cost: number, cfg: BudgetClassConfig, now?: number): Promise<BudgetConsumeResult>;
+    credit(key: string, amount: number, cfg: BudgetClassConfig, now?: number): Promise<void>;
+}
+export declare const clearBudgetMemoryForTests: () => void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/abuse/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/abuse/budget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAIlD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AA2BD,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAT,QAAQ,CAAC,EAAE,SAAS,YAAA;IAEjD,OAAO,KAAK,EAAE,GAEb;YAEa,IAAI;YAuBJ,IAAI;IAwBlB;;;;OAIG;IACG,MAAM,CACV,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,iBAAiB,EACtB,GAAG,SAAa,GACf,OAAO,CAAC,mBAAmB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAc1F;;;;OAIG;IACG,MAAM,CACV,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,iBAAiB,EACtB,GAAG,SAAa,GACf,OAAO,CAAC,MAAM,CAAC;IAQZ,OAAO,CACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,iBAAiB,EACtB,GAAG,SAAa,GACf,OAAO,CAAC,mBAAmB,CAAC;IAkBzB,MAAM,CACV,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,iBAAiB,EACtB,GAAG,SAAa,GACf,OAAO,CAAC,IAAI,CAAC;CAMjB;AAED,eAAO,MAAM,yBAAyB,QAAO,IAE5C,CAAC"}

package/dist/abuse/budget.js

@@ -0,0 +1,122 @@
+/**
+ * Token-bucket budget store. Each identity class has a `capacity` and a
+ * `refillPerMinute`; operations deduct their declared cost. Exhaustion is a
+ * hard rejection (the caller raises 429). Backed by the global KV (or an
+ * injected store) with an in-process memory fallback, mirroring the rate-limit
+ * store's KV-or-memory pattern.
+ */
+import { getGlobalKV, hasGlobalKV } from "../kv/index.js";
+const BUDGET_PREFIX = "covara:budget:";
+const memoryBuckets = new Map();
+const refill = (state, cfg, now) => {
+    const elapsedMs = Math.max(0, now - state.lastRefillMs);
+    const refilled = (elapsedMs / 60000) * cfg.refillPerMinute;
+    return {
+        tokens: Math.min(cfg.capacity, state.tokens + refilled),
+        lastRefillMs: now,
+    };
+};
+const retryAfterMsFor = (deficit, cfg) => {
+    if (cfg.refillPerMinute <= 0)
+        return Number.MAX_SAFE_INTEGER;
+    return Math.ceil((deficit / cfg.refillPerMinute) * 60000);
+};
+export class BudgetStore {
+    constructor(injected) {
+        this.injected = injected;
+    }
+    get kv() {
+        return this.injected ?? (hasGlobalKV() ? getGlobalKV() : null);
+    }
+    async load(key, cfg, now) {
+        const kv = this.kv;
+        if (!kv) {
+            const existing = memoryBuckets.get(key);
+            return existing
+                ? refill(existing, cfg, now)
+                : { tokens: cfg.capacity, lastRefillMs: now };
+        }
+        const data = await kv.hgetall(`${BUDGET_PREFIX}${key}`);
+        if (!data || data.tokens === undefined || data.lastRefillMs === undefined) {
+            return { tokens: cfg.capacity, lastRefillMs: now };
+        }
+        return refill({ tokens: parseFloat(data.tokens), lastRefillMs: parseInt(data.lastRefillMs, 10) }, cfg, now);
+    }
+    async save(key, state, cfg) {
+        const kv = this.kv;
+        if (!kv) {
+            memoryBuckets.set(key, state);
+            return;
+        }
+        const kvKey = `${BUDGET_PREFIX}${key}`;
+        await kv.hmset(kvKey, {
+            tokens: String(state.tokens),
+            lastRefillMs: String(state.lastRefillMs),
+        });
+        const secondsToFull = cfg.refillPerMinute > 0
+            ? Math.ceil(((cfg.capacity - state.tokens) / cfg.refillPerMinute) * 60) + 1
+            : 0;
+        if (secondsToFull > 0) {
+            await kv.expire(kvKey, secondsToFull);
+        }
+    }
+    /**
+     * Inspect the bucket without deducting: report current (refilled) tokens,
+     * whether `cost` fits, the deficit, and the wait for a hard limit. Used to
+     * decide whether a request is within budget before any charge.
+     */
+    async assess(key, cost, cfg, now = Date.now()) {
+        const state = await this.load(key, cfg, now);
+        const sufficient = state.tokens >= cost;
+        const deficit = Math.max(0, cost - state.tokens);
+        return {
+            allowed: sufficient,
+            sufficient,
+            tokens: state.tokens,
+            remaining: state.tokens,
+            deficit,
+            retryAfterMs: sufficient ? 0 : retryAfterMsFor(deficit, cfg),
+        };
+    }
+    /**
+     * Debit `cost` from the bucket, flooring at zero (never negative). Used both
+     * for an in-budget charge and to settle the overdraft after a solved PoW
+     * challenge.
+     */
+    async deduct(key, cost, cfg, now = Date.now()) {
+        if (cost <= 0)
+            return (await this.load(key, cfg, now)).tokens;
+        const state = await this.load(key, cfg, now);
+        state.tokens = Math.max(0, state.tokens - cost);
+        await this.save(key, state, cfg);
+        return state.tokens;
+    }
+    async consume(key, cost, cfg, now = Date.now()) {
+        const state = await this.load(key, cfg, now);
+        if (cost <= 0) {
+            return { allowed: true, remaining: state.tokens, retryAfterMs: 0 };
+        }
+        if (state.tokens >= cost) {
+            state.tokens -= cost;
+            await this.save(key, state, cfg);
+            return { allowed: true, remaining: state.tokens, retryAfterMs: 0 };
+        }
+        await this.save(key, state, cfg);
+        return {
+            allowed: false,
+            remaining: state.tokens,
+            retryAfterMs: retryAfterMsFor(cost - state.tokens, cfg),
+        };
+    }
+    async credit(key, amount, cfg, now = Date.now()) {
+        if (amount <= 0)
+            return;
+        const state = await this.load(key, cfg, now);
+        state.tokens = Math.min(cfg.capacity, state.tokens + amount);
+        await this.save(key, state, cfg);
+    }
+}
+export const clearBudgetMemoryForTests = () => {
+    memoryBuckets.clear();
+};
+//# sourceMappingURL=budget.js.map

package/dist/abuse/budget.js.map

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

package/dist/abuse/captcha.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CAPTCHA providers (BETA). Fetch-based token verification against the common
+ * managed providers plus a generic escape hatch. Verification is fail-closed:
+ * any network/parse error or a falsy provider result rejects the token.
+ *
+ * Runs on Node and Cloudflare Workers (uses the global `fetch`, no node deps).
+ */
+export interface CaptchaVerifyContext {
+    ip?: string;
+    action?: string;
+}
+export interface CaptchaProvider {
+    /** "turnstile" | "hcaptcha" | "recaptcha" | "custom" (or any custom name). */
+    name: string;
+    /** Public site key, surfaced to the client so it can render the widget. */
+    siteKey?: string;
+    verify(token: string, ctx?: CaptchaVerifyContext): Promise<boolean>;
+}
+export interface TurnstileOptions {
+    secret: string;
+    siteKey?: string;
+    verifyUrl?: string;
+}
+export declare const turnstile: (options: TurnstileOptions) => CaptchaProvider;
+export interface HcaptchaOptions {
+    secret: string;
+    siteKey?: string;
+    verifyUrl?: string;
+}
+export declare const hcaptcha: (options: HcaptchaOptions) => CaptchaProvider;
+export interface RecaptchaOptions {
+    secret: string;
+    siteKey?: string;
+    /** v3 score threshold (0..1). When set, the score must be >= minScore. */
+    minScore?: number;
+    verifyUrl?: string;
+}
+export declare const recaptcha: (options: RecaptchaOptions) => CaptchaProvider;
+export interface CustomCaptchaOptions {
+    name?: string;
+    siteKey?: string;
+    verify: (token: string, ctx?: CaptchaVerifyContext) => Promise<boolean> | boolean;
+}
+export declare const customCaptcha: (options: CustomCaptchaOptions) => CaptchaProvider;
+//# sourceMappingURL=captcha.d.ts.map

package/dist/abuse/captcha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captcha.d.ts","sourceRoot":"","sources":["../../src/abuse/captcha.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrE;AAkCD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,SAAS,GAAI,SAAS,gBAAgB,KAAG,eAUpD,CAAC;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,QAAQ,GAAI,SAAS,eAAe,KAAG,eAUlD,CAAC;AAEH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,SAAS,GAAI,SAAS,gBAAgB,KAAG,eAiBpD,CAAC;AAEH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACnF;AAED,eAAO,MAAM,aAAa,GAAI,SAAS,oBAAoB,KAAG,eAa5D,CAAC"}

package/dist/abuse/captcha.js

@@ -0,0 +1,80 @@
+/**
+ * CAPTCHA providers (BETA). Fetch-based token verification against the common
+ * managed providers plus a generic escape hatch. Verification is fail-closed:
+ * any network/parse error or a falsy provider result rejects the token.
+ *
+ * Runs on Node and Cloudflare Workers (uses the global `fetch`, no node deps).
+ */
+import { getLogger } from "../server/logger.js";
+const postSiteVerify = async (url, fields) => {
+    const body = new URLSearchParams();
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined && value !== "")
+            body.set(key, value);
+    }
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body,
+        });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch (error) {
+        getLogger().warn("CAPTCHA verification request failed", {
+            url,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+};
+export const turnstile = (options) => ({
+    name: "turnstile",
+    siteKey: options.siteKey,
+    async verify(token, ctx) {
+        const data = await postSiteVerify(options.verifyUrl ?? "https://challenges.cloudflare.com/turnstile/v0/siteverify", { secret: options.secret, response: token, remoteip: ctx?.ip });
+        return data?.success === true;
+    },
+});
+export const hcaptcha = (options) => ({
+    name: "hcaptcha",
+    siteKey: options.siteKey,
+    async verify(token, ctx) {
+        const data = await postSiteVerify(options.verifyUrl ?? "https://api.hcaptcha.com/siteverify", { secret: options.secret, response: token, remoteip: ctx?.ip });
+        return data?.success === true;
+    },
+});
+export const recaptcha = (options) => ({
+    name: "recaptcha",
+    siteKey: options.siteKey,
+    async verify(token, ctx) {
+        const data = await postSiteVerify(options.verifyUrl ?? "https://www.google.com/recaptcha/api/siteverify", { secret: options.secret, response: token, remoteip: ctx?.ip });
+        if (data?.success !== true)
+            return false;
+        if (options.minScore !== undefined && (data.score ?? 0) < options.minScore) {
+            return false;
+        }
+        if (ctx?.action && data.action && data.action !== ctx.action) {
+            return false;
+        }
+        return true;
+    },
+});
+export const customCaptcha = (options) => ({
+    name: options.name ?? "custom",
+    siteKey: options.siteKey,
+    async verify(token, ctx) {
+        try {
+            return await options.verify(token, ctx);
+        }
+        catch (error) {
+            getLogger().warn("Custom CAPTCHA verifier threw", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    },
+});
+//# sourceMappingURL=captcha.js.map

package/dist/abuse/captcha.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captcha.js","sourceRoot":"","sources":["../../src/abuse/captcha.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C,MAAM,cAAc,GAAG,KAAK,EAC1B,GAAW,EACX,MAA0C,EACN,EAAE;IACtC,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;IACnC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE;YAChE,IAAI;SACL,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,EAAE,CAAC,IAAI,CAAC,qCAAqC,EAAE;YACtD,GAAG;YACH,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AAQF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAyB,EAAmB,EAAE,CAAC,CAAC;IACxE,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG;QACrB,MAAM,IAAI,GAAG,MAAM,cAAc,CAC/B,OAAO,CAAC,SAAS,IAAI,2DAA2D,EAChF,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE,CAC/D,CAAC;QACF,OAAO,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAChC,CAAC;CACF,CAAC,CAAC;AAQH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAwB,EAAmB,EAAE,CAAC,CAAC;IACtE,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG;QACrB,MAAM,IAAI,GAAG,MAAM,cAAc,CAC/B,OAAO,CAAC,SAAS,IAAI,qCAAqC,EAC1D,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE,CAC/D,CAAC;QACF,OAAO,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAChC,CAAC;CACF,CAAC,CAAC;AAUH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAyB,EAAmB,EAAE,CAAC,CAAC;IACxE,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG;QACrB,MAAM,IAAI,GAAG,MAAM,cAAc,CAC/B,OAAO,CAAC,SAAS,IAAI,iDAAiD,EACtE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE,CAC/D,CAAC;QACF,IAAI,IAAI,EAAE,OAAO,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACzC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC3E,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,GAAG,EAAE,MAAM,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,CAAC;YAC7D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAC,CAAC;AAQH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA6B,EAAmB,EAAE,CAAC,CAAC;IAChF,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ;IAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;IACxB,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG;QACrB,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,EAAE,CAAC,IAAI,CAAC,+BAA+B,EAAE;gBAChD,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

package/dist/abuse/config.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Abuse-protection configuration: a token-bucket `budget` (cost-weighted rate
+ * limiting, hard-rejects with 429) and a `pow` proof-of-work gate, which are
+ * fully independent and may be enabled together. Costs and PoW opt-ins live on
+ * the individual endpoints; this module holds only the shared/global settings.
+ */
+import type { Context } from "hono";
+import type { KVAdapter } from "../kv/index.js";
+import type { UserContext } from "../resource/types.js";
+import type { PowAlgorithm } from "../pow/core.js";
+import type { CaptchaProvider } from "./captcha.js";
+export interface BudgetClassConfig {
+    capacity: number;
+    refillPerMinute: number;
+}
+export interface BudgetConfig {
+    enabled?: boolean;
+    /**
+     * Map a request to an identity class name. Defaults to "authenticated" for a
+     * logged-in user and "anonymous" otherwise.
+     */
+    classify?: (c: Context) => string;
+    /** Token bucket parameters per identity class. */
+    classes: Record<string, BudgetClassConfig>;
+    /**
+     * Derive the bucket key for a request within its class. Defaults to the user
+     * id (authenticated) or client IP (anonymous), namespaced by class.
+     */
+    keyGenerator?: (c: Context, className: string) => string;
+    /** Optional explicit KV store; defaults to the global KV, else in-memory. */
+    store?: KVAdapter;
+}
+export interface PowDifficultyContext {
+    c: Context;
+    user: UserContext | null;
+    ip: string;
+    /** Operation key, e.g. "read", "create", "rpc:generate", "auth.signup". */
+    operation: string;
+    resource?: string;
+    /** The statically configured difficulty before any hook adjustment. */
+    baseDifficulty: number;
+    /**
+     * Why the challenge is being considered:
+     * - "endpoint": the endpoint always requires PoW (its `pow` opt-in).
+     * - "budget": the caller is over budget, so PoW is the overflow valve.
+     */
+    reason: "endpoint" | "budget";
+    /** Budget cost of the operation (present when reason === "budget"). */
+    cost?: number;
+    /** Tokens available before the charge (present when reason === "budget"). */
+    available?: number;
+    /** How far over budget the request is, `cost - available` (budget reason). */
+    deficit?: number;
+}
+export interface PowConfig {
+    enabled?: boolean;
+    secret?: string;
+    /** Default leading-zero-bit difficulty when an endpoint enables PoW. */
+    difficulty?: number;
+    /**
+     * Programmatic difficulty control (IP/user trust). Return 0 to skip the
+     * challenge for trusted callers. Overrides the static difficulty.
+     */
+    getDifficulty?: (ctx: PowDifficultyContext) => number | Promise<number>;
+    challengeTtlMs?: number;
+    algorithm?: PowAlgorithm;
+    /** Optional explicit KV store for the replay cache; defaults to global KV. */
+    store?: KVAdapter;
+    /** Bind challenges to a hash of the request body (default true). */
+    bindBody?: boolean;
+}
+/** Which mechanism a budget-exhausted (overflow) request is challenged with. */
+export type OverflowMechanism = "pow" | "captcha";
+export interface CaptchaContext {
+    c: Context;
+    user: UserContext | null;
+    ip: string;
+    operation: string;
+    resource?: string;
+    reason: "endpoint" | "budget";
+}
+export interface CaptchaConfig {
+    /** BETA. The verification provider (turnstile/hcaptcha/recaptcha/custom). */
+    provider: CaptchaProvider;
+    enabled?: boolean;
+    /** Request header carrying the solved token (default "Covara-Captcha-Token"). */
+    tokenHeader?: string;
+}
+export interface AbuseProtectionInput {
+    budget?: BudgetConfig;
+    pow?: PowConfig;
+    /** CAPTCHA challenge support (BETA). */
+    captcha?: CaptchaConfig;
+    /** Default mechanism for budget-overflow challenges (default "pow"). */
+    overflow?: OverflowMechanism;
+}
+export interface AbuseProtectionConfig {
+    budget: BudgetConfig | null;
+    pow: PowConfig | null;
+    captcha: CaptchaConfig | null;
+    overflow: OverflowMechanism;
+}
+export declare const DEFAULT_POW_DIFFICULTY = 20;
+export declare const DEFAULT_POW_TTL_MS = 120000;
+/**
+ * Per-endpoint PoW opt-in (procedures, auth routes). `true` uses the
+ * global/default difficulty; an object overrides difficulty or supplies an
+ * endpoint-specific trust hook.
+ */
+export type EndpointPowConfig = boolean | {
+    difficulty?: number;
+    getDifficulty?: (ctx: PowDifficultyContext) => number | Promise<number>;
+};
+/** Operations that can carry an inline budget cost or PoW gate on a resource. */
+export type AbuseOperation = "read" | "create" | "update" | "delete" | "subscribe" | "count" | "aggregate" | "search";
+/** Inline per-operation budget costs declared on a resource. */
+export type ResourceCostConfig = Partial<Record<AbuseOperation, number>>;
+/**
+ * Resource-level PoW opt-in. `true` gates the mutating operations
+ * (create/update/delete) at the default difficulty. An object can override the
+ * difficulty/trust hook and restrict (or widen) the gated `operations`.
+ */
+export type ResourcePowConfig = boolean | {
+    difficulty?: number;
+    getDifficulty?: (ctx: PowDifficultyContext) => number | Promise<number>;
+    operations?: AbuseOperation[];
+};
+/**
+ * Per-endpoint CAPTCHA opt-in (procedures, auth routes). `true` always requires
+ * a CAPTCHA; an object can supply a reCAPTCHA v3 `action` or a `required` hook.
+ */
+export type EndpointCaptchaConfig = boolean | {
+    action?: string;
+    required?: (ctx: CaptchaContext) => boolean | Promise<boolean>;
+};
+/** Resource-level CAPTCHA opt-in; `operations` restricts which it gates. */
+export type ResourceCaptchaConfig = boolean | {
+    action?: string;
+    required?: (ctx: CaptchaContext) => boolean | Promise<boolean>;
+    operations?: AbuseOperation[];
+};
+export declare const abuseProtection: (input: AbuseProtectionInput) => AbuseProtectionConfig;
+export declare const setGlobalAbuseProtection: (config: AbuseProtectionConfig | AbuseProtectionInput) => void;
+export declare const getGlobalAbuseProtection: () => AbuseProtectionConfig | null;
+export declare const hasGlobalAbuseProtection: () => boolean;
+export declare const clearGlobalAbuseProtection: () => void;
+export declare const isBudgetEnabled: (config: AbuseProtectionConfig | null) => boolean;
+export declare const isPowEnabled: (config: AbuseProtectionConfig | null) => boolean;
+export declare const isCaptchaEnabled: (config: AbuseProtectionConfig | null) => boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/abuse/config.d.ts.map

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

package/dist/abuse/config.js

@@ -0,0 +1,33 @@
+/**
+ * Abuse-protection configuration: a token-bucket `budget` (cost-weighted rate
+ * limiting, hard-rejects with 429) and a `pow` proof-of-work gate, which are
+ * fully independent and may be enabled together. Costs and PoW opt-ins live on
+ * the individual endpoints; this module holds only the shared/global settings.
+ */
+export const DEFAULT_POW_DIFFICULTY = 20;
+export const DEFAULT_POW_TTL_MS = 120000;
+const normalize = (input) => ({
+    budget: input.budget ?? null,
+    pow: input.pow ?? null,
+    captcha: input.captcha ?? null,
+    overflow: input.overflow ?? "pow",
+});
+let globalConfig = null;
+export const abuseProtection = (input) => {
+    const config = normalize(input);
+    setGlobalAbuseProtection(config);
+    return config;
+};
+export const setGlobalAbuseProtection = (config) => {
+    globalConfig = normalize(config);
+};
+export const getGlobalAbuseProtection = () => globalConfig;
+export const hasGlobalAbuseProtection = () => globalConfig !== null;
+export const clearGlobalAbuseProtection = () => {
+    globalConfig = null;
+};
+export const isBudgetEnabled = (config) => !!config?.budget && config.budget.enabled !== false &&
+    Object.keys(config.budget.classes ?? {}).length > 0;
+export const isPowEnabled = (config) => !config?.pow || config.pow.enabled !== false;
+export const isCaptchaEnabled = (config) => !!config?.captcha && config.captcha.enabled !== false;
+//# sourceMappingURL=config.js.map

package/dist/abuse/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/abuse/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4GH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAO,CAAC;AA6D1C,MAAM,SAAS,GAAG,CAChB,KAAmD,EAC5B,EAAE,CAAC,CAAC;IAC3B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;IAC5B,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,IAAI;IACtB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;IAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,KAAK;CAClC,CAAC,CAAC;AAEH,IAAI,YAAY,GAAiC,IAAI,CAAC;AAEtD,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,KAA2B,EACJ,EAAE;IACzB,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAChC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,MAAoD,EAC9C,EAAE;IACR,YAAY,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAiC,EAAE,CACzE,YAAY,CAAC;AAEf,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAY,EAAE,CAAC,YAAY,KAAK,IAAI,CAAC;AAE7E,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAS,EAAE;IACnD,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAoC,EAAW,EAAE,CAC/E,CAAC,CAAC,MAAM,EAAE,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,KAAK,KAAK;IACnD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAEtD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAoC,EAAW,EAAE,CAC5E,CAAC,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,KAAK,KAAK,CAAC;AAE/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAoC,EAAW,EAAE,CAChF,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC"}

package/dist/abuse/enforce.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Unified abuse enforcement. A request's cost is charged against a token-bucket
+ * budget; when the budget is exhausted, proof of work is the overflow valve —
+ * the server issues a 428 challenge (difficulty scalable via a trust hook)
+ * instead of a hard rejection, and solving it pays the overdraft (the bucket is
+ * drained to zero). An endpoint can also *always* require PoW via its `pow`
+ * opt-in, independent of budget. When PoW is disabled, budget exhaustion falls
+ * back to a hard 429.
+ */
+import type { Context } from "hono";
+import { type EndpointCaptchaConfig, type EndpointPowConfig, type OverflowMechanism } from "./config.js";
+export interface EnforceAbuseOptions {
+    operation: string;
+    resource?: string;
+    /** Budget cost of this operation (0/undefined = not charged). */
+    cost?: number;
+    /** Endpoint always-PoW opt-in (independent of budget). */
+    endpointPow?: EndpointPowConfig;
+    /** Endpoint always-CAPTCHA opt-in (independent of budget). */
+    endpointCaptcha?: EndpointCaptchaConfig;
+    /** Override the budget-overflow mechanism for this endpoint. */
+    overflow?: OverflowMechanism;
+    /**
+     * Defer the budget debit: don't charge on allow, instead return a `settle()`
+     * the caller invokes when it decides the request counts (e.g. a failed
+     * login). When false (default) the cost is debited before returning.
+     */
+    defer?: boolean;
+}
+export interface AbuseGateResult {
+    /**
+     * Debit the operation's cost (floored at zero). A no-op in immediate mode
+     * (already charged); in deferred mode the caller invokes it to commit the
+     * charge. Safe to call at most once.
+     */
+    settle(): Promise<void>;
+}
+/**
+ * Charge an operation against the budget, gating with proof of work as needed.
+ * Throws `PowRequiredError` (428) when a challenge is required and unsolved, or
+ * `RateLimitError` (429) when over budget and PoW is disabled.
+ */
+export declare const enforceAbuse: (c: Context, options: EnforceAbuseOptions) => Promise<AbuseGateResult>;
+//# sourceMappingURL=enforce.d.ts.map

package/dist/abuse/enforce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce.d.ts","sourceRoot":"","sources":["../../src/abuse/enforce.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAYpC,OAAO,EAQL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAGvB,MAAM,UAAU,CAAC;AAwBlB,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,8DAA8D;IAC9D,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAYD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,GAAG,OAAO,EACV,SAAS,mBAAmB,KAC3B,OAAO,CAAC,eAAe,CAiJzB,CAAC"}