@donotdev/functions 0.0.10 → 0.0.12

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;
     }
   }
 

package/src/firebase/oauth/githubAccess.ts

@@ -68,12 +68,13 @@ async function grantGitHubAccessInternal(
 
     const validatedData = validationResult.output;
     const {
-      userId,
       githubUsername,
       repoConfig,
       permission = 'push',
       customClaims,
     } = validatedData;
+    // W20: Enforce authenticated user ID — never trust client-supplied userId
+    const userId = uid;
 
     // Get GitHub token
     const githubToken = githubPersonalAccessToken.value();
@@ -206,7 +207,9 @@ async function revokeGitHubAccessInternal(
       );
     }
 
-    const { userId, githubUsername, repoConfig } = validationResult.output;
+    const { githubUsername, repoConfig } = validationResult.output;
+    // W20: Enforce authenticated user ID — never trust client-supplied userId
+    const userId = uid;
 
     // Get GitHub token
     const githubToken = githubPersonalAccessToken.value();
@@ -335,7 +338,9 @@ async function checkGitHubAccessInternal(
       );
     }
 
-    const { userId, githubUsername, repoConfig } = validationResult.output;
+    const { githubUsername, repoConfig } = validationResult.output;
+    // W20: Enforce authenticated user ID — never trust client-supplied userId
+    const userId = uid;
 
     // Get GitHub token
     const githubToken = githubPersonalAccessToken.value();

package/src/firebase/registerCrudFunctions.ts

@@ -9,7 +9,7 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { createSchemas } from '@donotdev/core/server';
+import { createSchemas, getListCardFieldNames } from '@donotdev/core/server';
 import type { Entity } from '@donotdev/core/server';
 
 import {
@@ -91,7 +91,7 @@ export function createCrudFunctions(
       schemas.get,
       access.read,
       undefined,
-      entity.listCardFields ?? entity.listFields ?? undefined,
+      getListCardFieldNames(entity),
       entity.ownership,
       true
     );

package/src/firebase/scheduled/checkExpiredSubscriptions.ts

@@ -21,7 +21,16 @@ import { handleError } from '../../shared/errorHandling.js';
 
 /**
  * Scheduled function that runs daily to check for expired subscriptions
- * and update custom claims with expired status
+ * and update custom claims with expired status.
+ *
+ * **Architecture decision — opt-in scheduled function:**
+ * This function is not automatically deployed. Consumer apps opt in by
+ * exporting it from their functions entry point (e.g. `index.ts`). If not
+ * exported, Firebase never schedules it.
+ *
+ * The `users` collection path defaults to `'users'` but is configurable via
+ * the `USERS_COLLECTION_PATH` environment variable, allowing consumers to
+ * use their own collection structure (e.g. `'app_users'`, `'tenants/{id}/users'`).
  */
 export const checkExpiredSubscriptions = onSchedule(
   {
@@ -36,9 +45,17 @@ export const checkExpiredSubscriptions = onSchedule(
       const db = getFirebaseAdminFirestore();
       const now = new Date();
 
+      // W18: The 'users' collection name is configurable. Consumer apps may use
+      // a different collection. Default to 'users' but respect
+      // USERS_COLLECTION_PATH env var if set.
+      const usersCollection = process.env.USERS_COLLECTION_PATH || 'users';
+
+      // Guard: if the collection doesn't exist the query returns empty, which
+      // is safe. Log a warning so operators know if misconfigured.
+      const collectionRef = db.collection(usersCollection);
+
       // Get all users with active subscriptions
-      const usersSnapshot = await db
-        .collection('users')
+      const usersSnapshot = await collectionRef
         .where('subscription.status', '==', 'active')
         .get();
 

package/src/shared/__tests__/detectFirestore.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { isFirestoreConfigured } from '../utils/detectFirestore';
+
+describe('isFirestoreConfigured', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    // Clear all relevant env vars
+    delete process.env.FUNCTION_NAME;
+    delete process.env.FIREBASE_CONFIG;
+    delete process.env.FIREBASE_PROJECT_ID;
+    delete process.env.FIREBASE_CLIENT_EMAIL;
+    delete process.env.FIREBASE_PRIVATE_KEY;
+  });
+
+  afterEach(() => {
+    // Restore original env
+    process.env = { ...originalEnv };
+  });
+
+  it('returns true when FUNCTION_NAME is set (Firebase Functions runtime)', () => {
+    process.env.FUNCTION_NAME = 'myFunction';
+
+    expect(isFirestoreConfigured()).toBe(true);
+  });
+
+  it('returns true when FIREBASE_CONFIG is set', () => {
+    process.env.FIREBASE_CONFIG = '{"projectId":"test"}';
+
+    expect(isFirestoreConfigured()).toBe(true);
+  });
+
+  it('returns true when all manual credentials are set', () => {
+    process.env.FIREBASE_PROJECT_ID = 'my-project';
+    process.env.FIREBASE_CLIENT_EMAIL = 'sa@project.iam.gserviceaccount.com';
+    process.env.FIREBASE_PRIVATE_KEY = '-----BEGIN PRIVATE KEY-----\n...';
+
+    expect(isFirestoreConfigured()).toBe(true);
+  });
+
+  it('returns false when only partial credentials are set', () => {
+    process.env.FIREBASE_PROJECT_ID = 'my-project';
+    // Missing CLIENT_EMAIL and PRIVATE_KEY
+
+    expect(isFirestoreConfigured()).toBe(false);
+  });
+
+  it('returns false when no env vars are set', () => {
+    expect(isFirestoreConfigured()).toBe(false);
+  });
+});

package/src/shared/__tests__/errorHandling.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock firebase-functions
+vi.mock('firebase-functions/v2/https', () => ({
+  HttpsError: class HttpsError extends Error {
+    code: string;
+    details: any;
+    constructor(code: string, message: string, details?: any) {
+      super(message);
+      this.code = code;
+      this.details = details;
+      this.name = 'HttpsError';
+    }
+  },
+}));
+
+vi.mock('firebase-functions/v2', () => ({
+  logger: { warn: vi.fn(), info: vi.fn(), error: vi.fn(), log: vi.fn() },
+}));
+
+vi.mock('@donotdev/firebase/server', () => ({
+  getFirebaseAdminFirestore: vi.fn(),
+}));
+
+import { handleError, DoNotDevError } from '../errorHandling';
+
+describe('DoNotDevError (functions)', () => {
+  it('creates with default code "unknown"', () => {
+    const error = new DoNotDevError('test');
+
+    expect(error.code).toBe('unknown');
+    expect(error.message).toBe('test');
+    expect(error.name).toBe('DoNotDevError');
+  });
+
+  it('creates with explicit code and details', () => {
+    const error = new DoNotDevError('bad input', 'invalid-argument', {
+      field: 'email',
+    });
+
+    expect(error.code).toBe('invalid-argument');
+    expect(error.details).toEqual({ field: 'email' });
+  });
+
+  it('toString formats correctly', () => {
+    const error = new DoNotDevError('test', 'not-found');
+
+    expect(error.toString()).toBe('DoNotDevError [not-found]: test');
+  });
+
+  it('toJSON includes all fields', () => {
+    const error = new DoNotDevError('test', 'internal', { key: 'val' });
+    const json = error.toJSON();
+
+    expect(json).toEqual({
+      name: 'DoNotDevError',
+      code: 'internal',
+      message: 'test',
+      details: { key: 'val' },
+    });
+  });
+
+  it('instanceof chain works', () => {
+    const error = new DoNotDevError('test');
+
+    expect(error instanceof DoNotDevError).toBe(true);
+    expect(error instanceof Error).toBe(true);
+  });
+});
+
+describe('handleError', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    // Clear env to force fallback (no Firebase, no Vercel)
+    delete process.env.FUNCTIONS_EMULATOR;
+    delete process.env.FIREBASE_CONFIG;
+    delete process.env.GCLOUD_PROJECT;
+    delete process.env.VERCEL;
+    delete process.env.VERCEL_ENV;
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('throws for DoNotDevError (fallback env)', () => {
+    const original = new DoNotDevError('Bad', 'invalid-argument');
+
+    expect(() => handleError(original)).toThrow('invalid-argument: Bad');
+  });
+
+  it('throws for generic Error (fallback env)', () => {
+    const original = new Error('Something broke');
+
+    expect(() => handleError(original)).toThrow('internal: Something broke');
+  });
+
+  it('throws for string error (fallback env)', () => {
+    expect(() => handleError('random string')).toThrow(
+      'internal: An unexpected error occurred'
+    );
+  });
+
+  it('throws HttpsError in Firebase environment', () => {
+    process.env.FIREBASE_CONFIG = '{}';
+
+    try {
+      handleError(new DoNotDevError('test', 'not-found'));
+      expect.fail('should have thrown');
+    } catch (error: any) {
+      expect(error.name).toBe('HttpsError');
+      expect(error.code).toBe('not-found');
+    }
+  });
+
+  it('maps EntityHookError types correctly', () => {
+    // Simulate EntityHookError (name-based detection)
+    const entityError = new Error('Permission denied');
+    (entityError as any).name = 'EntityHookError';
+    (entityError as any).type = 'PERMISSION_DENIED';
+
+    try {
+      handleError(entityError);
+      expect.fail('should have thrown');
+    } catch (error: any) {
+      expect(error.message).toContain('permission-denied');
+    }
+  });
+
+  it('maps ValiError to invalid-argument', () => {
+    const valiError = new Error('Validation failed');
+    (valiError as any).name = 'ValiError';
+    (valiError as any).issues = [{ path: [], message: 'required' }];
+
+    try {
+      handleError(valiError);
+      expect.fail('should have thrown');
+    } catch (error: any) {
+      expect(error.message).toContain('invalid-argument');
+    }
+  });
+});

package/src/shared/__tests__/idempotency.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock detectFirestore to return false (force in-memory)
+vi.mock('../utils/detectFirestore.js', () => ({
+  isFirestoreConfigured: vi.fn(() => false),
+}));
+
+import {
+  createIdempotencyStore,
+  resetIdempotencyStore,
+} from '../billing/idempotency';
+
+describe('InMemoryIdempotency', () => {
+  beforeEach(() => {
+    resetIdempotencyStore();
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('creates in-memory store when Firestore not configured', () => {
+    const store = createIdempotencyStore();
+
+    expect(store).toBeDefined();
+    expect(typeof store.isProcessed).toBe('function');
+    expect(typeof store.markProcessed).toBe('function');
+  });
+
+  it('returns singleton instance', () => {
+    const store1 = createIdempotencyStore();
+    const store2 = createIdempotencyStore();
+
+    expect(store1).toBe(store2);
+  });
+
+  it('reports event as not processed initially', async () => {
+    const store = createIdempotencyStore();
+
+    const result = await store.isProcessed('evt_001');
+    expect(result).toBe(false);
+  });
+
+  it('reports event as processed after marking', async () => {
+    const store = createIdempotencyStore();
+
+    await store.markProcessed('evt_002');
+    const result = await store.isProcessed('evt_002');
+
+    expect(result).toBe(true);
+  });
+
+  it('distinguishes between different events', async () => {
+    const store = createIdempotencyStore();
+
+    await store.markProcessed('evt_a');
+
+    expect(await store.isProcessed('evt_a')).toBe(true);
+    expect(await store.isProcessed('evt_b')).toBe(false);
+  });
+
+  it('warns once on first isProcessed call', async () => {
+    const warnSpy = vi.spyOn(console, 'warn');
+    const store = createIdempotencyStore();
+
+    await store.isProcessed('evt_x');
+    await store.isProcessed('evt_y');
+
+    // Should warn at least once about in-memory usage
+    const inMemoryWarns = warnSpy.mock.calls.filter(
+      (call) => typeof call[0] === 'string' && call[0].includes('in-memory')
+    );
+    expect(inMemoryWarns.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('auto-cleans after 1000 entries (keeps last entries)', async () => {
+    const store = createIdempotencyStore();
+
+    // Add 1001 entries
+    for (let i = 0; i < 1001; i++) {
+      await store.markProcessed(`evt_${i}`);
+    }
+
+    // First entry should have been evicted
+    expect(await store.isProcessed('evt_0')).toBe(false);
+    // Recent entry should still exist
+    expect(await store.isProcessed('evt_1000')).toBe(true);
+  });
+
+  it('resetIdempotencyStore clears singleton', () => {
+    const store1 = createIdempotencyStore();
+    resetIdempotencyStore();
+    const store2 = createIdempotencyStore();
+
+    expect(store1).not.toBe(store2);
+  });
+});

package/src/shared/__tests__/rateLimiter.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock firebase-functions/v2 logger
+vi.mock('firebase-functions/v2', () => ({
+  logger: {
+    warn: vi.fn(),
+    info: vi.fn(),
+    error: vi.fn(),
+    log: vi.fn(),
+  },
+}));
+
+// Mock @donotdev/firebase/server (not used in in-memory path, but imported)
+vi.mock('@donotdev/firebase/server', () => ({
+  getFirebaseAdminFirestore: vi.fn(),
+}));
+
+import {
+  checkRateLimit,
+  resetRateLimit,
+  getRateLimitStatus,
+  DEFAULT_RATE_LIMITS,
+} from '../utils/internal/rateLimiter';
+
+const TEST_CONFIG = {
+  maxAttempts: 3,
+  windowMs: 60_000,
+  blockDurationMs: 300_000,
+};
+
+describe('checkRateLimit (in-memory)', () => {
+  beforeEach(() => {
+    // Reset rate limit store between tests
+    resetRateLimit('test-key');
+    resetRateLimit('other-key');
+  });
+
+  it('allows first request', async () => {
+    const result = await checkRateLimit('test-key', TEST_CONFIG);
+
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(2); // 3 max - 1 used
+    expect(result.blockRemainingSeconds).toBeNull();
+  });
+
+  it('decrements remaining on each request', async () => {
+    await checkRateLimit('test-key', TEST_CONFIG);
+    const result = await checkRateLimit('test-key', TEST_CONFIG);
+
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(1); // 3 max - 2 used
+  });
+
+  it('blocks after max attempts exceeded', async () => {
+    // Use all 3 attempts
+    await checkRateLimit('test-key', TEST_CONFIG);
+    await checkRateLimit('test-key', TEST_CONFIG);
+    await checkRateLimit('test-key', TEST_CONFIG);
+
+    // 4th request should be blocked
+    const result = await checkRateLimit('test-key', TEST_CONFIG);
+
+    expect(result.allowed).toBe(false);
+    expect(result.remaining).toBe(0);
+    expect(result.blockRemainingSeconds).toBeGreaterThan(0);
+    expect(result.resetAt).toBeInstanceOf(Date);
+  });
+
+  it('isolates keys from each other', async () => {
+    await checkRateLimit('test-key', TEST_CONFIG);
+    await checkRateLimit('test-key', TEST_CONFIG);
+    await checkRateLimit('test-key', TEST_CONFIG);
+
+    // Different key should still be allowed
+    const result = await checkRateLimit('other-key', TEST_CONFIG);
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(2);
+  });
+});
+
+describe('resetRateLimit', () => {
+  it('clears rate limit allowing new requests', async () => {
+    // Exhaust attempts
+    await checkRateLimit('test-key', TEST_CONFIG);
+    await checkRateLimit('test-key', TEST_CONFIG);
+    await checkRateLimit('test-key', TEST_CONFIG);
+
+    // Reset
+    resetRateLimit('test-key');
+
+    // Should be allowed again
+    const result = await checkRateLimit('test-key', TEST_CONFIG);
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(2);
+  });
+});
+
+describe('getRateLimitStatus', () => {
+  beforeEach(() => {
+    resetRateLimit('test-key');
+  });
+
+  it('returns full remaining for unknown key', () => {
+    const result = getRateLimitStatus('unknown-key', TEST_CONFIG);
+
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(3);
+    expect(result.resetAt).toBeNull();
+    expect(result.blockRemainingSeconds).toBeNull();
+  });
+
+  it('reflects current usage without consuming attempt', async () => {
+    await checkRateLimit('test-key', TEST_CONFIG);
+    await checkRateLimit('test-key', TEST_CONFIG);
+
+    const status = getRateLimitStatus('test-key', TEST_CONFIG);
+    expect(status.remaining).toBe(1);
+
+    // Check again — should be same (no attempt consumed)
+    const status2 = getRateLimitStatus('test-key', TEST_CONFIG);
+    expect(status2.remaining).toBe(1);
+  });
+});
+
+describe('DEFAULT_RATE_LIMITS', () => {
+  it('has checkout config', () => {
+    expect(DEFAULT_RATE_LIMITS.checkout.maxAttempts).toBe(5);
+    expect(DEFAULT_RATE_LIMITS.checkout.windowMs).toBe(60_000);
+  });
+
+  it('has webhook config', () => {
+    expect(DEFAULT_RATE_LIMITS.webhook.maxAttempts).toBe(100);
+  });
+
+  it('has auth config', () => {
+    expect(DEFAULT_RATE_LIMITS.auth.maxAttempts).toBe(10);
+  });
+
+  it('has api config', () => {
+    expect(DEFAULT_RATE_LIMITS.api.maxAttempts).toBe(100);
+  });
+});