@cequrebackends/plugin-security 0.12.2

package/dist/mfa.d.ts

@@ -0,0 +1,18 @@
+/**
+ * RFC 6238 TOTP (Time-Based One-Time Password) implementation.
+ * Uses HMAC-SHA1 via Web Crypto — no external dependencies.
+ * Compatible with Google Authenticator, Authy, 1Password, etc.
+ */
+/** Generate a random 20-byte base32-encoded TOTP secret. */
+export declare function generateTOTPSecret(): string;
+/** Generate a TOTP code for the current time. */
+export declare function generateTOTP(secret: string, timeStep?: number, digits?: number): Promise<string>;
+/** Verify a TOTP code against the current time, with a configurable window. */
+export declare function verifyTOTP(secret: string, code: string, window?: number): Promise<boolean>;
+/** Generate an `otpauth://` provisioning URI for QR code enrollment. */
+export declare function generateOTPAuthURI(secret: string, account: string, issuer?: string): string;
+/** Generate single-use backup codes (hex format: XXXXX-XXXXX-XXXXXX). */
+export declare function generateBackupCodes(count?: number): string[];
+/** Hash a backup code with SHA-256 for storage (like refresh tokens). */
+export declare function hashBackupCode(code: string): Promise<string>;
+//# sourceMappingURL=mfa.d.ts.map

package/dist/mfa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mfa.d.ts","sourceRoot":"","sources":["../src/mfa.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,4DAA4D;AAC5D,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AA8BD,iDAAiD;AACjD,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7F;AAED,+EAA+E;AAC/E,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3F;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAiB,GAAG,MAAM,CAIrG;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,MAAW,GAAG,MAAM,EAAE,CAQhE;AAED,yEAAyE;AACzE,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAElE"}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,20 @@
+import type { CequreAST } from "@cequrebackends/cequre-ts";
+import type { CequreKV } from "@cequrebackends/cequre-ts";
+/**
+ * Extract the real client IP, respecting trusted proxies.
+ *
+ * When `trustedProxies` is provided, X-Forwarded-For / X-Real-IP are
+ * only honoured if the direct connection IP is in the trusted list.
+ * When empty, the headers are ignored and the direct IP is used.
+ */
+export declare function resolveClientIP(request: Request, trustedProxies?: string[]): string;
+export declare class RateLimiter {
+    private kv;
+    private schema;
+    private hasRateLimit;
+    private trustedProxies;
+    constructor(schema: CequreAST, kv: CequreKV, trustedProxies?: string[]);
+    check(request: Request): Promise<Response | null> | Response | null;
+    private _doCheckAsync;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAI1D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,MAAM,EAAE,GACvB,MAAM,CA4BR;AAED,qBAAa,WAAW;IACvB,OAAO,CAAC,EAAE,CAAW;IACrB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,cAAc,CAAW;gBAErB,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE;IAOtE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI;YAyCrD,aAAa;CAW3B"}

package/dist/secrets.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Secrets provider abstraction.
+ *
+ * Allows production deployments to resolve secrets (JWT keys, encryption
+ * keys, audit secrets) from a KMS, HashiCorp Vault, or other external
+ * store instead of environment variables.
+ *
+ * The default implementation (`EnvVarSecrets`) reads from `process.env`.
+ * Future implementations: `VaultSecrets`, `KMSSecrets` — same interface.
+ */
+export interface SecretsProvider {
+    /** Resolve a secret value by name. Returns null if not found. */
+    getSecret(name: string): Promise<string | null>;
+    /** List all available secret names (for diagnostics). */
+    listSecrets(): Promise<string[]>;
+}
+/**
+ * Default secrets provider — reads from environment variables.
+ * No external dependencies, works everywhere.
+ */
+export declare class EnvVarSecrets implements SecretsProvider {
+    getSecret(name: string): Promise<string | null>;
+    listSecrets(): Promise<string[]>;
+}
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEhD,yDAAyD;IACzD,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,eAAe;IAC7C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI/C,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAGvC"}

package/dist/token-store.d.ts

@@ -0,0 +1,58 @@
+import type { CequreAdapter } from "@cequrebackends/cequre-ts";
+/**
+ * A persisted entry for a refresh token.
+ * The hash is the SHA-256 of the raw refresh JWT string.
+ */
+export interface RefreshTokenEntry {
+    userId: string;
+    collection: string;
+    role?: string;
+    expiresAt: number;
+}
+/**
+ * Abstraction over where refresh tokens are stored.
+ *
+ * - `InMemoryTokenStore` — process-local Map (dev / single-instance).
+ * - `AdapterTokenStore`  — persisted via the CequreAdapter in a
+ *   `cequre_refresh_tokens` system table (multi-instance / production).
+ *
+ * Every method takes the token *hash* (SHA-256 hex), never the raw token.
+ */
+export interface TokenStore {
+    store(hash: string, entry: RefreshTokenEntry): Promise<void>;
+    lookup(hash: string): Promise<RefreshTokenEntry | null>;
+    revoke(hash: string): Promise<void>;
+    revokeAllForUser(userId: string): Promise<void>;
+    purgeExpired(): Promise<void>;
+}
+export declare class InMemoryTokenStore implements TokenStore {
+    private store_;
+    store(hash: string, entry: RefreshTokenEntry): Promise<void>;
+    lookup(hash: string): Promise<RefreshTokenEntry | null>;
+    revoke(hash: string): Promise<void>;
+    revokeAllForUser(userId: string): Promise<void>;
+    purgeExpired(): Promise<void>;
+}
+/**
+ * System collection/table name used by AdapterTokenStore.
+ */
+export declare const REFRESH_TOKEN_COLLECTION = "cequre_refresh_tokens";
+/**
+ * Persists refresh tokens through the CequreAdapter so they survive
+ * process restarts and are visible across multiple server instances.
+ *
+ * Each token is stored as a document whose `id` is the token hash.
+ * This works across SQL adapters (Postgres, SQLite), MongoDB, Redis,
+ * and SurrealDB — all of which expose the same `create / findById /
+ * find / delete` contract.
+ */
+export declare class AdapterTokenStore implements TokenStore {
+    private adapter;
+    constructor(adapter: CequreAdapter);
+    store(hash: string, entry: RefreshTokenEntry): Promise<void>;
+    lookup(hash: string): Promise<RefreshTokenEntry | null>;
+    revoke(hash: string): Promise<void>;
+    revokeAllForUser(userId: string): Promise<void>;
+    purgeExpired(): Promise<void>;
+}
+//# sourceMappingURL=token-store.d.ts.map

package/dist/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../src/token-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAK/D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAMD,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,MAAM,CAAwC;IAEhD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAIvD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAMpC;AAMD;;GAEG;AACH,eAAO,MAAM,wBAAwB,0BAA0B,CAAC;AAEhE;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IACtC,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa;IAEpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAgBvD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAepC"}

package/dist/webhooks.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Webhook signing utility.
+ *
+ * Provides HMAC-SHA256 signing for outbound webhook payloads so consumers
+ * can verify authenticity. Follows the Stripe-style header format:
+ *
+ *   X-Cequre-Signature: t=<timestamp>,v1=<hex-hmac>
+ *
+ * Consumers verify by:
+ * 1. Splitting the header on ","
+ * 2. Extracting the timestamp (t=) and signature (v1=)
+ * 3. Computing HMAC-SHA256 over "<timestamp>.<payload>"
+ * 4. Comparing with constant-time equality
+ */
+/**
+ * Signs a webhook payload and returns the signature header value.
+ *
+ * @param secret - The shared secret (must be known by both sender and receiver)
+ * @param payload - The raw payload string (JSON body, etc.)
+ * @param timestamp - Optional timestamp (defaults to now, in seconds)
+ * @returns Header value string: "t=<ts>,v1=<hex>"
+ */
+export declare function signWebhook(secret: string, payload: string, timestamp?: number): Promise<string>;
+/**
+ * The header name to use for the signature.
+ */
+export declare const WEBHOOK_SIGNATURE_HEADER = "X-Cequre-Signature";
+/**
+ * Verifies a webhook signature against a payload.
+ *
+ * @param secret - The shared secret
+ * @param headerValue - The value of the X-Cequre-Signature header
+ * @param payload - The raw payload string
+ * @param toleranceSeconds - Maximum age of the signature (default: 300 = 5 min)
+ * @returns true if the signature is valid and within the tolerance window
+ */
+export declare function verifyWebhookSignature(secret: string, headerValue: string, payload: string, toleranceSeconds?: number): Promise<boolean>;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,uBAAgB,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,gBAAgB,GAAE,MAAY,GAC7B,OAAO,CAAC,OAAO,CAAC,CAmClB"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@cequrebackends/plugin-security",
+  "version": "0.12.2",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target bun --packages external && tsc --emitDeclarationOnly"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0",
+    "@cequrebackends/cequre-ts": "0.12.2"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.js",
+      "default": "./dist/auth.js"
+    },
+    "./rate-limiter": {
+      "types": "./dist/rate-limiter.d.ts",
+      "import": "./dist/rate-limiter.js",
+      "default": "./dist/rate-limiter.js"
+    },
+    "./token-store": {
+      "types": "./dist/token-store.d.ts",
+      "import": "./dist/token-store.js",
+      "default": "./dist/token-store.js"
+    },
+    "./audit": {
+      "types": "./dist/audit.d.ts",
+      "import": "./dist/audit.js",
+      "default": "./dist/audit.js"
+    },
+    "./encryption": {
+      "types": "./dist/encryption.d.ts",
+      "import": "./dist/encryption.js",
+      "default": "./dist/encryption.js"
+    },
+    "./mfa": {
+      "types": "./dist/mfa.d.ts",
+      "import": "./dist/mfa.js",
+      "default": "./dist/mfa.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cequrebackends/cequre.git"
+  },
+  "peerDependencies": {
+    "@cequrebackends/cequre-ts": "0.12.2"
+  }
+}