secure-vibe-runtime 0.0.0-stage → 7.3.0

package/dist/convex/securityTables.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Schema fragments and validators for the security log.
+ *
+ * Apps spread `securityTables` into their own defineSchema() so the three
+ * tables, their indexes and their validators are owned by this package: an
+ * index or field change ships as a package update followed by the app's
+ * normal `npx convex deploy`, not as a hand-edited schema in every app.
+ *
+ * `securityEvents.userId` references a `users` table the app defines; Convex
+ * validates that reference when the app's schema is pushed.
+ */
+import { DataModelFromSchemaDefinition, GenericMutationCtx, GenericQueryCtx, DocumentByName } from "convex/server";
+import { Infer } from "convex/values";
+export declare const eventTypeValidator: import("convex/values").VUnion<"csrf_validation_failed" | "rate_limit_exceeded" | "origin_mismatch" | "invalid_api_key" | "fingerprint_change" | "suspicious_activity" | "jwt_validation_failed" | "unauthorized_access" | "input_validation_failed" | "replay_detected" | "not_found_enumeration" | "jwt_algorithm_attack" | "tenant_isolation_attack" | "jwt_replay_attack" | "xss_attempt" | "fingerprint_manipulation" | "http_origin_blocked" | "prompt_injection_attempt" | "ai_response_validation_failed", [import("convex/values").VLiteral<"origin_mismatch", "required">, import("convex/values").VLiteral<"rate_limit_exceeded", "required">, import("convex/values").VLiteral<"invalid_api_key", "required">, import("convex/values").VLiteral<"fingerprint_change", "required">, import("convex/values").VLiteral<"suspicious_activity", "required">, import("convex/values").VLiteral<"jwt_validation_failed", "required">, import("convex/values").VLiteral<"unauthorized_access", "required">, import("convex/values").VLiteral<"input_validation_failed", "required">, import("convex/values").VLiteral<"replay_detected", "required">, import("convex/values").VLiteral<"not_found_enumeration", "required">, import("convex/values").VLiteral<"jwt_algorithm_attack", "required">, import("convex/values").VLiteral<"tenant_isolation_attack", "required">, import("convex/values").VLiteral<"jwt_replay_attack", "required">, import("convex/values").VLiteral<"xss_attempt", "required">, import("convex/values").VLiteral<"fingerprint_manipulation", "required">, import("convex/values").VLiteral<"http_origin_blocked", "required">, import("convex/values").VLiteral<"prompt_injection_attempt", "required">, import("convex/values").VLiteral<"ai_response_validation_failed", "required">, import("convex/values").VLiteral<"csrf_validation_failed", "required">], "required", never>;
+export declare const severityValidator: import("convex/values").VUnion<"critical" | "medium" | "low" | "high", [import("convex/values").VLiteral<"low", "required">, import("convex/values").VLiteral<"medium", "required">, import("convex/values").VLiteral<"high", "required">, import("convex/values").VLiteral<"critical", "required">], "required", never>;
+export declare const metadataValidator: import("convex/values").VObject<{
+    origin?: string | undefined;
+    endpoint?: string | undefined;
+    ipAddress?: string | undefined;
+    errorMessage?: string | undefined;
+    fingerprint?: string | undefined;
+    endUserEmail?: string | undefined;
+    endUserName?: string | undefined;
+    endUserId?: string | undefined;
+    actionType?: string | undefined;
+    requestPayload?: string | undefined;
+}, {
+    origin: import("convex/values").VString<string | undefined, "optional">;
+    ipAddress: import("convex/values").VString<string | undefined, "optional">;
+    fingerprint: import("convex/values").VString<string | undefined, "optional">;
+    endpoint: import("convex/values").VString<string | undefined, "optional">;
+    errorMessage: import("convex/values").VString<string | undefined, "optional">;
+    endUserEmail: import("convex/values").VString<string | undefined, "optional">;
+    endUserName: import("convex/values").VString<string | undefined, "optional">;
+    endUserId: import("convex/values").VString<string | undefined, "optional">;
+    actionType: import("convex/values").VString<string | undefined, "optional">;
+    requestPayload: import("convex/values").VString<string | undefined, "optional">;
+}, "required", "origin" | "endpoint" | "ipAddress" | "errorMessage" | "fingerprint" | "endUserEmail" | "endUserName" | "endUserId" | "actionType" | "requestPayload">;
+export type SecurityEventType = Infer<typeof eventTypeValidator>;
+export type SecuritySeverity = Infer<typeof severityValidator>;
+export type SecurityMetadata = Infer<typeof metadataValidator>;
+export declare const securityTables: {
+    securityEvents: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        userId?: import("convex/values").GenericId<"users"> | undefined;
+        eventType: "csrf_validation_failed" | "rate_limit_exceeded" | "origin_mismatch" | "invalid_api_key" | "fingerprint_change" | "suspicious_activity" | "jwt_validation_failed" | "unauthorized_access" | "input_validation_failed" | "replay_detected" | "not_found_enumeration" | "jwt_algorithm_attack" | "tenant_isolation_attack" | "jwt_replay_attack" | "xss_attempt" | "fingerprint_manipulation" | "http_origin_blocked" | "prompt_injection_attempt" | "ai_response_validation_failed";
+        severity: "critical" | "medium" | "low" | "high";
+        metadata: {
+            origin?: string | undefined;
+            endpoint?: string | undefined;
+            ipAddress?: string | undefined;
+            errorMessage?: string | undefined;
+            fingerprint?: string | undefined;
+            endUserEmail?: string | undefined;
+            endUserName?: string | undefined;
+            endUserId?: string | undefined;
+            actionType?: string | undefined;
+            requestPayload?: string | undefined;
+        };
+        timestamp: number;
+        isRead: boolean;
+    }, {
+        userId: import("convex/values").VId<import("convex/values").GenericId<"users"> | undefined, "optional">;
+        eventType: import("convex/values").VUnion<"csrf_validation_failed" | "rate_limit_exceeded" | "origin_mismatch" | "invalid_api_key" | "fingerprint_change" | "suspicious_activity" | "jwt_validation_failed" | "unauthorized_access" | "input_validation_failed" | "replay_detected" | "not_found_enumeration" | "jwt_algorithm_attack" | "tenant_isolation_attack" | "jwt_replay_attack" | "xss_attempt" | "fingerprint_manipulation" | "http_origin_blocked" | "prompt_injection_attempt" | "ai_response_validation_failed", [import("convex/values").VLiteral<"origin_mismatch", "required">, import("convex/values").VLiteral<"rate_limit_exceeded", "required">, import("convex/values").VLiteral<"invalid_api_key", "required">, import("convex/values").VLiteral<"fingerprint_change", "required">, import("convex/values").VLiteral<"suspicious_activity", "required">, import("convex/values").VLiteral<"jwt_validation_failed", "required">, import("convex/values").VLiteral<"unauthorized_access", "required">, import("convex/values").VLiteral<"input_validation_failed", "required">, import("convex/values").VLiteral<"replay_detected", "required">, import("convex/values").VLiteral<"not_found_enumeration", "required">, import("convex/values").VLiteral<"jwt_algorithm_attack", "required">, import("convex/values").VLiteral<"tenant_isolation_attack", "required">, import("convex/values").VLiteral<"jwt_replay_attack", "required">, import("convex/values").VLiteral<"xss_attempt", "required">, import("convex/values").VLiteral<"fingerprint_manipulation", "required">, import("convex/values").VLiteral<"http_origin_blocked", "required">, import("convex/values").VLiteral<"prompt_injection_attempt", "required">, import("convex/values").VLiteral<"ai_response_validation_failed", "required">, import("convex/values").VLiteral<"csrf_validation_failed", "required">], "required", never>;
+        severity: import("convex/values").VUnion<"critical" | "medium" | "low" | "high", [import("convex/values").VLiteral<"low", "required">, import("convex/values").VLiteral<"medium", "required">, import("convex/values").VLiteral<"high", "required">, import("convex/values").VLiteral<"critical", "required">], "required", never>;
+        metadata: import("convex/values").VObject<{
+            origin?: string | undefined;
+            endpoint?: string | undefined;
+            ipAddress?: string | undefined;
+            errorMessage?: string | undefined;
+            fingerprint?: string | undefined;
+            endUserEmail?: string | undefined;
+            endUserName?: string | undefined;
+            endUserId?: string | undefined;
+            actionType?: string | undefined;
+            requestPayload?: string | undefined;
+        }, {
+            origin: import("convex/values").VString<string | undefined, "optional">;
+            ipAddress: import("convex/values").VString<string | undefined, "optional">;
+            fingerprint: import("convex/values").VString<string | undefined, "optional">;
+            endpoint: import("convex/values").VString<string | undefined, "optional">;
+            errorMessage: import("convex/values").VString<string | undefined, "optional">;
+            endUserEmail: import("convex/values").VString<string | undefined, "optional">;
+            endUserName: import("convex/values").VString<string | undefined, "optional">;
+            endUserId: import("convex/values").VString<string | undefined, "optional">;
+            actionType: import("convex/values").VString<string | undefined, "optional">;
+            requestPayload: import("convex/values").VString<string | undefined, "optional">;
+        }, "required", "origin" | "endpoint" | "ipAddress" | "errorMessage" | "fingerprint" | "endUserEmail" | "endUserName" | "endUserId" | "actionType" | "requestPayload">;
+        timestamp: import("convex/values").VFloat64<number, "required">;
+        isRead: import("convex/values").VBoolean<boolean, "required">;
+    }, "required", "eventType" | "severity" | "metadata" | "userId" | "timestamp" | "isRead" | "metadata.origin" | "metadata.endpoint" | "metadata.ipAddress" | "metadata.errorMessage" | "metadata.fingerprint" | "metadata.endUserEmail" | "metadata.endUserName" | "metadata.endUserId" | "metadata.actionType" | "metadata.requestPayload">, {
+        byUser: ["userId", "timestamp", "_creationTime"];
+        bySeverity: ["userId", "severity", "timestamp", "_creationTime"];
+        byUnread: ["userId", "isRead", "timestamp", "_creationTime"];
+        byTimestamp: ["timestamp", "_creationTime"];
+        byTypeTime: ["eventType", "timestamp", "_creationTime"];
+        bySeverityTime: ["severity", "timestamp", "_creationTime"];
+        byReadTime: ["isRead", "timestamp", "_creationTime"];
+        byTypeSeverityTime: ["eventType", "severity", "timestamp", "_creationTime"];
+        byTypeReadTime: ["eventType", "isRead", "timestamp", "_creationTime"];
+        bySeverityReadTime: ["severity", "isRead", "timestamp", "_creationTime"];
+        byTypeSeverityReadTime: ["eventType", "severity", "isRead", "timestamp", "_creationTime"];
+    }, {}, {}>;
+    securityEventCounts: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        hour: number;
+        counts: Record<string, number>;
+        unread: Record<string, number>;
+    }, {
+        hour: import("convex/values").VFloat64<number, "required">;
+        counts: import("convex/values").VRecord<Record<string, number>, import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">, "required", string>;
+        unread: import("convex/values").VRecord<Record<string, number>, import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">, "required", string>;
+    }, "required", "hour" | "counts" | "unread" | `counts.${string}` | `unread.${string}`>, {
+        byHour: ["hour", "_creationTime"];
+    }, {}, {}>;
+    securityCountsRebuild: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        runId: string;
+        upTo: number;
+        startedAt: number;
+    }, {
+        runId: import("convex/values").VString<string, "required">;
+        upTo: import("convex/values").VFloat64<number, "required">;
+        startedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "runId" | "upTo" | "startedAt">, {}, {}, {}>;
+};
+/** The three tables as a standalone schema; apps spread `securityTables` instead. */
+export declare const securitySchema: import("convex/server").SchemaDefinition<{
+    securityEvents: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        userId?: import("convex/values").GenericId<"users"> | undefined;
+        eventType: "csrf_validation_failed" | "rate_limit_exceeded" | "origin_mismatch" | "invalid_api_key" | "fingerprint_change" | "suspicious_activity" | "jwt_validation_failed" | "unauthorized_access" | "input_validation_failed" | "replay_detected" | "not_found_enumeration" | "jwt_algorithm_attack" | "tenant_isolation_attack" | "jwt_replay_attack" | "xss_attempt" | "fingerprint_manipulation" | "http_origin_blocked" | "prompt_injection_attempt" | "ai_response_validation_failed";
+        severity: "critical" | "medium" | "low" | "high";
+        metadata: {
+            origin?: string | undefined;
+            endpoint?: string | undefined;
+            ipAddress?: string | undefined;
+            errorMessage?: string | undefined;
+            fingerprint?: string | undefined;
+            endUserEmail?: string | undefined;
+            endUserName?: string | undefined;
+            endUserId?: string | undefined;
+            actionType?: string | undefined;
+            requestPayload?: string | undefined;
+        };
+        timestamp: number;
+        isRead: boolean;
+    }, {
+        userId: import("convex/values").VId<import("convex/values").GenericId<"users"> | undefined, "optional">;
+        eventType: import("convex/values").VUnion<"csrf_validation_failed" | "rate_limit_exceeded" | "origin_mismatch" | "invalid_api_key" | "fingerprint_change" | "suspicious_activity" | "jwt_validation_failed" | "unauthorized_access" | "input_validation_failed" | "replay_detected" | "not_found_enumeration" | "jwt_algorithm_attack" | "tenant_isolation_attack" | "jwt_replay_attack" | "xss_attempt" | "fingerprint_manipulation" | "http_origin_blocked" | "prompt_injection_attempt" | "ai_response_validation_failed", [import("convex/values").VLiteral<"origin_mismatch", "required">, import("convex/values").VLiteral<"rate_limit_exceeded", "required">, import("convex/values").VLiteral<"invalid_api_key", "required">, import("convex/values").VLiteral<"fingerprint_change", "required">, import("convex/values").VLiteral<"suspicious_activity", "required">, import("convex/values").VLiteral<"jwt_validation_failed", "required">, import("convex/values").VLiteral<"unauthorized_access", "required">, import("convex/values").VLiteral<"input_validation_failed", "required">, import("convex/values").VLiteral<"replay_detected", "required">, import("convex/values").VLiteral<"not_found_enumeration", "required">, import("convex/values").VLiteral<"jwt_algorithm_attack", "required">, import("convex/values").VLiteral<"tenant_isolation_attack", "required">, import("convex/values").VLiteral<"jwt_replay_attack", "required">, import("convex/values").VLiteral<"xss_attempt", "required">, import("convex/values").VLiteral<"fingerprint_manipulation", "required">, import("convex/values").VLiteral<"http_origin_blocked", "required">, import("convex/values").VLiteral<"prompt_injection_attempt", "required">, import("convex/values").VLiteral<"ai_response_validation_failed", "required">, import("convex/values").VLiteral<"csrf_validation_failed", "required">], "required", never>;
+        severity: import("convex/values").VUnion<"critical" | "medium" | "low" | "high", [import("convex/values").VLiteral<"low", "required">, import("convex/values").VLiteral<"medium", "required">, import("convex/values").VLiteral<"high", "required">, import("convex/values").VLiteral<"critical", "required">], "required", never>;
+        metadata: import("convex/values").VObject<{
+            origin?: string | undefined;
+            endpoint?: string | undefined;
+            ipAddress?: string | undefined;
+            errorMessage?: string | undefined;
+            fingerprint?: string | undefined;
+            endUserEmail?: string | undefined;
+            endUserName?: string | undefined;
+            endUserId?: string | undefined;
+            actionType?: string | undefined;
+            requestPayload?: string | undefined;
+        }, {
+            origin: import("convex/values").VString<string | undefined, "optional">;
+            ipAddress: import("convex/values").VString<string | undefined, "optional">;
+            fingerprint: import("convex/values").VString<string | undefined, "optional">;
+            endpoint: import("convex/values").VString<string | undefined, "optional">;
+            errorMessage: import("convex/values").VString<string | undefined, "optional">;
+            endUserEmail: import("convex/values").VString<string | undefined, "optional">;
+            endUserName: import("convex/values").VString<string | undefined, "optional">;
+            endUserId: import("convex/values").VString<string | undefined, "optional">;
+            actionType: import("convex/values").VString<string | undefined, "optional">;
+            requestPayload: import("convex/values").VString<string | undefined, "optional">;
+        }, "required", "origin" | "endpoint" | "ipAddress" | "errorMessage" | "fingerprint" | "endUserEmail" | "endUserName" | "endUserId" | "actionType" | "requestPayload">;
+        timestamp: import("convex/values").VFloat64<number, "required">;
+        isRead: import("convex/values").VBoolean<boolean, "required">;
+    }, "required", "eventType" | "severity" | "metadata" | "userId" | "timestamp" | "isRead" | "metadata.origin" | "metadata.endpoint" | "metadata.ipAddress" | "metadata.errorMessage" | "metadata.fingerprint" | "metadata.endUserEmail" | "metadata.endUserName" | "metadata.endUserId" | "metadata.actionType" | "metadata.requestPayload">, {
+        byUser: ["userId", "timestamp", "_creationTime"];
+        bySeverity: ["userId", "severity", "timestamp", "_creationTime"];
+        byUnread: ["userId", "isRead", "timestamp", "_creationTime"];
+        byTimestamp: ["timestamp", "_creationTime"];
+        byTypeTime: ["eventType", "timestamp", "_creationTime"];
+        bySeverityTime: ["severity", "timestamp", "_creationTime"];
+        byReadTime: ["isRead", "timestamp", "_creationTime"];
+        byTypeSeverityTime: ["eventType", "severity", "timestamp", "_creationTime"];
+        byTypeReadTime: ["eventType", "isRead", "timestamp", "_creationTime"];
+        bySeverityReadTime: ["severity", "isRead", "timestamp", "_creationTime"];
+        byTypeSeverityReadTime: ["eventType", "severity", "isRead", "timestamp", "_creationTime"];
+    }, {}, {}>;
+    securityEventCounts: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        hour: number;
+        counts: Record<string, number>;
+        unread: Record<string, number>;
+    }, {
+        hour: import("convex/values").VFloat64<number, "required">;
+        counts: import("convex/values").VRecord<Record<string, number>, import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">, "required", string>;
+        unread: import("convex/values").VRecord<Record<string, number>, import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">, "required", string>;
+    }, "required", "hour" | "counts" | "unread" | `counts.${string}` | `unread.${string}`>, {
+        byHour: ["hour", "_creationTime"];
+    }, {}, {}>;
+    securityCountsRebuild: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        runId: string;
+        upTo: number;
+        startedAt: number;
+    }, {
+        runId: import("convex/values").VString<string, "required">;
+        upTo: import("convex/values").VFloat64<number, "required">;
+        startedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "runId" | "upTo" | "startedAt">, {}, {}, {}>;
+}, true>;
+export type SecurityDataModel = DataModelFromSchemaDefinition<typeof securitySchema>;
+/**
+ * An app's MutationCtx/QueryCtx is assignable to these because its data model
+ * is a superset of SecurityDataModel (verified with tsc; no cast needed).
+ */
+export type SecurityMutationCtx = GenericMutationCtx<SecurityDataModel>;
+export type SecurityQueryCtx = GenericQueryCtx<SecurityDataModel>;
+export type SecurityEventDoc = DocumentByName<SecurityDataModel, "securityEvents">;

package/dist/convex/securityTables.js

@@ -0,0 +1,67 @@
+/**
+ * Schema fragments and validators for the security log.
+ *
+ * Apps spread `securityTables` into their own defineSchema() so the three
+ * tables, their indexes and their validators are owned by this package: an
+ * index or field change ships as a package update followed by the app's
+ * normal `npx convex deploy`, not as a hand-edited schema in every app.
+ *
+ * `securityEvents.userId` references a `users` table the app defines; Convex
+ * validates that reference when the app's schema is pushed.
+ */
+import { defineSchema, defineTable, } from "convex/server";
+import { v } from "convex/values";
+export const eventTypeValidator = v.union(v.literal("origin_mismatch"), v.literal("rate_limit_exceeded"), v.literal("invalid_api_key"), v.literal("fingerprint_change"), v.literal("suspicious_activity"), v.literal("jwt_validation_failed"), v.literal("unauthorized_access"), v.literal("input_validation_failed"), v.literal("replay_detected"), v.literal("not_found_enumeration"), v.literal("jwt_algorithm_attack"), v.literal("tenant_isolation_attack"), v.literal("jwt_replay_attack"), v.literal("xss_attempt"), v.literal("fingerprint_manipulation"), v.literal("http_origin_blocked"), v.literal("prompt_injection_attempt"), v.literal("ai_response_validation_failed"), v.literal("csrf_validation_failed"));
+export const severityValidator = v.union(v.literal("low"), v.literal("medium"), v.literal("high"), v.literal("critical"));
+export const metadataValidator = v.object({
+    origin: v.optional(v.string()),
+    ipAddress: v.optional(v.string()),
+    fingerprint: v.optional(v.string()),
+    endpoint: v.optional(v.string()),
+    errorMessage: v.optional(v.string()),
+    endUserEmail: v.optional(v.string()),
+    endUserName: v.optional(v.string()),
+    endUserId: v.optional(v.string()),
+    actionType: v.optional(v.string()),
+    requestPayload: v.optional(v.string()),
+});
+export const securityTables = {
+    securityEvents: defineTable({
+        userId: v.optional(v.id("users")),
+        eventType: eventTypeValidator,
+        severity: severityValidator,
+        metadata: metadataValidator,
+        timestamp: v.number(),
+        isRead: v.boolean(),
+    })
+        .index("byUser", ["userId", "timestamp"])
+        .index("bySeverity", ["userId", "severity", "timestamp"])
+        .index("byUnread", ["userId", "isRead", "timestamp"])
+        // Cross-user, time-ordered access. The three indexes above all lead with
+        // userId, so none of them can serve the admin dashboard (all users) or the
+        // retention cron (all rows older than a cutoff) without a table scan.
+        .index("byTimestamp", ["timestamp"])
+        // One index per filter combination the admin feed offers (event type,
+        // severity, open/closed), each ending in timestamp, so every filtered
+        // view is a single index range read one page at a time. Nothing is
+        // filtered in JavaScript, so no over-read window is needed.
+        .index("byTypeTime", ["eventType", "timestamp"])
+        .index("bySeverityTime", ["severity", "timestamp"])
+        .index("byReadTime", ["isRead", "timestamp"])
+        .index("byTypeSeverityTime", ["eventType", "severity", "timestamp"])
+        .index("byTypeReadTime", ["eventType", "isRead", "timestamp"])
+        .index("bySeverityReadTime", ["severity", "isRead", "timestamp"])
+        .index("byTypeSeverityReadTime", ["eventType", "severity", "isRead", "timestamp"]),
+    securityEventCounts: defineTable({
+        hour: v.number(),
+        counts: v.record(v.string(), v.number()),
+        unread: v.record(v.string(), v.number()),
+    }).index("byHour", ["hour"]),
+    securityCountsRebuild: defineTable({
+        runId: v.string(),
+        upTo: v.number(),
+        startedAt: v.number(),
+    }),
+};
+/** The three tables as a standalone schema; apps spread `securityTables` instead. */
+export const securitySchema = defineSchema(securityTables);

package/dist/csrf.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Generates a CSRF token bound to a session ID using HMAC-SHA256
+ * @param sessionId - The session ID to bind the token to
+ * @returns The generated CSRF token (HMAC digest)
+ */
+export declare function generateCsrfToken(sessionId: string): Promise<string>;
+/**
+ * Validates a CSRF token against the stored token
+ * @param sentToken - Token received from the client
+ * @param storedToken - Token stored in the cookie
+ * @returns True if tokens match, false otherwise
+ */
+export declare function validateCsrfToken(sentToken: string, storedToken: string): boolean;
+/**
+ * Generates a UUID for session identification
+ * @returns A v4 UUID string
+ */
+export declare function generateUUID(): string;

package/dist/csrf.js

@@ -0,0 +1,66 @@
+import { v4 as uuidv4 } from 'uuid';
+import CryptoJS from 'crypto-js';
+/**
+ * Reads CSRF_SECRET, or throws.
+ *
+ * There is deliberately no fallback value. A previous version used
+ * `process.env.CSRF_SECRET || 'default-secret'`, which meant a deployment that
+ * forgot to set the variable still produced tokens — signed with a constant
+ * that is public in this repository, and therefore forgeable by anyone. The
+ * failure was invisible: tokens validated, the flow worked, and CSRF protection
+ * was simply absent.
+ *
+ * Failing loudly at first use is the correct trade. `/install` and
+ * `/deploy-to-*` both provision CSRF_SECRET, so reaching this throw means the
+ * environment is genuinely misconfigured.
+ */
+function csrfSecret() {
+    const secret = process.env.CSRF_SECRET;
+    if (!secret || secret.length < 32) {
+        throw new Error('CSRF_SECRET is not set (or is shorter than 32 chars). Refusing to sign CSRF ' +
+            'tokens with a weak or absent key — that would silently disable CSRF protection. ' +
+            'Set CSRF_SECRET in Doppler (or .env.local in legacy mode) and redeploy.');
+    }
+    return secret;
+}
+/**
+ * Generates a CSRF token bound to a session ID using HMAC-SHA256
+ * @param sessionId - The session ID to bind the token to
+ * @returns The generated CSRF token (HMAC digest)
+ */
+export async function generateCsrfToken(sessionId) {
+    // Read the secret OUTSIDE the try. A missing secret is a configuration fault
+    // that must propagate, not get swallowed and rethrown as a generic failure.
+    const secret = csrfSecret();
+    try {
+        const token = CryptoJS.lib.WordArray.random(32).toString(CryptoJS.enc.Hex);
+        const hmac = CryptoJS.HmacSHA256(token + sessionId, secret).toString(CryptoJS.enc.Hex);
+        return hmac;
+    }
+    catch (err) {
+        console.error('CSRF token generation error:', err.message);
+        throw new Error('Failed to generate CSRF token');
+    }
+}
+/**
+ * Validates a CSRF token against the stored token
+ * @param sentToken - Token received from the client
+ * @param storedToken - Token stored in the cookie
+ * @returns True if tokens match, false otherwise
+ */
+export function validateCsrfToken(sentToken, storedToken) {
+    try {
+        return sentToken === storedToken;
+    }
+    catch (err) {
+        console.error('CSRF validation error:', err.message);
+        return false;
+    }
+}
+/**
+ * Generates a UUID for session identification
+ * @returns A v4 UUID string
+ */
+export function generateUUID() {
+    return uuidv4();
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./csrf";
+export * from "./secrets";
+export * from "./withCsrf";
+export * from "./withRateLimit";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./csrf";
+export * from "./secrets";
+export * from "./withCsrf";
+export * from "./withRateLimit";

package/dist/secrets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime secrets fetcher for Vercel + Doppler.
+ *
+ * On cold start, calls Doppler's API with a service token to fetch all secrets
+ * for the deployment's config and writes them into `process.env` so the rest of
+ * the app (Clerk SDK, lib/csrf.ts, etc.) reads them transparently.
+ *
+ * Local dev path: when DOPPLER_TOKEN is unset (developers run via
+ * `doppler run -- next dev`), this is a no-op — values are already in
+ * process.env via the doppler CLI wrapper.
+ *
+ * Cache: a single in-flight Promise is memoized in module scope. Vercel
+ * Fluid Compute reuses function instances across requests, so the fetch
+ * cost (~100–300ms) is paid once per instance lifetime, not per request.
+ *
+ * Cache invalidation: app/api/revalidate-secrets calls revalidateSecrets()
+ * to drop the cache and force a refetch — used by /rotate after a key change.
+ */
+/**
+ * Ensure secrets are loaded into process.env before the caller proceeds.
+ * Safe to call from many places — fetch happens at most once per instance.
+ */
+export declare function ensureSecretsLoaded(): Promise<void>;
+/**
+ * Drop the in-memory cache and force a refetch on the next call.
+ * Used by /api/revalidate-secrets after rotation.
+ */
+export declare function revalidateSecrets(): void;

package/dist/secrets.js

@@ -0,0 +1,111 @@
+/**
+ * Runtime secrets fetcher for Vercel + Doppler.
+ *
+ * On cold start, calls Doppler's API with a service token to fetch all secrets
+ * for the deployment's config and writes them into `process.env` so the rest of
+ * the app (Clerk SDK, lib/csrf.ts, etc.) reads them transparently.
+ *
+ * Local dev path: when DOPPLER_TOKEN is unset (developers run via
+ * `doppler run -- next dev`), this is a no-op — values are already in
+ * process.env via the doppler CLI wrapper.
+ *
+ * Cache: a single in-flight Promise is memoized in module scope. Vercel
+ * Fluid Compute reuses function instances across requests, so the fetch
+ * cost (~100–300ms) is paid once per instance lifetime, not per request.
+ *
+ * Cache invalidation: app/api/revalidate-secrets calls revalidateSecrets()
+ * to drop the cache and force a refetch — used by /rotate after a key change.
+ */
+const DOPPLER_API_URL = 'https://api.doppler.com/v3/configs/config/secrets/download?format=json';
+// Retry tuning: transient network blips between Vercel egress and Doppler's
+// edge last seconds, not milliseconds. Backoff totals ~3.75s across attempts
+// (250/500/1000/2000ms) so a brief blip becomes a slower cold start, not a 500.
+const MAX_ATTEMPTS = 5;
+const BASE_BACKOFF_MS = 250;
+const PER_ATTEMPT_TIMEOUT_MS = 5_000;
+let secretsPromise = null;
+/**
+ * Flatten an error for logging. Undici wraps the real network failure
+ * (DNS, TLS, connection reset) in `err.cause`, so a bare `err.message`
+ * is often just "fetch failed" — walk the cause chain to keep the detail.
+ */
+function describeError(err) {
+    const parts = [];
+    let current = err;
+    while (current instanceof Error) {
+        const code = current.code;
+        parts.push(`${current.name}: ${current.message}${code ? ` (${code})` : ''}`);
+        current = current.cause;
+    }
+    if (current !== undefined && current !== null)
+        parts.push(String(current));
+    return parts.join(' <- ') || String(err);
+}
+async function fetchFromDoppler(token) {
+    let lastError;
+    const started = Date.now();
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        const attemptStarted = Date.now();
+        try {
+            const res = await fetch(DOPPLER_API_URL, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/json',
+                },
+                signal: AbortSignal.timeout(PER_ATTEMPT_TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                throw new Error(`Doppler API returned ${res.status} ${res.statusText}`);
+            }
+            const json = (await res.json());
+            if (attempt > 1) {
+                console.warn(`[secrets] Doppler fetch recovered on attempt ${attempt}/${MAX_ATTEMPTS} after ${Date.now() - started}ms`);
+            }
+            return json;
+        }
+        catch (err) {
+            lastError = err;
+            console.warn(`[secrets] Doppler fetch attempt ${attempt}/${MAX_ATTEMPTS} failed after ${Date.now() - attemptStarted}ms: ${describeError(err)}`);
+            if (attempt < MAX_ATTEMPTS) {
+                await new Promise((r) => setTimeout(r, BASE_BACKOFF_MS * 2 ** (attempt - 1)));
+            }
+        }
+    }
+    console.error(`[secrets] Doppler fetch exhausted ${MAX_ATTEMPTS} attempts over ${Date.now() - started}ms; last error: ${describeError(lastError)}`);
+    throw new Error(`Doppler fetch failed after ${MAX_ATTEMPTS} attempts: ${describeError(lastError)}`);
+}
+async function applySecrets() {
+    const token = process.env.DOPPLER_TOKEN;
+    if (!token) {
+        // Local dev or legacy mode — process.env already populated upstream.
+        return;
+    }
+    const secrets = await fetchFromDoppler(token);
+    for (const [key, value] of Object.entries(secrets)) {
+        if (typeof value === 'string') {
+            process.env[key] = value;
+        }
+    }
+}
+/**
+ * Ensure secrets are loaded into process.env before the caller proceeds.
+ * Safe to call from many places — fetch happens at most once per instance.
+ */
+export function ensureSecretsLoaded() {
+    if (!secretsPromise) {
+        secretsPromise = applySecrets().catch((err) => {
+            // Reset on failure so the next call retries instead of caching the error.
+            secretsPromise = null;
+            throw err;
+        });
+    }
+    return secretsPromise;
+}
+/**
+ * Drop the in-memory cache and force a refetch on the next call.
+ * Used by /api/revalidate-secrets after rotation.
+ */
+export function revalidateSecrets() {
+    secretsPromise = null;
+}

package/dist/withCsrf.d.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+/**
+ * Higher-order function that wraps API route handlers with CSRF protection
+ * Validates the CSRF token from the request header against the stored cookie
+ * Tokens are single-use and cleared after validation
+ *
+ * @param handler - The API route handler to wrap
+ * @returns A wrapped handler with CSRF protection
+ *
+ * @example
+ * ```typescript
+ * import { withCsrf } from '@/lib/withCsrf';
+ *
+ * async function loginHandler(request: NextRequest) {
+ *   // Your login logic here
+ *   return NextResponse.json({ success: true });
+ * }
+ *
+ * export const POST = withCsrf(loginHandler);
+ * ```
+ */
+export declare function withCsrf(handler: (request: NextRequest) => Promise<NextResponse>): (request: NextRequest) => Promise<NextResponse<unknown>>;