hazo_auth 10.0.0 → 10.2.0

package/README.md

@@ -2,6 +2,83 @@
 
 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.2.0 🧪
+
+**Test-friendly hazo_connect injection + autotest/middleware fixes.**
+
+- **`set_hazo_connect_instance(adapter)` / `reset_hazo_connect_instance()`** from `hazo_auth/server-lib` — inject a pre-built adapter into both the hazo_auth singleton cache and the underlying hazo_connect singleton (companion to hazo_connect 3.6.0 FR-001). Call `set_*` in `beforeAll` and `reset_*` in `afterAll` to swap in a test SQLite adapter without touching the production config:
+
+  ```typescript
+  import { set_hazo_connect_instance, reset_hazo_connect_instance } from "hazo_auth/server-lib";
+
+  beforeAll(() => set_hazo_connect_instance(testAdapter));
+  afterAll(() => reset_hazo_connect_instance());
+  ```
+
+- **Middleware no longer redirects `/api/` requests to the login page** — protected API routes return JSON `401`/`403` and the login redirect is now built from the request's own origin (fixes `Failed to fetch` on any non-default dev/prod port).
+- **`/api/hazo_auth/me`** now exposes `legal_acceptance` at the top level; **`/api/hazo_auth/health`** now returns a top-level `ok` boolean.
+- Browser autotest scenarios corrected for browser `fetch` semantics (opaque redirects, `*_default.jpg` images, admin-gated `401`/`403`, current `relationships` body shape).
+
+Requires `hazo_connect ^3.6.0`.
+
+### 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**
@@ -1251,6 +1328,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

package/SETUP_CHECKLIST.md

@@ -1133,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

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";

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/hazo_connect_instance.server.ts

@@ -8,6 +8,7 @@ import "server-only";
 // section: imports
 import type { HazoConnectAdapter } from "hazo_connect";
 import { getHazoConnectSingleton } from "hazo_connect/nextjs/setup";
+import { setHazoConnectSingleton, resetHazoConnectSingleton } from "hazo_connect/testing";
 import { create_sqlite_hazo_connect_server, get_hazo_connect_config_options } from "./hazo_connect_setup.server.js";
 import { initializeAdminService, getSqliteAdminService } from "hazo_connect/server";
 import { create_app_logger } from "./app_logger.js";
@@ -32,6 +33,8 @@ let isInitialized = false;
  * @returns The singleton HazoConnectAdapter instance
  */
 export function get_hazo_connect_instance(): HazoConnectAdapter {
+  // Honor test injection or cached fallback first
+  if (hazoConnectInstance) return hazoConnectInstance;
   // Use the new singleton API from hazo_connect
   // This automatically handles:
   // - Instance reuse
@@ -102,3 +105,16 @@ export function get_hazo_connect_instance(): HazoConnectAdapter {
   }
 }
 
+/** Inject a connect adapter for tests (mirrors set_hazo_connect_instance pattern). */
+export function set_hazo_connect_instance(adapter: HazoConnectAdapter): void {
+  hazoConnectInstance = adapter;
+  setHazoConnectSingleton(adapter);
+}
+
+/** Reset the injected adapter (call in afterAll). */
+export function reset_hazo_connect_instance(): void {
+  hazoConnectInstance = null;
+  isInitialized = false;
+  resetHazoConnectSingleton();
+}
+

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

@@ -161,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);
 `;