secure-vibe-runtime 0.0.0-stage → 7.3.0

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# secure-vibe-runtime
 
-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.
+The runtime security pieces of [Secure Vibe Coding OS](https://github.com/harperaa/secure-vibe-coding-OS) as one package, so every app built from the template gets security fixes by updating a dependency instead of copying files.
+
+| Entry point | What it provides |
+|---|---|
+| `secure-vibe-runtime/secrets` | `ensureSecretsLoaded()`, `revalidateSecrets()`: Doppler runtime fetch with retry and a per-instance cache |
+| `secure-vibe-runtime/csrf` | `generateCsrfToken()`, `validateCsrfToken()`, `generateUUID()`: HMAC tokens bound to a session; refuses to run without `CSRF_SECRET` |
+| `secure-vibe-runtime/withCsrf` | `withCsrf(handler)`: route wrapper that validates the token and logs failures |
+| `secure-vibe-runtime/withRateLimit` | `withRateLimit(handler)`: per-instance IP rate limit that fails closed on an unresolvable IP and logs refusals |
+| `secure-vibe-runtime/convex` | `securityTables` (schema fragment), the validators, `logSecurity()` and the exact-counter helpers, `redactIdentifiers()` |
+
+## Install
+
+```bash
+npm install secure-vibe-runtime
+```
+
+Peer dependencies: `next` and `convex`. The template already wires everything below; these notes are for an app that adds the package by hand.
+
+### Next.js side
+
+```ts
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  const { ensureSecretsLoaded } = await import("secure-vibe-runtime/secrets");
+  await ensureSecretsLoaded();
+}
+
+// app/api/something/route.ts
+import { withRateLimit } from "secure-vibe-runtime/withRateLimit";
+import { withCsrf } from "secure-vibe-runtime/withCsrf";
+export const POST = withRateLimit(withCsrf(handler));
+```
+
+The wrappers write refusals to the Convex security log by calling the app's `security:logSecurityViolation` mutation with `SECURITY_LOG_KEY`. The app owns that mutation and the admin dashboard; see the template's `convex/security.ts`.
+
+### Convex side
+
+```ts
+// convex/schema.ts
+import { securityTables } from "secure-vibe-runtime/convex";
+export default defineSchema({ users: ..., ...securityTables });
+
+// any mutation
+import { logSecurity } from "secure-vibe-runtime/convex";
+await logSecurity(ctx, user?._id, "unauthorized_access", "high", { endpoint: "..." });
+```
+
+Every write to `securityEvents` must go through `insertSecurityEvent`, `deleteSecurityEvent`, or `setSecurityEventRead` so the hourly counters stay exact. An app's `MutationCtx` is assignable to the package's `SecurityMutationCtx` without a cast.
+
+## Versioning
+
+The package version tracks the template release it ships with. Breaking changes to the schema fragment or function contracts are called out in the template's release notes, together with the Convex deploy or rebuild step they need.

package/dist/convex/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./securityTables";
+export * from "./securityLogger";
+export * from "./securityCounts";
+export * from "./redact";

package/dist/convex/index.js

@@ -0,0 +1,4 @@
+export * from "./securityTables";
+export * from "./securityLogger";
+export * from "./securityCounts";
+export * from "./redact";

package/dist/convex/redact.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Redacts identifiers from text before it leaves the system.
+ *
+ * Used by the background-job example (convex/jobs.ts) as the server-side step
+ * that runs BEFORE any outside call: an AI model, a document processor, a
+ * third-party API. The browser is never trusted to do this. No Convex imports,
+ * so it is unit-tested directly (scripts/redact.test.mjs).
+ *
+ * What it catches, deliberately narrow and documented:
+ *   - email addresses
+ *   - US phone numbers (10 digits with common separators, optional +1)
+ *   - US Social Security numbers (###-##-####)
+ *   - record identifiers written as "MRN 123456", "patient id: 42", etc.
+ * Anything else your data protection rules require (names, dates of birth,
+ * free-text clinical detail) needs its own rule here. A redactor is a
+ * floor, not a guarantee; keep humans in the loop for anything regulated.
+ */
+export declare function redactIdentifiers(text: string): {
+    text: string;
+    redactions: number;
+};

package/dist/convex/redact.js

@@ -0,0 +1,34 @@
+/**
+ * Redacts identifiers from text before it leaves the system.
+ *
+ * Used by the background-job example (convex/jobs.ts) as the server-side step
+ * that runs BEFORE any outside call: an AI model, a document processor, a
+ * third-party API. The browser is never trusted to do this. No Convex imports,
+ * so it is unit-tested directly (scripts/redact.test.mjs).
+ *
+ * What it catches, deliberately narrow and documented:
+ *   - email addresses
+ *   - US phone numbers (10 digits with common separators, optional +1)
+ *   - US Social Security numbers (###-##-####)
+ *   - record identifiers written as "MRN 123456", "patient id: 42", etc.
+ * Anything else your data protection rules require (names, dates of birth,
+ * free-text clinical detail) needs its own rule here. A redactor is a
+ * floor, not a guarantee; keep humans in the loop for anything regulated.
+ */
+const RULES = [
+    { label: "EMAIL", pattern: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g },
+    { label: "SSN", pattern: /\b\d{3}-\d{2}-\d{4}\b/g },
+    { label: "PHONE", pattern: /(?:\+?1[\s.-]?)?\(?\b\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}\b/g },
+    { label: "RECORD_ID", pattern: /\b(?:MRN|patient(?:\s+id)?|record(?:\s+id)?)\s*[:#]?\s*\d{3,}\b/gi },
+];
+export function redactIdentifiers(text) {
+    let redactions = 0;
+    let out = text;
+    for (const { label, pattern } of RULES) {
+        out = out.replace(pattern, () => {
+            redactions += 1;
+            return `[${label}]`;
+        });
+    }
+    return { text: out, redactions };
+}

package/dist/convex/securityCounts.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure helpers for the security log's exact counters. No Convex imports, so
+ * this file is unit-tested directly with node:test (see securityCounts.test.ts).
+ *
+ * Why counters exist: the dashboard's summary tiles used to be computed from
+ * the newest SCAN_CEILING rows in the window, so "Total events" was a lower
+ * bound under load, not a count. Reading the whole table to count it is the
+ * failure mode the bound was added to avoid. Instead every insert, delete and
+ * read-state change updates one small bucket document per UTC hour, keyed by
+ * "eventType:severity". A 90-day window is then at most ~2,200 small reads,
+ * independent of how many events were logged.
+ */
+export declare const HOUR_MS: number;
+/** Start of the UTC hour that contains `timestamp`, in ms. */
+export declare function hourStart(timestamp: number): number;
+export declare function countKey(eventType: string, severity: string): string;
+export declare function parseKey(key: string): {
+    eventType: string;
+    severity: string;
+};
+/** Add `delta` to `record[key]`, dropping the key when it reaches zero. */
+export declare function bump(record: Record<string, number>, key: string, delta: number): Record<string, number>;
+export type CountBucket = {
+    hour: number;
+    counts: Record<string, number>;
+    unread: Record<string, number>;
+};
+export type SecuritySummary = {
+    totalEvents: number;
+    unreadCount: number;
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+    eventTypeBreakdown: Record<string, number>;
+};
+/** Fold hourly buckets into the shape the dashboard tiles consume. */
+export declare function summarize(buckets: CountBucket[], eventType?: string): SecuritySummary;

package/dist/convex/securityCounts.js

@@ -0,0 +1,69 @@
+/**
+ * Pure helpers for the security log's exact counters. No Convex imports, so
+ * this file is unit-tested directly with node:test (see securityCounts.test.ts).
+ *
+ * Why counters exist: the dashboard's summary tiles used to be computed from
+ * the newest SCAN_CEILING rows in the window, so "Total events" was a lower
+ * bound under load, not a count. Reading the whole table to count it is the
+ * failure mode the bound was added to avoid. Instead every insert, delete and
+ * read-state change updates one small bucket document per UTC hour, keyed by
+ * "eventType:severity". A 90-day window is then at most ~2,200 small reads,
+ * independent of how many events were logged.
+ */
+export const HOUR_MS = 60 * 60 * 1000;
+/** Start of the UTC hour that contains `timestamp`, in ms. */
+export function hourStart(timestamp) {
+    return Math.floor(timestamp / HOUR_MS) * HOUR_MS;
+}
+export function countKey(eventType, severity) {
+    return `${eventType}:${severity}`;
+}
+export function parseKey(key) {
+    const i = key.lastIndexOf(":");
+    return { eventType: key.slice(0, i), severity: key.slice(i + 1) };
+}
+/** Add `delta` to `record[key]`, dropping the key when it reaches zero. */
+export function bump(record, key, delta) {
+    const next = { ...record };
+    const value = (next[key] ?? 0) + delta;
+    if (value <= 0)
+        delete next[key];
+    else
+        next[key] = value;
+    return next;
+}
+/** Fold hourly buckets into the shape the dashboard tiles consume. */
+export function summarize(buckets, eventType) {
+    const summary = {
+        totalEvents: 0,
+        unreadCount: 0,
+        criticalCount: 0,
+        highCount: 0,
+        mediumCount: 0,
+        lowCount: 0,
+        eventTypeBreakdown: {},
+    };
+    for (const bucket of buckets) {
+        for (const [key, n] of Object.entries(bucket.counts)) {
+            const { eventType: type, severity } = parseKey(key);
+            if (eventType !== undefined && type !== eventType)
+                continue;
+            summary.totalEvents += n;
+            summary.eventTypeBreakdown[type] = (summary.eventTypeBreakdown[type] ?? 0) + n;
+            if (severity === "critical")
+                summary.criticalCount += n;
+            else if (severity === "high")
+                summary.highCount += n;
+            else if (severity === "medium")
+                summary.mediumCount += n;
+            else if (severity === "low")
+                summary.lowCount += n;
+        }
+        for (const [key, n] of Object.entries(bucket.unread)) {
+            if (eventType !== undefined && parseKey(key).eventType !== eventType)
+                continue;
+            summary.unreadCount += n;
+        }
+    }
+    return summary;
+}

package/dist/convex/securityLogger.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Security Logger
+ *
+ * Unified helper for logging ALL security events.
+ * Used within mutations that return results instead of throwing.
+ * Direct DB insert ensures events persist (no scheduler, no separate transaction).
+ */
+import { GenericId } from "convex/values";
+import { SecurityEventDoc as SecurityEventRow, SecurityEventType, SecurityMetadata, SecurityMutationCtx as MutationCtx, SecuritySeverity } from "./securityTables";
+export type { SecurityEventType, SecurityMetadata, SecuritySeverity } from "./securityTables";
+type Id<T extends string> = GenericId<T>;
+type Doc<T extends "securityEvents"> = T extends "securityEvents" ? SecurityEventRow : never;
+/**
+ * All security event types that can be logged
+ */
+/**
+ * Severity levels for security events
+ */
+/**
+ * Metadata for security events
+ */
+/**
+ * Log a security event directly to the database.
+ *
+ * This function is designed to be called from mutations that return
+ * result objects instead of throwing. Since the mutation won't throw
+ * after logging, the event will persist.
+ *
+ * @param ctx - Mutation context
+ * @param userId - User ID who owns this security event (optional for anonymous violations)
+ * @param eventType - Type of security event
+ * @param severity - Severity level of the event
+ * @param metadata - Additional event metadata
+ * @returns The ID of the created security event
+ */
+export declare function logSecurity(ctx: MutationCtx, userId: Id<"users"> | undefined, eventType: SecurityEventType, severity: SecuritySeverity, metadata: SecurityMetadata): Promise<Id<"securityEvents">>;
+type SecurityEventDoc = Omit<Doc<"securityEvents">, "_id" | "_creationTime">;
+/** The in-progress rebuild marker, or null. One tiny read. */
+export declare function activeRebuild(ctx: MutationCtx): Promise<{
+    _id: GenericId<"securityCountsRebuild">;
+    _creationTime: number;
+    runId: string;
+    upTo: number;
+    startedAt: number;
+} | null>;
+/**
+ * Adds `delta` to the hourly bucket for (timestamp, eventType, severity).
+ * `unreadDelta` moves the unread counter independently (read-state changes
+ * pass count 0). Empty buckets are deleted so retention leaves nothing behind.
+ *
+ * While a rebuild is running, a delete or read-state change on a row the
+ * rebuild has not scanned yet would adjust a counter that does not include
+ * that row, and the rebuild would then count the row in its new state: the
+ * result is off by one forever. So those adjustments (delta <= 0) on rows at
+ * or before the rebuild's upTo are refused until the rebuild finishes. Inserts
+ * are unaffected: new rows have timestamps after upTo. The rebuild's own
+ * +1 adjustments pass because delta > 0. Callers surface the error; the
+ * retention cron checks first and skips the run instead.
+ */
+export declare function adjustSecurityCounts(ctx: MutationCtx, event: {
+    timestamp: number;
+    eventType: string;
+    severity: string;
+}, delta: number, unreadDelta: number): Promise<void>;
+export declare function insertSecurityEvent(ctx: MutationCtx, event: SecurityEventDoc): Promise<Id<"securityEvents">>;
+export declare function deleteSecurityEvent(ctx: MutationCtx, event: Doc<"securityEvents">): Promise<void>;
+export declare function setSecurityEventRead(ctx: MutationCtx, event: Doc<"securityEvents">, isRead: boolean): Promise<void>;

package/dist/convex/securityLogger.js

@@ -0,0 +1,214 @@
+/**
+ * Security Logger
+ *
+ * Unified helper for logging ALL security events.
+ * Used within mutations that return results instead of throwing.
+ * Direct DB insert ensures events persist (no scheduler, no separate transaction).
+ */
+import { bump, countKey, hourStart } from "./securityCounts";
+/**
+ * SECURITY: Sanitize email for logging - preserves domain but masks local part
+ * Example: john.doe@example.com -> j***e@example.com
+ */
+function sanitizeEmailForLog(email) {
+    if (!email)
+        return undefined;
+    const atIndex = email.indexOf('@');
+    if (atIndex <= 0)
+        return '***@invalid';
+    const localPart = email.substring(0, atIndex);
+    const domain = email.substring(atIndex);
+    // For very short local parts, just mask completely
+    if (localPart.length <= 2) {
+        return `***${domain}`;
+    }
+    // Keep first and last character, mask the rest
+    return `${localPart[0]}***${localPart[localPart.length - 1]}${domain}`;
+}
+/**
+ * SECURITY: Sanitize name for logging - keeps first character and length indication
+ * Example: John Doe -> J*** (8 chars)
+ */
+function sanitizeNameForLog(name) {
+    if (!name)
+        return undefined;
+    const trimmed = name.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // Keep first character and indicate length
+    return `${trimmed[0]}*** (${trimmed.length} chars)`;
+}
+/**
+ * SECURITY: Sanitize user ID for logging - partial redaction
+ * Example: usr_123456789 -> usr_1234***
+ */
+function sanitizeIdForLog(id) {
+    if (!id)
+        return undefined;
+    if (id.length <= 8) {
+        return `${id.substring(0, 2)}***`;
+    }
+    // Keep first 8 characters, mask the rest
+    return `${id.substring(0, 8)}***`;
+}
+/**
+ * Maximum stored length for caller-supplied free-text log fields.
+ *
+ * 2 KB is far more than any genuine errorMessage or requestPayload excerpt needs
+ * for triage, and small enough that even sustained abuse grows the table slowly
+ * relative to Convex's per-transaction read ceiling.
+ */
+const MAX_LOG_FIELD_CHARS = 2000;
+/**
+ * Cap for every OTHER caller-supplied string (origin, endpoint, IP,
+ * fingerprint, action type, and the PII fields before masking). None of these
+ * has a legitimate value anywhere near this long; an origin or endpoint over
+ * 256 chars is itself evidence of abuse.
+ *
+ * Worst-case row size is what the dashboard's SCAN_CEILING and the retention
+ * cron's PRUNE_BATCH in convex/security.ts are derived from: two 2,000-char
+ * fields plus eight 256-char fields is under ~6 KB per row, so 1,000 rows
+ * stay under Convex's 8 MiB per-transaction read budget. Change these caps
+ * and those batch sizes together.
+ */
+const MAX_LOG_SHORT_FIELD_CHARS = 256;
+/**
+ * Caps a caller-supplied string so one caller cannot write unbounded rows.
+ *
+ * This exists because logSecurityViolation records violations before a session
+ * exists, gated only by a shared server-side key. If that key leaks, and
+ * without a cap, the audit table is an unbounded write primitive for anyone who
+ * knows the Convex deployment URL — and the failure mode is self-concealing, because the first
+ * thing that breaks is the dashboard used to notice it. A row of uncapped
+ * fields can approach Convex's 1 MiB document limit, and a handful of those
+ * exhausts the read budget of any query or cleanup that touches them.
+ *
+ * Truncation is marked so a reader can tell a clipped value from a short one.
+ */
+function capForLog(value, max = MAX_LOG_FIELD_CHARS) {
+    if (!value)
+        return undefined;
+    if (value.length <= max)
+        return value;
+    return `${value.substring(0, max)}…[truncated ${value.length - max} chars]`;
+}
+const capShort = (value) => capForLog(value, MAX_LOG_SHORT_FIELD_CHARS);
+/**
+ * All security event types that can be logged
+ */
+/**
+ * Severity levels for security events
+ */
+/**
+ * Metadata for security events
+ */
+/**
+ * Log a security event directly to the database.
+ *
+ * This function is designed to be called from mutations that return
+ * result objects instead of throwing. Since the mutation won't throw
+ * after logging, the event will persist.
+ *
+ * @param ctx - Mutation context
+ * @param userId - User ID who owns this security event (optional for anonymous violations)
+ * @param eventType - Type of security event
+ * @param severity - Severity level of the event
+ * @param metadata - Additional event metadata
+ * @returns The ID of the created security event
+ */
+export async function logSecurity(ctx, userId, eventType, severity, metadata) {
+    // SECURITY: Sanitize PII before logging
+    // Preserves enough info for security analysis while protecting user privacy
+    // Every field is size-capped because logSecurityViolation is gated only by a
+    // shared key. If it leaks and without caps, one caller can write arbitrarily large rows
+    // and grow the securityEvents table until the dashboard's reads (and the
+    // retention cron's deletes) exceed Convex's per-transaction limit —
+    // silencing the monitoring it is meant to feed. Truncate rather than
+    // reject: a clipped event is still evidence. The two free-text fields get
+    // the long cap; everything else the short one.
+    const sanitizedMetadata = {
+        endpoint: capShort(metadata.endpoint),
+        origin: capShort(metadata.origin),
+        ipAddress: capShort(metadata.ipAddress), // IPs are needed for security analysis
+        fingerprint: capShort(metadata.fingerprint), // Fingerprints are anonymized identifiers
+        errorMessage: capForLog(metadata.errorMessage),
+        // PII fields are capped first (a masked email still keeps its domain), then sanitized
+        endUserEmail: sanitizeEmailForLog(capShort(metadata.endUserEmail)),
+        endUserName: sanitizeNameForLog(capShort(metadata.endUserName)),
+        endUserId: sanitizeIdForLog(capShort(metadata.endUserId)),
+        actionType: capShort(metadata.actionType),
+        requestPayload: capForLog(metadata.requestPayload),
+    };
+    // Direct insert - no scheduler, no separate transaction
+    const eventId = await insertSecurityEvent(ctx, {
+        userId,
+        eventType,
+        severity,
+        metadata: sanitizedMetadata,
+        timestamp: Date.now(),
+        isRead: false,
+    });
+    // Also log to console for debugging (using sanitized metadata)
+    console.log(`[SECURITY EVENT] ${severity.toUpperCase()}: ${eventType} | ` +
+        `user=${userId} endpoint=${sanitizedMetadata.endpoint} ` +
+        (sanitizedMetadata.errorMessage ? `error="${sanitizedMetadata.errorMessage}"` : ""));
+    return eventId;
+}
+/** The in-progress rebuild marker, or null. One tiny read. */
+export async function activeRebuild(ctx) {
+    return await ctx.db.query("securityCountsRebuild").first();
+}
+/**
+ * Adds `delta` to the hourly bucket for (timestamp, eventType, severity).
+ * `unreadDelta` moves the unread counter independently (read-state changes
+ * pass count 0). Empty buckets are deleted so retention leaves nothing behind.
+ *
+ * While a rebuild is running, a delete or read-state change on a row the
+ * rebuild has not scanned yet would adjust a counter that does not include
+ * that row, and the rebuild would then count the row in its new state: the
+ * result is off by one forever. So those adjustments (delta <= 0) on rows at
+ * or before the rebuild's upTo are refused until the rebuild finishes. Inserts
+ * are unaffected: new rows have timestamps after upTo. The rebuild's own
+ * +1 adjustments pass because delta > 0. Callers surface the error; the
+ * retention cron checks first and skips the run instead.
+ */
+export async function adjustSecurityCounts(ctx, event, delta, unreadDelta) {
+    if (delta <= 0) {
+        const rebuild = await activeRebuild(ctx);
+        if (rebuild && event.timestamp <= rebuild.upTo) {
+            throw new Error("Security log counters are being rebuilt; retry this change in a moment.");
+        }
+    }
+    const hour = hourStart(event.timestamp);
+    const key = countKey(event.eventType, event.severity);
+    const bucket = await ctx.db
+        .query("securityEventCounts")
+        .withIndex("byHour", (q) => q.eq("hour", hour))
+        .unique();
+    const counts = bump(bucket?.counts ?? {}, key, delta);
+    const unread = bump(bucket?.unread ?? {}, key, unreadDelta);
+    if (bucket) {
+        if (Object.keys(counts).length === 0)
+            await ctx.db.delete(bucket._id);
+        else
+            await ctx.db.patch(bucket._id, { counts, unread });
+    }
+    else if (Object.keys(counts).length > 0) {
+        await ctx.db.insert("securityEventCounts", { hour, counts, unread });
+    }
+}
+export async function insertSecurityEvent(ctx, event) {
+    const id = await ctx.db.insert("securityEvents", event);
+    await adjustSecurityCounts(ctx, event, 1, event.isRead ? 0 : 1);
+    return id;
+}
+export async function deleteSecurityEvent(ctx, event) {
+    await ctx.db.delete(event._id);
+    await adjustSecurityCounts(ctx, event, -1, event.isRead ? 0 : -1);
+}
+export async function setSecurityEventRead(ctx, event, isRead) {
+    if (event.isRead === isRead)
+        return; // idempotent: no double-counting on repeat clicks
+    await ctx.db.patch(event._id, { isRead });
+    await adjustSecurityCounts(ctx, event, 0, isRead ? -1 : 1);
+}