@donotdev/functions 0.0.9 → 0.0.11

package/src/firebase/crud/list.ts

@@ -16,7 +16,11 @@ import {
   hasRoleAccess,
   HIDDEN_STATUSES,
 } from '@donotdev/core/server';
-import type { UserRole } from '@donotdev/core/server';
+import type {
+  EntityOwnershipConfig,
+  EntityOwnershipPublicCondition,
+  UserRole,
+} from '@donotdev/core/server';
 import { getFirebaseAdminFirestore, Query } from '@donotdev/firebase/server';
 
 import { transformFirestoreData } from '../../shared/index.js';
@@ -40,6 +44,20 @@ export interface ListEntityRequest {
   };
 }
 
+/**
+ * Apply public-condition where clauses to a query (for listCard when ownership is set).
+ */
+function applyPublicCondition(
+  query: Query,
+  publicCondition: EntityOwnershipPublicCondition[]
+): Query {
+  let q = query;
+  for (const c of publicCondition) {
+    q = q.where(c.field, c.op as any, c.value);
+  }
+  return q;
+}
+
 /**
  * Generic business logic for listing entities
  * Base function handles: validation, auth, rate limiting, monitoring
@@ -47,7 +65,9 @@ export interface ListEntityRequest {
 function listEntitiesLogicFactory(
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
-  listFields?: string[]
+  listFields?: string[],
+  ownership?: EntityOwnershipConfig,
+  isListCard?: boolean
 ) {
   return async function listEntitiesLogic(
     data: ListEntityRequest,
@@ -58,7 +78,8 @@ function listEntitiesLogicFactory(
     }
   ) {
     const { where = [], orderBy = [], limit, startAfterId, search } = data;
-    const { userRole } = context;
+    // Extract uid and userRole once (reused for all document masking)
+    const { userRole, uid } = context;
 
     const isAdmin = hasRoleAccess(userRole, 'admin'); // Uses role hierarchy
 
@@ -71,6 +92,26 @@ function listEntitiesLogicFactory(
       query = query.where('status', 'not-in', [...HIDDEN_STATUSES]);
     }
 
+    // Ownership: when set and not admin, listCard = public condition, list = mine filter
+    if (ownership && !isAdmin) {
+      if (
+        isListCard &&
+        ownership.publicCondition &&
+        ownership.publicCondition.length > 0
+      ) {
+        query = applyPublicCondition(query, ownership.publicCondition);
+      } else if (!isListCard && ownership.ownerFields.length > 0) {
+        // "Mine" filter: Firestore does not support OR across different fields in one query.
+        // Use first owner field only for single query; recommend ownerIds array-contains for multiple.
+        const firstOwnerField = ownership.ownerFields[0];
+        query = query.where(firstOwnerField, '==', uid);
+        if (ownership.ownerFields.length > 1) {
+          // Optional: run second query and merge (complex pagination). For now, single field only.
+          // Document ownerIds pattern for multiple stakeholders.
+        }
+      }
+    }
+
     // Apply search if provided
     if (search) {
       const { field, query: searchQuery } = search;
@@ -103,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 (
@@ -158,13 +184,18 @@ function listEntitiesLogicFactory(
       return value;
     };
 
-    // Filter document fields based on visibility and user role
+    const visibilityOptions = ownership && uid ? { uid, ownership } : undefined;
+
+    // Filter document fields based on visibility and user role (uid/userRole from context, once)
     const docs = snapshot.docs.map((doc: any) => {
       const rawData = doc.data() || {};
       const visibleData = filterVisibleFields(
         rawData,
         documentSchema,
-        userRole
+        userRole,
+        visibilityOptions
+          ? { ...visibilityOptions, documentData: rawData }
+          : undefined
       );
 
       // If listFields specified, filter to only those fields (plus id always)
@@ -206,6 +237,8 @@ function listEntitiesLogicFactory(
  * @param requiredRole - Minimum role required for this operation
  * @param customSchema - Optional custom request schema
  * @param listFields - Optional array of field names to include (plus id). If not provided, all visible fields are returned.
+ * @param ownership - Optional ownership config for list constraints and visibility: 'owner' masking
+ * @param isListCard - When true and ownership is set, applies public condition; when false, applies "mine" filter
  * @returns Firebase callable function
  */
 export const listEntities = (
@@ -213,7 +246,9 @@ export const listEntities = (
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
   requiredRole: UserRole,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
-  listFields?: string[]
+  listFields?: string[],
+  ownership?: EntityOwnershipConfig,
+  isListCard?: boolean
 ): CallableFunction<ListEntityRequest, Promise<any>> => {
   const requestSchema =
     customSchema ||
@@ -222,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({
@@ -236,7 +271,13 @@ export const listEntities = (
     CRUD_READ_CONFIG,
     requestSchema,
     'list_entities',
-    listEntitiesLogicFactory(collection, documentSchema, listFields),
+    listEntitiesLogicFactory(
+      collection,
+      documentSchema,
+      listFields,
+      ownership,
+      isListCard
+    ),
     requiredRole
   );
 };

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 {
@@ -67,14 +67,23 @@ export function createCrudFunctions(
       schemas.create,
       access.create
     );
-    functions[`${prefix}get_${col}`] = getEntity(col, schemas.get, access.read);
+    functions[`${prefix}get_${col}`] = getEntity(
+      col,
+      schemas.get,
+      access.read,
+      undefined,
+      entity.ownership
+    );
     // Use schemas.get for visibility filtering, entity.listFields for field selection
+    // When ownership is set: list = "mine" filter, listCard = public condition
     functions[`${prefix}list_${col}`] = listEntities(
       col,
       schemas.get,
       access.read,
       undefined,
-      entity.listFields
+      entity.listFields,
+      entity.ownership,
+      false
     );
     // Always create listCard - uses same schemas.get, field selection via listCardFields ?? listFields ?? undefined
     functions[`${prefix}listCard_${col}`] = listEntities(
@@ -82,7 +91,9 @@ export function createCrudFunctions(
       schemas.get,
       access.read,
       undefined,
-      entity.listCardFields ?? entity.listFields ?? undefined
+      getListCardFieldNames(entity),
+      entity.ownership,
+      true
     );
     functions[`${prefix}update_${col}`] = updateEntity(
       col,

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');
+    }
+  });
+});