hazo_auth 6.0.0 → 6.1.1

package/README.md

@@ -2,6 +2,76 @@
 
 A reusable authentication UI component package powered by Next.js, TailwindCSS, and shadcn. It integrates `hazo_config` for configuration management and `hazo_connect` for data access, enabling future components to stay aligned with platform conventions.
 
+## What's New in v6.1.0
+
+**Email-OTP sign-in** — a passwordless, OAuth-free way to sign in via a 6-digit code emailed to the user. Targeted at single-operator deployments that don't want to wire Google OAuth or manage passwords.
+
+### Highlights
+
+- **New routes** — `POST /api/hazo_auth/otp/request` and `POST /api/hazo_auth/otp/verify`
+- **New components** — `<OTPRequestForm/>` and `<OTPVerifyForm/>` exported from `hazo_auth/client`
+- **New page** — `/hazo_auth/otp` (zero-config) via `hazo_auth/pages/otp`
+- **Sliding 7-day session** — OTP sessions auto-extend on `/me` when within 24h of expiry. OAuth/password sessions keep their existing 30-day fixed behaviour.
+- **Auto-register (opt-in)** — set `otp_auto_register = true` to let unknown emails sign in on first successful /verify
+- **Rate limited** — 3 requests/email/15min, 20 requests/IP/hour; per-code attempts capped at 5
+
+### Consumer example
+
+Mount the routes:
+
+```ts
+// app/api/hazo_auth/otp/request/route.ts
+export { otpRequestPOST as POST } from "hazo_auth/server/routes";
+
+// app/api/hazo_auth/otp/verify/route.ts
+export { otpVerifyPOST as POST } from "hazo_auth/server/routes";
+```
+
+Render the zero-config page:
+
+```tsx
+// app/hazo_auth/otp/page.tsx
+export { default } from "hazo_auth/pages/otp";
+```
+
+Or compose components yourself:
+
+```tsx
+"use client";
+import { OTPRequestForm, OTPVerifyForm } from "hazo_auth/client";
+import { useState } from "react";
+
+export default function CustomOtp() {
+  const [sent_to, set_sent_to] = useState<string | null>(null);
+  return sent_to
+    ? <OTPVerifyForm email={sent_to} redirect_url="/" />
+    : <OTPRequestForm on_sent={set_sent_to} />;
+}
+```
+
+### Required setup
+
+1. Apply migration: `npm run migrate migrations/015_email_otp.sql`
+2. Add `[hazo_auth__otp]` section to `config/hazo_auth_config.ini` (template in `hazo_auth_config.example.ini`)
+3. `hazo_notify ^3.0.0` (existing peer dep) must be configured to deliver email
+4. New peer dep: `input-otp` (optional; required only if you render `<OTPVerifyForm/>`)
+5. **Add OTP routes to your middleware/proxy `public_routes`** — unauthenticated users land on the OTP page, so the page route and its API routes must bypass auth guards:
+
+```typescript
+// middleware.ts / proxy.ts  (in your consuming app)
+const public_routes = [
+  // ... existing entries ...
+  "/hazo_auth/otp",        // OTP sign-in page (public — users arrive unauthenticated)
+  "/api/hazo_auth/otp",    // OTP request + verify API routes
+];
+```
+
+Without this your middleware redirects unauthenticated users away from the sign-in page before they can authenticate.
+
+See `MIGRATION.md` "v6.0.x → v6.1" for the full upgrade walkthrough.
+
+---
+
 ### What's New in v6.0.0 🚨 BREAKING CHANGE
 
 **`TenantAuthResult.organization` / `.organization_id` renamed to `.selected_scope` / `.selected_scope_id`.**

package/SETUP_CHECKLIST.md

@@ -1443,6 +1443,98 @@ export { POST } from "hazo_auth/server/routes/pin_login";
 
 ---
 
+## Phase 5.3: Email-OTP Sign-in Setup (Optional)
+
+Email-OTP sign-in lets users authenticate with a 6-digit code sent to their email — no password or Google OAuth required. Skip this phase if your app uses only password or OAuth authentication.
+
+### Step 5.3.1: Apply the OTP migration
+
+```bash
+npm run migrate migrations/015_email_otp.sql
+```
+
+This creates the `hazo_email_otps` table (stores hashed codes with expiry).
+
+**Verify the table exists:**
+```bash
+sqlite3 data/hazo_auth.sqlite ".tables" | tr ' ' '\n' | grep hazo_email_otps
+# Expected: hazo_email_otps
+```
+
+### Step 5.3.2: Add OTP config section
+
+Add to `config/hazo_auth_config.ini`:
+
+```ini
+[hazo_auth__otp]
+# Whether OTP sign-in is enabled
+enabled = true
+
+# Auto-register unknown emails on first successful verify (default: false)
+otp_auto_register = false
+
+# Code expiry in minutes (default: 10)
+code_expiry_minutes = 10
+```
+
+### Step 5.3.3: Create OTP API routes
+
+```bash
+npx hazo_auth generate-routes
+```
+
+Or manually:
+
+`app/api/hazo_auth/otp/request/route.ts`:
+```typescript
+export { otpRequestPOST as POST } from "hazo_auth/server/routes";
+```
+
+`app/api/hazo_auth/otp/verify/route.ts`:
+```typescript
+export { otpVerifyPOST as POST } from "hazo_auth/server/routes";
+```
+
+### Step 5.3.4: Create the OTP sign-in page
+
+`app/hazo_auth/otp/page.tsx`:
+```typescript
+export { default } from "hazo_auth/pages/otp";
+```
+
+### Step 5.3.5: Add OTP routes to middleware/proxy public_routes (REQUIRED)
+
+**This step is critical.** Unauthenticated users arrive at the OTP sign-in page before they have auth cookies. If the OTP routes are not in `public_routes`, your middleware will redirect them to `/login` in a loop.
+
+Edit your `middleware.ts` or `proxy.ts`:
+
+```typescript
+const public_routes = [
+  // ... existing entries ...
+  "/hazo_auth/otp",        // OTP sign-in page (public — users arrive unauthenticated)
+  "/api/hazo_auth/otp",    // OTP request + verify API routes
+];
+```
+
+### Step 5.3.6: Install optional peer dep (if using OTPVerifyForm)
+
+If you render `<OTPVerifyForm/>` directly (rather than using the zero-config page), install:
+
+```bash
+npm install input-otp
+```
+
+**OTP Setup Checklist:**
+- [ ] `hazo_email_otps` table created (`npm run migrate migrations/015_email_otp.sql`)
+- [ ] `[hazo_auth__otp]` section added to `hazo_auth_config.ini`
+- [ ] OTP API routes created (`/api/hazo_auth/otp/request` and `/api/hazo_auth/otp/verify`)
+- [ ] OTP page created (`/hazo_auth/otp`)
+- [ ] `/hazo_auth/otp` and `/api/hazo_auth/otp` added to middleware `public_routes`
+- [ ] `input-otp` installed (only if using `<OTPVerifyForm/>` directly)
+- [ ] Email delivery configured (`hazo_notify` + valid `ZEPTOMAIL_API_KEY`)
+
+---
+
 ## Phase 6: Verification Tests
 
 Run these tests to verify your setup is working correctly.

package/cli-src/cli/validate.ts

@@ -64,6 +64,9 @@ const REQUIRED_API_ROUTES = [
   { path: "api/hazo_auth/user_management/users/roles", method: "GET" },
   { path: "api/hazo_auth/user_management/users/roles", method: "POST" },
   { path: "api/hazo_auth/user_management/users/roles", method: "PUT" },
+  // OTP routes
+  { path: "api/hazo_auth/otp/request", method: "POST" },
+  { path: "api/hazo_auth/otp/verify", method: "POST" },
 ];
 
 // section: helpers
@@ -534,6 +537,7 @@ const REQUIRED_TABLES = [
   "hazo_role_permissions",
   "hazo_invitations",
   "hazo_refresh_tokens",
+  "hazo_email_otps",
 ];
 
 const TEXT_ID_TABLES = [

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

@@ -27,6 +27,7 @@ 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)

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

@@ -31,6 +31,12 @@ 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
@@ -94,6 +100,11 @@ 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,
@@ -111,6 +122,9 @@ export function get_login_config(): LoginConfig {
     imageAlt,
     imageBackgroundColor,
     oauth,
+    otpSigninEnabled,
+    otpSigninLabel,
+    otpSigninHref,
   };
 }
 

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

@@ -0,0 +1,91 @@
+// file_description: server-only helper to read OTP sign-in configuration from hazo_auth_config.ini
+// section: server-only-guard
+import "server-only";
+
+// section: imports
+import { get_config_value, get_config_boolean, get_config_number } from "./config/config_loader.server.js";
+
+// section: defaults
+export const OTP_CONFIG_DEFAULTS = {
+  auto_register: false,
+  code_ttl_seconds: 600,
+  session_ttl_seconds: 604800,
+  slide_when_within_seconds: 86400,
+  email_rate_limit_max: 3,
+  email_rate_limit_window_seconds: 900,
+  ip_rate_limit_max: 20,
+  ip_rate_limit_window_seconds: 3600,
+  max_verify_attempts: 5,
+  auto_assign_scope_id: "00000000-0000-0000-0000-000000000001",
+  auto_assign_role_name: "member",
+} as const;
+
+// section: types
+export type OtpConfig = {
+  /** Whether to automatically register a new user when an unrecognised email requests an OTP */
+  auto_register: boolean;
+  /** How long (seconds) a generated OTP code is valid */
+  code_ttl_seconds: number;
+  /** How long (seconds) the session created after successful OTP verification lasts */
+  session_ttl_seconds: number;
+  /** Slide the session expiry when the remaining TTL falls below this many seconds */
+  slide_when_within_seconds: number;
+  /** Maximum OTP requests allowed per email address within the rate-limit window */
+  email_rate_limit_max: number;
+  /** Rate-limit window (seconds) for per-email OTP requests */
+  email_rate_limit_window_seconds: number;
+  /** Maximum OTP requests allowed per IP address within the rate-limit window */
+  ip_rate_limit_max: number;
+  /** Rate-limit window (seconds) for per-IP OTP requests */
+  ip_rate_limit_window_seconds: number;
+  /** Maximum failed verify attempts before the OTP code is invalidated */
+  max_verify_attempts: number;
+  /** Scope ID to auto-assign a newly registered OTP user to */
+  auto_assign_scope_id: string;
+  /** Role name to assign within the auto-assign scope */
+  auto_assign_role_name: string;
+};
+
+// section: helpers
+/**
+ * Reads OTP configuration from hazo_auth_config.ini [hazo_auth__otp] section.
+ * Falls back to defaults if the config file or section is missing.
+ */
+export function get_otp_config(): OtpConfig {
+  const section = "hazo_auth__otp";
+  const d = OTP_CONFIG_DEFAULTS;
+
+  return {
+    auto_register: get_config_boolean(section, "otp_auto_register", d.auto_register),
+    code_ttl_seconds: get_config_number(section, "otp_code_ttl_seconds", d.code_ttl_seconds),
+    session_ttl_seconds: get_config_number(section, "otp_session_ttl_seconds", d.session_ttl_seconds),
+    slide_when_within_seconds: get_config_number(
+      section,
+      "otp_slide_when_within_seconds",
+      d.slide_when_within_seconds
+    ),
+    email_rate_limit_max: get_config_number(section, "otp_email_rate_limit_max", d.email_rate_limit_max),
+    email_rate_limit_window_seconds: get_config_number(
+      section,
+      "otp_email_rate_limit_window_seconds",
+      d.email_rate_limit_window_seconds
+    ),
+    ip_rate_limit_max: get_config_number(section, "otp_ip_rate_limit_max", d.ip_rate_limit_max),
+    ip_rate_limit_window_seconds: get_config_number(
+      section,
+      "otp_ip_rate_limit_window_seconds",
+      d.ip_rate_limit_window_seconds
+    ),
+    max_verify_attempts: get_config_number(section, "otp_max_verify_attempts", d.max_verify_attempts),
+    auto_assign_scope_id: get_config_value(section, "otp_auto_assign_scope_id", d.auto_assign_scope_id),
+    auto_assign_role_name: get_config_value(section, "otp_auto_assign_role_name", d.auto_assign_role_name),
+  };
+}
+
+/**
+ * Convenience accessor — returns just the session TTL seconds from OTP config.
+ * Suitable for passing to token-creation utilities.
+ */
+export function hazo_auth_otp_session_ttl_seconds(): number {
+  return get_otp_config().session_ttl_seconds;
+}

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

@@ -14,7 +14,7 @@ export type EmailOptions = {
   text_body?: string;
 };
 
-export type EmailTemplateType = "forgot_password" | "email_verification" | "password_changed";
+export type EmailTemplateType = "forgot_password" | "email_verification" | "password_changed" | "otp_signin_code";
 
 export type EmailTemplateData = {
   token?: string;
@@ -243,6 +243,8 @@ function get_email_subject(template_type: EmailTemplateType): string {
       return "Reset Your Password";
     case "password_changed":
       return "Password Changed Successfully";
+    case "otp_signin_code":
+      return "Your sign-in code";
     default:
       return "Email from hazo_auth";
   }

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

@@ -101,4 +101,21 @@ 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/email_templates/otp_signin_code.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Your sign-in code</title>
+</head>
+<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333; max-width: 600px; margin: 0 auto; padding: 20px;">
+  <p>Your sign-in code is:</p>
+  <p style="font-size: 28px; font-weight: bold; letter-spacing: 0.2em; font-family: monospace; margin: 16px 0;">{{otp_code}}</p>
+  <p>This code expires in {{expires_in_minutes}} minutes.</p>
+  <p style="color: #666; font-size: 12px;">If you didn't request this code, you can safely ignore this email.</p>
+</body>
+</html>

package/cli-src/lib/services/email_templates/otp_signin_code.txt

@@ -0,0 +1,5 @@
+Your sign-in code is: {{otp_code}}
+
+This code expires in {{expires_in_minutes}} minutes.
+
+If you didn't request this code, you can safely ignore this email.

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

@@ -20,5 +20,11 @@ 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";