@useatlas/create 0.0.6 → 0.0.7

package/templates/nextjs-standalone/src/lib/db/source-rate-limit.ts

@@ -2,13 +2,18 @@
  * Per-source rate limiting for multi-database deployments.
  *
  * Enforces QPM (queries per minute) and concurrency limits per datasource.
- * Uses a sliding-window pattern for QPM tracking.
+ * Stale QPM entries are filtered on read — no periodic cleanup timer needed.
+ *
+ * Primary API: {@link withSourceSlot} acquires a slot, runs the effect, and
+ * releases the slot on completion (success or failure). Callers never need
+ * to manually decrement concurrency.
  */
 
+import { Effect } from "effect";
+import { RateLimitExceededError, ConcurrencyLimitError } from "@atlas/api/lib/effect/errors";
 import { createLogger } from "@atlas/api/lib/logger";
 
 const log = createLogger("source-rate-limit");
-
 const WINDOW_MS = 60_000;
 
 export interface SourceRateLimit {
@@ -21,14 +26,30 @@ const DEFAULT_LIMIT: SourceRateLimit = {
   concurrency: 5,
 };
 
-/** Per-source config overrides. */
+// ── State ──────────────────────────────────────────────────────────
+
+interface SourceState {
+  timestamps: number[];
+  active: number;
+}
+
 const limits = new Map<string, SourceRateLimit>();
+const states = new Map<string, SourceState>();
 
-/** Per-source sliding window of request timestamps. */
-const windows = new Map<string, number[]>();
+function getLimit(id: string): SourceRateLimit {
+  return limits.get(id) ?? DEFAULT_LIMIT;
+}
+
+function getState(id: string): SourceState {
+  let s = states.get(id);
+  if (!s) {
+    s = { timestamps: [], active: 0 };
+    states.set(id, s);
+  }
+  return s;
+}
 
-/** Per-source current concurrency count. */
-const concurrency = new Map<string, number>();
+// ── Config ─────────────────────────────────────────────────────────
 
 /** Register a custom rate limit for a datasource. */
 export function registerSourceRateLimit(id: string, limit: SourceRateLimit): void {
@@ -46,146 +67,75 @@ export function clearSourceRateLimit(id: string): void {
   limits.delete(id);
 }
 
-function getLimit(id: string): SourceRateLimit {
-  return limits.get(id) ?? DEFAULT_LIMIT;
-}
-
-export function checkSourceRateLimit(sourceId: string): {
-  allowed: boolean;
-  reason?: string;
-  retryAfterMs?: number;
-} {
-  const limit = getLimit(sourceId);
-
-  // Check concurrency first
-  const current = concurrency.get(sourceId) ?? 0;
-  if (current >= limit.concurrency) {
-    return {
-      allowed: false,
-      reason: `Source "${sourceId}" concurrency limit reached (${limit.concurrency})`,
-    };
-  }
-
-  // Check QPM
-  const now = Date.now();
-  const cutoff = now - WINDOW_MS;
-
-  let timestamps = windows.get(sourceId);
-  if (!timestamps) {
-    timestamps = [];
-    windows.set(sourceId, timestamps);
-  }
-
-  // Evict stale entries
-  const firstValid = timestamps.findIndex((t) => t > cutoff);
-  if (firstValid > 0) timestamps.splice(0, firstValid);
-  else if (firstValid === -1) timestamps.length = 0;
-
-  if (timestamps.length >= limit.queriesPerMinute) {
-    const retryAfterMs = Math.max(1, timestamps[0] + WINDOW_MS - now);
-    return {
-      allowed: false,
-      reason: `Source "${sourceId}" QPM limit reached (${limit.queriesPerMinute}/min)`,
-      retryAfterMs,
-    };
-  }
-
-  timestamps.push(now);
-  return { allowed: true };
-}
+// ── Effect API ─────────────────────────────────────────────────────
 
 /**
- * Atomic check-and-acquire: checks both QPM and concurrency limits, and if
- * allowed, atomically records the QPM timestamp AND increments the concurrency
- * counter. This prevents the TOCTOU race where two concurrent requests both
- * pass the concurrency check before either increments.
- *
- * Callers MUST call `decrementSourceConcurrency()` in a `finally` block after
- * the query completes (success or failure).
+ * Acquire a rate-limit slot: check QPM + concurrency, record timestamp,
+ * increment concurrency counter. Fails with tagged errors.
  */
-export function acquireSourceSlot(sourceId: string): {
-  acquired: boolean;
-  reason?: string;
-  retryAfterMs?: number;
-} {
-  const limit = getLimit(sourceId);
-
-  // Check concurrency first
-  const current = concurrency.get(sourceId) ?? 0;
-  if (current >= limit.concurrency) {
-    return {
-      acquired: false,
-      reason: `Source "${sourceId}" concurrency limit reached (${limit.concurrency})`,
-    };
-  }
-
-  // Check QPM
-  const now = Date.now();
-  const cutoff = now - WINDOW_MS;
-
-  let timestamps = windows.get(sourceId);
-  if (!timestamps) {
-    timestamps = [];
-    windows.set(sourceId, timestamps);
-  }
-
-  // Evict stale entries
-  const firstValid = timestamps.findIndex((t) => t > cutoff);
-  if (firstValid > 0) timestamps.splice(0, firstValid);
-  else if (firstValid === -1) timestamps.length = 0;
-
-  if (timestamps.length >= limit.queriesPerMinute) {
-    const retryAfterMs = Math.max(1, timestamps[0] + WINDOW_MS - now);
-    return {
-      acquired: false,
-      reason: `Source "${sourceId}" QPM limit reached (${limit.queriesPerMinute}/min)`,
-      retryAfterMs,
-    };
-  }
-
-  // Atomically record QPM timestamp AND increment concurrency
-  timestamps.push(now);
-  concurrency.set(sourceId, current + 1);
-  return { acquired: true };
-}
-
-/** Increment concurrency counter before query execution. */
-export function incrementSourceConcurrency(sourceId: string): void {
-  concurrency.set(sourceId, (concurrency.get(sourceId) ?? 0) + 1);
-}
-
-/** Decrement concurrency counter after query execution. */
-export function decrementSourceConcurrency(sourceId: string): void {
-  const current = concurrency.get(sourceId) ?? 0;
-  concurrency.set(sourceId, Math.max(0, current - 1));
-}
+export const acquireSlot = (
+  sourceId: string,
+): Effect.Effect<void, RateLimitExceededError | ConcurrencyLimitError> =>
+  Effect.gen(function* () {
+    const limit = getLimit(sourceId);
+    const state = getState(sourceId);
+    const now = Date.now();
+
+    // Check concurrency first
+    if (state.active >= limit.concurrency) {
+      return yield* new ConcurrencyLimitError({
+        message: `Source "${sourceId}" concurrency limit reached (${limit.concurrency})`,
+        sourceId,
+        limit: limit.concurrency,
+      });
+    }
 
-/** Periodic cleanup — evict stale QPM windows. */
-const cleanupInterval = setInterval(() => {
-  try {
-    const cutoff = Date.now() - WINDOW_MS;
-    for (const [key, timestamps] of windows) {
-      if (timestamps.length === 0 || timestamps[timestamps.length - 1] <= cutoff) {
-        windows.delete(key);
-      }
+    // Filter stale QPM timestamps (replaces setInterval cleanup)
+    const cutoff = now - WINDOW_MS;
+    state.timestamps = state.timestamps.filter((t) => t > cutoff);
+
+    if (state.timestamps.length >= limit.queriesPerMinute) {
+      const retryAfterMs = Math.max(1, state.timestamps[0] + WINDOW_MS - now);
+      return yield* new RateLimitExceededError({
+        message: `Source "${sourceId}" QPM limit reached (${limit.queriesPerMinute}/min)`,
+        sourceId,
+        limit: limit.queriesPerMinute,
+        retryAfterMs,
+      });
     }
-  } catch (err) {
-    log.error(
-      { err: err instanceof Error ? err : new Error(String(err)) },
-      "Source rate limit cleanup failed",
-    );
-  }
-}, WINDOW_MS);
-cleanupInterval.unref();
 
-/** Stop the periodic cleanup timer. For tests. */
-export function _stopSourceRateLimitCleanup(): void {
-  clearInterval(cleanupInterval);
-}
+    // Atomically record QPM timestamp AND increment concurrency
+    state.timestamps.push(now);
+    state.active++;
+  });
+
+/**
+ * Run an effect inside a rate-limit slot. The slot is released on completion
+ * (success or failure) — callers never need to manually decrement.
+ */
+export const withSourceSlot = <A, E>(
+  sourceId: string,
+  effect: Effect.Effect<A, E>,
+): Effect.Effect<A, E | RateLimitExceededError | ConcurrencyLimitError> =>
+  Effect.acquireUseRelease(
+    acquireSlot(sourceId),
+    () => effect,
+    () =>
+      Effect.sync(() => {
+        const state = states.get(sourceId);
+        if (state) {
+          if (state.active <= 0) {
+            log.warn({ sourceId, active: state.active }, "Rate limit slot double-release detected — active count already zero");
+          }
+          state.active = Math.max(0, state.active - 1);
+        }
+      }),
+  );
+
+// ── Test helpers ───────────────────────────────────────────────────
 
 /** Reset all state. For tests. */
 export function _resetSourceRateLimits(): void {
   limits.clear();
-  windows.clear();
-  concurrency.clear();
+  states.clear();
 }

package/templates/nextjs-standalone/src/lib/demo.ts

@@ -0,0 +1,308 @@
+/**
+ * Demo mode — email-gated public demo with lead capture.
+ *
+ * Token mechanism: HMAC-SHA256 signed payload (email + expiry).
+ * Conversations persisted with synthetic user ID: "demo:<email_hash>".
+ * Separate rate limiter from the main auth flow.
+ */
+
+import * as crypto from "crypto";
+import { createLogger } from "@atlas/api/lib/logger";
+import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+
+const log = createLogger("demo");
+
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+
+/** Whether demo mode is enabled (ATLAS_DEMO_ENABLED=true). */
+export function isDemoEnabled(): boolean {
+  return process.env.ATLAS_DEMO_ENABLED === "true";
+}
+
+const DEMO_DEFAULT_MAX_STEPS = 10;
+const DEMO_DEFAULT_RPM = 10;
+const DEMO_TOKEN_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+let lastWarnedDemoMaxSteps: string | undefined;
+
+/** Max agent steps for demo sessions. Default 10. */
+export function getDemoMaxSteps(): number {
+  const raw = process.env.ATLAS_DEMO_MAX_STEPS ?? String(DEMO_DEFAULT_MAX_STEPS);
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1 || n > 100) {
+    if (raw !== lastWarnedDemoMaxSteps) {
+      log.warn({ value: raw }, `Invalid ATLAS_DEMO_MAX_STEPS; using default ${DEMO_DEFAULT_MAX_STEPS}`);
+      lastWarnedDemoMaxSteps = raw;
+    }
+    return DEMO_DEFAULT_MAX_STEPS;
+  }
+  return n;
+}
+
+let lastWarnedDemoRpm: string | undefined;
+
+/** Requests per minute for demo users. Default 10. 0 = disabled. */
+export function getDemoRpmLimit(): number {
+  const raw = process.env.ATLAS_DEMO_RATE_LIMIT_RPM ?? String(DEMO_DEFAULT_RPM);
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) {
+    if (raw !== lastWarnedDemoRpm) {
+      log.warn({ value: raw }, `Invalid ATLAS_DEMO_RATE_LIMIT_RPM; using default ${DEMO_DEFAULT_RPM}`);
+      lastWarnedDemoRpm = raw;
+    }
+    return DEMO_DEFAULT_RPM;
+  }
+  return Math.floor(n);
+}
+
+// ---------------------------------------------------------------------------
+// Token signing / verification
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the HMAC key for demo tokens. Uses BETTER_AUTH_SECRET with a
+ * ":demo" suffix to avoid collision with other derived keys.
+ */
+function getDemoKey(): Buffer | null {
+  const secret = process.env.BETTER_AUTH_SECRET;
+  if (!secret) return null;
+  return crypto.createHash("sha256").update(secret + ":demo").digest();
+}
+
+function base64urlEncode(data: Buffer | string): string {
+  const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+  return buf.toString("base64url");
+}
+
+function base64urlDecode(str: string): Buffer {
+  return Buffer.from(str, "base64url");
+}
+
+interface DemoTokenPayload {
+  email: string;
+  exp: number;
+}
+
+/**
+ * Sign a demo token for the given email.
+ * Returns the token string, or null if no signing key is available.
+ */
+export function signDemoToken(email: string): { token: string; expiresAt: number } | null {
+  const key = getDemoKey();
+  if (!key) {
+    log.error("Cannot sign demo token: BETTER_AUTH_SECRET is not set");
+    return null;
+  }
+
+  const normalized = email.toLowerCase().trim();
+  const exp = Date.now() + DEMO_TOKEN_TTL_MS;
+  const payload: DemoTokenPayload = { email: normalized, exp };
+  const payloadStr = base64urlEncode(JSON.stringify(payload));
+  const signature = crypto.createHmac("sha256", key).update(payloadStr).digest();
+  const signatureStr = base64urlEncode(signature);
+
+  return {
+    token: `${payloadStr}.${signatureStr}`,
+    expiresAt: exp,
+  };
+}
+
+/**
+ * Verify a demo token and extract the email.
+ * Returns the email on success, null on failure (expired, tampered, malformed).
+ */
+export function verifyDemoToken(token: string): string | null {
+  const key = getDemoKey();
+  if (!key) {
+    log.warn("Cannot verify demo token: BETTER_AUTH_SECRET is not set");
+    return null;
+  }
+
+  const parts = token.split(".");
+  if (parts.length !== 2) return null;
+
+  const [payloadStr, signatureStr] = parts;
+
+  // Recompute signature and compare in constant time
+  const expectedSig = crypto.createHmac("sha256", key).update(payloadStr).digest();
+  let actualSig: Buffer;
+  try {
+    actualSig = base64urlDecode(signatureStr);
+  } catch {
+    // intentionally ignored: malformed base64 in signature — reject token
+    return null;
+  }
+
+  if (expectedSig.length !== actualSig.length) return null;
+  if (!crypto.timingSafeEqual(expectedSig, actualSig)) return null;
+
+  // Parse payload
+  let payload: DemoTokenPayload;
+  try {
+    const decoded = base64urlDecode(payloadStr).toString("utf8");
+    payload = JSON.parse(decoded) as DemoTokenPayload;
+  } catch {
+    // intentionally ignored: malformed or unparseable payload JSON — reject token
+    return null;
+  }
+
+  if (typeof payload.email !== "string" || typeof payload.exp !== "number") return null;
+  if (payload.exp < Date.now()) return null;
+
+  return payload.email;
+}
+
+// ---------------------------------------------------------------------------
+// User ID helper
+// ---------------------------------------------------------------------------
+
+/** Deterministic user ID for demo conversations. Hashed to avoid PII. */
+export function demoUserId(email: string): string {
+  const normalized = email.toLowerCase().trim();
+  const hash = crypto.createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return `demo:${hash}`;
+}
+
+// ---------------------------------------------------------------------------
+// Demo rate limiter (separate from main rate limiter)
+// ---------------------------------------------------------------------------
+
+const WINDOW_MS = 60_000;
+const demoWindows = new Map<string, number[]>();
+
+/**
+ * Sliding-window rate limit for demo users.
+ * Returns `{ allowed: true }` or `{ allowed: false, retryAfterMs }`.
+ */
+export function checkDemoRateLimit(email: string): {
+  allowed: boolean;
+  retryAfterMs?: number;
+} {
+  const limit = getDemoRpmLimit();
+  if (limit === 0) return { allowed: true };
+
+  const now = Date.now();
+  const cutoff = now - WINDOW_MS;
+  const key = demoUserId(email);
+
+  let timestamps = demoWindows.get(key);
+  if (!timestamps) {
+    timestamps = [];
+    demoWindows.set(key, timestamps);
+  }
+
+  // Evict stale entries
+  const firstValid = timestamps.findIndex((t) => t > cutoff);
+  if (firstValid > 0) timestamps.splice(0, firstValid);
+  else if (firstValid === -1) timestamps.length = 0;
+
+  if (timestamps.length < limit) {
+    timestamps.push(now);
+    return { allowed: true };
+  }
+
+  const retryAfterMs = Math.max(1, timestamps[0] + WINDOW_MS - now);
+  return { allowed: false, retryAfterMs };
+}
+
+/** Clear demo rate limit state. For tests. */
+export function resetDemoRateLimits(): void {
+  demoWindows.clear();
+}
+
+// Periodic cleanup — evict keys with no recent timestamps
+const demoCleanupInterval = setInterval(() => {
+  try {
+    const cutoff = Date.now() - WINDOW_MS;
+    for (const [key, timestamps] of demoWindows) {
+      if (timestamps.length === 0 || timestamps[timestamps.length - 1] <= cutoff) {
+        demoWindows.delete(key);
+      }
+    }
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err : new Error(String(err)) },
+      "Demo rate limit cleanup failed",
+    );
+  }
+}, WINDOW_MS);
+demoCleanupInterval.unref();
+
+/** Stop the demo cleanup timer. For tests. */
+export function _stopDemoCleanup(): void {
+  clearInterval(demoCleanupInterval);
+}
+
+// ---------------------------------------------------------------------------
+// Lead capture
+// ---------------------------------------------------------------------------
+
+export interface DemoLeadResult {
+  returning: boolean;
+  sessionCount: number;
+}
+
+/**
+ * Capture or update a demo lead in the internal DB.
+ * Returns whether this is a returning user and their session count.
+ */
+export async function captureDemoLead(opts: {
+  email: string;
+  ip?: string | null;
+  userAgent?: string | null;
+}): Promise<DemoLeadResult> {
+  if (!hasInternalDB()) {
+    log.debug("No internal DB — demo lead not captured");
+    return { returning: false, sessionCount: 1 };
+  }
+
+  const email = opts.email.toLowerCase().trim();
+
+  try {
+    // Try to insert; on conflict update last_active_at and bump session_count
+    const rows = await internalQuery(
+      `INSERT INTO demo_leads (email, ip_address, user_agent)
+       VALUES ($1, $2, $3)
+       ON CONFLICT (email) DO UPDATE
+         SET last_active_at = now(),
+             session_count = demo_leads.session_count + 1,
+             ip_address = COALESCE(EXCLUDED.ip_address, demo_leads.ip_address),
+             user_agent = COALESCE(EXCLUDED.user_agent, demo_leads.user_agent)
+       RETURNING session_count`,
+      [email, opts.ip ?? null, opts.userAgent ?? null],
+    );
+
+    const sessionCount = (rows[0] as { session_count: number } | undefined)?.session_count ?? 1;
+    return { returning: sessionCount > 1, sessionCount };
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err : new Error(String(err)) },
+      "Failed to capture demo lead — lead data lost. Check that demo_leads table exists (run migrations)",
+    );
+    return { returning: false, sessionCount: 1 };
+  }
+}
+
+/**
+ * Count conversations for a demo user.
+ */
+export async function countDemoConversations(email: string): Promise<number> {
+  if (!hasInternalDB()) return 0;
+
+  const userId = demoUserId(email);
+  try {
+    const rows = await internalQuery(
+      `SELECT COUNT(*)::int AS count FROM conversations WHERE user_id = $1 AND surface = 'demo' AND deleted_at IS NULL`,
+      [userId],
+    );
+    return (rows[0] as { count: number } | undefined)?.count ?? 0;
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Failed to count demo conversations",
+    );
+    return 0;
+  }
+}