hazo_auth 5.2.0 → 5.3.0

package/SETUP_CHECKLIST.md

@@ -2,6 +2,52 @@
 
 This checklist provides step-by-step instructions for setting up the `hazo_auth` package in your Next.js project. AI assistants can follow this guide to ensure complete and correct setup.
 
+## v5.3.0 Migration (from v5.2.x)
+
+If you are already on hazo_auth `5.2.x`, the only mandatory work is wiring up hazo_notify's template manager at boot. Apps that don't use the templated email path (only the plain `send_email`) keep working unchanged after bumping the peer dep.
+
+**1. Bump the peer dep.** Update your app's `package.json`:
+
+```diff
+- "hazo_notify": "^1.1.0",
++ "hazo_notify": "^3.0.0",
+```
+
+Then `npm install`.
+
+**2. Apply the hazo_notify template-manager migration.** hazo_notify 3.0.0 introduces two new tables (`hazo_notify_template_cat`, `hazo_notify_templates`). If you are using SQLite via the existing schema seed, the tables are created on first connect when `initial_sql` is provided to the adapter (see step 4 below). If you are on PostgREST or you manage migrations explicitly, run `migrations/002_template_manager.sql` from hazo_notify.
+
+**3. Register the `notify_templates_admin` permission (optional).** Users with this permission can edit auth email templates via the hazo_notify admin UI. Grant `notify_templates_super_admin` to also allow deleting system templates. These are hazo_notify permissions, declared in your app's permission set; hazo_auth does not grant them itself.
+
+**4. Wire up `init_template_manager` and `set_hazo_notify_connect` at boot.** In your Next.js `instrumentation.ts` (or equivalent), feed hazo_auth's manifest into hazo_notify and register the connect instance with hazo_auth:
+
+```ts
+// instrumentation.ts
+import { init_template_manager } from "hazo_notify/template_manager";
+import { hazo_auth_template_manifest } from "hazo_auth/server-lib";
+import { set_hazo_notify_connect } from "hazo_auth/server-lib"; // re-exported from email_service
+import { build_my_hazo_notify_connect } from "./lib/hazo_notify_connect";
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+
+  const notify_connect = build_my_hazo_notify_connect();
+
+  await init_template_manager({
+    hazo_connect_factory: () => notify_connect,
+    manifests: [...hazo_auth_template_manifest],
+  });
+
+  set_hazo_notify_connect(notify_connect);
+}
+```
+
+`build_my_hazo_notify_connect()` is consuming-app code that wraps your `hazo_connect` adapter into the `HazoConnectInstance` shape hazo_notify expects (`list`/`findById`/`findBy`/`insert`/`updateById`/`deleteById`/`query`). hazo_auth's own test-app ships an example wrapper at `instrumentation_hazo_notify_connect.ts` you can copy.
+
+**5. Migrate any custom templates.** The `[hazo_auth__email] email_template_main_directory` config key is deprecated and no longer overrides anything — a one-time `warn` log will fire on first send if it is set. Move any custom HTML/text into the admin UI as scope-specific (or super-admin-edited global) templates before `hazo_auth@6.0.0` removes the key.
+
+**6. (Optional) Mount the template admin UI.** Use `<TemplateManagerAdmin />` from `hazo_notify/template_manager_admin` to give your admins a UI for managing the auth templates. See hazo_notify's docs for routing and permission-gating.
+
 ## Quick Start (Recommended)
 
 The fastest way to set up hazo_auth:

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

@@ -1,10 +1,9 @@
 // file_description: service for sending emails with template support
 // section: imports
-import fs from "fs";
-import path from "path";
 import { create_app_logger } from "../app_logger.js";
 import { read_config_section } from "../config/config_loader.server.js";
 import type { EmailerConfig, SendEmailOptions } from "hazo_notify";
+import type { HazoConnectInstance } from "hazo_notify/template_manager";
 
 // section: types
 export type EmailOptions = {
@@ -26,16 +25,6 @@ export type EmailTemplateData = {
   [key: string]: string | undefined;
 };
 
-// section: constants
-const DEFAULT_EMAIL_FROM = "noreply@hazo_auth.local";
-
-/**
- * Gets the default email template directory (lazy-evaluated to avoid Edge Runtime issues)
- */
-function get_default_email_template_dir(): string {
-  return path.resolve(process.cwd(), "email_templates");
-}
-
 // section: singleton
 /**
  * Singleton instance for hazo_notify emailer configuration
@@ -43,6 +32,14 @@ function get_default_email_template_dir(): string {
  */
 let hazo_notify_config: EmailerConfig | null = null;
 
+/**
+ * Singleton hazo_notify-compatible hazo_connect instance used by the template
+ * manager. The consuming app builds this once (typically the same instance fed
+ * into `init_template_manager({ hazo_connect_factory })`) and registers it via
+ * {@link set_hazo_notify_connect}. Required for `send_template_email`.
+ */
+let hazo_notify_connect: HazoConnectInstance | null = null;
+
 /**
  * Sets the hazo_notify emailer configuration instance
  * This is called from instrumentation.ts during initialization
@@ -52,6 +49,17 @@ export function set_hazo_notify_instance(config: EmailerConfig): void {
   hazo_notify_config = config;
 }
 
+/**
+ * Registers the hazo_notify-compatible hazo_connect instance used by
+ * `send_template_email`. Call this from `instrumentation.ts` with the same
+ * instance you pass to `init_template_manager({ hazo_connect_factory })`.
+ *
+ * @param instance - hazo_notify-shaped database adapter
+ */
+export function set_hazo_notify_connect(instance: HazoConnectInstance): void {
+  hazo_notify_connect = instance;
+}
+
 /**
  * Gets the hazo_notify emailer configuration instance
  * If not set, loads it from config file as fallback
@@ -84,24 +92,36 @@ async function get_hazo_notify_instance(): Promise<EmailerConfig> {
   return hazo_notify_config;
 }
 
-// section: helpers
+// section: deprecated_config_helpers
 /**
- * Gets email template directory from config
- * @returns Email template directory path
+ * One-time warning state for the deprecated email_template_main_directory key.
  */
-function get_email_template_directory(): string {
+let warned_about_template_dir = false;
+
+/**
+ * Reads the deprecated [hazo_auth__email] email_template_main_directory key
+ * solely to emit a one-time deprecation warning. The value is no longer used —
+ * template overrides now live in hazo_notify's database and are managed via
+ * the template admin UI. The key will be removed in hazo_auth@6.0.0.
+ */
+function warn_if_template_directory_configured(): void {
+  if (warned_about_template_dir) return;
   const email_section = read_config_section("hazo_auth__email");
   const template_dir = email_section?.email_template_main_directory;
-  
-  if (template_dir) {
-    return path.isAbsolute(template_dir)
-      ? template_dir
-      : path.resolve(process.cwd(), template_dir);
-  }
-  
-  return get_default_email_template_dir();
+  if (!template_dir) return;
+  warned_about_template_dir = true;
+  create_app_logger().warn("hazo_auth_email_template_main_directory_deprecated", {
+    filename: "email_service.ts",
+    line_number: 0,
+    note:
+      "Filesystem template overrides are deprecated in hazo_auth@5.3.0. " +
+      "Use the hazo_notify template admin UI (mounted via <TemplateManagerAdmin />) " +
+      "to override the email_verification / forgot_password / password_changed templates per scope. " +
+      "This config key will be removed in hazo_auth@6.0.0.",
+  });
 }
 
+// section: helpers
 /**
  * Gets email from address from config
  * Priority: 1. hazo_auth__email.from_email, 2. hazo_notify_config.from_email
@@ -111,12 +131,12 @@ function get_email_template_directory(): string {
 async function get_email_from(notify_config: EmailerConfig): Promise<string> {
   const email_section = read_config_section("hazo_auth__email");
   const hazo_auth_from_email = email_section?.from_email;
-  
+
   // If set in hazo_auth_config.ini, use it (overrides hazo_notify config)
   if (hazo_auth_from_email) {
     return hazo_auth_from_email;
   }
-  
+
   // Fall back to hazo_notify config
   return notify_config.from_email;
 }
@@ -130,12 +150,12 @@ async function get_email_from(notify_config: EmailerConfig): Promise<string> {
 async function get_email_from_name(notify_config: EmailerConfig): Promise<string> {
   const email_section = read_config_section("hazo_auth__email");
   const hazo_auth_from_name = email_section?.from_name;
-  
+
   // If set in hazo_auth_config.ini, use it (overrides hazo_notify config)
   if (hazo_auth_from_name) {
     return hazo_auth_from_name;
   }
-  
+
   // Fall back to hazo_notify config
   return notify_config.from_name;
 }
@@ -148,11 +168,11 @@ async function get_email_from_name(notify_config: EmailerConfig): Promise<string
 function get_base_url(): string {
   const email_section = read_config_section("hazo_auth__email");
   const base_url = email_section?.base_url;
-  
+
   if (base_url) {
     return base_url.endsWith("/") ? base_url.slice(0, -1) : base_url;
   }
-  
+
   // Try to get from APP_DOMAIN_NAME environment variable (adds protocol if needed)
   const app_domain_name = process.env.APP_DOMAIN_NAME;
   if (app_domain_name) {
@@ -164,13 +184,13 @@ function get_base_url(): string {
     // If no protocol, default to https
     return `https://${domain}`;
   }
-  
+
   // Try to get from other environment variables (fallback)
   const env_base_url = process.env.NEXT_PUBLIC_APP_URL || process.env.APP_URL;
   if (env_base_url) {
     return env_base_url.endsWith("/") ? env_base_url.slice(0, -1) : env_base_url;
   }
-  
+
   // Default to empty string (will use relative URLs)
   return "";
 }
@@ -199,195 +219,6 @@ function get_reset_password_url(token: string): string {
   return url;
 }
 
-/**
- * Gets default HTML template for a given template type
- * @param template_type - Type of email template
- * @param data - Template data for variable substitution
- * @returns Default HTML template content
- */
-function get_default_html_template(
-  template_type: EmailTemplateType,
-  data: EmailTemplateData
-): string {
-  switch (template_type) {
-    case "email_verification":
-      return `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <title>Verify Your Email</title>
-</head>
-<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
-  <h1 style="color: #0f172a;">Verify Your Email Address</h1>
-  <p>Thank you for registering! Please click the link below to verify your email address:</p>
-  <p style="margin: 20px 0;">
-    <a href="${data.verification_url || "#"}" style="display: inline-block; padding: 12px 24px; background-color: #0f172a; color: #ffffff; text-decoration: none; border-radius: 4px;">Verify Email Address</a>
-  </p>
-  <p>Or copy and paste this link into your browser:</p>
-  <p style="word-break: break-all; color: #666;">${data.verification_url || data.token || ""}</p>
-  <p>This link will expire in 48 hours.</p>
-  <p style="margin-top: 30px; color: #666; font-size: 12px;">If you didn't create an account, you can safely ignore this email.</p>
-</body>
-</html>
-      `.trim();
-    
-    case "forgot_password":
-      return `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <title>Reset Your Password</title>
-</head>
-<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
-  <h1 style="color: #0f172a;">Reset Your Password</h1>
-  <p>We received a request to reset your password. Click the link below to reset it:</p>
-  <p style="margin: 20px 0;">
-    <a href="${data.reset_url || "#"}" style="display: inline-block; padding: 12px 24px; background-color: #0f172a; color: #ffffff; text-decoration: none; border-radius: 4px;">Reset Password</a>
-  </p>
-  <p>Or copy and paste this link into your browser:</p>
-  <p style="word-break: break-all; color: #666;">${data.reset_url || data.token || ""}</p>
-  <p>This link will expire in 10 minutes.</p>
-  <p style="margin-top: 30px; color: #666; font-size: 12px;">If you didn't request a password reset, you can safely ignore this email.</p>
-</body>
-</html>
-      `.trim();
-    
-    case "password_changed":
-      return `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <title>Password Changed</title>
-</head>
-<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
-  <h1 style="color: #0f172a;">Password Changed Successfully</h1>
-  <p>Hello${data.user_name ? ` ${data.user_name}` : ""},</p>
-  <p>This email confirms that your password has been changed successfully.</p>
-  <p>If you did not make this change, please contact support immediately to secure your account.</p>
-  <p style="margin-top: 30px; color: #666; font-size: 12px;">This is an automated notification. Please do not reply to this email.</p>
-</body>
-</html>
-      `.trim();
-    
-    default:
-      return "<p>Email content</p>";
-  }
-}
-
-/**
- * Gets default text template for a given template type
- * @param template_type - Type of email template
- * @param data - Template data for variable substitution
- * @returns Default text template content
- */
-function get_default_text_template(
-  template_type: EmailTemplateType,
-  data: EmailTemplateData
-): string {
-  switch (template_type) {
-    case "email_verification":
-      return `
-Verify Your Email Address
-
-Thank you for registering! Please click the link below to verify your email address:
-
-${data.verification_url || data.token || ""}
-
-This link will expire in 48 hours.
-
-If you didn't create an account, you can safely ignore this email.
-      `.trim();
-    
-    case "forgot_password":
-      return `
-Reset Your Password
-
-We received a request to reset your password. Click the link below to reset it:
-
-${data.reset_url || data.token || ""}
-
-This link will expire in 10 minutes.
-
-If you didn't request a password reset, you can safely ignore this email.
-      `.trim();
-    
-    case "password_changed":
-      return `
-Password Changed Successfully
-
-Hello${data.user_name ? ` ${data.user_name}` : ""},
-
-This email confirms that your password has been changed successfully.
-
-If you did not make this change, please contact support immediately to secure your account.
-
-This is an automated notification. Please do not reply to this email.
-      `.trim();
-    
-    default:
-      return "Email content";
-  }
-}
-
-/**
- * Loads email template from file system
- * @param template_type - Type of email template
- * @param extension - File extension (html or txt)
- * @returns Template content or undefined if not found
- */
-function load_template_file(
-  template_type: EmailTemplateType,
-  extension: "html" | "txt"
-): string | undefined {
-  const template_dir = get_email_template_directory();
-  const template_filename = `${template_type}.${extension}`;
-  const template_path = path.join(template_dir, template_filename);
-  
-  if (!fs.existsSync(template_path)) {
-    return undefined;
-  }
-  
-  try {
-    return fs.readFileSync(template_path, "utf-8");
-  } catch (error) {
-    const logger = create_app_logger();
-    logger.error("email_service_template_load_failed", {
-      filename: "email_service.ts",
-      line_number: 0,
-      template_path,
-      error: error instanceof Error ? error.message : "Unknown error",
-    });
-    return undefined;
-  }
-}
-
-/**
- * Simple template variable substitution
- * Replaces {{variable_name}} with values from data object
- * @param template - Template string with variables
- * @param data - Data object for variable substitution
- * @returns Template with variables substituted
- */
-function substitute_template_variables(
-  template: string,
-  data: EmailTemplateData
-): string {
-  let result = template;
-  
-  // Replace {{variable}} with values from data
-  Object.entries(data).forEach(([key, value]) => {
-    if (value !== undefined) {
-      const regex = new RegExp(`{{\\s*${key}\\s*}}`, "g");
-      result = result.replace(regex, value);
-    }
-  });
-  
-  return result;
-}
-
 /**
  * Gets email subject for a given template type
  * @param template_type - Type of email template
@@ -397,13 +228,13 @@ function get_email_subject(template_type: EmailTemplateType): string {
   const email_section = read_config_section("hazo_auth__email");
   const template_config_key = `email_template__${template_type}`;
   const subject_key = `${template_config_key}__subject`;
-  
+
   // Try to get subject from config
   const subject = email_section?.[subject_key];
   if (subject) {
     return subject;
   }
-  
+
   // Default subjects
   switch (template_type) {
     case "email_verification":
@@ -417,33 +248,6 @@ function get_email_subject(template_type: EmailTemplateType): string {
   }
 }
 
-/**
- * Gets email templates (HTML and text) for a given template type
- * Falls back to default templates if custom templates are not found
- * @param template_type - Type of email template
- * @param data - Template data for variable substitution
- * @returns Object with html_body and text_body
- */
-function get_email_templates(
-  template_type: EmailTemplateType,
-  data: EmailTemplateData
-): { html_body: string; text_body: string } {
-  // Try to load custom templates
-  const html_template = load_template_file(template_type, "html");
-  const text_template = load_template_file(template_type, "txt");
-  
-  // Use custom templates if found, otherwise use defaults
-  const html_body = html_template
-    ? substitute_template_variables(html_template, data)
-    : get_default_html_template(template_type, data);
-  
-  const text_body = text_template
-    ? substitute_template_variables(text_template, data)
-    : get_default_text_template(template_type, data);
-  
-  return { html_body, text_body };
-}
-
 /**
  * Sends an email using hazo_notify
  * @param options - Email options (to, from, subject, html_body, text_body)
@@ -451,20 +255,20 @@ function get_email_templates(
  */
 export async function send_email(options: EmailOptions): Promise<{ success: boolean; error?: string }> {
   const logger = create_app_logger();
-  
+
   try {
     // Get hazo_notify configuration instance
     const notify_config = await get_hazo_notify_instance();
-    
+
     // Dynamic import to avoid build-time issues with hazo_notify
     const hazo_notify_module = await import("hazo_notify");
     const { send_email: hazo_notify_send_email } = hazo_notify_module;
-    
+
     // Get from email and from name (hazo_auth_config overrides hazo_notify_config)
     // Priority: 1. options.from (explicit parameter), 2. hazo_auth_config.from_email, 3. hazo_notify_config.from_email
     const from_email = options.from || await get_email_from(notify_config);
     const from_name = await get_email_from_name(notify_config);
-    
+
     // Prepare hazo_notify email options
     const hazo_notify_options: SendEmailOptions = {
       to: options.to,
@@ -477,10 +281,10 @@ export async function send_email(options: EmailOptions): Promise<{ success: bool
       from: from_email,
       from_name: from_name,
     };
-    
+
     // Send email using hazo_notify
     const result = await hazo_notify_send_email(hazo_notify_options, notify_config);
-    
+
     if (result.success) {
       logger.info("email_sent", {
         filename: "email_service.ts",
@@ -490,11 +294,11 @@ export async function send_email(options: EmailOptions): Promise<{ success: bool
         subject: options.subject,
         message_id: result.message_id,
       });
-      
+
       return { success: true };
     } else {
       const error_message = result.error || result.message || "Unknown error";
-      
+
       logger.error("email_send_failed", {
         filename: "email_service.ts",
         line_number: 0,
@@ -504,12 +308,12 @@ export async function send_email(options: EmailOptions): Promise<{ success: bool
         error: error_message,
         raw_response: result.raw_response,
       });
-      
+
       return { success: false, error: error_message };
     }
   } catch (error) {
     const error_message = error instanceof Error ? error.message : "Unknown error";
-    
+
     logger.error("email_send_failed", {
       filename: "email_service.ts",
       line_number: 0,
@@ -518,17 +322,21 @@ export async function send_email(options: EmailOptions): Promise<{ success: bool
       subject: options.subject,
       error: error_message,
     });
-    
+
     return { success: false, error: error_message };
   }
 }
 
 /**
- * Sends an email using a template
- * @param template_type - Type of email template
+ * Sends an email using a template, delegating rendering to hazo_notify's
+ * scope-aware template manager. Templates and per-scope overrides live in
+ * hazo_notify's database; hazo_auth ships the global defaults via
+ * `hazo_auth_template_manifest`.
+ *
+ * @param template_type - System template name (email_verification | forgot_password | password_changed)
  * @param to - Recipient email address
- * @param data - Template data for variable substitution
- * @returns Promise that resolves when email is sent
+ * @param data - Template data; `token` is auto-expanded into verification_url/reset_url
+ * @returns Promise that resolves with success status
  */
 export async function send_template_email(
   template_type: EmailTemplateType,
@@ -536,11 +344,13 @@ export async function send_template_email(
   data: EmailTemplateData
 ): Promise<{ success: boolean; error?: string }> {
   const logger = create_app_logger();
-  
+
+  // Emit a one-time deprecation warning if the old filesystem override key is set.
+  warn_if_template_directory_configured();
+
   try {
-    // Enhance data with URLs if token is provided
+    // URL construction stays here — hazo_notify just renders variables.
     const enhanced_data: EmailTemplateData = { ...data };
-    
     if (data.token) {
       if (template_type === "email_verification") {
         enhanced_data.verification_url = get_verification_url(data.token);
@@ -548,31 +358,69 @@ export async function send_template_email(
         enhanced_data.reset_url = get_reset_password_url(data.token);
       }
     }
-    
-    // Get email templates
-    const { html_body, text_body } = get_email_templates(template_type, enhanced_data);
-    
-    // Get email subject
-    const subject = get_email_subject(template_type);
-    
-    // Get hazo_notify config instance
+
+    // Coerce `string | undefined` data into `Record<string, string>` for Handlebars.
+    const variables: Record<string, string> = {};
+    for (const [key, value] of Object.entries(enhanced_data)) {
+      if (typeof value === "string") {
+        variables[key] = value;
+      }
+    }
+
+    if (!hazo_notify_connect) {
+      throw new Error(
+        "hazo_notify connect not initialized. Call set_hazo_notify_connect() " +
+          "from instrumentation.ts with the same HazoConnectInstance you pass " +
+          "to init_template_manager({ hazo_connect_factory })."
+      );
+    }
+
     const notify_config = await get_hazo_notify_instance();
-    
-    // Get email from address and from name
-    // Priority: 1. hazo_auth_config.from_email/from_name, 2. hazo_notify_config.from_email/from_name
     const from = await get_email_from(notify_config);
-    
-    // Send email (from_name is handled inside send_email function)
-    return await send_email({
+    const from_name = await get_email_from_name(notify_config);
+    const subject = get_email_subject(template_type);
+
+    // Dynamic import keeps hazo_notify optional at build time.
+    const { send_template_email: notify_send_template_email } = await import(
+      "hazo_notify/template_manager"
+    );
+
+    const result = await notify_send_template_email(
+      {
+        template_name: template_type,
+        to,
+        variables,
+        scope_id: null,
+        subject,
+        from,
+        from_name,
+      },
+      hazo_notify_connect
+    );
+
+    if (result.success) {
+      logger.info("email_sent_via_template", {
+        filename: "email_service.ts",
+        line_number: 0,
+        template_type,
+        to,
+        message_id: result.message_id,
+      });
+      return { success: true };
+    }
+
+    const error_message = result.error || result.message || "Unknown error";
+    logger.error("email_template_send_failed", {
+      filename: "email_service.ts",
+      line_number: 0,
+      template_type,
       to,
-      from,
-      subject,
-      html_body,
-      text_body,
+      error: error_message,
     });
+    return { success: false, error: error_message };
   } catch (error) {
     const error_message = error instanceof Error ? error.message : "Unknown error";
-    
+
     logger.error("email_template_send_failed", {
       filename: "email_service.ts",
       line_number: 0,
@@ -580,8 +428,7 @@ export async function send_template_email(
       to,
       error: error_message,
     });
-    
+
     return { success: false, error: error_message };
   }
 }
-