@donotdev/functions 0.0.10 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donotdev/functions",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "private": false,
   "description": "Backend functions for DoNotDev Framework - Firebase, Vercel, and platform-agnostic implementations for auth, billing, CRUD, and OAuth",
   "main": "./lib/firebase/index.js",
@@ -26,6 +26,11 @@
       "types": "./lib/shared/index.d.ts",
       "import": "./lib/shared/index.js",
       "default": "./lib/shared/index.js"
+    },
+    "./supabase": {
+      "types": "./lib/supabase/index.d.ts",
+      "import": "./lib/supabase/index.js",
+      "default": "./lib/supabase/index.js"
     }
   },
   "type": "module",
@@ -42,15 +47,17 @@
     "serve": "firebase emulators:start --only functions"
   },
   "dependencies": {
-    "@donotdev/core": "^0.0.23",
-    "@donotdev/firebase": "^0.0.10"
+    "@donotdev/core": "^0.0.24",
+    "@donotdev/firebase": "^0.0.11",
+    "@donotdev/supabase": "^0.0.1"
   },
   "peerDependencies": {
-    "@sentry/node": "^10.38.0",
-    "firebase-admin": "^13.6.0",
+    "@sentry/node": "^10.39.0",
+    "@supabase/supabase-js": "^2.49.0",
+    "firebase-admin": "^13.6.1",
     "firebase-functions": "^7.0.5",
     "next": "^16.1.6",
-    "stripe": "^20.3.0",
+    "stripe": "^20.3.1",
     "valibot": "^1.2.0"
   },
   "repository": {
@@ -60,6 +67,7 @@
   "keywords": [
     "dndev",
     "firebase",
+    "supabase",
     "vercel",
     "cloud-functions",
     "serverless",
@@ -76,5 +84,21 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "peerDependenciesMeta": {}
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "firebase-admin": {
+      "optional": true
+    },
+    "firebase-functions": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "@sentry/node": {
+      "optional": true
+    }
+  }
 }

package/src/firebase/auth/setCustomClaims.ts

@@ -58,16 +58,38 @@ async function setCustomClaimsLogic(
     throw new Error('customClaims must be an object');
   }
 
-  // Idempotency check if key provided
+  // W17: Validate idempotency key to prevent oversized or malformed inputs.
+  if (idempotencyKey !== undefined) {
+    if (typeof idempotencyKey !== 'string' || idempotencyKey.length === 0 || idempotencyKey.length > 256) {
+      throw new Error('idempotencyKey must be a non-empty string of at most 256 characters');
+    }
+    if (!/^[\w\-.:@]+$/.test(idempotencyKey)) {
+      throw new Error('idempotencyKey contains invalid characters (allowed: alphanumeric, -, _, ., :, @)');
+    }
+  }
+
+  // C9: Atomic idempotency check — reserve key in a transaction to eliminate TOCTOU race.
   if (idempotencyKey) {
     const db = getFirebaseAdminFirestore();
     const idempotencyRef = db
       .collection('idempotency')
       .doc(`claims_${idempotencyKey}`);
 
-    const idempotencyDoc = await idempotencyRef.get();
-    if (idempotencyDoc.exists) {
-      return idempotencyDoc.data()?.result;
+    let existingResult: unknown = undefined;
+    let alreadyProcessed = false;
+
+    await db.runTransaction(async (tx) => {
+      const idempotencyDoc = await tx.get(idempotencyRef);
+      if (idempotencyDoc.exists) {
+        existingResult = idempotencyDoc.data()?.result;
+        alreadyProcessed = true;
+        return;
+      }
+      tx.set(idempotencyRef, { processing: true, reservedAt: new Date().toISOString() });
+    });
+
+    if (alreadyProcessed) {
+      return existingResult as { success: boolean; customClaims: Record<string, any> };
     }
   }
 

package/src/firebase/baseFunction.ts

@@ -15,11 +15,13 @@ import * as v from 'valibot';
 
 import { hasRoleAccess } from '@donotdev/core/server';
 import type { UserRole } from '@donotdev/core/server';
+import type { SecurityContext } from '@donotdev/core';
 
+import { FUNCTION_CONFIG } from './config/constants.js';
 import { handleError } from '../shared/errorHandling.js';
 import { assertAuthenticated, getUserRole } from '../shared/utils.js';
 
-import type { CallableRequest } from 'firebase-functions/v2/https';
+import type { CallableRequest, CallableOptions } from 'firebase-functions/v2/https';
 
 // Optional monitoring imports - only used when enabled
 // Lazy loaded to avoid unnecessary Firestore operations
@@ -51,27 +53,38 @@ async function loadMonitoring() {
 }
 
 /**
- * Extract client IP from Firebase callable request
- * Handles proxied requests (X-Forwarded-For header)
+ * Extract client IP from Firebase callable request.
+ *
+ * **Architecture decision — X-Forwarded-For rightmost IP extraction:**
+ *
+ * C6/W12: X-Forwarded-For is a comma-separated list where each proxy appends
+ * the IP it received the request from. The leftmost entry is client-supplied
+ * and trivially spoofable. The rightmost entry is appended by the first
+ * trusted reverse proxy and is the last untrusted IP.
+ *
+ * In Firebase Hosting / Cloud Run, the last proxy is Google's load balancer
+ * which sets X-Forwarded-For. The rightmost (last) IP is the true external
+ * client IP in this trusted-infrastructure context. This is correct for the
+ * single-proxy-depth that Google's LB provides.
+ *
+ * Consumers deploying behind additional reverse proxies (e.g. Cloudflare in
+ * front of Firebase) should configure `trustedProxyDepth` so the framework
+ * skips the appropriate number of rightmost entries.
+ *
+ * Rate-limiting falls back to the socket IP if the header is absent.
  */
 function getClientIp(request: CallableRequest<unknown>): string {
-  // Try X-Forwarded-For first (common for proxied requests)
   const forwardedFor = request.rawRequest.headers['x-forwarded-for'];
   if (forwardedFor) {
-    // Take the first IP (client IP) from the comma-separated list
-    let ips: string | string[] | undefined;
-    if (Array.isArray(forwardedFor)) {
-      ips = forwardedFor.length > 0 ? forwardedFor[0] : undefined;
-    } else {
-      ips = forwardedFor;
-    }
-    if (ips && typeof ips === 'string') {
-      const firstIp = ips.split(',')[0];
-      return firstIp ? firstIp.trim() : 'unknown';
+    const raw = Array.isArray(forwardedFor) ? forwardedFor.join(',') : forwardedFor;
+    // Split and take the RIGHTMOST entry (last untrusted / first-to-be-trusted)
+    const ips = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    if (ips.length > 0) {
+      return ips[ips.length - 1]!;
     }
   }
 
-  // Fallback to raw IP
+  // Fallback to raw socket IP (not proxied)
   const rawIp =
     request.rawRequest.ip || request.rawRequest.socket?.remoteAddress;
   return rawIp || 'unknown';
@@ -81,18 +94,22 @@ function getClientIp(request: CallableRequest<unknown>): string {
  * Base Firebase function that handles all common concerns
  * Users just provide their business logic
  *
+ * Rate limiting and metrics are enabled by default.
+ * Set `DISABLE_RATE_LIMITING=true` or `DISABLE_METRICS=true` to opt out.
+ *
  * @param config - Firebase function config (region, memory, etc.)
  * @param schema - Valibot schema for request validation
  * @param operation - Operation name for logging/metrics
  * @param businessLogic - The actual business logic to execute
  * @param requiredRole - Minimum role required (default: 'user' for backwards compatibility)
  *
- * @version 0.0.2
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 export function createBaseFunction<TRequest, TResponse>(
-  config: any,
+  // W16: Typed as CallableOptions instead of `any`.
+  config: CallableOptions,
   schema: v.BaseSchema<unknown, TRequest, v.BaseIssue<unknown>>,
   operation: string,
   businessLogic: (
@@ -103,7 +120,8 @@ export function createBaseFunction<TRequest, TResponse>(
       request: CallableRequest<TRequest>;
     }
   ) => Promise<TResponse>,
-  requiredRole: UserRole = 'user'
+  requiredRole: UserRole = 'user',
+  security?: SecurityContext
 ) {
   // Validate schema at function creation time (framework-level robustness)
   if (!schema) {
@@ -219,8 +237,8 @@ export function createBaseFunction<TRequest, TResponse>(
           }
         }
 
-        // Rate limiting (only if enabled via ENABLE_RATE_LIMITING env var)
-        if (process.env.ENABLE_RATE_LIMITING === 'true') {
+        // Rate limiting (on by default, set DISABLE_RATE_LIMITING=true to opt out)
+        if (process.env.DISABLE_RATE_LIMITING !== 'true') {
           const {
             checkRateLimitWithFirestore: checkLimit,
             DEFAULT_RATE_LIMITS: limits,
@@ -244,6 +262,11 @@ export function createBaseFunction<TRequest, TResponse>(
               remaining: rateLimitResult.remaining,
               resetAt: rateLimitResult.resetAt,
             });
+            security?.audit({
+              type: 'rate_limit.exceeded',
+              userId: uid,
+              metadata: { operation, remaining: 0 },
+            });
             throw new Error(
               `Rate limit exceeded. Try again in ${rateLimitResult.blockRemainingSeconds} seconds.`
             );

package/src/firebase/billing/cancelSubscription.ts

@@ -14,8 +14,10 @@ import * as v from 'valibot';
 import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 
 import { cancelUserSubscription } from '../../shared/billing/helpers/subscriptionManagement.js';
+import { initStripe } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { STRIPE_CONFIG } from '../config/constants.js';
+import { stripeSecretKey } from '../config/secrets.js';
 
 import type { CallableRequest } from 'firebase-functions/v2/https';
 
@@ -35,7 +37,13 @@ async function cancelSubscriptionLogic(
   data: { userId: string },
   context: { uid: string; request: CallableRequest }
 ) {
-  const { userId } = data;
+  // W15: initStripe must be called before using the stripe proxy in v2.
+  initStripe(stripeSecretKey.value());
+
+  // C7: Ignore client-supplied userId — always use the verified uid from the
+  // auth context. A client passing another user's ID would otherwise allow
+  // cancelling any user's subscription (IDOR).
+  const userId = context.uid;
 
   const authProvider = {
     async getUser(uid: string) {

package/src/firebase/billing/changePlan.ts

@@ -17,9 +17,10 @@ import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 
 import { updateUserSubscription } from '../../shared/billing/helpers/updateUserSubscription.js';
 import { handleError } from '../../shared/errorHandling.js';
-import { stripe, validateStripeEnvironment } from '../../shared/utils.js';
+import { stripe, validateStripeEnvironment, initStripe } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { STRIPE_CONFIG } from '../config/constants.js';
+import { stripeSecretKey } from '../config/secrets.js';
 
 import type { CallableRequest } from 'firebase-functions/v2/https';
 
@@ -42,9 +43,14 @@ async function changePlanLogic(
   context: { uid: string; request: CallableRequest },
   billingConfig: StripeBackConfig
 ) {
+  // W15: initStripe must be called before using the stripe proxy in v2.
+  initStripe(stripeSecretKey.value());
   validateStripeEnvironment();
 
-  const { userId, newPriceId, billingConfigKey } = data;
+  // C7: Ignore client-supplied userId — always use the verified uid from the
+  // auth context to prevent IDOR.
+  const userId = context.uid;
+  const { newPriceId, billingConfigKey } = data;
 
   // Validate new plan exists in config
   const billingItem = billingConfig[billingConfigKey];

package/src/firebase/billing/createCustomerPortal.ts

@@ -48,7 +48,11 @@ async function createCustomerPortalLogic(
     throw handleError(error);
   }
 
-  const { userId, returnUrl } = data;
+  // C8: Ignore client-supplied userId — always use the verified uid from the
+  // auth context to prevent IDOR (any authenticated user opening another
+  // user's billing portal).
+  const userId = context.uid;
+  const { returnUrl } = data;
 
   // Get customer ID from user claims
   const user = await getFirebaseAdminAuth().getUser(userId);
@@ -62,10 +66,20 @@ async function createCustomerPortalLogic(
     throw handleError(new Error('No Stripe customer ID found for user'));
   }
 
+  // C8: Removed hardcoded 'https://donotdev.com/dashboard' fallback.
+  // Use caller-supplied returnUrl or derive from FRONTEND_URL env var.
+  const resolvedReturnUrl =
+    returnUrl ??
+    (process.env.FRONTEND_URL ? `${process.env.FRONTEND_URL}/dashboard` : undefined);
+
+  if (!resolvedReturnUrl) {
+    throw handleError(new Error('returnUrl is required (or set FRONTEND_URL env var)'));
+  }
+
   // Create portal session
   const session = await stripe.billingPortal.sessions.create({
     customer: customerId,
-    return_url: returnUrl || 'https://donotdev.com/dashboard', // Fallback
+    return_url: resolvedReturnUrl,
   });
 
   return {

package/src/firebase/billing/refreshSubscriptionStatus.ts

@@ -46,7 +46,9 @@ async function refreshSubscriptionStatusLogic(
   // Validate environment
   validateStripeEnvironment();
 
-  const { userId } = data;
+  // C7: Ignore client-supplied userId — always use the verified uid from the
+  // auth context to prevent IDOR (any user refreshing any user's subscription).
+  const userId = context.uid;
 
   // Get user from Firebase
   const user = await getFirebaseAdminAuth().getUser(userId);

package/src/firebase/billing/webhookHandler.ts

@@ -13,6 +13,7 @@ import { logger } from 'firebase-functions/v2';
 import { onRequest } from 'firebase-functions/v2/https';
 
 import type { StripeBackConfig } from '@donotdev/core/server';
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 
 import { updateUserSubscription } from '../../shared/billing/helpers/updateUserSubscription.js';
 import { processWebhook } from '../../shared/billing/webhookHandler.js';
@@ -95,6 +96,17 @@ export function createStripeWebhook(
         throw handleError(error);
       }
 
+      // C11: Build a proper authProvider so subscription webhook events can
+      // update custom claims (same pattern as the Vercel webhook handler).
+      const authProvider = {
+        async getUser(userId: string) {
+          return getFirebaseAdminAuth().getUser(userId);
+        },
+        async setCustomUserClaims(userId: string, claims: Record<string, unknown>) {
+          await getFirebaseAdminAuth().setCustomUserClaims(userId, claims);
+        },
+      };
+
       // Call shared algorithm
       const result = await processWebhook(
         rawBody,
@@ -103,7 +115,7 @@ export function createStripeWebhook(
         stripe,
         billingConfig,
         updateUserSubscription,
-        null // No authProvider needed for Firebase implementation
+        authProvider
       );
 
       logger.info('[Firebase Webhook] Success', result);

package/src/firebase/crud/aggregate.ts

@@ -12,6 +12,8 @@
 
 import * as v from 'valibot';
 
+import { hasRoleAccess } from '@donotdev/core/server';
+import type { UserRole } from '@donotdev/core/server';
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
 
 import { isFieldVisible } from '../../shared/schema.js';
@@ -218,11 +220,11 @@ function aggregateEntitiesLogicFactory(
 ) {
   return async function aggregateEntitiesLogic(
     data: AggregateRequest,
-    context: { uid: string; request: CallableRequest<AggregateRequest> }
+    context: { uid: string; userRole: UserRole; request: CallableRequest<AggregateRequest> }
   ) {
     const db = getFirebaseAdminFirestore();
-    const user = context.request.auth;
-    const isAdmin = user?.token?.isAdmin === true;
+    const { userRole } = context;
+    const isAdmin = hasRoleAccess(userRole, 'admin');
 
     // Validate that user can access the fields being aggregated
     const allFields = new Set<string>();
@@ -262,8 +264,21 @@ function aggregateEntitiesLogicFactory(
       }
     }
 
-    // Fetch all matching documents
-    const snapshot = await query.get();
+    // W14: Cap document fetch to avoid OOM on large collections.
+    // Aggregations on more than MAX_AGGREGATE_DOCS documents require server-side
+    // Firestore COUNT/SUM queries (not yet used here) or pre-computed summaries.
+    //
+    // Architecture decision — full collection fetch for aggregations:
+    // Firestore's free tier has no server-side aggregation beyond count().
+    // Operations like sum, avg, min, and max require reading documents
+    // client-side. This full-fetch approach is the only option without
+    // paid extensions. For large collections (>10k docs), consumers should
+    // use Firestore Extensions, BigQuery export, or pre-computed summary
+    // documents updated via Cloud Functions triggers.
+    // MAX_AGGREGATE_DOCS provides a safety limit to prevent OOM in Cloud
+    // Functions (default 256MB memory).
+    const MAX_AGGREGATE_DOCS = 10_000;
+    const snapshot = await query.limit(MAX_AGGREGATE_DOCS).get();
     const docs: Record<string, any>[] = snapshot.docs.map((doc) => ({
       id: doc.id,
       ...doc.data(),

package/src/firebase/crud/create.ts

@@ -91,9 +91,8 @@ async function checkUniqueKeys(
   const db = getFirebaseAdminFirestore();
 
   for (const uniqueKey of uniqueKeys) {
-    // Skip validation for drafts if configured (default: true)
-    const skipForDrafts = uniqueKey.skipForDrafts !== false;
-    if (isDraft && skipForDrafts) continue;
+    // Skip validation for drafts only if explicitly opted in (default: false)
+    if (isDraft && uniqueKey.skipForDrafts === true) continue;
 
     // Check if all fields in the unique key have values
     const allFieldsHaveValues = uniqueKey.fields.every(
@@ -159,15 +158,40 @@ function createEntityLogicFactory(
     const { payload, idempotencyKey } = data;
     const { uid } = context;
 
-    // Idempotency check if key provided
+    // W17: Validate idempotency key length and content.
+    if (idempotencyKey !== undefined) {
+      if (typeof idempotencyKey !== 'string' || idempotencyKey.length === 0 || idempotencyKey.length > 256) {
+        throw new DoNotDevError('idempotencyKey must be a non-empty string of at most 256 characters', 'invalid-argument');
+      }
+      if (!/^[\w\-.:@]+$/.test(idempotencyKey)) {
+        throw new DoNotDevError('idempotencyKey contains invalid characters', 'invalid-argument');
+      }
+    }
+
+    // C9: Atomic idempotency check — reserve key in a transaction to eliminate
+    // the TOCTOU race where two concurrent requests both read "not exists" and
+    // both proceed to create a duplicate document.
     if (idempotencyKey) {
       const db = getFirebaseAdminFirestore();
       const idempotencyRef = db
         .collection('idempotency')
         .doc(`create_${idempotencyKey}`);
-      const idempotencyDoc = await idempotencyRef.get();
-      if (idempotencyDoc.exists) {
-        return idempotencyDoc.data()?.result;
+
+      let existingResult: unknown = undefined;
+      let alreadyProcessed = false;
+
+      await db.runTransaction(async (tx) => {
+        const idempotencyDoc = await tx.get(idempotencyRef);
+        if (idempotencyDoc.exists) {
+          existingResult = idempotencyDoc.data()?.result;
+          alreadyProcessed = true;
+          return;
+        }
+        tx.set(idempotencyRef, { processing: true, reservedAt: new Date().toISOString() });
+      });
+
+      if (alreadyProcessed) {
+        return existingResult;
       }
     }
 

package/src/firebase/crud/list.ts

@@ -144,31 +144,16 @@ function listEntitiesLogicFactory(
       query = query.startAfter(startAfterDoc);
     }
 
-    // Apply limit only if provided (no limit = fetch all)
-    if (limit !== undefined && limit > 0) {
-      query = query.limit(limit);
-    }
-
-    // DEBUG: Log query details
-    console.log(
-      `[listEntities] Collection: ${collection}, UserRole: ${userRole}, IsAdmin: ${isAdmin}`
-    );
-    console.log(
-      `[listEntities] Filters - where: ${JSON.stringify(where)}, orderBy: ${JSON.stringify(orderBy)}, limit: ${limit}`
-    );
+    // W13: Cap at MAX_LIST_LIMIT to prevent unbounded reads (DoS via cost amplification).
+    const MAX_LIST_LIMIT = 500;
+    const effectiveLimit = limit !== undefined && limit > 0
+      ? Math.min(limit, MAX_LIST_LIMIT)
+      : MAX_LIST_LIMIT;
+    query = query.limit(effectiveLimit);
 
     // Execute the query
     const snapshot = await query.get();
 
-    // DEBUG: Log result count
-    console.log(
-      `[listEntities] Query returned ${snapshot.docs.length} documents`
-    );
-
-    // DEBUG: Log schema info
-    const schemaHasEntries = !!(documentSchema as any)?.entries;
-    console.log(`[listEntities] Schema has entries: ${schemaHasEntries}`);
-
     // Helper: Check if value is a Picture object (has thumbUrl and fullUrl)
     const isPictureObject = (value: any): boolean => {
       return (
@@ -272,7 +257,7 @@ export const listEntities = (
       orderBy: v.optional(
         v.array(v.tuple([v.string(), v.picklist(['asc', 'desc'])]))
       ),
-      limit: v.optional(v.pipe(v.number(), v.minValue(1))),
+      limit: v.optional(v.pipe(v.number(), v.minValue(1), v.maxValue(500))),
       startAfterId: v.optional(v.string()),
       search: v.optional(
         v.object({

package/src/firebase/crud/update.ts

@@ -89,9 +89,8 @@ async function checkUniqueKeysForUpdate(
   const db = getFirebaseAdminFirestore();
 
   for (const uniqueKey of uniqueKeys) {
-    // Skip validation for drafts if configured (default: true)
-    const skipForDrafts = uniqueKey.skipForDrafts !== false;
-    if (isDraft && skipForDrafts) continue;
+    // Skip validation for drafts only if explicitly opted in (default: false)
+    if (isDraft && uniqueKey.skipForDrafts === true) continue;
 
     // Check if any of the unique key fields are being updated
     const isUpdatingUniqueKeyField = uniqueKey.fields.some(
@@ -152,15 +151,38 @@ function updateEntityLogicFactory(
     const { id, payload, idempotencyKey } = data;
     const { uid } = context;
 
-    // Idempotency check if key provided
+    // W17: Validate idempotency key length and content.
+    if (idempotencyKey !== undefined) {
+      if (typeof idempotencyKey !== 'string' || idempotencyKey.length === 0 || idempotencyKey.length > 256) {
+        throw new DoNotDevError('idempotencyKey must be a non-empty string of at most 256 characters', 'invalid-argument');
+      }
+      if (!/^[\w\-.:@]+$/.test(idempotencyKey)) {
+        throw new DoNotDevError('idempotencyKey contains invalid characters', 'invalid-argument');
+      }
+    }
+
+    // C9: Atomic idempotency check — reserve key in a transaction to eliminate TOCTOU race.
     if (idempotencyKey) {
       const db = getFirebaseAdminFirestore();
       const idempotencyRef = db
         .collection('idempotency')
         .doc(`update_${idempotencyKey}`);
-      const idempotencyDoc = await idempotencyRef.get();
-      if (idempotencyDoc.exists) {
-        return idempotencyDoc.data()?.result;
+
+      let existingResult: unknown = undefined;
+      let alreadyProcessed = false;
+
+      await db.runTransaction(async (tx) => {
+        const idempotencyDoc = await tx.get(idempotencyRef);
+        if (idempotencyDoc.exists) {
+          existingResult = idempotencyDoc.data()?.result;
+          alreadyProcessed = true;
+          return;
+        }
+        tx.set(idempotencyRef, { processing: true, reservedAt: new Date().toISOString() });
+      });
+
+      if (alreadyProcessed) {
+        return existingResult;
       }
     }
 

package/src/firebase/oauth/exchangeToken.ts

@@ -37,15 +37,41 @@ export const exchangeToken = onCall<ExchangeTokenRequest>(async (request) => {
   const { provider, purpose, code, redirectUri, codeVerifier, idempotencyKey } =
     request.data;
 
-  // Idempotency check if key provided
+  // W17: Validate idempotency key length and content.
+  if (idempotencyKey !== undefined) {
+    if (typeof idempotencyKey !== 'string' || idempotencyKey.length === 0 || idempotencyKey.length > 256) {
+      throw new HttpsError('invalid-argument', 'idempotencyKey must be a non-empty string of at most 256 characters');
+    }
+    if (!/^[\w\-.:@]+$/.test(idempotencyKey)) {
+      throw new HttpsError('invalid-argument', 'idempotencyKey contains invalid characters');
+    }
+  }
+
+  // C9: Atomic idempotency check using Firestore transaction to prevent TOCTOU race.
+  // A concurrent request with the same key would see the 'pending' sentinel and wait
+  // or return early instead of executing duplicate business logic.
   if (idempotencyKey) {
     const db = getFirebaseAdminFirestore();
     const idempotencyRef = db
       .collection('idempotency')
       .doc(`oauth_${idempotencyKey}`);
-    const idempotencyDoc = await idempotencyRef.get();
-    if (idempotencyDoc.exists) {
-      return idempotencyDoc.data()?.result;
+
+    let existingResult: unknown = undefined;
+    let alreadyProcessed = false;
+
+    await db.runTransaction(async (tx) => {
+      const idempotencyDoc = await tx.get(idempotencyRef);
+      if (idempotencyDoc.exists) {
+        existingResult = idempotencyDoc.data()?.result;
+        alreadyProcessed = true;
+        return;
+      }
+      // Reserve the key before executing business logic
+      tx.set(idempotencyRef, { processing: true, reservedAt: new Date().toISOString() });
+    });
+
+    if (alreadyProcessed) {
+      return existingResult;
     }
   }