hazo_auth 5.1.31 → 5.1.34

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

@@ -0,0 +1,563 @@
+// file_description: service for managing parent-child user relationships (managed sub-profiles)
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import argon2 from "argon2";
+import { create_app_logger } from "../app_logger.js";
+import { get_relationships_config, get_allowed_relationship_types } from "../relationships_config.server.js";
+
+// section: types
+export type CreateChildData = {
+  parent_user_id: string;
+  name: string;
+  pin?: string;
+  relationship_type?: string;
+  app_user_data?: Record<string, unknown>;
+};
+
+export type RelationshipRecord = {
+  id: string;
+  parent_user_id: string;
+  child_user_id: string;
+  relationship_type: string;
+  can_view_progress: boolean;
+  can_edit_profile: boolean;
+  can_delete: boolean;
+  is_self: boolean;
+  created_at: string;
+};
+
+export type ChildProfile = {
+  relationship_id: string;
+  relationship_type: string;
+  can_view_progress: boolean;
+  can_edit_profile: boolean;
+  can_delete: boolean;
+  is_self: boolean;
+  user_id: string;
+  name: string | null;
+  email: string | null; // null for managed users (sentinel stripped)
+  profile_picture_url: string | null;
+  app_user_data: Record<string, unknown> | null;
+  has_pin: boolean;
+  created_at: string;
+};
+
+export type RelationshipServiceResult = {
+  success: boolean;
+  child_user_id?: string;
+  relationship_id?: string;
+  children?: ChildProfile[];
+  error?: string;
+};
+
+// section: sentinel-email-helpers
+const SENTINEL_DOMAIN = "@hazo.internal";
+const SENTINEL_PREFIX = "managed_";
+
+export function is_sentinel_email(email: string | null | undefined): boolean {
+  if (!email) return false;
+  return email.startsWith(SENTINEL_PREFIX) && email.endsWith(SENTINEL_DOMAIN);
+}
+
+export function get_display_email(email: string | null | undefined): string | null {
+  if (!email) return null;
+  return is_sentinel_email(email) ? null : email;
+}
+
+function generate_sentinel_email(): string {
+  return `${SENTINEL_PREFIX}${crypto.randomUUID()}${SENTINEL_DOMAIN}`;
+}
+
+// section: helpers
+
+/**
+ * Creates a managed child user and links them to a parent via a relationship record.
+ * The child gets a sentinel email and cannot log in independently.
+ * @param adapter - The hazo_connect adapter instance
+ * @param data - Child creation data including parent_user_id, name, optional pin and relationship_type
+ * @returns Result with child_user_id and relationship_id on success
+ */
+export async function create_managed_child(
+  adapter: HazoConnectAdapter,
+  data: CreateChildData,
+): Promise<RelationshipServiceResult> {
+  try {
+    const config = get_relationships_config();
+
+    // Check feature is enabled
+    if (!config.enabled) {
+      return { success: false, error: "Relationship accounts feature is not enabled" };
+    }
+
+    // Validate relationship type
+    const allowed_types = get_allowed_relationship_types();
+    const relationship_type = data.relationship_type || config.default_type;
+
+    if (!allowed_types.includes(relationship_type)) {
+      return {
+        success: false,
+        error: `Invalid relationship type "${relationship_type}". Allowed types: ${allowed_types.join(", ")}`,
+      };
+    }
+
+    const relationships_service = createCrudService(adapter, "hazo_user_relationships");
+    const users_service = createCrudService(adapter, "hazo_users");
+
+    // Check child count limit
+    const existing_relationships = await relationships_service.findBy({
+      parent_user_id: data.parent_user_id,
+    });
+
+    if (Array.isArray(existing_relationships) && existing_relationships.length >= config.max_children_per_user) {
+      return {
+        success: false,
+        error: `Maximum number of managed profiles reached (${config.max_children_per_user})`,
+      };
+    }
+
+    // Validate and hash PIN if provided
+    let pin_hash: string | null = null;
+    if (data.pin) {
+      if (data.pin.length < config.pin_min_length || data.pin.length > config.pin_max_length) {
+        return {
+          success: false,
+          error: `PIN must be between ${config.pin_min_length} and ${config.pin_max_length} characters`,
+        };
+      }
+      pin_hash = await argon2.hash(data.pin);
+    }
+
+    // Generate IDs
+    const child_user_id = crypto.randomUUID();
+    const relationship_id = crypto.randomUUID();
+    const now = new Date().toISOString();
+
+    // Insert managed child user
+    await users_service.insert({
+      id: child_user_id,
+      email_address: generate_sentinel_email(),
+      name: data.name,
+      pin_hash: pin_hash,
+      managed_by_user_id: data.parent_user_id,
+      status: "ACTIVE",
+      email_verified: true,
+      auth_providers: "managed",
+      app_user_data: JSON.stringify(data.app_user_data || {}),
+      created_at: now,
+      changed_at: now,
+    });
+
+    // Insert relationship record
+    await relationships_service.insert({
+      id: relationship_id,
+      parent_user_id: data.parent_user_id,
+      child_user_id: child_user_id,
+      relationship_type: relationship_type,
+      can_view_progress: 1,
+      can_edit_profile: 1,
+      can_delete: 0,
+      is_self: 0,
+      created_at: now,
+    });
+
+    return {
+      success: true,
+      child_user_id,
+      relationship_id,
+    };
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("create_managed_child_failed", { error: err instanceof Error ? err.message : String(err) });
+    return {
+      success: false,
+      error: "Failed to create managed profile",
+    };
+  }
+}
+
+/**
+ * Lists all children (managed profiles) linked to a parent user.
+ * @param adapter - The hazo_connect adapter instance
+ * @param parent_user_id - The parent user's ID
+ * @returns Result with array of ChildProfile objects
+ */
+export async function list_children(
+  adapter: HazoConnectAdapter,
+  parent_user_id: string,
+): Promise<RelationshipServiceResult> {
+  try {
+    const relationships_service = createCrudService(adapter, "hazo_user_relationships");
+    const users_service = createCrudService(adapter, "hazo_users");
+
+    // Get all relationships for this parent
+    const relationships = await relationships_service.findBy({
+      parent_user_id,
+    });
+
+    if (!Array.isArray(relationships) || relationships.length === 0) {
+      return { success: true, children: [] };
+    }
+
+    // Fetch user data for each child
+    const children: ChildProfile[] = [];
+
+    for (const rel of relationships) {
+      const child_user_id = rel.child_user_id as string;
+      const child_user = await users_service.findById(child_user_id);
+
+      if (child_user) {
+        const email = child_user.email_address as string | null;
+        const app_data_raw = child_user.app_user_data;
+        let app_user_data: Record<string, unknown> | null = null;
+
+        if (app_data_raw) {
+          try {
+            app_user_data = typeof app_data_raw === "string"
+              ? JSON.parse(app_data_raw)
+              : app_data_raw as Record<string, unknown>;
+          } catch {
+            app_user_data = null;
+          }
+        }
+
+        children.push({
+          relationship_id: rel.id as string,
+          relationship_type: rel.relationship_type as string,
+          can_view_progress: Boolean(rel.can_view_progress),
+          can_edit_profile: Boolean(rel.can_edit_profile),
+          can_delete: Boolean(rel.can_delete),
+          is_self: Boolean(rel.is_self),
+          user_id: child_user_id,
+          name: (child_user.name as string) || null,
+          email: get_display_email(email),
+          profile_picture_url: (child_user.profile_picture_url as string) || null,
+          app_user_data,
+          has_pin: !!(child_user.pin_hash),
+          created_at: rel.created_at as string,
+        });
+      }
+    }
+
+    return { success: true, children };
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("list_children_failed", { error: err instanceof Error ? err.message : String(err) });
+    return {
+      success: false,
+      error: "Failed to list managed profiles",
+    };
+  }
+}
+
+/**
+ * Updates relationship permissions between a parent and child.
+ * @param adapter - The hazo_connect adapter instance
+ * @param relationship_id - The relationship record ID
+ * @param parent_user_id - The parent user's ID (for ownership verification)
+ * @param updates - Fields to update (can_view_progress, can_edit_profile, can_delete)
+ * @returns Success or error result
+ */
+export async function update_relationship(
+  adapter: HazoConnectAdapter,
+  relationship_id: string,
+  parent_user_id: string,
+  updates: { can_view_progress?: boolean; can_edit_profile?: boolean; can_delete?: boolean },
+): Promise<RelationshipServiceResult> {
+  try {
+    // Verify ownership
+    const rel = await validate_relationship_ownership(adapter, relationship_id, parent_user_id);
+    if (!rel) {
+      return { success: false, error: "Relationship not found or access denied" };
+    }
+
+    const relationships_service = createCrudService(adapter, "hazo_user_relationships");
+
+    const patch: Record<string, unknown> = {};
+    if (updates.can_view_progress !== undefined) patch.can_view_progress = updates.can_view_progress ? 1 : 0;
+    if (updates.can_edit_profile !== undefined) patch.can_edit_profile = updates.can_edit_profile ? 1 : 0;
+    if (updates.can_delete !== undefined) patch.can_delete = updates.can_delete ? 1 : 0;
+
+    if (Object.keys(patch).length === 0) {
+      return { success: false, error: "No valid fields to update" };
+    }
+
+    await relationships_service.updateById(relationship_id, patch);
+
+    return { success: true, relationship_id };
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("update_relationship_failed", { error: err instanceof Error ? err.message : String(err) });
+    return {
+      success: false,
+      error: "Failed to update relationship",
+    };
+  }
+}
+
+/**
+ * Deletes a relationship and optionally the child user.
+ * @param adapter - The hazo_connect adapter instance
+ * @param relationship_id - The relationship record ID
+ * @param parent_user_id - The parent user's ID (for ownership verification)
+ * @param delete_child_user - If true, also delete the child user (only if no other parents)
+ * @returns Success or error result
+ */
+export async function delete_relationship(
+  adapter: HazoConnectAdapter,
+  relationship_id: string,
+  parent_user_id: string,
+  delete_child_user: boolean = false,
+): Promise<RelationshipServiceResult> {
+  try {
+    // Verify ownership
+    const rel = await validate_relationship_ownership(adapter, relationship_id, parent_user_id);
+    if (!rel) {
+      return { success: false, error: "Relationship not found or access denied" };
+    }
+
+    const relationships_service = createCrudService(adapter, "hazo_user_relationships");
+    const child_user_id = rel.child_user_id as string;
+
+    // Delete the relationship record
+    await relationships_service.deleteById(relationship_id);
+
+    // Optionally delete the child user
+    if (delete_child_user) {
+      // Check no other parent relationships exist for this child
+      const other_relationships = await relationships_service.findBy({
+        child_user_id,
+      });
+
+      if (!Array.isArray(other_relationships) || other_relationships.length === 0) {
+        const users_service = createCrudService(adapter, "hazo_users");
+        await users_service.deleteById(child_user_id);
+      }
+    }
+
+    return { success: true, relationship_id };
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("delete_relationship_failed", { error: err instanceof Error ? err.message : String(err) });
+    return {
+      success: false,
+      error: "Failed to delete relationship",
+    };
+  }
+}
+
+/**
+ * Creates a self-relationship where parent_user_id === child_user_id.
+ * Used when a parent wants to include themselves in a profile list.
+ * @param adapter - The hazo_connect adapter instance
+ * @param parent_user_id - The user's ID (acts as both parent and child)
+ * @returns Success or error result
+ */
+export async function create_self_relationship(
+  adapter: HazoConnectAdapter,
+  parent_user_id: string,
+): Promise<RelationshipServiceResult> {
+  try {
+    const relationships_service = createCrudService(adapter, "hazo_user_relationships");
+
+    // Check if self-relationship already exists
+    const existing = await relationships_service.findBy({
+      parent_user_id,
+      child_user_id: parent_user_id,
+      is_self: 1,
+    });
+
+    if (Array.isArray(existing) && existing.length > 0) {
+      return {
+        success: true,
+        relationship_id: existing[0].id as string,
+      };
+    }
+
+    const config = get_relationships_config();
+    const relationship_id = crypto.randomUUID();
+    const now = new Date().toISOString();
+
+    await relationships_service.insert({
+      id: relationship_id,
+      parent_user_id,
+      child_user_id: parent_user_id,
+      relationship_type: config.default_type,
+      can_view_progress: 1,
+      can_edit_profile: 1,
+      can_delete: 0,
+      is_self: 1,
+      created_at: now,
+    });
+
+    return { success: true, relationship_id };
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("create_self_relationship_failed", { error: err instanceof Error ? err.message : String(err) });
+    return {
+      success: false,
+      error: "Failed to create self-relationship",
+    };
+  }
+}
+
+/**
+ * Upgrades a managed child user to an independent user with email/password login.
+ * Removes sentinel email, sets real email and password, clears managed_by_user_id.
+ * @param adapter - The hazo_connect adapter instance
+ * @param relationship_id - The relationship record ID
+ * @param parent_user_id - The parent user's ID (for ownership verification)
+ * @param email - The real email address for the upgraded user
+ * @param password - The password for the upgraded user
+ * @returns Success or error result
+ */
+export async function upgrade_managed_user(
+  adapter: HazoConnectAdapter,
+  relationship_id: string,
+  parent_user_id: string,
+  email: string,
+  password: string,
+): Promise<RelationshipServiceResult> {
+  try {
+    // Verify ownership
+    const rel = await validate_relationship_ownership(adapter, relationship_id, parent_user_id);
+    if (!rel) {
+      return { success: false, error: "Relationship not found or access denied" };
+    }
+
+    const child_user_id = rel.child_user_id as string;
+    const users_service = createCrudService(adapter, "hazo_users");
+
+    // Get child user and verify it's a managed user
+    const child_user = await users_service.findById(child_user_id);
+    if (!child_user) {
+      return { success: false, error: "Child user not found" };
+    }
+
+    const child_email = child_user.email_address as string;
+    if (!is_sentinel_email(child_email)) {
+      return { success: false, error: "User is already an independent account" };
+    }
+
+    // Check email not already taken
+    const existing = await users_service.findBy({ email_address: email });
+    if (Array.isArray(existing) && existing.length > 0) {
+      return { success: false, error: "Email address already registered" };
+    }
+
+    // Hash password and update user
+    const password_hash = await argon2.hash(password);
+    const now = new Date().toISOString();
+
+    await users_service.updateById(child_user_id, {
+      email_address: email,
+      password_hash,
+      managed_by_user_id: null,
+      auth_providers: "email",
+      changed_at: now,
+    });
+
+    return { success: true, child_user_id, relationship_id };
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("upgrade_managed_user_failed", { error: err instanceof Error ? err.message : String(err) });
+    return {
+      success: false,
+      error: "Failed to upgrade managed user",
+    };
+  }
+}
+
+/**
+ * Authenticates a managed child user by verifying their PIN.
+ * Used for profile switching where children are protected by a PIN.
+ * @param adapter - The hazo_connect adapter instance
+ * @param parent_user_id - The parent user's ID
+ * @param child_user_id - The child user's ID
+ * @param pin - The PIN to verify
+ * @returns Result with child user info on success
+ */
+export async function authenticate_by_pin(
+  adapter: HazoConnectAdapter,
+  parent_user_id: string,
+  child_user_id: string,
+  pin: string,
+): Promise<{ success: boolean; child_user_id?: string; child_name?: string; child_email?: string | null; error?: string }> {
+  try {
+    const relationships_service = createCrudService(adapter, "hazo_user_relationships");
+
+    // Find relationship between parent and child
+    const relationships = await relationships_service.findBy({
+      parent_user_id,
+      child_user_id,
+    });
+
+    if (!Array.isArray(relationships) || relationships.length === 0) {
+      return { success: false, error: "No relationship found between users" };
+    }
+
+    const users_service = createCrudService(adapter, "hazo_users");
+    const child_user = await users_service.findById(child_user_id);
+
+    if (!child_user) {
+      return { success: false, error: "Child user not found" };
+    }
+
+    const pin_hash = child_user.pin_hash as string;
+    if (!pin_hash) {
+      return { success: false, error: "No PIN set for this profile" };
+    }
+
+    // Verify PIN
+    const is_valid = await argon2.verify(pin_hash, pin);
+    if (!is_valid) {
+      return { success: false, error: "Invalid PIN" };
+    }
+
+    return {
+      success: true,
+      child_user_id,
+      child_name: (child_user.name as string) || undefined,
+      child_email: get_display_email(child_user.email_address as string),
+    };
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("authenticate_by_pin_failed", { error: err instanceof Error ? err.message : String(err) });
+    return {
+      success: false,
+      error: "Failed to authenticate by PIN",
+    };
+  }
+}
+
+/**
+ * Validates that a relationship belongs to the specified parent user.
+ * @param adapter - The hazo_connect adapter instance
+ * @param relationship_id - The relationship record ID
+ * @param parent_user_id - The expected parent user's ID
+ * @returns The relationship record if ownership is valid, null otherwise
+ */
+export async function validate_relationship_ownership(
+  adapter: HazoConnectAdapter,
+  relationship_id: string,
+  parent_user_id: string,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const relationships_service = createCrudService(adapter, "hazo_user_relationships");
+
+    const rel = await relationships_service.findById(relationship_id);
+    if (!rel) {
+      return null;
+    }
+
+    if (rel.parent_user_id !== parent_user_id) {
+      return null;
+    }
+
+    return rel as Record<string, unknown>;
+  } catch (err) {
+    const logger = create_app_logger();
+    logger.error("validate_relationship_ownership_failed", { error: err instanceof Error ? err.message : String(err) });
+    return null;
+  }
+}

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

@@ -9,6 +9,7 @@ import { get_filename, get_line_number } from "../utils/api_route_helpers.js";
 export type SessionTokenPayload = {
   user_id: string;
   email: string;
+  managed_by_user_id?: string;
   iat: number;
   exp: number;
 };
@@ -17,6 +18,7 @@ export type ValidateSessionTokenResult = {
   valid: boolean;
   user_id?: string;
   email?: string;
+  managed_by_user_id?: string;
 };
 
 // section: helpers
@@ -66,19 +68,22 @@ function get_session_token_expiry_seconds(): number {
 export async function create_session_token(
   user_id: string,
   email: string,
+  managed_by_user_id?: string,
 ): 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 exp = now + expiry_seconds;
-    
-    const jwt = await new SignJWT({
-      user_id,
-      email,
-    })
+
+    const payload: Record<string, unknown> = { user_id, email };
+    if (managed_by_user_id) {
+      payload.managed_by_user_id = managed_by_user_id;
+    }
+
+    const jwt = await new SignJWT(payload)
       .setProtectedHeader({ alg: "HS256" })
       .setIssuedAt(now)
       .setExpirationTime(exp)
@@ -128,10 +133,11 @@ export async function validate_session_token(
       algorithms: ["HS256"],
     });
     
-    // Extract user_id and email from payload
+    // Extract user_id, email, and managed_by_user_id from payload
     const user_id = payload.user_id as string;
     const email = payload.email as string;
-    
+    const managed_by_user_id = payload.managed_by_user_id as string | undefined;
+
     if (!user_id || !email) {
       logger.warn("session_token_invalid_payload", {
         filename: get_filename(),
@@ -153,6 +159,7 @@ export async function validate_session_token(
       valid: true,
       user_id,
       email,
+      managed_by_user_id,
     };
   } catch (error) {
     const error_message = error instanceof Error ? error.message : "Unknown error";

package/cli-src/lib/utils/proxy_request.ts

@@ -0,0 +1,81 @@
+// file_description: Shared utility for rewriting request.url behind reverse proxies (Cloudflare Tunnel, nginx, AWS ALB)
+import { NextRequest } from "next/server";
+
+/**
+ * Detects the public-facing origin from proxy headers.
+ * Returns null if not behind a proxy (origins match).
+ */
+function detect_public_origin(request_url: URL, headers: Headers): string | null {
+  // Priority 1: NEXTAUTH_URL env var (explicitly configured)
+  const nextauth_url = process.env.NEXTAUTH_URL;
+  if (nextauth_url) {
+    try {
+      const public_origin = new URL(nextauth_url).origin;
+      if (public_origin !== request_url.origin) {
+        return public_origin;
+      }
+    } catch {
+      // Invalid NEXTAUTH_URL, fall through
+    }
+  }
+
+  // Priority 2: x-forwarded-host header (set by Cloudflare Tunnel, nginx, etc.)
+  const forwarded_host = headers.get("x-forwarded-host");
+  if (forwarded_host && forwarded_host !== request_url.hostname) {
+    const proto = headers.get("x-forwarded-proto") || "https";
+    return `${proto}://${forwarded_host}`;
+  }
+
+  // Priority 3: host header (Cloudflare Tunnel also sets this)
+  const host_header = headers.get("host");
+  if (host_header && host_header !== request_url.host) {
+    const proto = headers.get("x-forwarded-proto") || "https";
+    return `${proto}://${host_header}`;
+  }
+
+  return null;
+}
+
+/**
+ * Rewrites request.url to use the public-facing origin when behind a reverse proxy.
+ *
+ * Behind proxies like Cloudflare Tunnel, Next.js sets request.url to the internal
+ * address (e.g., https://localhost:3000). This causes NextResponse.redirect() to
+ * resolve Location headers against the internal origin instead of the public domain.
+ *
+ * Apply this at the TOP of any route handler that uses NextResponse.redirect().
+ *
+ * @param request - The incoming NextRequest
+ * @returns A new NextRequest with corrected URL, or the original if no proxy detected
+ */
+export function rewrite_request_for_proxy(request: NextRequest): NextRequest {
+  try {
+    const request_url = new URL(request.url);
+    const public_origin = detect_public_origin(request_url, request.headers);
+
+    if (!public_origin) {
+      return request; // Not behind a proxy, no rewriting needed
+    }
+
+    // Construct corrected URL: public origin + original path + query
+    const corrected_url = `${public_origin}${request_url.pathname}${request_url.search}`;
+
+    // Create new NextRequest with corrected URL, preserving everything else
+    return new NextRequest(corrected_url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+    });
+  } catch {
+    return request;
+  }
+}
+
+/**
+ * Gets the public-facing origin for constructing redirect URLs.
+ * Use this when you need the origin string but don't need to rewrite the request.
+ */
+export function get_public_origin(request: NextRequest): string {
+  const request_url = new URL(request.url);
+  return detect_public_origin(request_url, request.headers) || request_url.origin;
+}