hazo_auth 6.1.1 → 7.0.2

package/cli-src/lib/auth/hazo_get_tenant_auth.server.ts

@@ -14,7 +14,7 @@ import type {
   TenantAuthOptions,
   TenantAuthResult,
   RequiredTenantAuthResult,
-  SelectedScope,
+  TenantOrganization,
   ScopeDetails,
 } from "./auth_types";
 import {
@@ -62,15 +62,15 @@ export function extract_scope_id_from_request(
 }
 
 /**
- * Builds SelectedScope from scope details and access info.
+ * Builds TenantOrganization from scope details and access info
  * @param scope_details - Full scope details from cache
  * @param is_super_admin - Whether user is accessing as super admin
- * @returns SelectedScope object
+ * @returns TenantOrganization object
  */
-function build_selected_scope(
+function build_tenant_organization(
   scope_details: ScopeDetails,
   is_super_admin: boolean,
-): SelectedScope {
+): TenantOrganization {
   return {
     id: scope_details.id,
     name: scope_details.name,
@@ -96,21 +96,20 @@ function build_selected_scope(
  * Tenant-aware authentication function
  *
  * Extracts tenant/scope context from request headers or cookies,
- * validates access, and returns enriched result including the currently
- * selected scope.
+ * validates access, and returns enriched result with organization info.
  *
  * Header priority: X-Hazo-Scope-Id > Cookie
  *
  * @param request - NextRequest object
  * @param options - TenantAuthOptions for customization
- * @returns TenantAuthResult with user, permissions, selected_scope, and user_scopes
+ * @returns TenantAuthResult with user, permissions, organization, and user_scopes
  *
  * @example
  * ```typescript
  * const auth = await hazo_get_tenant_auth(request);
- * if (auth.authenticated && auth.selected_scope) {
+ * if (auth.authenticated && auth.organization) {
  *   // Access tenant-specific data
- *   const data = await getData(auth.selected_scope.id);
+ *   const data = await getData(auth.organization.id);
  * }
  * ```
  */
@@ -137,8 +136,8 @@ export async function hazo_get_tenant_auth(
       user: null,
       permissions: [],
       permission_ok: false,
-      selected_scope: null,
-      selected_scope_id: null,
+      organization: null,
+      organization_id: null,
       user_scopes: [],
       scope_ok: false,
     };
@@ -156,8 +155,8 @@ export async function hazo_get_tenant_auth(
   // User scopes from cache or empty array
   const user_scopes: ScopeDetails[] = cached?.scopes || [];
 
-  // Build selected_scope info if scope access was successful
-  let selected_scope: SelectedScope | null = null;
+  // Build organization info if scope access was successful
+  let organization: TenantOrganization | null = null;
 
   if (scope_id && auth_result.scope_ok && auth_result.scope_access_via) {
     // Find the scope in user's scopes that matches the access_via scope
@@ -166,7 +165,7 @@ export async function hazo_get_tenant_auth(
     );
 
     if (access_scope) {
-      selected_scope = build_selected_scope(
+      organization = build_tenant_organization(
         access_scope,
         auth_result.scope_access_via.is_super_admin || false,
       );
@@ -175,7 +174,7 @@ export async function hazo_get_tenant_auth(
       const hazoConnect = get_hazo_connect_instance();
       const scope_result = await get_scope_by_id(hazoConnect, scope_id);
       if (scope_result.success && scope_result.scope) {
-        selected_scope = {
+        organization = {
           id: scope_result.scope.id,
           name: scope_result.scope.name,
           slug: null, // Could fetch from scope if slug column exists
@@ -201,8 +200,8 @@ export async function hazo_get_tenant_auth(
     permissions: auth_result.permissions,
     permission_ok: auth_result.permission_ok,
     missing_permissions: auth_result.missing_permissions,
-    selected_scope,
-    selected_scope_id: selected_scope?.id || null,
+    organization,
+    organization_id: organization?.id || null,
     user_scopes,
     scope_ok: auth_result.scope_ok,
     scope_access_via: auth_result.scope_access_via,
@@ -219,15 +218,15 @@ export async function hazo_get_tenant_auth(
  *
  * @param request - NextRequest object
  * @param options - TenantAuthOptions for customization
- * @returns RequiredTenantAuthResult with guaranteed non-null selected_scope
+ * @returns RequiredTenantAuthResult with guaranteed non-null organization
  * @throws AuthenticationRequiredError, TenantRequiredError, TenantAccessDeniedError
  *
  * @example
  * ```typescript
  * try {
  *   const auth = await require_tenant_auth(request);
- *   // auth.selected_scope is guaranteed non-null here
- *   const data = await getData(auth.selected_scope.id);
+ *   // auth.organization is guaranteed non-null here
+ *   const data = await getData(auth.organization.id);
  * } catch (error) {
  *   if (error instanceof HazoAuthError) {
  *     return NextResponse.json(
@@ -258,14 +257,14 @@ export async function require_tenant_auth(
     throw new TenantAccessDeniedError(scope_id, result.user_scopes);
   }
 
-  // Check if scope context is required but missing
-  if (!result.selected_scope) {
+  // Check if organization context is required but missing
+  if (!result.organization) {
     throw new TenantRequiredError(
-      "No tenant scope context provided. Include X-Hazo-Scope-Id header or scope cookie.",
+      "No organization context provided. Include X-Hazo-Scope-Id header or scope cookie.",
       result.user_scopes,
     );
   }
 
-  // Type assertion: at this point we know selected_scope is non-null
+  // Type assertion: at this point we know organization is non-null
   return result as RequiredTenantAuthResult;
 }

package/cli-src/lib/auth/index.ts

@@ -22,7 +22,7 @@ export {
 } from "./hazo_get_tenant_auth.server.js";
 export type {
   ScopeDetails,
-  SelectedScope,
+  TenantOrganization,
   TenantAuthOptions,
   TenantAuthResult,
   RequiredTenantAuthResult,
@@ -50,7 +50,7 @@ export {
 } from "./with_auth.server.js";
 export type {
   AuthenticatedTenantAuth,
-  AuthenticatedTenantAuthWithSelectedScope,
+  AuthenticatedTenantAuthWithOrg,
   WithAuthOptions,
 } from "./with_auth.server";
 

package/cli-src/lib/auth/nextauth_config.ts

@@ -5,6 +5,8 @@ import type { JWT } from "next-auth/jwt";
 // ESM/CJS interop: next-auth providers are CommonJS, handle both export scenarios
 import GoogleProviderImport from "next-auth/providers/google";
 const GoogleProvider = (GoogleProviderImport as any).default || GoogleProviderImport;
+import FacebookProviderImport from "next-auth/providers/facebook";
+const FacebookProvider = (FacebookProviderImport as any).default || FacebookProviderImport;
 import { get_oauth_config } from "../oauth_config.server.js";
 import { handle_google_oauth_login } from "../services/oauth_service.js";
 import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
@@ -67,6 +69,16 @@ export function get_nextauth_config(): AuthOptions {
     }
   }
 
+  // Add Facebook provider if enabled
+  if (oauth_config.enable_facebook_oauth && oauth_config.facebook_app_id) {
+    providers.push(
+      FacebookProvider({
+        clientId: oauth_config.facebook_app_id,
+        clientSecret: oauth_config.facebook_app_secret,
+      })
+    );
+  }
+
   return {
     providers,
     pages: {
@@ -85,7 +97,10 @@ export function get_nextauth_config(): AuthOptions {
 
         // Always redirect to our custom callback after sign-in to set hazo_auth cookies
         // The callbackUrl from signIn() comes through as `url`
-        if (url.includes("/api/hazo_auth/oauth/google/callback")) {
+        if (
+          url.includes("/api/hazo_auth/oauth/google/callback") ||
+          url.includes("/api/hazo_auth/oauth/facebook/callback")
+        ) {
           return url;
         }
 
@@ -98,6 +113,9 @@ export function get_nextauth_config(): AuthOptions {
         }
 
         // Default: redirect to our custom OAuth callback to set cookies
+        if (url.includes("facebook")) {
+          return `${baseUrl}/api/hazo_auth/oauth/facebook/callback`;
+        }
         return `${baseUrl}/api/hazo_auth/oauth/google/callback`;
       },
       /**
@@ -162,6 +180,48 @@ export function get_nextauth_config(): AuthOptions {
             return false;
           }
         }
+
+        if (account?.provider === "facebook" && profile) {
+          try {
+            const fbProfile = profile as NextAuthCallbackProfile;
+            const hazoConnect = get_hazo_connect_instance();
+            const { handle_facebook_oauth_login } = await import("../services/oauth_service");
+
+            logger.info("nextauth_facebook_signin_attempt", {
+              email: user.email,
+              facebook_id: account.providerAccountId,
+            });
+
+            const result = await handle_facebook_oauth_login(hazoConnect, {
+              facebook_id: account.providerAccountId,
+              email: user.email || fbProfile.email || "",
+              name: user.name || fbProfile.name || undefined,
+              profile_picture_url: user.image || undefined,
+              // Facebook's email_verified is not exposed in the profile; default to false
+              // for safety — the user will be auto-verified if email matches a verified hazo user.
+              email_verified: false,
+            });
+
+            if (!result.success) {
+              logger.error("nextauth_facebook_signin_failed", { email: user.email, error: result.error });
+              return false;
+            }
+
+            logger.info("nextauth_facebook_signin_success", {
+              user_id: result.user_id,
+              email: result.email,
+              is_new_user: result.is_new_user,
+              was_linked: result.was_linked,
+            });
+
+            (account as Record<string, unknown>).hazo_user_id = result.user_id;
+            return true;
+          } catch (err) {
+            logger.error("nextauth_facebook_signin_exception", { error: String(err) });
+            return false;
+          }
+        }
+
         return true;
       },
       /**

package/cli-src/lib/auth/with_auth.server.ts

@@ -10,7 +10,7 @@ import {
   PermissionError,
   type TenantAuthOptions,
   type TenantAuthResult,
-  type SelectedScope,
+  type TenantOrganization,
   type HazoAuthUser,
   type ScopeDetails,
   type ScopeAccessInfo,
@@ -27,19 +27,19 @@ export type AuthenticatedTenantAuth = {
   permissions: string[];
   permission_ok: boolean;
   missing_permissions?: string[];
-  selected_scope: SelectedScope | null;
-  selected_scope_id: string | null;
+  organization: TenantOrganization | null;
+  organization_id: string | null;
   user_scopes: ScopeDetails[];
   scope_ok?: boolean;
   scope_access_via?: ScopeAccessInfo;
 };
 
 /**
- * Authenticated branch with guaranteed non-null selected_scope
+ * Authenticated branch with guaranteed non-null organization
  */
-export type AuthenticatedTenantAuthWithSelectedScope = AuthenticatedTenantAuth & {
-  selected_scope: SelectedScope;
-  selected_scope_id: string;
+export type AuthenticatedTenantAuthWithOrg = AuthenticatedTenantAuth & {
+  organization: TenantOrganization;
+  organization_id: string;
 };
 
 /**
@@ -48,8 +48,8 @@ export type AuthenticatedTenantAuthWithSelectedScope = AuthenticatedTenantAuth &
  */
 export type WithAuthOptions = TenantAuthOptions & {
   /**
-   * If true, requires tenant/scope context (403 if missing)
-   * Narrows auth type to AuthenticatedTenantAuthWithSelectedScope
+   * If true, requires organization context (403 if missing)
+   * Narrows auth type to AuthenticatedTenantAuthWithOrg
    */
   require_tenant?: boolean;
 };
@@ -75,7 +75,7 @@ type AuthenticatedHandler<TParams> = (
  */
 type AuthenticatedTenantHandler<TParams> = (
   request: NextRequest,
-  auth: AuthenticatedTenantAuthWithSelectedScope,
+  auth: AuthenticatedTenantAuthWithOrg,
   params: TParams,
 ) => Promise<NextResponse> | NextResponse;
 
@@ -138,7 +138,7 @@ async function resolve_params<TParams>(
  *
  * - Calls `hazo_get_tenant_auth` and returns 401 if not authenticated
  * - Returns 403 if `required_permissions` are specified and not satisfied
- * - Returns 403 if `require_tenant: true` and no tenant/scope context
+ * - Returns 403 if `require_tenant: true` and no organization context
  * - Resolves `await context.params` (Next.js 15 pattern)
  * - Catches HazoAuthError, PermissionError, and unexpected errors
  *
@@ -161,8 +161,8 @@ async function resolve_params<TParams>(
  * // With tenant requirement
  * export const GET = withAuth<{ id: string }>(
  *   async (request, auth, { id }) => {
- *     // auth.selected_scope is guaranteed non-null
- *     const data = await getData(auth.selected_scope.id, id);
+ *     // auth.organization is guaranteed non-null
+ *     const data = await getData(auth.organization.id, id);
  *     return NextResponse.json(data);
  *   },
  *   { require_tenant: true }
@@ -227,10 +227,10 @@ export function withAuth<TParams = Record<string, never>>(
       }
 
       // Check tenant requirement
-      if (options.require_tenant && !auth.selected_scope) {
+      if (options.require_tenant && !auth.organization) {
         return NextResponse.json(
           {
-            error: "Tenant scope context required",
+            error: "Organization context required",
             code: "TENANT_REQUIRED",
           },
           { status: 403 },

package/cli-src/lib/config/default_config.ts

@@ -177,6 +177,14 @@ export const DEFAULT_OAUTH = {
   skip_invitation_check: false,
   /** Redirect when skip_invitation_check=true and user has no scope */
   no_scope_redirect: "/",
+  /** Enable Facebook OAuth login (requires HAZO_AUTH_FACEBOOK_APP_ID and HAZO_AUTH_FACEBOOK_APP_SECRET env vars) */
+  enable_facebook_oauth: false,
+  /** Facebook App ID — set via env var HAZO_AUTH_FACEBOOK_APP_ID or config */
+  facebook_app_id: "",
+  /** Facebook App Secret — set via env var HAZO_AUTH_FACEBOOK_APP_SECRET or config */
+  facebook_app_secret: "",
+  /** Text displayed on the Facebook sign-in button */
+  facebook_button_text: "Continue with Facebook",
 } as const;
 
 // section: navbar

package/cli-src/lib/cookies_config.server.ts

@@ -27,10 +27,10 @@ export const BASE_COOKIE_NAMES = {
   USER_ID: "hazo_auth_user_id",
   USER_EMAIL: "hazo_auth_user_email",
   SESSION: "hazo_auth_session",
-  SESSION_KIND: "hazo_auth_session_kind", // v6.1: marks OTP-issued sessions so /me can apply sliding expiry
   DEV_LOCK: "hazo_auth_dev_lock",
   SCOPE_ID: "hazo_auth_scope_id", // v5.2: Tenant context cookie for multi-tenancy
   ANON_ID: "hazo_auth_anon_id", // v5.2: Stable opaque per-visitor ID for anonymous flows (e.g. hazo_feedback)
+  SESSION_KIND: "hazo_auth_session_kind", // v5.4: Sign-in method identifier (e.g. "otp", "google", "password")
 } as const;
 
 // section: main_function

package/cli-src/lib/login_config.server.ts

@@ -7,10 +7,8 @@ import { get_config_value, get_config_value_allow_empty } from "./config/config_
 import { get_already_logged_in_config } from "./already_logged_in_config.server.js";
 import { get_oauth_config, type OAuthConfig } from "./oauth_config.server.js";
 
-// Default image path - consuming apps should either:
-// 1. Configure their own image_src in hazo_auth_config.ini
-// 2. Copy the default images from node_modules/hazo_auth/public/hazo_auth/images/ to their public folder
-const DEFAULT_LOGIN_IMAGE_PATH = "/hazo_auth/images/login_default.jpg";
+// Assets served via the package's own API route — no manual copy needed.
+const DEFAULT_LOGIN_IMAGE_PATH = "/api/hazo_auth/assets/login_default.jpg";
 
 // section: types
 export type LoginConfig = {
@@ -31,12 +29,6 @@ export type LoginConfig = {
   imageBackgroundColor: string;
   /** OAuth configuration */
   oauth: OAuthConfig;
-  /** Whether the OTP sign-in link is shown below the login form */
-  otpSigninEnabled: boolean;
-  /** Label for the OTP sign-in link */
-  otpSigninLabel: string;
-  /** href for the OTP sign-in link */
-  otpSigninHref: string;
 };
 
 // section: helpers
@@ -100,11 +92,6 @@ export function get_login_config(): LoginConfig {
   // Get OAuth configuration
   const oauth = get_oauth_config();
 
-  // OTP sign-in link
-  const otpSigninEnabled = get_config_value(section, "otp_signin_enabled", "false") === "true";
-  const otpSigninLabel = get_config_value(section, "otp_signin_label", "Sign in with email code");
-  const otpSigninHref = get_config_value(section, "otp_signin_href", "/hazo_auth/otp");
-
   return {
     redirectRoute,
     successMessage,
@@ -122,9 +109,6 @@ export function get_login_config(): LoginConfig {
     imageAlt,
     imageBackgroundColor,
     oauth,
-    otpSigninEnabled,
-    otpSigninLabel,
-    otpSigninHref,
   };
 }
 

package/cli-src/lib/oauth_config.server.ts

@@ -30,6 +30,14 @@ export type OAuthConfig = {
   skip_invitation_check: boolean;
   /** Redirect when skip_invitation_check=true and user has no scope */
   no_scope_redirect: string;
+  /** Enable Facebook OAuth login */
+  enable_facebook_oauth: boolean;
+  /** Facebook App ID (env: HAZO_AUTH_FACEBOOK_APP_ID overrides config) */
+  facebook_app_id: string;
+  /** Facebook App Secret (env: HAZO_AUTH_FACEBOOK_APP_SECRET overrides config) */
+  facebook_app_secret: string;
+  /** Text displayed on the Facebook sign-in button */
+  facebook_button_text: string;
 };
 
 // section: constants
@@ -108,6 +116,26 @@ export function get_oauth_config(): OAuthConfig {
     DEFAULT_OAUTH.no_scope_redirect
   );
 
+  const enable_facebook_oauth = get_config_boolean(
+    SECTION_NAME,
+    "enable_facebook_oauth",
+    false
+  );
+
+  const facebook_app_id =
+    process.env.HAZO_AUTH_FACEBOOK_APP_ID ||
+    get_config_value(SECTION_NAME, "facebook_app_id", "");
+
+  const facebook_app_secret =
+    process.env.HAZO_AUTH_FACEBOOK_APP_SECRET ||
+    get_config_value(SECTION_NAME, "facebook_app_secret", "");
+
+  const facebook_button_text = get_config_value(
+    SECTION_NAME,
+    "facebook_button_text",
+    "Continue with Facebook"
+  );
+
   return {
     enable_google,
     enable_email_password,
@@ -120,6 +148,10 @@ export function get_oauth_config(): OAuthConfig {
     default_redirect,
     skip_invitation_check,
     no_scope_redirect,
+    enable_facebook_oauth,
+    facebook_app_id,
+    facebook_app_secret,
+    facebook_button_text,
   };
 }
 

package/cli-src/lib/register_config.server.ts

@@ -40,6 +40,8 @@ export type RegisterConfig = {
     enable_email_password: boolean;
     google_button_text: string;
     oauth_divider_text: string;
+    enable_facebook_oauth: boolean;
+    facebook_button_text: string;
   };
 };
 
@@ -125,6 +127,8 @@ export function get_register_config(): RegisterConfig {
       enable_email_password: oauthConfig.enable_email_password,
       google_button_text: registerGoogleButtonText,
       oauth_divider_text: oauthConfig.oauth_divider_text,
+      enable_facebook_oauth: oauthConfig.enable_facebook_oauth,
+      facebook_button_text: oauthConfig.facebook_button_text,
     },
   };
 }

package/cli-src/lib/services/email_template_manifest.ts

@@ -101,21 +101,4 @@ export const hazo_auth_template_manifest: SystemTemplateManifest[] = [
       },
     ],
   },
-  {
-    template_name: "otp_signin_code",
-    template_label: "OTP sign-in code",
-    category: SYSTEM_CATEGORY,
-    html: read_template("otp_signin_code", "html"),
-    text: read_template("otp_signin_code", "txt"),
-    variables: [
-      {
-        variable_name: "otp_code",
-        variable_description: "6-digit OTP code for email sign-in (v6.1.0+)",
-      },
-      {
-        variable_name: "expires_in_minutes",
-        variable_description: "Number of minutes until the OTP code expires",
-      },
-    ],
-  },
 ];

package/cli-src/lib/services/index.ts

@@ -20,11 +20,5 @@ export * from "./scope_service.js";
 export * from "./user_scope_service.js";
 export * from "./oauth_service.js";
 export * from "./branding_service.js";
-export {
-  request_email_otp,
-  verify_email_otp,
-  generate_otp_code,
-  hash_otp_code,
-  verify_otp_code,
-} from "./otp_service.js";
-export type { RequestEmailOTPResult, VerifyEmailOTPResult } from "./otp_service";
+
+

package/cli-src/lib/services/oauth_service.ts

@@ -22,6 +22,15 @@ export type GoogleOAuthData = {
   email_verified: boolean;
 };
 
+export type FacebookOAuthData = {
+  facebook_id: string;
+  email: string;
+  name?: string;
+  profile_picture_url?: string;
+  /** Facebook does not always verify emails — only link when hazo user is verified */
+  email_verified: boolean;
+};
+
 export type OAuthLoginResult = {
   success: boolean;
   user_id?: string;
@@ -241,6 +250,140 @@ export async function handle_google_oauth_login(
   }
 }
 
+/**
+ * Handles Facebook OAuth login: find-by-facebook_id → find-by-email+link → create new.
+ * Mirrors handle_google_oauth_login exactly. Uses auto_link_unverified_accounts gate.
+ */
+export async function handle_facebook_oauth_login(
+  adapter: HazoConnectAdapter,
+  data: FacebookOAuthData
+): Promise<OAuthLoginResult> {
+  const logger = create_app_logger();
+
+  try {
+    const { facebook_id, email, name, profile_picture_url, email_verified } = data;
+    const oauth_config = get_oauth_config();
+    const users_service = createCrudService(adapter, "hazo_users");
+    const now = new Date().toISOString();
+
+    // Step 1: existing user with this facebook_id
+    const users_by_fb_id = await users_service.findBy({ facebook_id });
+    if (Array.isArray(users_by_fb_id) && users_by_fb_id.length > 0) {
+      const user = users_by_fb_id[0];
+      await users_service.updateById(user.id, { last_logon: now, changed_at: now });
+      logger.info("oauth_service_facebook_login_existing_fb_user", {
+        filename: "oauth_service.ts",
+        user_id: user.id,
+        email: user.email_address,
+      });
+      return {
+        success: true,
+        user_id: user.id as string,
+        is_new_user: false,
+        was_linked: false,
+        email: user.email_address as string,
+        name: user.name as string | undefined,
+      };
+    }
+
+    // Step 2: existing user with matching email
+    const users_by_email = await users_service.findBy({ email_address: email });
+    if (Array.isArray(users_by_email) && users_by_email.length > 0) {
+      const user = users_by_email[0];
+      const user_email_verified = user.email_verified as boolean;
+
+      if (!user_email_verified && !oauth_config.auto_link_unverified_accounts) {
+        return {
+          success: false,
+          error: "An account with this email exists but is not verified. Please verify your email first.",
+        };
+      }
+
+      const current_auth_providers = (user.auth_providers as string) || "email";
+      const new_auth_providers = current_auth_providers.includes("facebook")
+        ? current_auth_providers
+        : `${current_auth_providers},facebook`;
+
+      const update_data: Record<string, unknown> = {
+        facebook_id,
+        auth_providers: new_auth_providers,
+        last_logon: now,
+        changed_at: now,
+      };
+
+      if (!user_email_verified && email_verified) {
+        update_data.email_verified = true;
+      }
+      if (!user.name && name) update_data.name = name;
+      if (!user.profile_picture_url && profile_picture_url) {
+        update_data.profile_picture_url = profile_picture_url;
+        update_data.profile_source = "custom";
+      }
+
+      await users_service.updateById(user.id, update_data);
+      logger.info("oauth_service_facebook_linked_to_existing", {
+        filename: "oauth_service.ts",
+        user_id: user.id,
+        email,
+        was_unverified: !user_email_verified,
+      });
+      return {
+        success: true,
+        user_id: user.id as string,
+        is_new_user: false,
+        was_linked: true,
+        email: user.email_address as string,
+        name: user.name as string | undefined,
+      };
+    }
+
+    // Step 3: create new user
+    const user_id = randomUUID();
+    const insert_data: Record<string, unknown> = {
+      id: user_id,
+      email_address: email,
+      facebook_id,
+      auth_providers: "facebook",
+      email_verified: email_verified,
+      last_logon: now,
+      created_at: now,
+      changed_at: now,
+    };
+    if (name) insert_data.name = name;
+    if (profile_picture_url) {
+      insert_data.profile_picture_url = profile_picture_url;
+      insert_data.profile_source = "custom";
+    }
+
+    const inserted = await users_service.insert(insert_data);
+    if (!Array.isArray(inserted) || inserted.length === 0) {
+      return { success: false, error: "Failed to create user account" };
+    }
+
+    logger.info("oauth_service_facebook_new_user_created", {
+      filename: "oauth_service.ts",
+      user_id,
+      email,
+    });
+    return {
+      success: true,
+      user_id,
+      is_new_user: true,
+      was_linked: false,
+      email,
+      name,
+    };
+  } catch (error) {
+    const user_friendly_error = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: { filename: "oauth_service.ts", email: data.email, operation: "handle_facebook_oauth_login" },
+    });
+    return { success: false, error: user_friendly_error };
+  }
+}
+
 /**
  * Links a Google account to an existing user
  * @param adapter - The hazo_connect adapter instance