@donotdev/functions 0.0.10 → 0.0.12

package/src/shared/utils.ts

@@ -10,6 +10,7 @@
  */
 
 import Stripe from 'stripe';
+import * as v from 'valibot';
 
 import { DoNotDevError } from '@donotdev/core/server';
 import type { OAuthPartnerId, UserRole } from '@donotdev/core/server';
@@ -19,6 +20,11 @@ import {
   initFirebaseAdmin,
 } from '@donotdev/firebase/server';
 
+import {
+  assertAuthenticated as internalAssertAuthenticated,
+  assertAdmin as internalAssertAdmin,
+} from './utils/internal/auth.js';
+
 // Re-export DoNotDevError for external use
 export { DoNotDevError };
 
@@ -101,17 +107,25 @@ export const stripe = new Proxy({} as Stripe, {
 });
 
 /**
- * Assert that a user is authenticated
+ * Assert that a user is authenticated from a Firebase callable auth context.
  *
- * @version 0.0.1
+ * @deprecated Use `assertAuthenticated` from `shared/utils/internal/auth.js` instead.
+ * This wrapper extracts uid from a Firebase callable auth context and delegates
+ * to the canonical version.
+ *
+ * @param auth - Firebase callable request auth context (object with `.uid`)
+ * @returns The authenticated user's uid
+ *
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 export function assertAuthenticated(auth: any): string {
-  if (!auth || !auth.uid) {
+  const uid = auth?.uid;
+  if (!uid) {
     throw new Error('User must be authenticated');
   }
-  return auth.uid;
+  return internalAssertAuthenticated(uid);
 }
 
 /**
@@ -220,68 +234,91 @@ export function createErrorResponse(error: unknown): {
 }
 
 /**
- * Updates user subscription in Firebase
- * TODO: Implement this function based on your Firebase setup
+ * Updates user subscription in Firebase.
  *
- * @version 0.0.1
+ * **Architecture decision — throwing stubs for billing functions:**
+ * These subscription functions (`updateUserSubscription`, `getUserSubscription`,
+ * `cancelUserSubscription`, `handleSubscriptionCancellation`) are intentional
+ * placeholder implementations. They exist so the framework compiles and
+ * type-checks out of the box, but throw at runtime to surface missing
+ * integration early. Consumer apps replace them with their billing provider
+ * integration (Stripe, Paddle, LemonSqueezy, etc.) via the documented
+ * `shared/billing/helpers/` modules.
+ *
+ * C10: This was a silent no-op stub. It now throws to surface the missing
+ * implementation at startup rather than silently dropping webhook events.
+ * Use `updateUserSubscription` from `shared/billing/helpers/updateUserSubscription.ts`
+ * (which requires an authProvider) instead.
+ *
+ * @deprecated Use shared/billing/helpers/updateUserSubscription.ts
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 export async function updateUserSubscription(
-  firebaseUid: string,
-  subscription: any
+  _firebaseUid: string,
+  _subscription: any
 ): Promise<void> {
-  // TODO: Implement subscription update logic
-  console.log('Updating subscription for user:', firebaseUid, subscription.id);
+  throw new DoNotDevError(
+    'updateUserSubscription stub called — import from shared/billing/helpers/updateUserSubscription.ts and supply an authProvider',
+    'unimplemented'
+  );
 }
 
 /**
- * Gets user subscription from Firebase
- * TODO: Implement this function based on your Firebase setup
+ * Gets user subscription from Firebase.
  *
- * @version 0.0.1
+ * C10: This was a silent no-op stub. Now throws to surface the missing implementation.
+ *
+ * @deprecated Implement directly using Firebase Admin SDK or Stripe API.
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
-export async function getUserSubscription(firebaseUid: string): Promise<any> {
-  // TODO: Implement subscription retrieval logic
-  console.log('Getting subscription for user:', firebaseUid);
-  return null;
+export async function getUserSubscription(_firebaseUid: string): Promise<any> {
+  throw new DoNotDevError(
+    'getUserSubscription stub called — implement using Firebase Admin SDK or Stripe API',
+    'unimplemented'
+  );
 }
 
 /**
- * Cancels user subscription
- * TODO: Implement this function based on your Firebase setup
+ * Cancels user subscription.
  *
- * @version 0.0.1
+ * C10: This was a silent no-op stub. Now throws to surface the missing implementation.
+ *
+ * @deprecated Use cancelUserSubscription from shared/billing/helpers/subscriptionManagement.ts
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 export async function cancelUserSubscription(
-  firebaseUid: string,
-  subscription: any
+  _firebaseUid: string,
+  _subscription: any
 ): Promise<void> {
-  // TODO: Implement subscription cancellation logic
-  console.log('Canceling subscription for user:', firebaseUid, subscription.id);
+  throw new DoNotDevError(
+    'cancelUserSubscription stub called — import from shared/billing/helpers/subscriptionManagement.ts',
+    'unimplemented'
+  );
 }
 
 /**
- * Handles subscription cancellation
- * TODO: Implement this function based on your Firebase setup
+ * Handles subscription cancellation.
  *
- * @version 0.0.1
+ * C10: This was a silent no-op stub. Now throws to surface the missing implementation.
+ *
+ * @deprecated Implement using Stripe webhook events and updateUserSubscription.
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 export async function handleSubscriptionCancellation(
-  firebaseUid: string,
-  subscription: any
+  _firebaseUid: string,
+  _subscription: any
 ): Promise<void> {
-  // TODO: Implement subscription cancellation handling
-  console.log(
-    'Handling subscription cancellation for user:',
-    firebaseUid,
-    subscription.id
+  throw new DoNotDevError(
+    'handleSubscriptionCancellation stub called — handle via Stripe webhook events',
+    'unimplemented'
   );
 }
 
@@ -289,35 +326,15 @@ export async function handleSubscriptionCancellation(
  * Asserts that a user has admin privileges
  * Uses role hierarchy: super > admin > user > guest
  *
- * @version 0.0.2
+ * @deprecated Use `assertAdmin` from `shared/utils/internal/auth.js` instead.
+ * This is a thin wrapper that delegates to the canonical provider-agnostic version.
+ *
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
 export async function assertAdmin(uid: string): Promise<string> {
-  if (!uid) {
-    throw new DoNotDevError('Authentication required', 'unauthenticated');
-  }
-
-  try {
-    const user = await getFirebaseAdminAuth().getUser(uid);
-    const claims = user.customClaims || {};
-
-    // Check role claim first (standard pattern)
-    const role = claims.role;
-    if (role === 'admin' || role === 'super') {
-      return uid;
-    }
-
-    // Fallback: check legacy boolean flags
-    if (claims.isAdmin === true || claims.isSuper === true) {
-      return uid;
-    }
-
-    throw new DoNotDevError('Admin privileges required', 'permission-denied');
-  } catch (error) {
-    if (error instanceof DoNotDevError) throw error;
-    throw new DoNotDevError('Failed to verify admin status', 'internal');
-  }
+  return internalAssertAdmin(uid);
 }
 
 /**
@@ -335,6 +352,54 @@ export function validateDocument(data: any, schema?: any): void {
   if (Array.isArray(data)) {
     throw new Error('Document data cannot be an array');
   }
+
+  // Run Valibot schema validation when a schema is provided
+  if (schema) {
+    try {
+      v.parse(schema, data);
+    } catch (error: any) {
+      if (error?.issues) {
+        const messages = error.issues
+          .map(
+            (issue: v.BaseIssue<unknown>) =>
+              `${issue.path?.map((p: any) => p.key).join('.') || 'root'}: ${issue.message}`
+          )
+          .join('; ');
+        throw new DoNotDevError(
+          `Validation failed: ${messages}`,
+          'invalid-argument',
+          { details: { validationErrors: error.issues } }
+        );
+      }
+      throw error;
+    }
+  }
+}
+
+/**
+ * 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 "_"'
+    );
+  }
 }
 
 /**
@@ -345,9 +410,16 @@ export function validateDocument(data: any, schema?: any): void {
  * @author AMBROISE PARK Consulting
  */
 export async function verifyFirebaseAuthToken(token: string): Promise<string> {
-  // TODO: Implement Firebase token verification
-  // For now, just return a mock uid
-  return 'mock-uid';
+  if (!token) {
+    throw new DoNotDevError('Missing authentication token', 'unauthenticated');
+  }
+
+  try {
+    const decodedToken = await getFirebaseAdminAuth().verifyIdToken(token);
+    return decodedToken.uid;
+  } catch (error) {
+    throw new DoNotDevError('Invalid or expired token', 'unauthenticated');
+  }
 }
 
 /**
@@ -357,7 +429,39 @@ export async function verifyFirebaseAuthToken(token: string): Promise<string> {
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
-export function findReferences(collection: string, docId: string): string[] {
-  // TODO: Implement reference finding logic
-  return [];
+export async function findReferences(
+  collection: string,
+  docId: string,
+  referenceMetadata?: {
+    incoming?: Array<{
+      sourceCollection: string;
+      sourceField: string;
+    }>;
+  }
+): Promise<Array<{ collection: string; field: string; count: number }>> {
+  const references: Array<{ collection: string; field: string; count: number }> = [];
+
+  if (!referenceMetadata?.incoming?.length) {
+    return references;
+  }
+
+  const db = getFirebaseAdminFirestore();
+
+  for (const ref of referenceMetadata.incoming) {
+    const snapshot = await db
+      .collection(ref.sourceCollection)
+      .where(ref.sourceField, '==', docId)
+      .limit(1)
+      .get();
+
+    if (!snapshot.empty) {
+      references.push({
+        collection: ref.sourceCollection,
+        field: ref.sourceField,
+        count: snapshot.size,
+      });
+    }
+  }
+
+  return references;
 }

package/src/supabase/auth/deleteAccount.ts

@@ -0,0 +1,52 @@
+// packages/functions/src/supabase/auth/deleteAccount.ts
+
+/**
+ * @fileoverview Delete Account Supabase Edge Function
+ * @description Deletes the authenticated user's account via Supabase Admin.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { createSupabaseHandler } from '../baseFunction.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const deleteAccountSchema = v.object({});
+
+// =============================================================================
+// Handler
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for account deletion.
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @example
+ * ```typescript
+ * // supabase/functions/delete-account/index.ts
+ * import { createDeleteAccount } from '@donotdev/functions/supabase';
+ * Deno.serve(createDeleteAccount());
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createDeleteAccount() {
+  return createSupabaseHandler(
+    'delete-account',
+    deleteAccountSchema,
+    async (_data, ctx) => {
+      const { error } = await ctx.supabaseAdmin.auth.admin.deleteUser(ctx.uid);
+      if (error) throw error;
+
+      return { success: true };
+    },
+  );
+}

package/src/supabase/auth/getCustomClaims.ts

@@ -0,0 +1,56 @@
+// packages/functions/src/supabase/auth/getCustomClaims.ts
+
+/**
+ * @fileoverview Get Custom Claims Supabase Edge Function
+ * @description Returns the authenticated user's app_metadata (custom claims).
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { createSupabaseHandler } from '../baseFunction.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const getCustomClaimsSchema = v.object({});
+
+// =============================================================================
+// Handler
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for retrieving custom claims (app_metadata).
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @example
+ * ```typescript
+ * // supabase/functions/get-custom-claims/index.ts
+ * import { createGetCustomClaims } from '@donotdev/functions/supabase';
+ * Deno.serve(createGetCustomClaims());
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ */
+export function createGetCustomClaims() {
+  return createSupabaseHandler(
+    'get-custom-claims',
+    getCustomClaimsSchema,
+    async (_data, ctx) => {
+      const { data: { user }, error } =
+        await ctx.supabaseAdmin.auth.admin.getUserById(ctx.uid);
+      if (error || !user) {
+        throw new Error('User not found');
+      }
+
+      return { customClaims: user.app_metadata ?? {} };
+    },
+    'user',
+  );
+}

package/src/supabase/auth/getUserAuthStatus.ts

@@ -0,0 +1,64 @@
+// packages/functions/src/supabase/auth/getUserAuthStatus.ts
+
+/**
+ * @fileoverview Get User Auth Status Supabase Edge Function
+ * @description Returns the authenticated user's profile and custom claims.
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { createSupabaseHandler } from '../baseFunction.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const getUserAuthStatusSchema = v.object({});
+
+// =============================================================================
+// Handler
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for retrieving user auth status.
+ *
+ * Returns uid, email, verification status, custom claims, and ban status.
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @example
+ * ```typescript
+ * // supabase/functions/get-user-auth-status/index.ts
+ * import { createGetUserAuthStatus } from '@donotdev/functions/supabase';
+ * Deno.serve(createGetUserAuthStatus());
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ */
+export function createGetUserAuthStatus() {
+  return createSupabaseHandler(
+    'get-user-auth-status',
+    getUserAuthStatusSchema,
+    async (_data, ctx) => {
+      const { data: { user }, error } =
+        await ctx.supabaseAdmin.auth.admin.getUserById(ctx.uid);
+      if (error || !user) {
+        throw new Error('User not found');
+      }
+
+      return {
+        uid: user.id,
+        email: user.email,
+        emailVerified: user.email_confirmed_at != null,
+        customClaims: user.app_metadata ?? {},
+        disabled: user.banned_until != null,
+      };
+    },
+    'user',
+  );
+}

package/src/supabase/auth/removeCustomClaims.ts

@@ -0,0 +1,75 @@
+// packages/functions/src/supabase/auth/removeCustomClaims.ts
+
+/**
+ * @fileoverview Remove Custom Claims Supabase Edge Function
+ * @description Removes specific keys from the user's app_metadata.
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { createSupabaseHandler } from '../baseFunction.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const removeCustomClaimsSchema = v.object({
+  claimsToRemove: v.pipe(
+    v.array(v.string()),
+    v.minLength(1, 'At least one claim key is required'),
+  ),
+});
+
+// =============================================================================
+// Handler
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for removing custom claims from app_metadata.
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @example
+ * ```typescript
+ * // supabase/functions/remove-custom-claims/index.ts
+ * import { createRemoveCustomClaims } from '@donotdev/functions/supabase';
+ * Deno.serve(createRemoveCustomClaims());
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ */
+export function createRemoveCustomClaims() {
+  return createSupabaseHandler(
+    'remove-custom-claims',
+    removeCustomClaimsSchema,
+    async (data, ctx) => {
+      // Get current app_metadata
+      const { data: { user }, error: getUserError } =
+        await ctx.supabaseAdmin.auth.admin.getUserById(ctx.uid);
+      if (getUserError || !user) {
+        throw new Error('User not found');
+      }
+
+      // Remove specified keys
+      const existingClaims = { ...(user.app_metadata ?? {}) } as Record<string, unknown>;
+      for (const key of data.claimsToRemove) {
+        delete existingClaims[key];
+      }
+
+      // Update app_metadata
+      const { error: updateError } =
+        await ctx.supabaseAdmin.auth.admin.updateUserById(ctx.uid, {
+          app_metadata: existingClaims,
+        });
+      if (updateError) throw updateError;
+
+      return { success: true, customClaims: existingClaims };
+    },
+    'user',
+  );
+}

package/src/supabase/auth/setCustomClaims.ts

@@ -0,0 +1,73 @@
+// packages/functions/src/supabase/auth/setCustomClaims.ts
+
+/**
+ * @fileoverview Set Custom Claims Supabase Edge Function
+ * @description Merges custom claims into the user's app_metadata.
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { createSupabaseHandler } from '../baseFunction.js';
+
+// =============================================================================
+// Schema
+// =============================================================================
+
+const setCustomClaimsSchema = v.object({
+  customClaims: v.record(v.string(), v.unknown()),
+  idempotencyKey: v.optional(v.string()),
+});
+
+// =============================================================================
+// Handler
+// =============================================================================
+
+/**
+ * Create a Supabase Edge Function handler for setting custom claims (app_metadata).
+ *
+ * Merges provided claims into the user's existing app_metadata.
+ *
+ * @returns `(req: Request) => Promise<Response>` handler
+ *
+ * @example
+ * ```typescript
+ * // supabase/functions/set-custom-claims/index.ts
+ * import { createSetCustomClaims } from '@donotdev/functions/supabase';
+ * Deno.serve(createSetCustomClaims());
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.6.0
+ */
+export function createSetCustomClaims() {
+  return createSupabaseHandler(
+    'set-custom-claims',
+    setCustomClaimsSchema,
+    async (data, ctx) => {
+      // Get current app_metadata
+      const { data: { user }, error: getUserError } =
+        await ctx.supabaseAdmin.auth.admin.getUserById(ctx.uid);
+      if (getUserError || !user) {
+        throw new Error('User not found');
+      }
+
+      // Merge new claims with existing app_metadata
+      const existingClaims = (user.app_metadata ?? {}) as Record<string, unknown>;
+      const updatedClaims = { ...existingClaims, ...data.customClaims };
+
+      // Update app_metadata
+      const { error: updateError } =
+        await ctx.supabaseAdmin.auth.admin.updateUserById(ctx.uid, {
+          app_metadata: updatedClaims,
+        });
+      if (updateError) throw updateError;
+
+      return { success: true, customClaims: updatedClaims };
+    },
+    'user',
+  );
+}