@donotdev/functions 0.0.9 → 0.0.11

package/src/shared/utils/external/subscription.ts

@@ -89,8 +89,13 @@ export async function updateUserSubscription(
     const auth = getFirebaseAdminAuth();
     const db = getFirebaseAdminFirestore();
 
+    // Read existing claims and merge to avoid overwriting other claims
+    const user = await auth.getUser(firebaseUid);
+    const currentClaims = user.customClaims || {};
+
     // Update Firebase Auth custom claims
     await auth.setCustomUserClaims(firebaseUid, {
+      ...currentClaims,
       subscription: subscriptionClaims,
     });
 
@@ -150,8 +155,13 @@ export async function cancelUserSubscription(
     const auth = getFirebaseAdminAuth();
     const db = getFirebaseAdminFirestore();
 
+    // Read existing claims and merge to avoid overwriting other claims
+    const user = await auth.getUser(firebaseUid);
+    const currentClaims = user.customClaims || {};
+
     // Update Firebase Auth custom claims
     await auth.setCustomUserClaims(firebaseUid, {
+      ...currentClaims,
       subscription: subscriptionClaims,
     });
 

package/src/shared/utils/internal/auth.ts

@@ -2,19 +2,23 @@
 
 /**
  * @fileoverview Authentication utility functions
- * @description Functions for user authentication and authorization
+ * @description Provider-agnostic functions for user authentication and authorization.
+ * Uses IServerAuthAdapter from provider registry when configured, falls back to Firebase Admin SDK.
  *
- * @version 0.0.1
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 
 import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+import { hasProvider, getProvider } from '@donotdev/core/server';
 
 import type { NextApiRequest } from 'next';
 
+/** Auth provider type for explicit configuration */
+export type AuthProvider = 'firebase' | 'supabase';
+
 // IMPORTANT: Don't call getAuth() at module load - breaks Firebase deployment
-// const auth = getAuth(); // REMOVED - use getAuth() directly in functions instead
 
 /**
  * Validates that user is authenticated
@@ -31,9 +35,10 @@ export function assertAuthenticated(uid: string): string {
 }
 
 /**
- * Validates that user has admin privileges
+ * Validates that user has admin privileges.
+ * Uses IServerAuthAdapter when configured, falls back to Firebase Admin SDK.
  *
- * @version 0.0.1
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -41,8 +46,25 @@ export async function assertAdmin(uid: string): Promise<string> {
   assertAuthenticated(uid);
 
   try {
-    const user = await getFirebaseAdminAuth().getUser(uid); // Lazy initialization
-    const isAdmin = user.customClaims?.isAdmin === true;
+    let claims: Record<string, unknown> = {};
+
+    if (hasProvider('serverAuth')) {
+      const user = await getProvider('serverAuth').getUser(uid);
+      claims = (user?.customClaims as Record<string, unknown>) ?? {};
+    } else {
+      // Legacy Firebase path
+      const user = await getFirebaseAdminAuth().getUser(uid);
+      claims = user.customClaims ?? {};
+    }
+
+    // W8: Unified role-check logic consistent with shared/utils.ts:assertAdmin.
+    // Check role string first (standard), then legacy boolean flags.
+    const role = claims.role;
+    const isAdmin =
+      role === 'admin' ||
+      role === 'super' ||
+      claims.isAdmin === true ||
+      claims.isSuper === true;
 
     if (!isAdmin) {
       throw new Error('Admin privileges required');
@@ -50,22 +72,23 @@ export async function assertAdmin(uid: string): Promise<string> {
 
     return uid;
   } catch (error) {
+    // C4: Re-throw permission-denied as-is so callers can distinguish it from
+    // infrastructure failures. Only wrap genuine unexpected errors.
+    if (error instanceof Error && error.message === 'Admin privileges required') {
+      throw error;
+    }
     throw new Error('Failed to verify admin status');
   }
 }
 
 /**
- * Verifies Firebase auth token from Vercel request
+ * Extract Bearer token from authorization header.
  *
  * @version 0.0.1
- * @since 0.0.1
+ * @since 0.5.0
  * @author AMBROISE PARK Consulting
  */
-export async function verifyFirebaseAuthToken(
-  req: NextApiRequest
-): Promise<string> {
-  const authHeader = req.headers.authorization;
-
+function extractBearerToken(authHeader: string | undefined): string {
   if (!authHeader || !authHeader.startsWith('Bearer ')) {
     throw new Error('Missing or invalid authorization header');
   }
@@ -76,10 +99,111 @@ export async function verifyFirebaseAuthToken(
     throw new Error('Missing token in authorization header');
   }
 
+  return token;
+}
+
+/**
+ * Verify a Bearer token using the specified auth provider.
+ * Returns `{ uid: string }` on success, throws on failure.
+ *
+ * Provider resolution order:
+ * 1. Explicit `provider` parameter ('firebase' | 'supabase')
+ * 2. Provider registry (IServerAuthAdapter via `hasProvider('serverAuth')`)
+ * 3. Firebase Admin SDK fallback
+ *
+ * @param token - Raw JWT token (without "Bearer " prefix)
+ * @param provider - Optional explicit auth provider
+ * @returns Object with verified user's uid
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+export async function verifyToken(
+  token: string,
+  provider?: AuthProvider
+): Promise<{ uid: string }> {
   try {
-    const decodedToken = await getFirebaseAdminAuth().verifyIdToken(token); // Lazy initialization
-    return decodedToken.uid;
+    // Explicit provider
+    if (provider === 'supabase') {
+      return await verifySupabaseToken(token);
+    }
+
+    if (provider === 'firebase') {
+      const decodedToken = await getFirebaseAdminAuth().verifyIdToken(token);
+      return { uid: decodedToken.uid };
+    }
+
+    // Auto-detect: provider registry first, then Firebase fallback
+    if (hasProvider('serverAuth')) {
+      const verified = await getProvider('serverAuth').verifyToken(token);
+      return { uid: verified.uid };
+    }
+
+    // Legacy Firebase path
+    const decodedToken = await getFirebaseAdminAuth().verifyIdToken(token);
+    return { uid: decodedToken.uid };
   } catch (error) {
     throw new Error('Invalid or expired token');
   }
 }
+
+/**
+ * Verify a Supabase JWT token using the Supabase admin client.
+ * Requires SUPABASE_URL and SUPABASE_SECRET_KEY (or SUPABASE_SERVICE_ROLE_KEY) env vars.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+async function verifySupabaseToken(token: string): Promise<{ uid: string }> {
+  // Lazy import to avoid pulling in @supabase/supabase-js when using Firebase
+  const { createClient } = await import('@supabase/supabase-js');
+
+  const supabaseUrl = process.env.SUPABASE_URL;
+  const secretKey = process.env.SUPABASE_SECRET_KEY || process.env.SUPABASE_SERVICE_ROLE_KEY;
+
+  if (!supabaseUrl || !secretKey) {
+    throw new Error(
+      'Missing SUPABASE_URL or SUPABASE_SECRET_KEY/SUPABASE_SERVICE_ROLE_KEY environment variables'
+    );
+  }
+
+  const supabaseAdmin = createClient(supabaseUrl, secretKey, {
+    auth: { autoRefreshToken: false, persistSession: false },
+  });
+
+  const { data: { user }, error } = await supabaseAdmin.auth.getUser(token);
+
+  if (error || !user) {
+    throw new Error('Invalid or expired token');
+  }
+
+  return { uid: user.id };
+}
+
+/**
+ * Verifies auth token from request.
+ * Uses IServerAuthAdapter when configured, falls back to Firebase Admin SDK.
+ *
+ * @param req - Next.js API request
+ * @param provider - Optional explicit auth provider ('firebase' | 'supabase')
+ * @returns Verified user's uid
+ *
+ * @version 0.0.3
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export async function verifyAuthToken(
+  req: NextApiRequest,
+  provider?: AuthProvider
+): Promise<string> {
+  const token = extractBearerToken(req.headers.authorization);
+  const { uid } = await verifyToken(token, provider);
+  return uid;
+}
+
+/**
+ * @deprecated Use verifyAuthToken instead. Kept for backwards compatibility.
+ */
+export const verifyFirebaseAuthToken = verifyAuthToken;

package/src/shared/utils/internal/rateLimiter.ts

@@ -12,19 +12,9 @@
 import { logger } from 'firebase-functions/v2';
 
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import type { ServerRateLimitConfig as RateLimitConfig, ServerRateLimitResult as RateLimitResult } from '@donotdev/core';
 
-interface RateLimitConfig {
-  maxAttempts: number;
-  windowMs: number;
-  blockDurationMs: number;
-}
-
-interface RateLimitResult {
-  allowed: boolean;
-  remaining: number;
-  resetAt: Date | null;
-  blockRemainingSeconds: number | null;
-}
+export type { RateLimitConfig, RateLimitResult };
 
 interface RateLimitEntry {
   attempts: number;
@@ -104,8 +94,21 @@ export async function checkRateLimit(
 }
 
 /**
- * Check rate limit using Firestore for persistent storage
- * This is the recommended approach for production
+ * Check rate limit using Firestore for persistent storage.
+ * This is the recommended approach for production.
+ *
+ * **Architecture decision — Firestore transaction for rate limiting:**
+ * The read-modify-write cycle is wrapped in a Firestore transaction to
+ * eliminate TOCTOU races. While transactions add some latency, rate limiting
+ * is a best-effort abuse-prevention mechanism, not a hard security boundary.
+ * The window-based approach (maxAttempts per windowMs) tolerates minor
+ * timing variations. If transaction contention becomes an issue under extreme
+ * load, the catch block fails open (allows the request) to avoid blocking
+ * legitimate traffic — this is an intentional trade-off favoring availability
+ * over strict enforcement.
+ *
+ * For stricter rate limiting (e.g. payment endpoints), consumers can use
+ * Redis-backed rate limiters or API gateway-level throttling.
  *
  * @version 0.0.1
  * @since 0.0.1
@@ -120,89 +123,97 @@ export async function checkRateLimitWithFirestore(
 
   try {
     const now = Date.now();
-    const doc = await rateLimitRef.get();
-
-    if (!doc.exists) {
-      // First attempt
-      await rateLimitRef.set({
-        attempts: 1,
-        windowStart: now,
-        blockUntil: null,
-        lastUpdated: now,
-      });
-
-      return {
-        allowed: true,
-        remaining: config.maxAttempts - 1,
-        resetAt: new Date(now + config.windowMs),
-        blockRemainingSeconds: null,
-      };
-    }
 
-    const data = doc.data() as RateLimitEntry & { lastUpdated: number };
+    // W2: Wrap the entire read-modify-write in a Firestore transaction to
+    // eliminate the TOCTOU race where two concurrent requests both read the
+    // same counter and both increment it independently.
+    let result: RateLimitResult = {
+      allowed: true,
+      remaining: config.maxAttempts - 1,
+      resetAt: new Date(now + config.windowMs),
+      blockRemainingSeconds: null,
+    };
 
-    // Check if currently blocked
-    if (data.blockUntil && now < data.blockUntil) {
-      return {
-        allowed: false,
-        remaining: 0,
-        resetAt: new Date(data.blockUntil),
-        blockRemainingSeconds: Math.ceil((data.blockUntil - now) / 1000),
-      };
-    }
-
-    // Check if window expired
-    if (now >= data.windowStart + config.windowMs) {
-      // Reset window
-      await rateLimitRef.set({
-        attempts: 1,
-        windowStart: now,
-        blockUntil: null,
-        lastUpdated: now,
-      });
-
-      return {
+    await db.runTransaction(async (tx) => {
+      const doc = await tx.get(rateLimitRef);
+
+      if (!doc.exists) {
+        tx.set(rateLimitRef, {
+          attempts: 1,
+          windowStart: now,
+          blockUntil: null,
+          lastUpdated: now,
+        });
+        result = {
+          allowed: true,
+          remaining: config.maxAttempts - 1,
+          resetAt: new Date(now + config.windowMs),
+          blockRemainingSeconds: null,
+        };
+        return;
+      }
+
+      const data = doc.data() as RateLimitEntry & { lastUpdated: number };
+
+      // Check if currently blocked
+      if (data.blockUntil && now < data.blockUntil) {
+        result = {
+          allowed: false,
+          remaining: 0,
+          resetAt: new Date(data.blockUntil),
+          blockRemainingSeconds: Math.ceil((data.blockUntil - now) / 1000),
+        };
+        return;
+      }
+
+      // Check if window expired — reset
+      if (now >= data.windowStart + config.windowMs) {
+        tx.set(rateLimitRef, {
+          attempts: 1,
+          windowStart: now,
+          blockUntil: null,
+          lastUpdated: now,
+        });
+        result = {
+          allowed: true,
+          remaining: config.maxAttempts - 1,
+          resetAt: new Date(now + config.windowMs),
+          blockRemainingSeconds: null,
+        };
+        return;
+      }
+
+      // Check if limit exceeded
+      if (data.attempts >= config.maxAttempts) {
+        const blockUntil = now + config.blockDurationMs;
+        tx.update(rateLimitRef, { blockUntil, lastUpdated: now });
+
+        logger.warn('Rate limit exceeded (Firestore)', {
+          key,
+          attempts: data.attempts,
+          blockUntil: new Date(blockUntil),
+        });
+
+        result = {
+          allowed: false,
+          remaining: 0,
+          resetAt: new Date(blockUntil),
+          blockRemainingSeconds: Math.ceil(config.blockDurationMs / 1000),
+        };
+        return;
+      }
+
+      // Increment attempts
+      tx.update(rateLimitRef, { attempts: data.attempts + 1, lastUpdated: now });
+      result = {
         allowed: true,
-        remaining: config.maxAttempts - 1,
-        resetAt: new Date(now + config.windowMs),
+        remaining: config.maxAttempts - (data.attempts + 1),
+        resetAt: new Date(data.windowStart + config.windowMs),
         blockRemainingSeconds: null,
       };
-    }
-
-    // Check if limit exceeded
-    if (data.attempts >= config.maxAttempts) {
-      const blockUntil = now + config.blockDurationMs;
-      await rateLimitRef.update({
-        blockUntil,
-        lastUpdated: now,
-      });
-
-      logger.warn('Rate limit exceeded (Firestore)', {
-        key,
-        attempts: data.attempts,
-        blockUntil: new Date(blockUntil),
-      });
-
-      return {
-        allowed: false,
-        remaining: 0,
-        resetAt: new Date(blockUntil),
-        blockRemainingSeconds: Math.ceil(config.blockDurationMs / 1000),
-      };
-    }
-
-    // Increment attempts
-    await rateLimitRef.update({
-      attempts: data.attempts + 1,
-      lastUpdated: now,
     });
 
-    return {
-      allowed: true,
-      remaining: config.maxAttempts - (data.attempts + 1),
-      resetAt: new Date(data.windowStart + config.windowMs),
-      blockRemainingSeconds: null,
-    };
+    return result;
   } catch (error) {
     logger.error('Rate limit check failed', {
       key,

package/src/shared/utils/internal/validation.ts

@@ -4,11 +4,13 @@
  * @fileoverview Validation utility functions
  * @description Functions for validating environment and data
  *
- * @version 0.0.1
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 
+import * as v from 'valibot';
+
 /**
  * Validates environment variables required for Stripe
  *
@@ -43,19 +45,61 @@ export function safeJsonParse<T = any>(json: string): T | null {
 }
 
 /**
- * Validates document data against schema
+ * Validates a Firestore collection name from client-supplied schema.
+ *
+ * W22: Vercel CRUD handlers accept `schema` (including collection name) from
+ * the client. This is a known design limitation. As a defense-in-depth measure,
+ * reject collection names that could be used for path traversal or access to
+ * internal collections.
+ *
+ * @param name - Collection name to validate
+ * @throws Error if the name is unsafe
  *
  * @version 0.0.1
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
+export function validateCollectionName(name: string): void {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Collection name is required');
+  }
+  if (name.includes('/') || name.includes('..') || name.startsWith('_')) {
+    throw new Error(
+      'Invalid collection name: must not contain "/", "..", or start with "_"'
+    );
+  }
+}
+
+/**
+ * Validates document data against an optional Valibot schema.
+ *
+ * W1: Previous stub ignored the schema parameter entirely. Now performs
+ * actual schema validation when a schema is provided.
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
 export function validateDocument(data: any, schema?: any): void {
   if (!data || typeof data !== 'object') {
     throw new Error('Invalid document data');
   }
 
-  // Basic validation - can be extended with schema validation
   if (Array.isArray(data)) {
     throw new Error('Document data cannot be an array');
   }
+
+  // W1: Perform schema validation when a Valibot schema is supplied.
+  if (schema) {
+    const result = v.safeParse(schema, data);
+    if (!result.success) {
+      const messages = result.issues
+        .map(
+          (issue) =>
+            `${issue.path?.map((p) => (p as any).key).join('.') || 'root'}: ${issue.message}`
+        )
+        .join('; ');
+      throw new Error(`Validation failed: ${messages}`);
+    }
+  }
 }