hazo_auth 6.0.0 → 7.0.1

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

@@ -36,6 +36,18 @@ export type OAuthLoginResult = {
   error?: string;
 };
 
+export type FacebookOAuthData = {
+  /** Facebook's unique user ID */
+  facebook_id: string;
+  /** User's email address from Facebook (may be null if user denied email permission) */
+  email: string | null;
+  /** User's full name from Facebook profile */
+  name?: string;
+  /** User's profile picture URL from Facebook */
+  profile_picture_url?: string;
+  // NOTE: no email_verified — we never trust Facebook's email_verified claim
+};
+
 export type LinkGoogleResult = {
   success: boolean;
   error?: string;
@@ -241,6 +253,191 @@ export async function handle_google_oauth_login(
   }
 }
 
+/**
+ * Handles Facebook OAuth login/registration flow
+ * 1. Check if user exists with facebook_id -> login
+ * 2. Check if user exists with email -> link Facebook account (respects auto_link_unverified)
+ * 3. Create new user with Facebook data (email_verified always false — never trust Facebook)
+ *
+ * @param adapter - The hazo_connect adapter instance
+ * @param data - Facebook OAuth user data
+ * @param opts - Options (auto_link_unverified: whether to link unverified accounts)
+ * @returns OAuth login result with user_id and status flags
+ */
+export async function handle_facebook_oauth_login(
+  adapter: HazoConnectAdapter,
+  data: FacebookOAuthData,
+  opts?: { auto_link_unverified?: boolean }
+): Promise<OAuthLoginResult> {
+  const logger = create_app_logger();
+
+  try {
+    const { facebook_id, email, name, profile_picture_url } = data;
+
+    const users_service = createCrudService(adapter, "hazo_users");
+    const now = new Date().toISOString();
+
+    // Step 1: Check if user exists with this facebook_id
+    const users_by_facebook_id = await users_service.findBy({ facebook_id });
+
+    if (Array.isArray(users_by_facebook_id) && users_by_facebook_id.length > 0) {
+      const user = users_by_facebook_id[0];
+
+      await users_service.updateById(user.id, {
+        last_logon: now,
+        changed_at: now,
+      });
+
+      logger.info("oauth_service_facebook_login_existing_facebook_user", {
+        filename: "oauth_service.ts",
+        line_number: get_line_number(),
+        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: Check if user exists with this email
+    if (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) {
+          if (!opts?.auto_link_unverified) {
+            return {
+              success: false,
+              error: "link_blocked_unverified",
+            };
+          }
+          // auto_link_unverified=true: link but do NOT change email_verified status
+        }
+
+        // Link Facebook account to existing user
+        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,
+        };
+
+        // Update name if not set and Facebook provides one
+        if (!user.name && name) {
+          update_data.name = name;
+        }
+
+        // Update profile picture if not set and Facebook provides one
+        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",
+          line_number: get_line_number(),
+          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: (update_data.name as string) || (user.name as string | undefined),
+        };
+      }
+    }
+
+    // Step 3: Create new user with Facebook data
+    const user_id = randomUUID();
+
+    const insert_data: Record<string, unknown> = {
+      id: user_id,
+      email_address: email,
+      password_hash: "", // Empty string for Facebook-only users
+      email_verified: false, // Never trust Facebook's email_verified claim
+      status: "ACTIVE",
+      login_attempts: 0,
+      facebook_id,
+      auth_providers: "facebook",
+      created_at: now,
+      changed_at: now,
+      last_logon: 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_users = await users_service.insert(insert_data);
+
+    if (!Array.isArray(inserted_users) || inserted_users.length === 0) {
+      return {
+        success: false,
+        error: "Failed to create user account",
+      };
+    }
+
+    logger.info("oauth_service_facebook_new_user_created", {
+      filename: "oauth_service.ts",
+      line_number: get_line_number(),
+      user_id,
+      email,
+    });
+
+    return {
+      success: true,
+      user_id,
+      is_new_user: true,
+      was_linked: false,
+      email: email ?? undefined,
+      name,
+    };
+  } catch (error) {
+    const user_friendly_error = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "oauth_service.ts",
+        line_number: get_line_number(),
+        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

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

@@ -0,0 +1,295 @@
+import "server-only";
+import crypto from "node:crypto";
+import argon2 from "argon2";
+import { createCrudService } from "hazo_connect/server";
+import { get_otp_config, hazo_auth_otp_session_ttl_seconds } from "../otp_config.server.js";
+import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
+import { send_template_email } from "./email_service.js";
+import { create_app_logger } from "../app_logger.js";
+import { create_session_token } from "./session_token_service.js";
+
+/**
+ * Generates a cryptographically random 6-digit numeric OTP code (000000–999999).
+ * Uses crypto.randomInt for uniform distribution.
+ */
+export function generate_otp_code(): string {
+  const n = crypto.randomInt(0, 1_000_000);
+  return String(n).padStart(6, "0");
+}
+
+export async function hash_otp_code(code: string): Promise<string> {
+  return argon2.hash(code);
+}
+
+export async function verify_otp_code(otp_hash: string, code: string): Promise<boolean> {
+  try {
+    return await argon2.verify(otp_hash, code);
+  } catch {
+    return false;
+  }
+}
+
+// section: types
+
+export type RequestEmailOTPResult =
+  | { ok: true }
+  | { ok: false; error: "rate_limited"; retry_after_seconds: number };
+
+// section: request_email_otp
+
+/**
+ * Initiates an OTP sign-in flow for the given email address.
+ *
+ * Behaviour:
+ * 1. Per-email rate limit — rejects if too many requests in the sliding window.
+ * 2. Per-IP rate limit — rejects if too many requests from this IP.
+ * 3. Unknown email + auto_register=false — silent no-op (constant-time padding).
+ * 4. Unknown email + auto_register=true — inserts OTP row with user_id=null, dispatches email.
+ * 5. Known email — marks prior unconsumed rows consumed, inserts fresh OTP row, dispatches email.
+ *
+ * Never reveals whether an email address is registered (always returns ok:true on success).
+ */
+export async function request_email_otp(args: {
+  email: string;
+  ip: string;
+}): Promise<RequestEmailOTPResult> {
+  const logger = create_app_logger();
+  const cfg = get_otp_config();
+  const email = args.email.trim().toLowerCase();
+  const ip = args.ip;
+
+  const adapter = get_hazo_connect_instance();
+  const otp_table = createCrudService(adapter, "hazo_email_otps");
+  const users_table = createCrudService(adapter, "hazo_users");
+
+  // 1. Per-email rate limit
+  const email_window_ms = cfg.email_rate_limit_window_seconds * 1000;
+  const email_threshold = new Date(Date.now() - email_window_ms).toISOString();
+  const recent_for_email = await otp_table.list((qb) =>
+    qb
+      .select(["created_at"])
+      .where("email", "eq", email)
+      .where("created_at", "gte", email_threshold)
+  );
+  if (recent_for_email.length >= cfg.email_rate_limit_max) {
+    const oldest = recent_for_email
+      .map((r) => Date.parse(String(r.created_at)))
+      .sort((a, b) => a - b)[0];
+    const retry_after_seconds = Math.max(
+      1,
+      Math.ceil((oldest + email_window_ms - Date.now()) / 1000),
+    );
+    logger.warn("otp_request_email_rate_limited", { email, ip, retry_after_seconds });
+    return { ok: false, error: "rate_limited", retry_after_seconds };
+  }
+
+  // 2. Per-IP rate limit
+  const ip_window_ms = cfg.ip_rate_limit_window_seconds * 1000;
+  const ip_threshold = new Date(Date.now() - ip_window_ms).toISOString();
+  const recent_for_ip = await otp_table.list((qb) =>
+    qb
+      .select(["created_at"])
+      .where("requester_ip", "eq", ip)
+      .where("created_at", "gte", ip_threshold)
+  );
+  if (recent_for_ip.length >= cfg.ip_rate_limit_max) {
+    const oldest = recent_for_ip
+      .map((r) => Date.parse(String(r.created_at)))
+      .sort((a, b) => a - b)[0];
+    const retry_after_seconds = Math.max(
+      1,
+      Math.ceil((oldest + ip_window_ms - Date.now()) / 1000),
+    );
+    logger.warn("otp_request_ip_rate_limited", { email, ip, retry_after_seconds });
+    return { ok: false, error: "rate_limited", retry_after_seconds };
+  }
+
+  // 3. Lookup user
+  const existing_users = await users_table.findBy({ email_address: email });
+  const existing_user = existing_users.length > 0 ? existing_users[0] : null;
+
+  // 4. Unknown email + auto_register=false → silent no-op with constant-time padding
+  if (!existing_user && !cfg.auto_register) {
+    await argon2.hash("000000"); // constant-time padding — never stored
+    return { ok: true };
+  }
+
+  // 5. Mark any unconsumed rows for this email as superseded
+  try {
+    const unconsumed = await otp_table.list((qb) =>
+      qb
+        .select(["id"])
+        .where("email", "eq", email)
+        .where("consumed_at", "is", null)
+    );
+    for (const row of unconsumed) {
+      await otp_table.updateById(String(row.id), { consumed_at: new Date().toISOString() });
+    }
+  } catch {
+    // IS NULL filter may not be supported in all adapter versions — not critical
+  }
+
+  // 6. Generate code + hash + insert row
+  const code = generate_otp_code();
+  const otp_hash = await hash_otp_code(code);
+  const expires_at = new Date(Date.now() + cfg.code_ttl_seconds * 1000).toISOString();
+  const row_id = crypto.randomUUID();
+
+  await otp_table.insert({
+    id: row_id,
+    user_id: existing_user ? String(existing_user.id) : null,
+    email,
+    otp_hash,
+    expires_at,
+    attempt_count: 0,
+    requester_ip: ip,
+  });
+
+  // 7. Dispatch email — fire-and-forget; errors are logged but do not surface to caller
+  try {
+    await send_template_email("otp_signin_code", email, {
+      otp_code: code,
+      expires_in_minutes: String(Math.round(cfg.code_ttl_seconds / 60)),
+    });
+  } catch (err) {
+    logger.error("otp_request_email_dispatch_failed", {
+      email,
+      ip,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    // Return ok:true to preserve no-enumeration property — caller cannot distinguish
+    // a missing user from a delivery failure.
+  }
+
+  return { ok: true };
+}
+
+// section: verify_email_otp
+
+export type VerifyEmailOTPResult =
+  | { ok: true; user_id: string; email: string; session_token: string }
+  | { ok: false; error: "invalid_or_expired" };
+
+export async function verify_email_otp(args: {
+  email: string;
+  code: string;
+  ip: string;
+}): Promise<VerifyEmailOTPResult> {
+  const logger = create_app_logger();
+  const cfg = get_otp_config();
+  const email = args.email.trim().toLowerCase();
+  const code = args.code.trim();
+
+  const adapter = get_hazo_connect_instance();
+  const otp_table = createCrudService(adapter, "hazo_email_otps");
+  const users_table = createCrudService(adapter, "hazo_users");
+  const user_scopes_table = createCrudService(adapter, "hazo_user_scopes");
+  const roles_table = createCrudService(adapter, "hazo_roles");
+
+  // 1. Find most-recent unconsumed row for this email
+  const now_iso = new Date().toISOString();
+  const candidates = await otp_table.list((qb) =>
+    qb
+      .select(["id", "user_id", "otp_hash", "expires_at", "attempt_count"])
+      .where("email", "eq", email)
+      .where("consumed_at", "is", null)
+      .order("created_at", "desc")
+      .limit(1)
+  );
+  const row = candidates.length > 0 ? candidates[0] : null;
+
+  if (!row) {
+    return { ok: false, error: "invalid_or_expired" };
+  }
+
+  // 2. Check expiry
+  const expires_at_ms = Date.parse(String(row.expires_at));
+  if (Number.isNaN(expires_at_ms) || expires_at_ms < Date.now()) {
+    return { ok: false, error: "invalid_or_expired" };
+  }
+
+  // 3. argon2 verify
+  const is_valid = await verify_otp_code(String(row.otp_hash), code);
+  if (!is_valid) {
+    const new_attempt_count = Number(row.attempt_count) + 1;
+    const updates: Record<string, unknown> = { attempt_count: new_attempt_count };
+    if (new_attempt_count >= cfg.max_verify_attempts) {
+      updates.consumed_at = now_iso; // poison
+    }
+    await otp_table.updateById(String(row.id), updates);
+    logger.info("otp_verify_invalid_code", {
+      email,
+      attempt_count: new_attempt_count,
+      poisoned: new_attempt_count >= cfg.max_verify_attempts,
+    });
+    return { ok: false, error: "invalid_or_expired" };
+  }
+
+  // 4. Mark consumed
+  await otp_table.updateById(String(row.id), { consumed_at: now_iso });
+
+  // 5. Resolve / create user
+  let user_id: string | null = row.user_id ? String(row.user_id) : null;
+
+  if (user_id) {
+    // Ensure email_verified=true
+    const user = await users_table.findById(user_id);
+    if (user && !user.email_verified) {
+      await users_table.updateById(user_id, { email_verified: true });
+    }
+  } else if (cfg.auto_register) {
+    // Create user + bind scope/role
+    const new_user_id = crypto.randomUUID();
+    await users_table.insert({
+      id: new_user_id,
+      email_address: email,
+      email_verified: true,
+      password_hash: null,
+      name: null,
+    });
+
+    // Resolve role_id from name — try scope-specific first, then any
+    const scoped_roles = await roles_table.findBy({
+      name: cfg.auto_assign_role_name,
+      scope_id: cfg.auto_assign_scope_id,
+    });
+    let role_id: string | null = null;
+    if (scoped_roles.length > 0) {
+      role_id = String(scoped_roles[0].id);
+    } else {
+      const any_roles = await roles_table.findBy({ name: cfg.auto_assign_role_name });
+      if (any_roles.length > 0) {
+        role_id = String(any_roles[0].id);
+      }
+    }
+
+    if (!role_id) {
+      logger.error("otp_verify_auto_register_role_not_found", {
+        email,
+        scope_id: cfg.auto_assign_scope_id,
+        role_name: cfg.auto_assign_role_name,
+      });
+      return { ok: false, error: "invalid_or_expired" };
+    }
+
+    await user_scopes_table.insert({
+      user_id: new_user_id,
+      scope_id: cfg.auto_assign_scope_id,
+      root_scope_id: cfg.auto_assign_scope_id,
+      role_id,
+    });
+
+    user_id = new_user_id;
+  } else {
+    // Row exists but no user and auto_register=false — stale edge case
+    logger.warn("otp_verify_no_user_resolvable", { email });
+    return { ok: false, error: "invalid_or_expired" };
+  }
+
+  // 6. Issue session JWT with OTP TTL
+  const ttl_seconds = hazo_auth_otp_session_ttl_seconds();
+  const session_token = await create_session_token(user_id, email, undefined, ttl_seconds);
+
+  logger.info("otp_verify_ok", { email, user_id, ttl_seconds });
+  return { ok: true, user_id, email, session_token };
+}

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

@@ -63,19 +63,22 @@ function get_session_token_expiry_seconds(): number {
  * Token includes user_id, email, issued at time, and expiration
  * @param user_id - User ID
  * @param email - User email address
+ * @param managed_by_user_id - Optional: ID of the managing user (for impersonation)
+ * @param ttl_seconds - Optional: token lifetime in seconds (default: 30 days). Use 604800 for 7-day OTP sessions.
  * @returns JWT token string
  */
 export async function create_session_token(
   user_id: string,
   email: string,
   managed_by_user_id?: string,
+  ttl_seconds?: number,
 ): Promise<string> {
   const logger = create_app_logger();
 
   try {
     const secret = get_jwt_secret();
     const now = Math.floor(Date.now() / 1000); // Current time in seconds
-    const expiry_seconds = get_session_token_expiry_seconds();
+    const expiry_seconds = ttl_seconds ?? get_session_token_expiry_seconds();
     const exp = now + expiry_seconds;
 
     const payload: Record<string, unknown> = { user_id, email };

package/config/hazo_auth_config.example.ini

@@ -74,11 +74,9 @@ enable_admin_ui = true
 # image_alt = Illustration of a globe representing secure authentication workflows
 # image_background_color = #e2e8f0
 
-# Labels
-# heading = Create your hazo account
-# sub_heading = Secure your access with editable fields powered by shadcn components.
-# submit_button = Register
-# cancel_button = Cancel
+; Page text is no longer configured via INI.
+; Use HazoAuthStringsProvider or per-page props instead.
+; See MIGRATION.md for details.
 
 # Field labels (defaults shown, uncomment to override)
 # name_label = Full name
@@ -129,11 +127,9 @@ enable_admin_ui = true
 # image_alt = Illustration of a globe representing secure authentication workflows
 # image_background_color = #e2e8f0
 
-# Labels
-# heading = Sign in to your account
-# sub_heading = Enter your credentials to access your secure workspace.
-# submit_button = Login
-# cancel_button = Cancel
+; Page text is no longer configured via INI.
+; Use HazoAuthStringsProvider or per-page props instead.
+; See MIGRATION.md for details.
 
 # Field labels (defaults shown, uncomment to override)
 # email_label = Email address
@@ -159,17 +155,20 @@ enable_admin_ui = true
 # Success message (shown when no redirect route is provided)
 # success_message = Successfully logged in
 
+; OTP sign-in link in the login layout.
+otp_signin_enabled = false
+otp_signin_label = Sign in with email code
+otp_signin_href = /hazo_auth/otp
+
 [hazo_auth__forgot_password_layout]
 # Image configuration
 # image_src = /globe.svg
 # image_alt = Illustration of a globe representing secure authentication workflows
 # image_background_color = #e2e8f0
 
-# Labels
-# heading = Forgot your password?
-# sub_heading = Enter your email address and we'll send you a link to reset your password.
-# submit_button = Send reset link
-# cancel_button = Cancel
+; Page text is no longer configured via INI.
+; Use HazoAuthStringsProvider or per-page props instead.
+; See MIGRATION.md for details.
 
 [hazo_auth__reset_password_layout]
 # Image configuration
@@ -177,11 +176,9 @@ enable_admin_ui = true
 # image_alt = Illustration of a globe representing secure authentication workflows
 # image_background_color = #e2e8f0
 
-# Labels
-# heading = Reset your password
-# sub_heading = Enter your new password below.
-# submit_button = Reset password
-# cancel_button = Cancel
+; Page text is no longer configured via INI.
+; Use HazoAuthStringsProvider or per-page props instead.
+; See MIGRATION.md for details.
 
 # Field labels (defaults shown, uncomment to override)
 # password_label = New password
@@ -213,22 +210,9 @@ enable_admin_ui = true
 # image_alt = Illustration of a globe representing secure authentication workflows
 # image_background_color = #e2e8f0
 
-# Labels (verifying state)
-# heading = Email verification
-# sub_heading = Verifying your email address...
-# submit_button = Resend verification email
-# cancel_button = Cancel
-
-# Success labels
-# success_heading = Email verified successfully
-# success_message = Your email address has been verified. You can now log in to your account.
-# success_redirect_message = Redirecting to login page in
-# success_go_to_login_button = Go to login
-
-# Error labels
-# error_heading = Verification failed
-# error_message = The verification link is invalid or has expired.
-# error_resend_form_heading = Resend verification email
+; Page text is no longer configured via INI.
+; Use HazoAuthStringsProvider or per-page props instead.
+; See MIGRATION.md for details.
 
 # Field labels (defaults shown, uncomment to override)
 # email_label = Email address
@@ -270,11 +254,9 @@ enable_admin_ui = true
 # - [hazo_auth__password_requirements] for password validation rules
 # - [hazo_auth__profile_picture] for profile picture settings and prioritization
 
-# Heading
-# heading = Account Settings
-
-# Sub heading
-# sub_heading = Manage your profile, password, and email preferences.
+; Page heading text is no longer configured via INI.
+; Use HazoAuthStringsProvider or the title prop on MySettingsPage instead.
+; See MIGRATION.md for details.
 
 # Profile Photo section
 # profile_photo_label = Profile Photo
@@ -597,6 +579,26 @@ application_permission_list_defaults = admin_user_management,admin_role_manageme
 # Redirect when skip_invitation_check=true and user has no scope
 # no_scope_redirect = /
 
+[hazo_auth__create_firm]
+; heading, sub_heading, and submit_button_label are no longer configured via INI in v7.0.0.
+; Use HazoAuthStringsProvider or the title/subtitle/ctaText props on CreateFirmPage instead.
+; See MIGRATION.md for details.
+
+; Firm name field label
+# firm_name_label = Firm Name
+
+; Organisation structure field label
+# org_structure_label = Organisation Structure
+
+; Default organisation structure value
+# org_structure_default = Headquarters
+
+; Success message shown after firm creation
+# success_message = Your firm has been created successfully!
+
+; Route to redirect to after firm creation
+# redirect_route = /
+
 [hazo_auth__multi_tenancy]
 # Multi-tenancy configuration for organization hierarchy
 # Enables hierarchical organization structures for company-wide access control
@@ -729,3 +731,36 @@ company_name = My Company
 #   [hazo_auth__login_layout]
 #   image_src = /your-custom-image.jpg
 
+[hazo_auth__otp]
+; Email-OTP sign-in configuration (v6.1.0+).
+;
+; Whether /otp/verify may create new hazo_users rows for unknown emails.
+;   false (default): /otp/request silently no-ops for unknown emails.
+;   true:            /otp/verify creates a user row on first successful code match.
+otp_auto_register = false
+
+; OTP code lifetime in seconds (default 600 = 10 minutes).
+otp_code_ttl_seconds = 600
+
+; OTP session lifetime in seconds (default 604800 = 7 days).
+otp_session_ttl_seconds = 604800
+
+; Sliding-session threshold: if a /me call lands and the JWT exp is within
+; this many seconds, re-issue the session for another otp_session_ttl_seconds.
+otp_slide_when_within_seconds = 86400
+
+; Per-email rate limit for /otp/request.
+otp_email_rate_limit_max = 3
+otp_email_rate_limit_window_seconds = 900
+
+; Per-IP rate limit for /otp/request.
+otp_ip_rate_limit_max = 20
+otp_ip_rate_limit_window_seconds = 3600
+
+; Wrong-guess limit per code; row is poisoned after this many failures.
+otp_max_verify_attempts = 5
+
+; Scope binding for newly auto-registered users (only used when otp_auto_register=true).
+otp_auto_assign_scope_id = 00000000-0000-0000-0000-000000000001
+otp_auto_assign_role_name = member
+