hazo_auth 9.1.1 → 10.1.0

package/README.md

@@ -2,6 +2,64 @@
 
 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 v10.1.0 🚀
+
+**Incremental Google OAuth Scopes & Server-Side Token Access** — Grant additional Google API scopes (Analytics, Sheets, Drive, etc.) without creating a separate OAuth app. Store encrypted tokens server-side and access them programmatically.
+
+**New Features:**
+- **`hazo_google_oauth_tokens` table** (migration 021) — Encrypted AES-256-GCM storage for Google OAuth tokens with scope tracking
+- **Token Service Exports** from `hazo_auth/server-lib`:
+  - `store_google_oauth_token(user_id, tokens, scopes)` — Save OAuth tokens after user grants new scopes
+  - `getGoogleToken(user_id, opts?)` — Get a fresh access token (refreshes if expired)
+  - `revoke_google_oauth_token(user_id)` — Permanently revoke stored token and forget scopes
+  - `get_google_token_status(user_id)` — Check connection status, scopes, and expiry
+- **Client Helper** — `requestGoogleScopes(scopes, opts?)` from `hazo_auth/client` triggers Google consent prompt for incremental scopes
+- **HTTP Routes:**
+  - `GET /api/hazo_auth/google/token` — Returns `{ connected, scopes, expires_at }`
+  - `DELETE /api/hazo_auth/google/token` — Revoke stored token without signing user out
+- **NextAuth Config Updates** — Captures `refresh_token` and adds `include_granted_scopes: true` parameter for incremental scope flow
+- **Route Handler Exports** from `hazo_auth/server/routes`:
+  - `googleTokenGET` — implements GET status endpoint
+  - `googleTokenDELETE` — implements DELETE revoke endpoint
+
+**Setup:**
+```bash
+# 1. Run the migration
+npm run migrate -- migrations/021_hazo_google_oauth_tokens.sql
+
+# 2. Set encryption environment variables
+HAZO_AUTH_OAUTH_KEY_CURRENT=v1
+HAZO_AUTH_OAUTH_KEY_V1=$(openssl rand -base64 32)
+
+# 3. Install optional peer (for token encryption)
+npm install hazo_secure
+```
+
+**Client Usage:**
+```tsx
+import { requestGoogleScopes } from "hazo_auth/client";
+
+<button onClick={() => requestGoogleScopes([
+  "https://www.googleapis.com/auth/analytics.readonly"
+])}>
+  Connect Google Analytics
+</button>
+```
+
+**Server Usage:**
+```ts
+import { getGoogleToken } from "hazo_auth/server-lib";
+
+const result = await getGoogleToken(userId, {
+  scopes: ["https://www.googleapis.com/auth/analytics.readonly"]
+});
+if (result.ok) {
+  // use result.access_token to call Google APIs
+}
+```
+
+See [Google API Access (Incremental Scopes)](#google-api-access-incremental-scopes) below for full details.
+
 ### What's New in v9.1.1 🔧
 
 **Dev-server noise fixes for Next.js 16 + Turbopack**
@@ -742,9 +800,7 @@ CREATE INDEX idx_hazo_scopes_level ON hazo_scopes(level);
 CREATE INDEX idx_hazo_scopes_slug ON hazo_scopes(slug);
 
 -- 7a. Reserved system scopes
-INSERT INTO hazo_scopes (id, parent_id, name, level)
-VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system')
-ON CONFLICT (id) DO NOTHING;
+-- Note: Super Admin scope retired in v10; use hazo_org_global_admin permission instead (see migration 020)
 INSERT INTO hazo_scopes (id, parent_id, name, level)
 VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default')
 ON CONFLICT (id) DO NOTHING;
@@ -900,8 +956,7 @@ 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);
 
 -- Reserved system scopes
-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'));
+-- Note: Super Admin scope retired in v10; use hazo_org_global_admin permission instead (see migration 020)
 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'));
 
@@ -1254,6 +1309,48 @@ Google OAuth adds one new dependency:
 - Check logs for `invitation_table_missing` warnings
 - If using custom paths, set `create_firm_url` to your app's create firm page URL
 
+### Google API Access (Incremental Scopes)
+
+`hazo_auth` v10.1+ supports granting additional Google API scopes (Analytics, Sheets, etc.) without a separate OAuth app.
+
+**Setup:**
+1. Run the migration: `npm run migrate -- migrations/021_hazo_google_oauth_tokens.sql`
+2. Set encryption env vars:
+   ```bash
+   HAZO_AUTH_OAUTH_KEY_CURRENT=v1
+   HAZO_AUTH_OAUTH_KEY_V1=$(openssl rand -base64 32)
+   ```
+3. Install the optional peer: `npm install hazo_secure`
+
+**Usage:**
+
+```tsx
+// Client component — triggers Google consent for extra scopes
+import { requestGoogleScopes } from "hazo_auth/client";
+
+<button onClick={() => requestGoogleScopes([
+  "https://www.googleapis.com/auth/analytics.readonly"
+])}>
+  Connect Analytics
+</button>
+```
+
+```ts
+// Server action / API route — get a fresh access token
+import { getGoogleToken } from "hazo_auth/server-lib";
+
+const result = await getGoogleToken(userId, {
+  scopes: ["https://www.googleapis.com/auth/analytics.readonly"]
+});
+if (result.ok) {
+  // use result.access_token to call Google APIs
+}
+```
+
+The incremental scope token is stored and revoked independently of the user's sign-in session. `DELETE /api/hazo_auth/google/token` removes the stored token without signing the user out.
+
+**Status endpoint:** `GET /api/hazo_auth/google/token` returns `{ connected, scopes, expires_at }`.
+
 ---
 
 ## Using Components
@@ -1743,7 +1840,6 @@ type TenantOrganization = {
   slug: string | null;          // URL-friendly identifier
   level: string;                // "Company", "Division", etc.
   role_id: string;              // User's role in this scope
-  is_super_admin: boolean;
   branding?: {
     logo_url: string | null;
     primary_color: string | null;
@@ -2500,6 +2596,28 @@ import { ProfilePicMenu } from "hazo_auth/components/layouts/shared";
 />
 ```
 
+#### Menu item types
+
+`custom_menu_items` accepts four `type` values:
+
+| Type | Renders as | Fields used |
+|------|------------|-------------|
+| `info` | Read-only label/value row | `label`, `value` |
+| `link` | Navigation link | `label`, `href` |
+| `separator` | Divider | — |
+| `action` | Clickable item that fires a client-side callback | `label`, `onSelect` |
+
+```typescript
+<ProfilePicMenu
+  variant="dropdown"
+  custom_menu_items={[
+    { type: "action", label: "Switch workspace", onSelect: () => openSwitcher(), order: 1, id: "switch" }
+  ]}
+/>
+```
+
+> **`action` items are React-only.** Because `onSelect` is a function, action items cannot be expressed via the INI `custom_menu_items` config (which only supports the serialisable `info` / `link` / `separator` types) — pass them through the `custom_menu_items` prop instead.
+
 ### Configuration
 
 ```ini

package/SETUP_CHECKLIST.md

@@ -544,9 +544,7 @@ 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);
 
 -- Reserved system scopes
-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'));
-
+-- Note: Super Admin scope retired in v10; use hazo_org_global_admin permission instead (see migration 020)
 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'));
 
@@ -733,10 +731,7 @@ CREATE INDEX idx_hazo_scopes_level ON hazo_scopes(level);
 CREATE INDEX idx_hazo_scopes_slug ON hazo_scopes(slug);
 
 -- 7a. Reserved system scopes
-INSERT INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
-VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', NOW(), NOW())
-ON CONFLICT (id) DO NOTHING;
-
+-- Note: Super Admin scope retired in v10; use hazo_org_global_admin permission instead (see migration 020)
 INSERT INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
 VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', NOW(), NOW())
 ON CONFLICT (id) DO NOTHING;
@@ -897,8 +892,8 @@ GRANT USAGE ON TYPE hazo_enum_invitation_status TO anon, authenticated;
   - [ ] `hazo_invitations`
   - [ ] `hazo_user_relationships` (managed sub-profile parent/child links)
 - [ ] Reserved system scopes inserted:
-  - [ ] `00000000-0000-0000-0000-000000000000` (Super Admin)
   - [ ] `00000000-0000-0000-0000-000000000001` (System / non-multi-tenancy default)
+- [ ] Migration 020 run: Super Admin scope retired, `hazo_org_global_admin` permission granted to affected roles
 - [ ] `firm_admin` role inserted into `hazo_roles`
 
 ---
@@ -1138,6 +1133,24 @@ ls app/api/hazo_auth/set_password/route.ts
 - [ ] OAuth API routes created (`[...nextauth]`, `oauth/google/callback`, `set_password`)
 - [ ] Post-login redirect configured (if not using invitations, set `skip_invitation_check = true`)
 
+#### Google API Token Storage (optional — required for `getGoogleToken`)
+
+Only needed if you use `requestGoogleScopes` / `getGoogleToken` for Google API access beyond sign-in:
+
+1. Install optional peer: `npm install hazo_secure`
+2. Run migration: `npm run migrate -- migrations/021_hazo_google_oauth_tokens.sql`
+3. Set env vars:
+   ```env
+   HAZO_AUTH_OAUTH_KEY_CURRENT=v1
+   HAZO_AUTH_OAUTH_KEY_V1=<base64-32-bytes from: openssl rand -base64 32>
+   ```
+4. Wire the new routes in your Next.js app (same pattern as other hazo_auth routes):
+   ```ts
+   // app/api/hazo_auth/google/token/route.ts
+   export { GET as googleTokenGET, DELETE as googleTokenDELETE } from "hazo_auth/server/routes";
+   export const dynamic = "force-dynamic";
+   ```
+
 ---
 
 ## Phase 4: API Routes
@@ -1768,10 +1781,7 @@ 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);
 
 -- 3. Create system scopes
-INSERT INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
-VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', NOW(), NOW())
-ON CONFLICT (id) DO NOTHING;
-
+-- Note: Super Admin scope retired in v10; use hazo_org_global_admin permission instead (see migration 020)
 INSERT INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
 VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', NOW(), NOW())
 ON CONFLICT (id) DO NOTHING;
@@ -1861,9 +1871,7 @@ 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);
 
 -- 3. Create system scopes
-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'));
-
+-- Note: Super Admin scope retired in v10; use hazo_org_global_admin permission instead (see migration 020)
 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'));
 
@@ -1959,8 +1967,8 @@ CREATE INDEX IF NOT EXISTS idx_hazo_scopes_slug ON hazo_scopes(slug);
   - [ ] `hazo_user_scopes` (user-scope-role assignments)
   - [ ] `hazo_invitations` (user invitation flow)
 - [ ] System scopes exist:
-  - [ ] Super Admin scope (00000000-0000-0000-0000-000000000000)
   - [ ] Default System scope (00000000-0000-0000-0000-000000000001)
+- [ ] Migration 020 run: Super Admin scope retired, `hazo_org_global_admin` permission granted
 - [ ] Grants applied (PostgreSQL)
 - [ ] HRBAC tabs visible in User Management
 - [ ] Scope test page works

package/cli-src/cli/init_users.ts

@@ -5,7 +5,8 @@ import { createCrudService } from "hazo_connect/server";
 import { get_user_management_config } from "../lib/user_management_config.server.js";
 import { get_config_value } from "../lib/config/config_loader.server.js";
 import { create_app_logger } from "../lib/app_logger.js";
-import { SUPER_ADMIN_SCOPE_ID } from "../lib/services/scope_service.js";
+import { DEFAULT_SYSTEM_SCOPE_ID } from "../lib/services/scope_service.js";
+import { GLOBAL_ADMIN_PERMISSION } from "../lib/constants.js";
 
 // section: types
 type InitSummary = {
@@ -23,10 +24,6 @@ type InitSummary = {
     existing: number;
   };
   // v5.x: Removed user_role - roles are now assigned via hazo_user_scopes
-  super_admin_scope: {
-    inserted: boolean;
-    existing: boolean;
-  };
   user_scope: {
     inserted: boolean;
     existing: boolean;
@@ -77,23 +74,13 @@ function print_summary(summary: InitSummary): void {
 
   // v5.x: User-Role assignments are now handled via User-Scope assignments (see below)
 
-  // Super admin scope summary
-  console.log("Super Admin Scope:");
-  if (summary.super_admin_scope.inserted) {
-    console.log(`  ✓ Inserted: Super Admin scope (ID: ${SUPER_ADMIN_SCOPE_ID})`);
-  }
-  if (summary.super_admin_scope.existing) {
-    console.log(`  ⊙ Already existed: Super Admin scope (ID: ${SUPER_ADMIN_SCOPE_ID})`);
-  }
-  console.log();
-
   // User scope summary
   console.log("User-Scope Assignment:");
   if (summary.user_scope.inserted) {
-    console.log(`  ✓ Inserted: User assigned to Super Admin scope`);
+    console.log(`  ✓ Inserted: User assigned to default system scope`);
   }
   if (summary.user_scope.existing) {
-    console.log(`  ⊙ Already existed: User already in Super Admin scope`);
+    console.log(`  ⊙ Already existed: User already in default system scope`);
   }
   console.log();
 
@@ -131,10 +118,6 @@ export async function handle_init_users(options: InitUsersOptions = {}): Promise
       existing: 0,
     },
     // v5.x: Removed user_role - roles are now assigned via hazo_user_scopes
-    super_admin_scope: {
-      inserted: false,
-      existing: false,
-    },
     user_scope: {
       inserted: false,
       existing: false,
@@ -155,7 +138,6 @@ export async function handle_init_users(options: InitUsersOptions = {}): Promise
     });
     const users_service = createCrudService(hazoConnect, "hazo_users");
     // v5.x: Removed hazo_user_roles - roles are now assigned via hazo_user_scopes
-    const scopes_service = createCrudService(hazoConnect, "hazo_scopes");
     // hazo_user_scopes uses composite primary key (user_id, scope_id), no 'id' column
     const user_scopes_service = createCrudService(hazoConnect, "hazo_user_scopes", {
       primaryKeys: ["user_id", "scope_id"],
@@ -317,54 +299,63 @@ export async function handle_init_users(options: InitUsersOptions = {}): Promise
     console.log(`✓ Found user: ${super_user_email} (ID: ${user_id})`);
     console.log();
 
-    // v5.x: Step 7 removed - role assignment now happens via hazo_user_scopes (see step 9)
-
-    // 8. Ensure super admin scope exists
-    const existing_scopes = await scopes_service.findBy({ id: SUPER_ADMIN_SCOPE_ID });
-
-    if (Array.isArray(existing_scopes) && existing_scopes.length > 0) {
-      summary.super_admin_scope.existing = true;
-      console.log(`✓ Super Admin scope already exists (ID: ${SUPER_ADMIN_SCOPE_ID})`);
-    } else {
-      await scopes_service.insert({
-        id: SUPER_ADMIN_SCOPE_ID,
-        parent_id: null,
-        name: "Super Admin",
-        level: "system",
+    // 7. Ensure hazo_org_global_admin is in the permission catalog
+    const global_admin_perms = await permissions_service.findBy({
+      permission_name: GLOBAL_ADMIN_PERMISSION,
+    });
+    if (!Array.isArray(global_admin_perms) || global_admin_perms.length === 0) {
+      await permissions_service.insert({
+        permission_name: GLOBAL_ADMIN_PERMISSION,
+        description: "Global admin — access to all scopes and operations",
         created_at: now,
         changed_at: now,
       });
-      summary.super_admin_scope.inserted = true;
-      console.log(`✓ Created Super Admin scope (ID: ${SUPER_ADMIN_SCOPE_ID})`);
+      console.log(`✓ Created permission: ${GLOBAL_ADMIN_PERMISSION}`);
+    } else {
+      console.log(`✓ Permission already exists: ${GLOBAL_ADMIN_PERMISSION}`);
     }
+    console.log();
 
+    // 9. Ensure hazo_org_global_admin is assigned to the super user role
+    // (The role already has all configured permissions; this ensures the global admin perm is included)
+    const perm_row = await permissions_service.findBy({ permission_name: GLOBAL_ADMIN_PERMISSION });
+    const perm_id = Array.isArray(perm_row) && perm_row.length > 0 ? (perm_row[0].id as string) : null;
+    if (perm_id && role_id) {
+      const existing_rp = await role_permissions_service.findBy({ role_id, permission_id: perm_id });
+      if (!Array.isArray(existing_rp) || existing_rp.length === 0) {
+        await role_permissions_service.insert({ role_id, permission_id: perm_id });
+        console.log(`✓ Assigned ${GLOBAL_ADMIN_PERMISSION} to super user role`);
+      } else {
+        console.log(`✓ Super user role already has ${GLOBAL_ADMIN_PERMISSION}`);
+      }
+    }
     console.log();
 
-    // 9. Assign user to super admin scope
+    // 10. Assign user to DEFAULT_SYSTEM_SCOPE_ID (global access comes from the permission, not the scope)
     const existing_user_scopes = await user_scopes_service.findBy({
       user_id,
-      scope_id: SUPER_ADMIN_SCOPE_ID,
+      scope_id: DEFAULT_SYSTEM_SCOPE_ID,
     });
 
     if (Array.isArray(existing_user_scopes) && existing_user_scopes.length > 0) {
       summary.user_scope.existing = true;
-      console.log(`✓ User already assigned to Super Admin scope`);
+      console.log(`✓ User already assigned to default system scope`);
     } else {
       await user_scopes_service.insert({
         user_id,
-        scope_id: SUPER_ADMIN_SCOPE_ID,
-        root_scope_id: SUPER_ADMIN_SCOPE_ID,
+        scope_id: DEFAULT_SYSTEM_SCOPE_ID,
+        root_scope_id: DEFAULT_SYSTEM_SCOPE_ID,
         role_id,
         created_at: now,
         changed_at: now,
       });
       summary.user_scope.inserted = true;
-      console.log(`✓ Assigned user to Super Admin scope`);
+      console.log(`✓ Assigned user to default system scope`);
     }
 
     console.log();
 
-    // 10. Print summary
+    // 11. Print summary
     print_summary(summary);
 
     logger.info("init_users_completed", {
@@ -402,15 +393,16 @@ export function show_init_users_help(): void {
   console.log(`
 hazo_auth init-users
 
-Initialize users, roles, permissions, and super admin scope from configuration.
+Initialize users, roles, and permissions from configuration.
 
 This command reads from hazo_auth_config.ini and:
   1. Creates permissions from [hazo_auth__user_management] application_permission_list_defaults
   2. Creates a 'default_super_user_role' role
   3. Assigns all permissions to the super user role
   4. Finds user by email (from --email parameter or config)
-  5. Creates the Super Admin scope (${SUPER_ADMIN_SCOPE_ID})
-  6. Assigns the user to the Super Admin scope with the super user role
+  5. Ensures the '${GLOBAL_ADMIN_PERMISSION}' permission exists and is assigned to the super user role
+  6. Assigns the user to the default system scope (${DEFAULT_SYSTEM_SCOPE_ID})
+     Global admin access is granted via the '${GLOBAL_ADMIN_PERMISSION}' permission, not by scope
      (v5.x: Roles are assigned per-scope via hazo_user_scopes table)
 
 Options:

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

@@ -24,7 +24,6 @@ export type HazoAuthUser = {
 export type ScopeAccessInfo = {
   scope_id: string;
   scope_name?: string;
-  is_super_admin?: boolean;
 };
 
 /**
@@ -135,7 +134,6 @@ export type TenantOrganization = {
   slug: string | null;
   level: string;
   role_id: string;
-  is_super_admin: boolean;
   branding?: {
     logo_url: string | null;
     primary_color: string | null;

package/cli-src/lib/auth/hazo_get_auth.server.ts

@@ -30,6 +30,7 @@ import {
 } from "../services/user_scope_service.js";
 import { get_cookie_name, BASE_COOKIE_NAMES } from "../cookies_config.server.js";
 import { get_app_permission_descriptions } from "../app_permissions_config.server.js";
+import { GLOBAL_ADMIN_PERMISSION } from "../constants.js";
 
 // section: helpers
 
@@ -383,7 +384,6 @@ async function check_scope_access_internal(
       scope_access_via: {
         scope_id: result.access_via.scope_id,
         scope_name: result.access_via.scope_name,
-        is_super_admin: result.is_super_admin,
       },
       user_scopes,
     };
@@ -587,31 +587,37 @@ export async function hazo_get_auth(
   const hrbac_enabled = is_hrbac_enabled();
 
   if (hrbac_enabled && options?.scope_id) {
-    const scope_result = await check_scope_access_internal(
-      user.id,
-      options.scope_id,
-    );
-
-    scope_ok = scope_result.scope_ok;
-    scope_access_via = scope_result.scope_access_via;
-
-    // Log scope denial if permission logging is enabled
-    if (!scope_ok && config.log_permission_denials) {
-      const client_ip = get_client_ip(request);
-      logger.warn("auth_utility_scope_access_denied", {
-        filename: get_filename(),
-        line_number: get_line_number(),
-        user_id: user.id,
-        scope_id: options.scope_id,
-        user_scopes: scope_result.user_scopes,
-        ip: client_ip,
-        correlation_id: getCorrelationId(),
-      });
-    }
+    // Global admin permission grants access to all scopes
+    const has_global_admin = permissions.includes(GLOBAL_ADMIN_PERMISSION);
+    if (has_global_admin) {
+      scope_ok = true;
+      scope_access_via = { scope_id: options.scope_id };
+    } else {
+      const scope_result = await check_scope_access_internal(
+        user.id,
+        options.scope_id,
+      );
+      scope_ok = scope_result.scope_ok;
+      scope_access_via = scope_result.scope_access_via;
+
+      // Log scope denial if permission logging is enabled
+      if (!scope_ok && config.log_permission_denials) {
+        const client_ip = get_client_ip(request);
+        logger.warn("auth_utility_scope_access_denied", {
+          filename: get_filename(),
+          line_number: get_line_number(),
+          user_id: user.id,
+          scope_id: options.scope_id,
+          user_scopes: scope_result.user_scopes,
+          ip: client_ip,
+          correlation_id: getCorrelationId(),
+        });
+      }
 
-    // Throw error if strict mode and scope access denied
-    if (!scope_ok && options.strict) {
-      throw new ScopeAccessError(options.scope_id, scope_result.user_scopes);
+      // Throw error if strict mode and scope access denied
+      if (!scope_ok && options.strict) {
+        throw new ScopeAccessError(options.scope_id, scope_result.user_scopes);
+      }
     }
   }
 

package/cli-src/lib/auth/hazo_get_tenant_auth.server.ts

@@ -7,6 +7,7 @@ import { NextRequest } from "next/server";
 import { hazo_get_auth } from "./hazo_get_auth.server.js";
 import { get_auth_cache } from "./auth_cache.js";
 import { get_scope_by_id } from "../services/scope_service.js";
+import { GLOBAL_ADMIN_PERMISSION } from "../constants.js";
 import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
 import { get_cookie_name } from "../cookies_config.server.js";
 import { get_auth_utility_config } from "../auth_utility_config.server.js";
@@ -62,14 +63,12 @@ export function extract_scope_id_from_request(
 }
 
 /**
- * Builds TenantOrganization from scope details and access info
+ * Builds TenantOrganization from scope details
  * @param scope_details - Full scope details from cache
- * @param is_super_admin - Whether user is accessing as super admin
  * @returns TenantOrganization object
  */
 function build_tenant_organization(
   scope_details: ScopeDetails,
-  is_super_admin: boolean,
 ): TenantOrganization {
   return {
     id: scope_details.id,
@@ -77,7 +76,6 @@ function build_tenant_organization(
     slug: scope_details.slug,
     level: scope_details.level,
     role_id: scope_details.role_id,
-    is_super_admin,
     branding:
       scope_details.logo_url || scope_details.primary_color
         ? {
@@ -159,18 +157,17 @@ export async function hazo_get_tenant_auth(
   let organization: TenantOrganization | null = null;
 
   if (scope_id && auth_result.scope_ok && auth_result.scope_access_via) {
-    // Find the scope in user's scopes that matches the access_via scope
+    // Try to find the scope in user's cached scope assignments first.
+    // For global admins the scope may not be in their cache (they can access any scope),
+    // in which case we fall through to the permission-based fetch below.
     const access_scope = user_scopes.find(
       (s) => s.id === auth_result.scope_access_via?.scope_id,
     );
 
     if (access_scope) {
-      organization = build_tenant_organization(
-        access_scope,
-        auth_result.scope_access_via.is_super_admin || false,
-      );
-    } else if (auth_result.scope_access_via.is_super_admin) {
-      // Super admin accessing scope they're not assigned to - fetch scope details
+      organization = build_tenant_organization(access_scope);
+    } else if (auth_result.permissions.includes(GLOBAL_ADMIN_PERMISSION)) {
+      // Global admin accessing a scope they aren't directly assigned to — fetch scope details
       const hazoConnect = get_hazo_connect_instance();
       const scope_result = await get_scope_by_id(hazoConnect, scope_id);
       if (scope_result.success && scope_result.scope) {
@@ -179,8 +176,7 @@ export async function hazo_get_tenant_auth(
           name: scope_result.scope.name,
           slug: null, // Could fetch from scope if slug column exists
           level: scope_result.scope.level,
-          role_id: "", // Super admin doesn't have a role in the scope
-          is_super_admin: true,
+          role_id: "", // Global admin doesn't have a role assignment in the scope
           branding: scope_result.scope.logo_url
             ? {
                 logo_url: scope_result.scope.logo_url,

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

@@ -11,6 +11,7 @@ import { get_oauth_config } from "../oauth_config.server.js";
 import { handle_google_oauth_login } from "../services/oauth_service.js";
 import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
 import { create_app_logger } from "../app_logger.js";
+import { store_google_oauth_token, GoogleTokenStorageUnconfigured } from "../services/google_token_service.js";
 
 // section: types
 export type NextAuthCallbackUser = {
@@ -27,6 +28,8 @@ export type NextAuthCallbackAccount = {
   access_token?: string;
   id_token?: string;
   expires_at?: number;
+  refresh_token?: string;
+  scope?: string;
 };
 
 export type NextAuthCallbackProfile = {
@@ -62,6 +65,7 @@ export function get_nextauth_config(): AuthOptions {
               prompt: "consent",
               access_type: "offline",
               response_type: "code",
+              include_granted_scopes: "true",
             },
           },
         })
@@ -170,6 +174,43 @@ export function get_nextauth_config(): AuthOptions {
             // Store user_id in account for the JWT callback to pick up
             (account as Record<string, unknown>).hazo_user_id = result.user_id;
 
+            // Capture refresh token when extra scopes were granted
+            const BASE_SCOPES = ["openid", "email", "profile"];
+            const granted_scopes = (account.scope ?? "").split(" ").filter(Boolean);
+            const has_extra_scopes = granted_scopes.some(s => !BASE_SCOPES.includes(s));
+
+            if (account.refresh_token && has_extra_scopes) {
+              try {
+                await store_google_oauth_token({
+                  user_id: result.user_id!,
+                  refresh_token: account.refresh_token,
+                  access_token: account.access_token,
+                  scopes: account.scope ?? "",
+                  expires_at: account.expires_at
+                    ? new Date(account.expires_at * 1000).toISOString()
+                    : undefined,
+                });
+                logger.info("nextauth_google_token_stored", {
+                  user_id: result.user_id,
+                  scopes: account.scope,
+                });
+              } catch (tokenError) {
+                if (tokenError instanceof GoogleTokenStorageUnconfigured) {
+                  logger.error("nextauth_google_token_storage_unconfigured", {
+                    user_id: result.user_id,
+                    error: tokenError.message,
+                  });
+                  return "/api/auth/error?error=GoogleTokenStorageUnconfigured";
+                }
+                const errorMsg = tokenError instanceof Error ? tokenError.message : String(tokenError);
+                logger.error("nextauth_google_token_store_failed", {
+                  user_id: result.user_id,
+                  error: errorMsg,
+                });
+                // Non-fatal: continue sign-in even if token storage fails
+              }
+            }
+
             return true;
           } catch (error) {
             const errorMessage = error instanceof Error ? error.message : "Unknown error";