@donotdev/functions 0.0.6 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donotdev/functions",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "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",
@@ -42,8 +42,8 @@
     "serve": "firebase emulators:start --only functions"
   },
   "dependencies": {
-    "@donotdev/core": "^0.0.13",
-    "@donotdev/firebase": "^0.0.5"
+    "@donotdev/core": "^0.0.14",
+    "@donotdev/firebase": "^0.0.6"
   },
   "peerDependencies": {
     "@sentry/node": "^10.33.0",

package/src/firebase/auth/getCustomClaims.ts

@@ -9,9 +9,10 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import * as v from 'valibot';
 
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+
 import { createBaseFunction } from '../baseFunction.js';
 import { AUTH_CONFIG } from '../config/constants.js';
 

package/src/firebase/auth/getUserAuthStatus.ts

@@ -9,9 +9,10 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import * as v from 'valibot';
 
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+
 import { createBaseFunction } from '../baseFunction.js';
 import { AUTH_CONFIG } from '../config/constants.js';
 

package/src/firebase/auth/removeCustomClaims.ts

@@ -9,9 +9,10 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import * as v from 'valibot';
 
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+
 import { createBaseFunction } from '../baseFunction.js';
 import { AUTH_CONFIG } from '../config/constants.js';
 

package/src/firebase/auth/setCustomClaims.ts

@@ -9,11 +9,13 @@
  * @author AMBROISE PARK Consulting
  */
 
+import * as v from 'valibot';
+
 import {
   getFirebaseAdminAuth,
   getFirebaseAdminFirestore,
 } from '@donotdev/firebase/server';
-import * as v from 'valibot';
+
 import { createBaseFunction } from '../baseFunction.js';
 import { AUTH_CONFIG } from '../config/constants.js';
 

package/src/firebase/baseFunction.ts

@@ -4,28 +4,90 @@
  * @fileoverview Base Firebase function that handles all common concerns
  * @description Rate limiting, monitoring, authentication, validation - all in one place
  *
- * @version 0.0.1
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 
 import { logger } from 'firebase-functions/v2';
-import { onCall, type CallableRequest } from 'firebase-functions/v2/https';
+import { onCall } from 'firebase-functions/v2/https';
 import * as v from 'valibot';
 
+import { hasRoleAccess } from '@donotdev/core/server';
+import type { UserRole } from '@donotdev/core/server';
+
 import { handleError } from '../shared/errorHandling.js';
-import { recordPaymentMetrics } from '../shared/utils/internal/monitoring.js';
-import {
-  checkRateLimitWithFirestore,
-  DEFAULT_RATE_LIMITS,
-} from '../shared/utils/internal/rateLimiter.js';
-import { assertAuthenticated } from '../shared/utils.js';
+import { assertAuthenticated, getUserRole } from '../shared/utils.js';
+
+import type { CallableRequest } from 'firebase-functions/v2/https';
+
+// Optional monitoring imports - only used when enabled
+// Lazy loaded to avoid unnecessary Firestore operations
+let checkRateLimitWithFirestore:
+  | typeof import('../shared/utils/internal/rateLimiter.js').checkRateLimitWithFirestore
+  | null = null;
+let DEFAULT_RATE_LIMITS:
+  | typeof import('../shared/utils/internal/rateLimiter.js').DEFAULT_RATE_LIMITS
+  | null = null;
+let recordPaymentMetrics:
+  | typeof import('../shared/utils/internal/monitoring.js').recordPaymentMetrics
+  | null = null;
+
+async function loadRateLimiter() {
+  if (!checkRateLimitWithFirestore) {
+    const mod = await import('../shared/utils/internal/rateLimiter.js');
+    checkRateLimitWithFirestore = mod.checkRateLimitWithFirestore;
+    DEFAULT_RATE_LIMITS = mod.DEFAULT_RATE_LIMITS;
+  }
+  return { checkRateLimitWithFirestore, DEFAULT_RATE_LIMITS };
+}
+
+async function loadMonitoring() {
+  if (!recordPaymentMetrics) {
+    const mod = await import('../shared/utils/internal/monitoring.js');
+    recordPaymentMetrics = mod.recordPaymentMetrics;
+  }
+  return recordPaymentMetrics;
+}
+
+/**
+ * Extract client IP from Firebase callable request
+ * Handles proxied requests (X-Forwarded-For header)
+ */
+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';
+    }
+  }
+
+  // Fallback to raw IP
+  const rawIp =
+    request.rawRequest.ip || request.rawRequest.socket?.remoteAddress;
+  return rawIp || 'unknown';
+}
 
 /**
  * Base Firebase function that handles all common concerns
  * Users just provide their business logic
  *
- * @version 0.0.1
+ * @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
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -37,9 +99,11 @@ export function createBaseFunction<TRequest, TResponse>(
     data: TRequest,
     context: {
       uid: string;
+      userRole: UserRole;
       request: CallableRequest<TRequest>;
     }
-  ) => Promise<TResponse>
+  ) => Promise<TResponse>,
+  requiredRole: UserRole = 'user'
 ) {
   // Validate schema at function creation time (framework-level robustness)
   if (!schema) {
@@ -110,21 +174,14 @@ export function createBaseFunction<TRequest, TResponse>(
             `Schema is undefined for ${operation} - this indicates a bundling/import issue`
           );
         }
-        if (request.data === undefined || request.data === null) {
-          logger.error(`Request data is missing for ${operation}`, {
-            operation,
-            dataValue: request.data,
-            hasAuth: !!request.auth,
-            userId: request.auth?.uid,
-          });
-          throw new Error(
-            `Request data is required for ${operation} but was ${request.data === null ? 'null' : 'undefined'}`
-          );
-        }
+
+        // Normalize undefined/null to empty object for validation
+        // This allows callable functions with no parameters to work correctly
+        const requestData = request.data ?? {};
 
         let validatedData: TRequest;
         try {
-          validatedData = v.parse(schema, request.data);
+          validatedData = v.parse(schema, requestData);
         } catch (parseError) {
           logger.error(`Schema validation failed for ${operation}`, {
             error:
@@ -136,57 +193,102 @@ export function createBaseFunction<TRequest, TResponse>(
           throw parseError;
         }
 
-        // Verify authentication
-        const uid = assertAuthenticated(request.auth);
-
-        // Rate limiting
-        const rateLimitKey = `${operation}_${uid}`;
-        const rateLimitConfig =
-          (DEFAULT_RATE_LIMITS as any)[operation] ||
-          DEFAULT_RATE_LIMITS.checkout;
-        const rateLimitResult = await checkRateLimitWithFirestore(
-          rateLimitKey,
-          rateLimitConfig
-        );
-
-        if (!rateLimitResult.allowed) {
-          logger.warn(`Rate limit exceeded for ${operation}`, {
-            userId: uid,
-            remaining: rateLimitResult.remaining,
-            resetAt: rateLimitResult.resetAt,
-          });
-          throw new Error(
-            `Rate limit exceeded. Try again in ${rateLimitResult.blockRemainingSeconds} seconds.`
+        // Get user role from auth context
+        const userRole = getUserRole(request.auth);
+        let uid: string;
+
+        // Role-based access control
+        if (requiredRole === 'guest') {
+          // Guest access: no authentication required
+          // Use 'guest' as UID for unauthenticated users
+          uid = request.auth?.uid || 'guest';
+        } else {
+          // Non-guest access: require authentication
+          uid = assertAuthenticated(request.auth);
+
+          // Verify user has required role level
+          if (!hasRoleAccess(userRole, requiredRole)) {
+            logger.warn(`Insufficient role for ${operation}`, {
+              userId: uid,
+              userRole,
+              requiredRole,
+            });
+            throw new Error(
+              `Access denied. Required role: ${requiredRole}, your role: ${userRole}`
+            );
+          }
+        }
+
+        // Rate limiting (only if enabled via ENABLE_RATE_LIMITING env var)
+        if (process.env.ENABLE_RATE_LIMITING === 'true') {
+          const {
+            checkRateLimitWithFirestore: checkLimit,
+            DEFAULT_RATE_LIMITS: limits,
+          } = await loadRateLimiter();
+
+          // Use IP-based key for guest operations, UID-based for authenticated
+          const rateLimitIdentifier =
+            requiredRole === 'guest' && uid === 'guest'
+              ? `ip_${getClientIp(request)}`
+              : `uid_${uid}`;
+          const rateLimitKey = `${operation}_${rateLimitIdentifier}`;
+          const rateLimitConfig = (limits as any)[operation] || limits!.api;
+          const rateLimitResult = await checkLimit!(
+            rateLimitKey,
+            rateLimitConfig
           );
+
+          if (!rateLimitResult.allowed) {
+            logger.warn(`Rate limit exceeded for ${operation}`, {
+              identifier: rateLimitIdentifier,
+              remaining: rateLimitResult.remaining,
+              resetAt: rateLimitResult.resetAt,
+            });
+            throw new Error(
+              `Rate limit exceeded. Try again in ${rateLimitResult.blockRemainingSeconds} seconds.`
+            );
+          }
         }
 
         // Call user's business logic
-        const result = await businessLogic(validatedData, { uid, request });
-
-        // Record metrics
-        await recordPaymentMetrics({
-          operation,
-          userId: uid,
-          status: 'success',
-          timestamp: new Date().toISOString(),
-          metadata: {
-            requestId: request.rawRequest.headers['x-request-id'] || 'unknown',
-          },
+        const result = await businessLogic(validatedData, {
+          uid,
+          userRole,
+          request,
         });
 
+        // Record metrics (only if enabled via ENABLE_METRICS env var)
+        if (process.env.ENABLE_METRICS === 'true') {
+          const recordMetrics = await loadMonitoring();
+          await recordMetrics!({
+            operation,
+            userId: uid,
+            status: 'success',
+            timestamp: new Date().toISOString(),
+            metadata: {
+              requestId:
+                request.rawRequest.headers['x-request-id'] || 'unknown',
+            },
+          });
+        }
+
         return result;
       } catch (error) {
-        // Record error metrics
-        await recordPaymentMetrics({
-          operation,
-          userId: request.auth?.uid || 'anonymous',
-          status: 'failed' as const,
-          timestamp: new Date().toISOString(),
-          metadata: {
-            error: error instanceof Error ? error.message : 'Unknown error',
-            requestId: request.rawRequest.headers['x-request-id'] || 'unknown',
-          },
-        });
+        // Record error metrics (only if enabled)
+        if (process.env.ENABLE_METRICS === 'true') {
+          const recordMetrics = await loadMonitoring();
+          await recordMetrics!({
+            operation,
+            userId: request.auth?.uid || 'anonymous',
+            status: 'failed' as const,
+            timestamp: new Date().toISOString(),
+            metadata: {
+              error: error instanceof Error ? error.message : 'Unknown error',
+              requestId:
+                request.rawRequest.headers['x-request-id'] || 'unknown',
+            },
+          });
+        }
 
         throw handleError(error);
       }

package/src/firebase/billing/cancelSubscription.ts

@@ -9,9 +9,10 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import * as v from 'valibot';
 
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+
 import { cancelUserSubscription } from '../../shared/billing/helpers/subscriptionManagement.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { STRIPE_CONFIG } from '../config/constants.js';

package/src/firebase/billing/changePlan.ts

@@ -9,11 +9,11 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import Stripe from 'stripe';
 import * as v from 'valibot';
 
 import type { StripeBackConfig } from '@donotdev/core/server';
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 
 import { updateUserSubscription } from '../../shared/billing/helpers/updateUserSubscription.js';
 import { handleError } from '../../shared/errorHandling.js';

package/src/firebase/billing/createCheckoutSession.ts

@@ -9,7 +9,6 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import { logger } from 'firebase-functions/v2';
 
 import type {
@@ -18,6 +17,7 @@ import type {
 } from '@donotdev/core/server';
 import { STRIPE_MODES } from '@donotdev/core/server';
 import { CreateCheckoutSessionRequestSchema } from '@donotdev/core/server';
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 
 import { handleError } from '../../shared/errorHandling.js';
 import {
@@ -25,10 +25,10 @@ import {
   validateMetadata,
 } from '../../shared/utils/validation.js';
 import { stripe, validateStripeEnvironment } from '../../shared/utils.js';
+import { initStripe } from '../../shared/utils.js'; // ✅ IMPORT INIT
 import { createBaseFunction } from '../baseFunction.js';
 import { STRIPE_CONFIG } from '../config/constants.js';
 import { stripeSecretKey } from '../config/secrets.js'; // ✅ IMPORT SECRET
-import { initStripe } from '../../shared/utils.js'; // ✅ IMPORT INIT
 
 import type {
   CallableFunction,

package/src/firebase/billing/createCustomerPortal.ts

@@ -9,9 +9,10 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import * as v from 'valibot';
 
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+
 import { handleError } from '../../shared/errorHandling.js';
 import {
   stripe,

package/src/firebase/billing/refreshSubscriptionStatus.ts

@@ -9,11 +9,11 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 import Stripe from 'stripe';
 import * as v from 'valibot';
 
 import type { RefreshSubscriptionRequest } from '@donotdev/core/server';
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
 
 import { stripe, validateStripeEnvironment } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';

package/src/firebase/billing/webhookHandler.ts

@@ -10,7 +10,7 @@
  */
 
 import { logger } from 'firebase-functions/v2';
-import { onRequest, type HttpsFunction } from 'firebase-functions/v2/https';
+import { onRequest } from 'firebase-functions/v2/https';
 
 import type { StripeBackConfig } from '@donotdev/core/server';
 
@@ -25,6 +25,8 @@ import {
 import { STRIPE_CONFIG } from '../config/constants.js';
 import { stripeSecretKey, stripeWebhookSecret } from '../config/secrets.js'; // ✅ IMPORT SECRETS
 
+import type { HttpsFunction } from 'firebase-functions/v2/https';
+
 /**
  * Read raw body from request stream
  */

package/src/firebase/config/constants.ts

@@ -18,13 +18,13 @@ const ENFORCE_APP_CHECK = process.env.ENFORCE_APP_CHECK === 'true';
 /** Base config inherited by all function configs */
 const BASE_CONFIG = {
   region: FIREBASE_REGION,
-  invoker: 'public', // Cloud Run allows HTTP, onCall validates Firebase Auth
   ...(ENFORCE_APP_CHECK && { enforceAppCheck: true }),
 } as const;
 
 /** Default function config */
 export const FUNCTION_CONFIG = {
   ...BASE_CONFIG,
+  invoker: 'public', // Cloud Run allows HTTP, onCall validates Firebase Auth
   memory: '1GiB' as const,
   timeoutSeconds: 60,
   cors: true, // Enable CORS by default for all functions (required for web apps)
@@ -48,9 +48,19 @@ export const AUTH_CONFIG = {
   timeoutSeconds: 20,
 } as const;
 
-/** CRUD functions */
+/** CRUD functions - all use public invoker (security enforced via role-based access in code) */
 export const CRUD_CONFIG = {
   ...BASE_CONFIG,
+  invoker: 'public', // Cloud Run allows HTTP, onCall validates Firebase Auth + role-based access
+  memory: '256MiB' as const,
+  timeoutSeconds: 15,
+  cors: true, // Enable CORS for cross-origin requests (required for web apps)
+} as const;
+
+/** CRUD read functions (get, list) - can be public for guest access */
+export const CRUD_READ_CONFIG = {
+  ...BASE_CONFIG,
+  invoker: 'public', // Cloud Run allows HTTP, onCall validates Firebase Auth
   memory: '256MiB' as const,
   timeoutSeconds: 15,
   cors: true, // Enable CORS for cross-origin requests (required for web apps)

package/src/firebase/crud/aggregate.ts

@@ -10,8 +10,6 @@
  * @author AMBROISE PARK Consulting
  */
 
-import type { CallableRequest } from 'firebase-functions/v2/https';
-
 import * as v from 'valibot';
 
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
@@ -21,6 +19,8 @@ import { DoNotDevError } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
+import type { CallableRequest } from 'firebase-functions/v2/https';
+
 /** Supported aggregation operations */
 export type AggregateOperation = 'count' | 'sum' | 'avg' | 'min' | 'max';
 

package/src/firebase/crud/create.ts

@@ -4,22 +4,23 @@
  * @fileoverview Generic function to create an entity.
  * @description Provides a reusable implementation for creating documents in Firestore with validation.
  *
- * @version 0.0.1
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 
 import * as v from 'valibot';
 
-import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
 import { DEFAULT_STATUS_VALUE } from '@donotdev/core/server';
+import type { UserRole } from '@donotdev/core/server';
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
 
 import {
   prepareForFirestore,
   transformFirestoreData,
 } from '../../shared/index.js';
 import { createMetadata } from '../../shared/index.js';
-import { assertAdmin, validateDocument } from '../../shared/utils.js';
+import { validateDocument } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
@@ -47,12 +48,10 @@ function createEntityLogicFactory(
 ) {
   return async function createEntityLogic(
     data: CreateEntityRequest,
-    context: { uid: string; request: CallableRequest<any> }
+    context: { uid: string; userRole: UserRole; request: CallableRequest<any> }
   ) {
     const { payload, idempotencyKey } = data;
-
-    // Ensure the user is an admin
-    const uid = await assertAdmin(context.uid);
+    const { uid } = context;
 
     // Idempotency check if key provided
     if (idempotencyKey) {
@@ -117,16 +116,14 @@ function createEntityLogicFactory(
  * Generic function to create entities in any Firestore collection
  * @param collection - The Firestore collection name
  * @param documentSchema - The Valibot schema for document validation
+ * @param requiredRole - Minimum role required for this operation
  * @param customSchema - Optional custom request schema
  * @returns Firebase callable function
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
  */
 export const createEntity = (
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  requiredRole: UserRole,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
 ): CallableFunction<CreateEntityRequest, Promise<any>> => {
   const requestSchema =
@@ -140,6 +137,7 @@ export const createEntity = (
     CRUD_CONFIG,
     requestSchema,
     'create_entity',
-    createEntityLogicFactory(collection, documentSchema)
+    createEntityLogicFactory(collection, documentSchema),
+    requiredRole
   );
 };

package/src/firebase/crud/delete.ts

@@ -9,14 +9,12 @@
  * @author AMBROISE PARK Consulting
  */
 
-import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
 import * as v from 'valibot';
 
-import {
-  assertAdmin,
-  DoNotDevError,
-  findReferences,
-} from '../../shared/utils.js';
+import type { UserRole } from '@donotdev/core/server';
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+
+import { DoNotDevError, findReferences } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
@@ -38,13 +36,10 @@ export type DeleteEntityRequest = { id: string };
 function deleteEntityLogicFactory(collection: string) {
   return async function deleteEntityLogic(
     data: DeleteEntityRequest,
-    context: { uid: string; request: CallableRequest<any> }
+    context: { uid: string; userRole: UserRole; request: CallableRequest<any> }
   ) {
     const { id } = data;
 
-    // Ensure the user is an admin
-    await assertAdmin(context.uid);
-
     // Check for references to this document
     const references = await findReferences(collection, id);
 
@@ -68,6 +63,7 @@ function deleteEntityLogicFactory(collection: string) {
 /**
  * Generic function to delete entities from any Firestore collection
  * @param collection - The Firestore collection name
+ * @param requiredRole - Minimum role required for this operation
  * @param customSchema - Optional custom request schema
  * @returns Firebase callable function
  *
@@ -77,6 +73,7 @@ function deleteEntityLogicFactory(collection: string) {
  */
 export const deleteEntity = (
   collection: string,
+  requiredRole: UserRole,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
 ): CallableFunction<DeleteEntityRequest, Promise<{ success: boolean }>> => {
   const requestSchema =
@@ -89,6 +86,7 @@ export const deleteEntity = (
     CRUD_CONFIG,
     requestSchema,
     'delete_entity',
-    deleteEntityLogicFactory(collection)
+    deleteEntityLogicFactory(collection),
+    requiredRole
   );
 };