hazo_auth 9.1.1 → 10.1.0

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

@@ -0,0 +1,23 @@
+// file_description: client helper to trigger incremental Google OAuth scope consent
+"use client";
+
+import { signIn } from "next-auth/react";
+
+/**
+ * Triggers an incremental Google OAuth consent flow to grant additional scopes.
+ * Call from a client component when the user needs to grant extra Google API access
+ * (e.g. analytics, sheets). On completion, hazo_auth stores the refresh token.
+ */
+export function requestGoogleScopes(
+  scopes: string[],
+  opts?: { callbackUrl?: string }
+): ReturnType<typeof signIn> {
+  const scope = Array.from(
+    new Set(["openid", "email", "profile", ...scopes])
+  ).join(" ");
+  return signIn(
+    "google",
+    { callbackUrl: opts?.callbackUrl ?? "/" },
+    { scope, access_type: "offline", include_granted_scopes: "true", prompt: "consent" }
+  );
+}

package/cli-src/lib/constants.ts

@@ -13,3 +13,5 @@ export const HAZO_AUTH_PERMISSIONS = {
 } as const;
 
 export const ALL_ADMIN_PERMISSIONS: string[] = Object.values(HAZO_AUTH_PERMISSIONS);
+
+export const GLOBAL_ADMIN_PERMISSION = "hazo_org_global_admin";

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

@@ -8,13 +8,14 @@ import { get_config_value, get_config_boolean, get_config_array } from "./config
 // section: types
 // Note: These types are also used in client components, but TypeScript types are erased at runtime
 // so importing from a server file is safe for type-only imports
-export type MenuItemType = "info" | "link" | "separator";
+export type MenuItemType = "info" | "link" | "separator" | "action";
 
 export type ProfilePicMenuMenuItem = {
   type: MenuItemType;
-  label?: string; // For info and link types
+  label?: string; // For info, link, and action types
   value?: string; // For info type (e.g., user name, email)
   href?: string; // For link type
+  onSelect?: () => void; // For action type (client-side callback, not serialisable via INI config)
   order: number; // Ordering within type group
   id: string; // Unique identifier for the item
 };
@@ -50,7 +51,7 @@ function parse_custom_menu_items(items_string: string[]): ProfilePicMenuMenuItem
     
     const type = parts[0] as MenuItemType;
     if (type !== "info" && type !== "link" && type !== "separator") {
-      return; // Invalid type, skip
+      return; // Invalid type or action (action items carry callbacks, not expressible in INI)
     }
     
     if (type === "separator") {

package/cli-src/lib/schema/sqlite_schema.ts

@@ -97,10 +97,6 @@ CREATE INDEX IF NOT EXISTS idx_hazo_scopes_parent ON hazo_scopes(parent_id);
 CREATE INDEX IF NOT EXISTS idx_hazo_scopes_level ON hazo_scopes(level);
 CREATE INDEX IF NOT EXISTS idx_hazo_scopes_slug ON hazo_scopes(slug);
 
--- Super admin scope
-INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
-VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', datetime('now'), datetime('now'));
-
 -- Default system scope (for non-multi-tenancy mode)
 INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
 VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', datetime('now'), datetime('now'));
@@ -165,4 +161,20 @@ CREATE INDEX IF NOT EXISTS idx_hazo_user_relationships_child ON hazo_user_relati
 -- Firm admin role (for firm creators)
 INSERT OR IGNORE INTO hazo_roles (id, role_name, created_at, changed_at)
 VALUES (lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)),2) || '-' || substr('89ab',abs(random()) % 4 + 1, 1) || substr(hex(randomblob(2)),2) || '-' || hex(randomblob(6))), 'firm_admin', datetime('now'), datetime('now'));
+
+-- Google OAuth tokens (encrypted refresh/access tokens for extra-scope API access)
+CREATE TABLE IF NOT EXISTS hazo_google_oauth_tokens (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  provider TEXT NOT NULL DEFAULT 'google',
+  refresh_token_enc TEXT NOT NULL,
+  access_token_enc TEXT,
+  scopes TEXT NOT NULL DEFAULT '',
+  expires_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(user_id, provider)
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_google_oauth_tokens_user ON hazo_google_oauth_tokens(user_id);
 `;

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

@@ -8,7 +8,7 @@ import {
   get_config_number,
   get_config_boolean,
 } from "./config/config_loader.server.js";
-import { SUPER_ADMIN_SCOPE_ID, DEFAULT_SYSTEM_SCOPE_ID } from "./services/scope_service.js";
+import { DEFAULT_SYSTEM_SCOPE_ID } from "./services/scope_service.js";
 
 // section: types
 
@@ -23,8 +23,6 @@ export type ScopeHierarchyConfig = {
   scope_cache_ttl_minutes: number;
   /** Maximum entries in scope cache (default: 5000) */
   scope_cache_max_entries: number;
-  /** Super admin scope ID */
-  super_admin_scope_id: string;
   /** Default system scope ID (for non-multi-tenancy mode) */
   default_system_scope_id: string;
 };
@@ -57,11 +55,6 @@ export function get_scope_hierarchy_config(): ScopeHierarchyConfig {
   );
 
   // Scope IDs (with defaults)
-  const super_admin_scope_id = get_config_value(
-    SECTION_NAME,
-    "super_admin_scope_id",
-    SUPER_ADMIN_SCOPE_ID,
-  );
   const default_system_scope_id = get_config_value(
     SECTION_NAME,
     "default_system_scope_id",
@@ -72,7 +65,6 @@ export function get_scope_hierarchy_config(): ScopeHierarchyConfig {
     enable_hrbac,
     scope_cache_ttl_minutes,
     scope_cache_max_entries,
-    super_admin_scope_id,
     default_system_scope_id,
   };
 }

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

@@ -0,0 +1,408 @@
+// file_description: stores, retrieves, refreshes, and revokes Google OAuth tokens with encrypted persistence
+// section: imports
+import { createCrudService } from "hazo_connect/server";
+import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
+import { create_app_logger } from "../app_logger.js";
+import { optional_import } from "hazo_core";
+import { randomUUID } from "crypto";
+
+// section: errors
+
+export class GoogleTokenStorageUnconfigured extends Error {
+  constructor() {
+    super(
+      "Google token storage is not configured. Set HAZO_AUTH_OAUTH_KEY_CURRENT and HAZO_AUTH_OAUTH_KEY_<ID> env vars."
+    );
+    this.name = "GoogleTokenStorageUnconfigured";
+  }
+}
+
+// section: types
+
+export type StoreGoogleOAuthTokenParams = {
+  user_id: string;
+  refresh_token: string;
+  access_token?: string;
+  scopes: string; // space-delimited
+  expires_at?: string; // ISO string for access token expiry
+};
+
+export type GoogleTokenResult =
+  | { ok: true; access_token: string; scopes: string }
+  | { ok: false; error: "not_connected" | "reconsent_required" | "refresh_failed" | "unconfigured" };
+
+export type GoogleTokenStatus = {
+  connected: boolean;
+  scopes: string;
+  expires_at: string | null;
+};
+
+// section: internal-types
+
+type GoogleOAuthRow = {
+  id: string;
+  user_id: string;
+  provider: string;
+  refresh_token_enc: string;
+  access_token_enc: string | null;
+  scopes: string;
+  expires_at: string | null;
+  created_at: string;
+  changed_at: string;
+};
+
+// section: cache
+
+const access_token_cache = new Map<string, { token: string; expires_at: string }>();
+
+// section: helpers
+
+function makeKeyProvider(
+  LookupKeyProvider: new (lookup: (name: string) => string | undefined) => unknown
+) {
+  return new LookupKeyProvider((name: string) => {
+    if (name === "current") return process.env.HAZO_AUTH_OAUTH_KEY_CURRENT;
+    if (name.startsWith("key_")) {
+      const keyId = name.slice(4).toUpperCase();
+      return process.env[`HAZO_AUTH_OAUTH_KEY_${keyId}`];
+    }
+    return undefined;
+  });
+}
+
+async function load_crypto_module() {
+  const cryptoModule = await optional_import<typeof import("hazo_secure/crypto")>(
+    "hazo_secure/crypto"
+  );
+  if (!cryptoModule) throw new GoogleTokenStorageUnconfigured();
+  return cryptoModule;
+}
+
+// section: store
+
+/**
+ * Stores (inserts or updates) Google OAuth tokens for a user, encrypting sensitive fields.
+ * Throws GoogleTokenStorageUnconfigured if hazo_secure/crypto is unavailable or keys are missing.
+ */
+export async function store_google_oauth_token(
+  params: StoreGoogleOAuthTokenParams
+): Promise<void> {
+  const logger = create_app_logger();
+
+  const { encryptField, decryptField: _decryptField, aadFor, LookupKeyProvider } = await load_crypto_module();
+
+  const keys = makeKeyProvider(LookupKeyProvider as new (lookup: (name: string) => string | undefined) => unknown) as Parameters<typeof encryptField>[1]["keys"];
+
+  // Force-fail early if no key is configured
+  try {
+    await (keys as unknown as { current(): Promise<unknown> }).current();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.error("google_token_service_key_provider_failed", {
+      filename: "google_token_service.ts",
+      error: msg,
+    });
+    throw new GoogleTokenStorageUnconfigured();
+  }
+
+  const refresh_enc = await encryptField(params.refresh_token, {
+    keys,
+    aad: aadFor("hazo_google_oauth_tokens", params.user_id, "refresh_token"),
+  });
+  const refresh_token_enc = JSON.stringify(refresh_enc);
+
+  let access_token_enc: string | null = null;
+  if (params.access_token) {
+    const access_enc = await encryptField(params.access_token, {
+      keys,
+      aad: aadFor("hazo_google_oauth_tokens", params.user_id, "access_token"),
+    });
+    access_token_enc = JSON.stringify(access_enc);
+  }
+
+  const adapter = get_hazo_connect_instance();
+  const service = createCrudService(adapter, "hazo_google_oauth_tokens");
+
+  const existing_rows = (await service.findBy({
+    user_id: params.user_id,
+    provider: "google",
+  })) as GoogleOAuthRow[];
+
+  const now = new Date().toISOString();
+
+  if (existing_rows.length > 0) {
+    const existing = existing_rows[0];
+    await service.updateById(existing.id, {
+      refresh_token_enc,
+      access_token_enc,
+      scopes: params.scopes,
+      expires_at: params.expires_at ?? null,
+      changed_at: now,
+    });
+    logger.info("google_token_service_token_updated", {
+      filename: "google_token_service.ts",
+      user_id: params.user_id,
+    });
+  } else {
+    await service.insert({
+      id: randomUUID(),
+      user_id: params.user_id,
+      provider: "google",
+      refresh_token_enc,
+      access_token_enc,
+      scopes: params.scopes,
+      expires_at: params.expires_at ?? null,
+      created_at: now,
+      changed_at: now,
+    });
+    logger.info("google_token_service_token_stored", {
+      filename: "google_token_service.ts",
+      user_id: params.user_id,
+    });
+  }
+}
+
+// section: get
+
+/**
+ * Returns a valid access token for the user, refreshing via Google if needed.
+ * Returns a typed error result instead of throwing for expected failure modes.
+ */
+export async function getGoogleToken(
+  userId: string,
+  opts?: { scopes?: string[] }
+): Promise<GoogleTokenResult> {
+  const logger = create_app_logger();
+
+  // Check in-memory cache first
+  const cached = access_token_cache.get(userId);
+  if (cached) {
+    const still_valid = new Date(cached.expires_at).getTime() - 60000 > Date.now();
+    if (still_valid) {
+      logger.info("google_token_service_cache_hit", {
+        filename: "google_token_service.ts",
+        user_id: userId,
+      });
+      // We need scopes from DB even on cache hit when scope check is requested
+      if (!opts?.scopes?.length) {
+        // No scope check needed — return cached token (scopes unknown from cache alone)
+        // Fall through to DB to get scopes for the result shape
+      }
+    }
+  }
+
+  const adapter = get_hazo_connect_instance();
+  const service = createCrudService(adapter, "hazo_google_oauth_tokens");
+
+  const rows = (await service.findBy({ user_id: userId, provider: "google" })) as GoogleOAuthRow[];
+  if (rows.length === 0) {
+    return { ok: false, error: "not_connected" };
+  }
+
+  const row = rows[0];
+
+  // Scope check
+  if (opts?.scopes?.length) {
+    const stored_scopes = row.scopes.split(" ").filter(Boolean);
+    const missing = opts.scopes.some((s) => !stored_scopes.includes(s));
+    if (missing) {
+      return { ok: false, error: "reconsent_required" };
+    }
+  }
+
+  // Return cached token now that we have the row (scope check passed)
+  if (cached) {
+    const still_valid = new Date(cached.expires_at).getTime() - 60000 > Date.now();
+    if (still_valid) {
+      return { ok: true, access_token: cached.token, scopes: row.scopes };
+    }
+  }
+
+  // Need to refresh — load crypto
+  let cryptoModule: Awaited<ReturnType<typeof load_crypto_module>>;
+  try {
+    cryptoModule = await load_crypto_module();
+  } catch {
+    return { ok: false, error: "unconfigured" };
+  }
+
+  const { decryptField, aadFor, LookupKeyProvider } = cryptoModule;
+  const keys = makeKeyProvider(LookupKeyProvider as new (lookup: (name: string) => string | undefined) => unknown) as Parameters<typeof cryptoModule.encryptField>[1]["keys"];
+
+  let decrypted_refresh: string;
+  try {
+    decrypted_refresh = await decryptField(JSON.parse(row.refresh_token_enc), {
+      keys,
+      aad: aadFor("hazo_google_oauth_tokens", userId, "refresh_token"),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.error("google_token_service_decrypt_failed", {
+      filename: "google_token_service.ts",
+      user_id: userId,
+      error: msg,
+    });
+    return { ok: false, error: "refresh_failed" };
+  }
+
+  // Call Google token refresh endpoint
+  let resp: Response;
+  try {
+    resp = await fetch("https://oauth2.googleapis.com/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: decrypted_refresh,
+        client_id: process.env.HAZO_AUTH_GOOGLE_CLIENT_ID!,
+        client_secret: process.env.HAZO_AUTH_GOOGLE_CLIENT_SECRET!,
+      }),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.error("google_token_service_refresh_fetch_failed", {
+      filename: "google_token_service.ts",
+      user_id: userId,
+      error: msg,
+    });
+    return { ok: false, error: "refresh_failed" };
+  }
+
+  if (!resp.ok) {
+    logger.warn("google_token_service_refresh_rejected", {
+      filename: "google_token_service.ts",
+      user_id: userId,
+      status: resp.status,
+    });
+    return { ok: false, error: "refresh_failed" };
+  }
+
+  const data = await resp.json() as { access_token: string; expires_in: number };
+
+  // Persist new access token (encrypted)
+  const new_expires_at = new Date(Date.now() + data.expires_in * 1000).toISOString();
+  try {
+    const { encryptField } = cryptoModule;
+    const access_enc = await encryptField(data.access_token, {
+      keys,
+      aad: aadFor("hazo_google_oauth_tokens", userId, "access_token"),
+    });
+    const access_token_enc = JSON.stringify(access_enc);
+    await service.updateById(row.id, {
+      access_token_enc,
+      expires_at: new_expires_at,
+      changed_at: new Date().toISOString(),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn("google_token_service_persist_access_token_failed", {
+      filename: "google_token_service.ts",
+      user_id: userId,
+      error: msg,
+      note: "Access token refreshed successfully but could not be persisted",
+    });
+  }
+
+  // Update in-memory cache
+  access_token_cache.set(userId, { token: data.access_token, expires_at: new_expires_at });
+
+  logger.info("google_token_service_token_refreshed", {
+    filename: "google_token_service.ts",
+    user_id: userId,
+  });
+
+  return { ok: true, access_token: data.access_token, scopes: row.scopes };
+}
+
+// section: revoke
+
+/**
+ * Revokes the user's Google OAuth tokens — best-effort remote revocation, then deletes DB row.
+ */
+export async function revoke_google_oauth_token(
+  userId: string
+): Promise<{ ok: boolean; error?: string }> {
+  const logger = create_app_logger();
+
+  const adapter = get_hazo_connect_instance();
+  const service = createCrudService(adapter, "hazo_google_oauth_tokens");
+
+  const rows = (await service.findBy({ user_id: userId, provider: "google" })) as GoogleOAuthRow[];
+  if (rows.length === 0) {
+    return { ok: false, error: "not_connected" };
+  }
+
+  const row = rows[0];
+
+  // Attempt remote revocation — best effort
+  try {
+    const { decryptField, aadFor, LookupKeyProvider } = await load_crypto_module();
+    const keys = makeKeyProvider(LookupKeyProvider as new (lookup: (name: string) => string | undefined) => unknown) as Parameters<typeof decryptField>[1]["keys"];
+
+    const decrypted_refresh = await decryptField(JSON.parse(row.refresh_token_enc), {
+      keys,
+      aad: aadFor("hazo_google_oauth_tokens", userId, "refresh_token"),
+    });
+
+    const revoke_resp = await fetch(
+      `https://oauth2.googleapis.com/revoke?token=${encodeURIComponent(decrypted_refresh)}`,
+      { method: "POST" }
+    );
+
+    if (!revoke_resp.ok) {
+      logger.warn("google_token_service_revoke_remote_failed", {
+        filename: "google_token_service.ts",
+        user_id: userId,
+        status: revoke_resp.status,
+        note: "Google revocation returned non-OK status; proceeding to delete local record",
+      });
+    } else {
+      logger.info("google_token_service_revoke_remote_ok", {
+        filename: "google_token_service.ts",
+        user_id: userId,
+      });
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn("google_token_service_revoke_remote_error", {
+      filename: "google_token_service.ts",
+      user_id: userId,
+      error: msg,
+      note: "Remote revocation failed; proceeding to delete local record",
+    });
+  }
+
+  // Always delete the local row
+  await service.deleteById(row.id);
+  access_token_cache.delete(userId);
+
+  logger.info("google_token_service_revoked", {
+    filename: "google_token_service.ts",
+    user_id: userId,
+  });
+
+  return { ok: true };
+}
+
+// section: status
+
+/**
+ * Returns connection status and scope information for a user's Google OAuth connection.
+ * Does not decrypt or refresh tokens.
+ */
+export async function get_google_token_status(userId: string): Promise<GoogleTokenStatus> {
+  const adapter = get_hazo_connect_instance();
+  const service = createCrudService(adapter, "hazo_google_oauth_tokens");
+
+  const rows = (await service.findBy({ user_id: userId, provider: "google" })) as GoogleOAuthRow[];
+  if (rows.length === 0) {
+    return { connected: false, scopes: "", expires_at: null };
+  }
+
+  const row = rows[0];
+  return {
+    connected: true,
+    scopes: row.scopes,
+    expires_at: row.expires_at ?? null,
+  };
+}

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

@@ -20,5 +20,5 @@ export * from "./scope_service.js";
 export * from "./user_scope_service.js";
 export * from "./oauth_service.js";
 export * from "./branding_service.js";
-
+export * from "./google_token_service.js";
 

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

@@ -478,7 +478,7 @@ export async function list_invitations_by_scope(
 }
 
 /**
- * Lists all invitations (for super admin)
+ * Lists all invitations (for global admins)
  */
 export async function list_all_invitations(
   adapter: HazoConnectAdapter,

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

@@ -7,12 +7,6 @@ import { sanitize_error_for_user } from "../utils/error_sanitizer.js";
 
 // section: constants
 
-/**
- * Super admin scope ID - special UUID for system-level administrators
- * Users assigned to this scope have global access
- */
-export const SUPER_ADMIN_SCOPE_ID = "00000000-0000-0000-0000-000000000000";
-
 /**
  * Default system scope ID - for non-multi-tenancy mode
  * All users are assigned to this scope when multi-tenancy is disabled
@@ -119,13 +113,6 @@ export function has_branding(scope: ScopeRecord): boolean {
   return !!(scope.logo_url || scope.primary_color || scope.secondary_color || scope.tagline);
 }
 
-/**
- * Checks if the given scope_id is the super admin scope
- */
-export function is_super_admin_scope(scope_id: string): boolean {
-  return scope_id === SUPER_ADMIN_SCOPE_ID;
-}
-
 /**
  * Checks if the given scope_id is the default system scope
  */
@@ -134,10 +121,10 @@ export function is_default_system_scope(scope_id: string): boolean {
 }
 
 /**
- * Checks if the given scope_id is a system scope (super admin or default system)
+ * Checks if the given scope_id is a system scope (default system)
  */
 export function is_system_scope(scope_id: string): boolean {
-  return is_super_admin_scope(scope_id) || is_default_system_scope(scope_id);
+  return is_default_system_scope(scope_id);
 }
 
 // section: crud operations
@@ -781,67 +768,6 @@ export async function get_scope_tree(
   }
 }
 
-/**
- * Ensures the super admin scope exists
- */
-export async function ensure_super_admin_scope(
-  adapter: HazoConnectAdapter,
-): Promise<ScopeServiceResult> {
-  try {
-    // Check if already exists
-    const existing = await get_scope_by_id(adapter, SUPER_ADMIN_SCOPE_ID);
-    if (existing.success && existing.scope) {
-      return existing;
-    }
-
-    // Create it
-    const scope_service = createCrudService(adapter, "hazo_scopes");
-    const now = new Date().toISOString();
-
-    const inserted = await scope_service.insert({
-      id: SUPER_ADMIN_SCOPE_ID,
-      name: "Super Admin",
-      level: "system",
-      parent_id: null,
-      logo_url: null,
-      primary_color: null,
-      secondary_color: null,
-      tagline: null,
-      created_at: now,
-      changed_at: now,
-    });
-
-    if (!Array.isArray(inserted) || inserted.length === 0) {
-      return {
-        success: false,
-        error: "Failed to create super admin scope",
-      };
-    }
-
-    return {
-      success: true,
-      scope: normalize_scope_record(inserted[0] as Record<string, unknown>),
-    };
-  } catch (error) {
-    const logger = create_app_logger();
-    const error_message = sanitize_error_for_user(error, {
-      logToConsole: true,
-      logToLogger: true,
-      logger,
-      context: {
-        filename: "scope_service.ts",
-        line_number: 0,
-        operation: "ensure_super_admin_scope",
-      },
-    });
-
-    return {
-      success: false,
-      error: error_message,
-    };
-  }
-}
-
 /**
  * Ensures the default system scope exists
  */