hazo_auth 5.1.40 → 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/auth/ensure_anon_id.server.ts

@@ -0,0 +1,88 @@
+// file_description: server-only helper to issue/read a stable opaque anonymous visitor ID via httpOnly cookie
+//
+// Used by hazo_feedback (and any future caller) to group submissions from the
+// same anonymous visitor across page loads / weeks without requiring login.
+//
+// Signature choice (v5.2.0): async, request-only — Option A in the design doc.
+// - Reads the existing cookie from the incoming `request.cookies`.
+// - Writes a freshly-issued cookie via the async `cookies()` API from
+//   `next/headers`, which is the supported write surface in Server Components,
+//   Server Actions, and Route Handlers in Next.js 15+.
+// - Tradeoff: NOT valid in Edge middleware (where `next/headers` throws). If a
+//   middleware caller ever needs this, add a sibling `ensure_anon_id_edge`
+//   that takes (request, response) and writes via `response.cookies.set`.
+//
+// Idempotent per-request: a per-request WeakMap remembers which id was issued
+// for a given NextRequest instance, so calling `ensure_anon_id(request)` twice
+// in the same request returns the same id and queues only one Set-Cookie. This
+// matters because `request.cookies` reflects the *incoming* state and won't
+// see an id that the same request just issued.
+
+// section: server-only-guard
+import "server-only";
+
+// section: imports
+import { NextRequest } from "next/server";
+import { cookies } from "next/headers";
+import {
+  BASE_COOKIE_NAMES,
+  get_cookie_name,
+  get_cookie_options,
+} from "../cookies_config.server.js";
+
+// section: constants
+const TWO_YEARS_SECONDS = 60 * 60 * 24 * 365 * 2;
+
+// section: state
+// WeakMap keyed by NextRequest so entries are GC'd with the request.
+const issued_per_request: WeakMap<NextRequest, string> = new WeakMap();
+
+// section: main_function
+/**
+ * Returns a stable opaque anonymous visitor ID for the caller, reading an
+ * existing httpOnly cookie or issuing a fresh UUID v4 if absent.
+ *
+ * - Cookie name: `hazo_auth_anon_id` (prefixed via `[hazo_auth__cookies] cookie_prefix`)
+ * - Cookie attributes: httpOnly, sameSite=lax, path=/, secure in production,
+ *   maxAge = 2 years.
+ * - Idempotent per-request: calling twice with the same NextRequest returns
+ *   the same id and only queues one Set-Cookie.
+ *
+ * Independent from authenticated identity: an authenticated user can still
+ * have an anon id cookie. Whether to consult it for a logged-in caller is up
+ * to the caller (hazo_feedback, for example, doesn't bother).
+ *
+ * @param request - The incoming NextRequest.
+ * @returns The existing or freshly-issued anonymous visitor id (UUID v4 string).
+ */
+export async function ensure_anon_id(request: NextRequest): Promise<string> {
+  const cookie_name = get_cookie_name(BASE_COOKIE_NAMES.ANON_ID);
+
+  // Per-request idempotency: if we already issued for this NextRequest, reuse it.
+  const already_issued = issued_per_request.get(request);
+  if (already_issued) {
+    return already_issued;
+  }
+
+  // Read the existing cookie from the incoming request.
+  const existing = request.cookies.get(cookie_name)?.value;
+  if (existing) {
+    return existing;
+  }
+
+  // Issue a new id and queue the Set-Cookie via the next/headers cookie store.
+  const new_id = crypto.randomUUID();
+  const cookie_options = get_cookie_options({
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax" as const,
+    path: "/",
+    maxAge: TWO_YEARS_SECONDS,
+  });
+
+  const cookie_store = await cookies();
+  cookie_store.set(cookie_name, new_id, cookie_options);
+
+  issued_per_request.set(request, new_id);
+  return new_id;
+}

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

@@ -11,6 +11,9 @@ export {
 } from "./auth_utils.server.js";
 export type { AuthResult, AuthUser } from "./auth_utils.server";
 
+// section: anon_id_exports (v5.2)
+export { ensure_anon_id } from "./ensure_anon_id.server.js";
+
 // section: tenant_auth_exports
 export {
   hazo_get_tenant_auth,

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

@@ -8,6 +8,7 @@ export const BASE_COOKIE_NAMES = {
   USER_EMAIL: "hazo_auth_user_email",
   SESSION: "hazo_auth_session",
   DEV_LOCK: "hazo_auth_dev_lock",
+  ANON_ID: "hazo_auth_anon_id", // v5.2: Stable opaque per-visitor ID for anonymous flows (e.g. hazo_feedback). Kept in sync with the server constant.
 } as const;
 
 // section: main_functions

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

@@ -29,6 +29,7 @@ export const BASE_COOKIE_NAMES = {
   SESSION: "hazo_auth_session",
   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)
 } as const;
 
 // section: main_function

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

@@ -109,14 +109,6 @@ function get_hazo_connect_config(): {
       }
     }
 
-    // Log the resolved path so consumers can see which DB file is being used
-    logger.info("hazo_connect_sqlite_path_resolved", {
-      filename: "hazo_connect_setup.server.ts",
-      line_number: 0,
-      sqlite_path,
-      process_cwd: process.cwd(),
-      config_source: hazo_connect_section ? "hazo_auth_config.ini" : "environment variables",
-    });
 
     return {
       type: "sqlite",