@cequrebackends/plugin-security 0.12.2

package/README.md

@@ -0,0 +1,23 @@
+# @cequrebackends/plugin-security
+
+Security enforcement plugin for Cequre backends. Handles access control, rate limiting, field encryption, and audit logging.
+
+## Installation
+
+```bash
+bun add @cequrebackends/plugin-security
+```
+
+## Usage
+
+```typescript
+import { CequreRuntime } from "@cequrebackends/cequre-ts";
+import { defaultSecurity } from "@cequrebackends/plugin-security";
+
+const runtime = new CequreRuntime(schema, {
+  adapter,
+  plugins: [
+    defaultSecurity()
+  ]
+});
+```

package/dist/audit.d.ts

@@ -0,0 +1,39 @@
+import type { CequreAST } from "@cequrebackends/cequre-ts";
+export interface CequreAuditEvent {
+    action: string;
+    collection?: string;
+    recordId?: string;
+    userId?: string;
+    requestId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AuditLogEntry extends CequreAuditEvent {
+    id?: string;
+    hmac: string;
+    prevHmac: string | null;
+    createdAt?: string;
+}
+/**
+ * Resolves the audit HMAC key. Precedence:
+ *   1. `config.security.audit.secret` (explicit operator override)
+ *   2. `CEQURE_AUDIT_SECRET` environment variable
+ *   3. HKDF-SHA256 derivation from `JWT_SECRET`
+ */
+export declare function resolveAuditSecret(config: CequreAST): Promise<CryptoKey>;
+/**
+ * Computes the HMAC-SHA256 over `canonical(payload) + prevHmac`.
+ */
+export declare function computeAuditHmac(key: CryptoKey, event: CequreAuditEvent, prevHmac: string | null): Promise<string>;
+/**
+ * Verifies an HMAC against an event + previous HMAC.
+ */
+export declare function verifyAuditHmac(key: CryptoKey, event: CequreAuditEvent, prevHmac: string | null, storedHmac: string): Promise<boolean>;
+/**
+ * Walks an ordered list of audit entries and returns the index of the first
+ * entry whose HMAC does not validate against the chain (or null if clean).
+ */
+export declare function verifyAuditChain(key: CryptoKey, entries: AuditLogEntry[]): Promise<{
+    ok: boolean;
+    firstBadIndex: number | null;
+}>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAG3D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAuB9E;AAiBD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,aAAa,EAAE,GACvB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAgBxD"}

package/dist/auth-routes.d.ts

@@ -0,0 +1,3 @@
+import type { CequreRuntime } from "@cequrebackends/cequre-ts";
+export declare function setupAuthRoutes(cequre: CequreRuntime<any>): void;
+//# sourceMappingURL=auth-routes.d.ts.map

package/dist/auth-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-routes.d.ts","sourceRoot":"","sources":["../src/auth-routes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAoD/D,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,QA8azD"}

package/dist/auth.d.ts

@@ -0,0 +1,61 @@
+import type { CequreAdapter } from "@cequrebackends/cequre-ts";
+import type { CollectionConfig } from "@cequrebackends/cequre-ts";
+import type { AuthUser } from "@cequrebackends/cequre-ts";
+import { type TokenStore } from "./token-store";
+export interface JWTConfig {
+    secret: string;
+    previousSecret?: string;
+    issuer?: string;
+    audience?: string;
+    accessTokenExpiry?: string;
+    refreshTokenExpiry?: string;
+}
+export interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser;
+}
+export declare class JWTAuthenticator {
+    private config;
+    private adapter;
+    private tokenStore;
+    private collections?;
+    private platformAdminCollection?;
+    private cleanupTimer;
+    constructor(config: JWTConfig, adapter: CequreAdapter, tokenStore?: TokenStore, collections?: CollectionConfig[], platformAdminCollection?: string);
+    generateTokenPair(user: Record<string, unknown>, collection: string): Promise<TokenPair>;
+    refreshTokenPair(refreshToken: string): Promise<TokenPair | null>;
+    verifyAccessToken(token: string): Promise<AuthUser | null>;
+    revokeRefreshToken(refreshToken: string): Promise<void>;
+    /**
+     * Revoke all refresh tokens for a given user (e.g. after password reset/change).
+     */
+    revokeAllForUser(userId: string): Promise<void>;
+    generatePasswordResetToken(userId: string, collection: string): Promise<string>;
+    verifyPasswordResetToken(token: string): Promise<{
+        userId: string;
+        collection: string;
+    } | null>;
+    /**
+     * Generates a short-lived MFA challenge token (5 min expiry).
+     * Uses type: "mfa" — distinct from "reset" so the two flows
+     * can't be confused or cross-used.
+     */
+    generateMFAChallengeToken(userId: string, collection: string): Promise<string>;
+    /**
+     * Verifies an MFA challenge token. Only accepts type: "mfa" —
+     * password reset tokens (type: "reset") are rejected.
+     */
+    verifyMFAChallengeToken(token: string): Promise<{
+        userId: string;
+        collection: string;
+    } | null>;
+    /**
+     * Shared verify+rotation logic for typed JWT tokens (reset, mfa).
+     * Tries the primary secret first, then falls back to `previousSecret`
+     * during a rotation grace period. Rejects tokens whose `type` claim
+     * doesn't match `expectedType`.
+     */
+    private verifyTypedToken;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAOpE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAMD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,WAAW,CAAC,CAAqB;IACzC,OAAO,CAAC,uBAAuB,CAAC,CAAS;IACzC,OAAO,CAAC,YAAY,CAAiC;gBAEzC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,gBAAgB,EAAE,EAAE,uBAAuB,CAAC,EAAE,MAAM;IAW5I,iBAAiB,CACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,CAAC;IA8Df,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAoCjE,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA+B1D,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW/E,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAIrG;;;;OAIG;IACG,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWpF;;;OAGG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAIpG;;;;;OAKG;YACW,gBAAgB;CAmB/B"}

package/dist/encryption.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Derives an AES-256-GCM CryptoKey from a passphrase string.
+ * Uses HKDF-SHA256 with a fixed label for key separation from other
+ * Cequre crypto uses (JWT signing, audit HMAC).
+ */
+export declare function resolveEncryptionKey(passphrase: string): Promise<CryptoKey>;
+/**
+ * Encrypts a string value using AES-256-GCM.
+ * Returns "enc:v1:<base64(iv)>:<base64(ciphertext)>".
+ * A random 12-byte IV is generated per call, so the same plaintext
+ * produces different ciphertexts each time.
+ */
+export declare function encryptField(key: CryptoKey, plaintext: string): Promise<string>;
+/**
+ * Decrypts an "enc:v1:..." value.
+ * Returns null for:
+ * - non-encrypted values (no prefix) — so encrypted and plaintext can coexist
+ * - decryption failures (tampered ciphertext, wrong key)
+ */
+export declare function decryptField(key: CryptoKey, value: string): Promise<string | null>;
+/**
+ * Check if a value is encrypted (has the enc:v1: prefix).
+ */
+export declare function isEncrypted(value: unknown): value is string;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAYjF;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOrF;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE3D"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { CequrePlugin } from "@cequrebackends/cequre-ts";
+export * from './auth';
+export * from './rate-limiter';
+export { type TokenStore, InMemoryTokenStore, AdapterTokenStore, REFRESH_TOKEN_COLLECTION } from './token-store';
+export * from './audit';
+export * from './encryption';
+export * from './mfa';
+export { type SecretsProvider, EnvVarSecrets } from './secrets';
+export { signWebhook, verifyWebhookSignature, WEBHOOK_SIGNATURE_HEADER } from './webhooks';
+export declare function defaultSecurity(): CequrePlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,2BAA2B,CAAC;AAMjF,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,KAAK,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACjH,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,OAAO,CAAC;AACtB,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAI3F,wBAAgB,eAAe,IAAI,YAAY,CAuI9C"}