@nomos-arc/arc 0.1.0

package/docs/auth/googel_plan.yaml

@@ -0,0 +1,1093 @@
+plan:
+  task_id: "auth-oauth-login"
+  task_title: "Frictionless OAuth 2.0 Google Login for arc CLI"
+  created_at: "2026-04-06T00:00:00Z"
+
+  context_analysis:
+    tech_stack:
+      language: "TypeScript (strict mode)"
+      framework: "Commander.js CLI, Zod validation"
+      runtime: "Node.js >= 20 (ESM)"
+      package_manager: "npm"
+    architecture_pattern: "Modular CLI — Commander.js registerXCommand(program) pattern, Zod config schemas with per-field defaults, NomosError typed error codes, Winston logger injection, no singletons"
+    touch_zone:
+      - "package.json"                        # Add google-auth-library dependency (open already present)
+      - "src/types/index.ts"                  # Add AuthCredentials interface, auth config section to NomosConfig
+      - "src/core/errors.ts"                  # Add auth_* error codes to NomosErrorCode union
+      - "src/core/config.ts"                  # Add AuthSchema with Zod defaults to NomosConfigSchema
+      - "src/core/auth/manager.ts"            # CREATE — AuthManager class
+      - "src/core/auth/server.ts"             # CREATE — OAuth loopback HTTP server
+      - "src/commands/auth.ts"                # CREATE — arc auth login/logout/status
+      - "src/cli.ts"                          # Register registerAuthCommand
+      - "src/search/embedder.ts"              # Credential chain fallback (sync→async factory)
+      - "src/core/graph/enricher.ts"          # Credential chain fallback
+      - "src/search/indexer.ts"               # Update Embedder instantiation to use factory
+      - "src/search/query-engine.ts"          # Update Embedder instantiation to use factory
+      - "src/core/graph/pipeline.ts"          # Update SemanticEnricher instantiation
+      - "src/commands/index.ts"               # Pass authManager or config to indexer
+      - "src/commands/search.ts"              # Pass authManager or config to query engine
+      - "src/commands/map.ts"                 # Pass authManager or config to pipeline
+    fragile_zone:
+      - "src/core/state.ts"                   # Task state management — no changes
+      - "src/core/orchestrator.ts"            # Orchestration loop — no changes
+      - "src/core/budget.ts"                  # Budget tracking — no changes
+      - "src/search/vector-store.ts"          # Vector storage — no changes
+      - "src/search/chunk-extractor.ts"       # Chunk extraction — no changes
+      - "src/utils/sanitize.ts"               # Sanitization — review only (ensure token coverage)
+    dependencies:
+      - "google-auth-library (new npm dependency)"
+      - "open (already in package.json ^11.0.0)"
+      - "@google/generative-ai (existing ^0.24.1)"
+      - "commander (existing ^14.0.3)"
+      - "winston (existing ^3.19.0)"
+      - "zod (existing ^4.3.6)"
+      - "Node.js built-in: http, net, fs, path, os, crypto"
+
+  steps:
+    # ═══════════════════════════════════════════════════════════════════════════
+    # PHASE 1: CONTRACT FIRST — Types, Error Codes, Config Schema
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    - step_id: "1.1"
+      title: "Install google-auth-library dependency"
+      action: "CONFIGURE"
+      file_path: "package.json"
+      description: |
+        Run `npm install google-auth-library`.
+        This adds the Google OAuth2 client library needed for token exchange,
+        refresh, and auth URL generation. The `open` package is already installed.
+        Also update the esbuild build script in package.json to add
+        `--external:google-auth-library` to the existing externals list.
+      inputs:
+        - "Current package.json with existing dependencies"
+      outputs:
+        - "package.json updated with google-auth-library dependency"
+        - "package-lock.json updated"
+        - "esbuild externals list includes google-auth-library"
+      validation: |
+        `npm ls google-auth-library` exits 0.
+        `grep 'google-auth-library' package.json` returns a match.
+        Build script contains `--external:google-auth-library`.
+      depends_on: []
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        `npm uninstall google-auth-library`. Revert esbuild script change.
+
+    - step_id: "1.2"
+      title: "Add AuthCredentials interface and auth config to NomosConfig"
+      action: "MODIFY"
+      file_path: "src/types/index.ts"
+      description: |
+        Add the following AFTER the existing `ExecutionMode` type declaration block
+        and BEFORE the `NomosConfig` interface:
+
+        ```typescript
+        // ─── Auth Types ──────────────────────────────────────────────────────────────
+        export interface AuthCredentials {
+          access_token: string;
+          refresh_token: string;
+          expiry_date: number;
+          token_type: string;
+          scope: string;
+        }
+        ```
+
+        Then add an `auth` section to the `NomosConfig` interface, after the `search`
+        block:
+
+        ```typescript
+        auth: {
+          client_id?: string;
+          client_secret?: string;
+          credentials_path: string;
+          redirect_port: number;
+        };
+        ```
+
+        The `credentials_path` defaults to `~/.nomos/credentials.json`.
+        The `redirect_port` defaults to `3000` (fixed port for Google Cloud Console
+        redirect URI matching, with fallback logic handled in the server module).
+      inputs:
+        - "Existing NomosConfig interface (lines 15-75 of src/types/index.ts)"
+      outputs:
+        - "AuthCredentials interface available for import"
+        - "NomosConfig.auth section defined"
+      validation: |
+        `npx tsc --noEmit` passes. AuthCredentials and NomosConfig['auth'] are
+        importable from '../types/index.js'.
+      depends_on: []
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        Remove the added interface and config section from src/types/index.ts.
+
+    - step_id: "1.3"
+      title: "Register auth error codes in NomosErrorCode union"
+      action: "MODIFY"
+      file_path: "src/core/errors.ts"
+      description: |
+        Add four new error codes to the `NomosErrorCode` union type, after the
+        existing `search_api_key_missing` entry:
+
+        ```typescript
+        | 'auth_not_logged_in'
+        | 'auth_token_expired'
+        | 'auth_login_failed'
+        | 'auth_client_config_missing';
+        ```
+
+        These codes are used by AuthManager and the auth commands to throw
+        typed NomosError instances.
+      inputs:
+        - "Existing NomosErrorCode union (lines 1-38 of src/core/errors.ts)"
+      outputs:
+        - "Four new error codes available in the NomosErrorCode type"
+      validation: |
+        `npx tsc --noEmit` passes. Code `new NomosError('auth_not_logged_in', '...')`
+        compiles without error.
+      depends_on: []
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        Remove the four added lines from the NomosErrorCode union.
+
+    - step_id: "1.4"
+      title: "Add AuthSchema to Zod config with defaults"
+      action: "MODIFY"
+      file_path: "src/core/config.ts"
+      description: |
+        Add a new `AuthSchema` Zod object AFTER the existing `SearchConfigSchema`
+        (around line 105) and BEFORE `NomosConfigSchema`:
+
+        ```typescript
+        const AuthSchema = z.object({
+          client_id: z.string().optional(),
+          client_secret: z.string().optional(),
+          credentials_path: z.string().default(
+            path.join(os.homedir(), '.nomos', 'credentials.json'),
+          ),
+          redirect_port: z.number().int().positive().default(3000),
+        });
+        ```
+
+        Add `import * as os from 'node:os';` to the top imports.
+
+        Then add the `auth` key to `NomosConfigSchema`:
+
+        ```typescript
+        auth: AuthSchema.default(() => AuthSchema.parse({})),
+        ```
+
+        This follows the exact same pattern as every other config section
+        (e.g., `search: SearchConfigSchema.default(...)`).
+      inputs:
+        - "Existing NomosConfigSchema (lines 118-129 of src/core/config.ts)"
+        - "Step 1.2 must be complete (NomosConfig type has auth section)"
+      outputs:
+        - "Auth config section parsed and defaulted by Zod"
+        - ".nomos-config.json can optionally contain auth.client_id, auth.client_secret, auth.redirect_port"
+      validation: |
+        `npx tsc --noEmit` passes. `getDefaultConfig().auth.credentials_path` ends
+        with `.nomos/credentials.json`.
+      depends_on: ["1.2"]
+      can_parallel: false
+      risk_level: "low"
+      rollback: |
+        Remove AuthSchema definition and the auth key from NomosConfigSchema.
+        Remove os import.
+
+    - step_id: "1.5"
+      title: "Create src/core/auth/ directory"
+      action: "CREATE"
+      file_path: "src/core/auth/"
+      description: |
+        Create the directory `src/core/auth/`. This is where manager.ts and
+        server.ts will live. No index barrel file needed — direct imports are
+        used throughout the project (e.g., `import { Embedder } from './embedder.js'`).
+      inputs: []
+      outputs:
+        - "Directory src/core/auth/ exists"
+      validation: |
+        `ls src/core/auth/` succeeds.
+      depends_on: []
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        `rm -rf src/core/auth/`
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # PHASE 2: ISOLATED LOGIC — AuthManager, Loopback Server
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    - step_id: "2.1"
+      title: "Implement AuthManager class"
+      action: "CREATE"
+      file_path: "src/core/auth/manager.ts"
+      description: |
+        Create `AuthManager` class with the following contract:
+
+        **Constructor:** `constructor(authConfig: NomosConfig['auth'], logger: Logger)`
+        - Stores config and logger. Does NOT read files or perform I/O in constructor.
+        - Logger type: `import type { Logger } from 'winston'`.
+
+        **Methods:**
+
+        1. `async saveCredentials(tokens: AuthCredentials): Promise<void>`
+           - Ensure `~/.nomos/` directory exists (`fs.mkdir(dir, { recursive: true })`).
+           - Write JSON to `authConfig.credentials_path`.
+           - Set file permissions: `fs.chmod(path, 0o600)`.
+           - Log success via `logger.info()`. Never log token values.
+
+        2. `loadCredentials(): AuthCredentials | null`
+           - Synchronous read. Return `null` if file doesn't exist or is invalid JSON.
+           - Parse and validate shape matches `AuthCredentials` interface.
+
+        3. `async getAuthenticatedClient(): Promise<OAuth2Client>`
+           - Load credentials via `loadCredentials()`.
+           - If null, throw `NomosError('auth_not_logged_in', ...)`.
+           - Create `OAuth2Client` from `google-auth-library`, set credentials.
+           - Check `expiry_date < Date.now()`:
+             - If expired, call `oauth2Client.refreshAccessToken()`.
+             - Persist refreshed tokens via `saveCredentials()`.
+           - Return the configured `OAuth2Client`.
+
+        4. `isLoggedIn(): boolean`
+           - Synchronous. Check if credentials file exists AND contains `refresh_token`.
+
+        5. `async clearCredentials(): Promise<void>`
+           - Delete credentials file if it exists (`fs.unlink`).
+           - Log confirmation.
+
+        6. `async getAccessToken(): Promise<string>`
+           - Convenience method. Calls `getAuthenticatedClient()`, then
+             `client.getAccessToken()`. Returns the token string.
+           - This is the method `Embedder` and `SemanticEnricher` will use
+             to get a bearer token when `GEMINI_API_KEY` is absent.
+
+        **Imports:** `fs` (node:fs and node:fs/promises), `path`, `OAuth2Client`
+        from `google-auth-library`, `NomosError`, `AuthCredentials`, `NomosConfig`.
+
+        **Security:** Never log `access_token`, `refresh_token`, or `client_secret`.
+        Use `logger.info('[nomos:auth:info] Credentials saved.')` style messages.
+      inputs:
+        - "AuthCredentials interface from step 1.2"
+        - "NomosConfig['auth'] type from step 1.2 + 1.4"
+        - "NomosError auth codes from step 1.3"
+      outputs:
+        - "AuthManager class with full token lifecycle management"
+      validation: |
+        `npx tsc --noEmit` passes. All methods have correct return types.
+        No `console.log` calls — only `logger.*`.
+      depends_on: ["1.2", "1.3", "1.4", "1.5"]
+      can_parallel: false
+      risk_level: "medium"
+      rollback: |
+        Delete src/core/auth/manager.ts.
+
+    - step_id: "2.2"
+      title: "Implement OAuth loopback server"
+      action: "CREATE"
+      file_path: "src/core/auth/server.ts"
+      description: |
+        Create a single exported function:
+
+        ```typescript
+        export async function startLoopbackServer(
+          oauth2Client: OAuth2Client,
+          scopes: string[],
+          port: number,
+          logger: Logger,
+        ): Promise<AuthCredentials>
+        ```
+
+        **Implementation details:**
+
+        1. **Server creation:** Use Node.js built-in `http.createServer()`.
+
+        2. **Port binding:** Attempt to listen on `port` (default 3000 from config).
+           If EADDRINUSE, try `listen(0)` for a random available port.
+           Log the actual port used.
+
+        3. **Auth URL generation:**
+           ```typescript
+           const redirectUri = `http://localhost:${actualPort}`;
+           oauth2Client.redirectUri = redirectUri; // must be set before generateAuthUrl
+           const authUrl = oauth2Client.generateAuthUrl({
+             access_type: 'offline',
+             scope: scopes,
+             redirect_uri: redirectUri,
+           });
+           ```
+
+        4. **Browser launch:** `import open from 'open'`. Call `await open(authUrl)`.
+           Wrap in try/catch — if browser launch fails (headless), log the URL:
+           `logger.info('[nomos:auth:info] Open this URL in your browser: <url>')`.
+
+        5. **Callback handler:** On incoming GET request:
+           - Parse `req.url` for `code` query parameter.
+           - If no code, respond 400 and continue listening.
+           - Exchange code: `const { tokens } = await oauth2Client.getToken(code)`.
+           - Respond with success HTML: simple page saying "Login successful! You can close this tab."
+           - Map tokens to `AuthCredentials` shape and resolve the Promise.
+
+        6. **Timeout:** 120-second timeout via `setTimeout`. On timeout:
+           - Destroy all tracked sockets.
+           - `server.close()`.
+           - Reject with `NomosError('auth_login_failed', 'Login timed out after 120 seconds.')`.
+
+        7. **Socket tracking:** Maintain `const sockets = new Set<net.Socket>()`.
+           Track on `server.on('connection', socket => sockets.add(socket))`.
+           On cleanup, iterate and `socket.destroy()`.
+
+        8. **Cleanup:** After receiving callback OR on timeout, destroy all sockets
+           and close server. The function must never leave a dangling server.
+
+        **Imports:** `http`, `net`, `url` (node:url for URL parsing), `open`,
+        `OAuth2Client` from google-auth-library.
+      inputs:
+        - "OAuth2Client instance (created by caller with client_id/client_secret)"
+        - "AuthCredentials interface from step 1.2"
+      outputs:
+        - "AuthCredentials object with access_token, refresh_token, expiry_date, etc."
+      validation: |
+        `npx tsc --noEmit` passes. Function signature matches spec.
+        Server cleanup is guaranteed (finally block or equivalent).
+      depends_on: ["1.2", "1.3", "1.5"]
+      can_parallel: true
+      risk_level: "high"
+      rollback: |
+        Delete src/core/auth/server.ts.
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # PHASE 3: CLI COMMANDS — arc auth login/logout/status
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    - step_id: "3.1"
+      title: "Create arc auth command group"
+      action: "CREATE"
+      file_path: "src/commands/auth.ts"
+      description: |
+        Create `registerAuthCommand(program: Command): void` following the exact
+        same pattern as every other command in `src/commands/`.
+
+        **Structure:**
+
+        ```typescript
+        import type { Command } from 'commander';
+        import { OAuth2Client } from 'google-auth-library';
+        import { loadConfig } from '../core/config.js';
+        import { createLogger } from '../core/logger.js';
+        import { NomosError } from '../core/errors.js';
+        import { AuthManager } from '../core/auth/manager.js';
+        import { startLoopbackServer } from '../core/auth/server.js';
+
+        const SCOPES = ['https://www.googleapis.com/auth/generative-language'];
+
+        export function registerAuthCommand(program: Command): void {
+          const auth = program
+            .command('auth')
+            .description('Manage Google OAuth authentication');
+
+          // ─── arc auth login ──────────────────────────────────────────────
+          auth
+            .command('login')
+            .description('Authenticate with Google via OAuth 2.0')
+            .option('--client-id <id>', 'Google OAuth client ID')
+            .option('--client-secret <secret>', 'Google OAuth client secret')
+            .action(async (opts) => { ... });
+
+          // ─── arc auth logout ─────────────────────────────────────────────
+          auth
+            .command('logout')
+            .description('Remove stored OAuth credentials')
+            .action(async () => { ... });
+
+          // ─── arc auth status ─────────────────────────────────────────────
+          auth
+            .command('status')
+            .description('Show current authentication state')
+            .action(async () => { ... });
+        }
+        ```
+
+        **`arc auth login` flow:**
+        1. Load config via `loadConfig()`.
+        2. Resolve `client_id` and `client_secret`:
+           - Priority: CLI flags `--client-id`/`--client-secret` > config `auth.client_id`/`auth.client_secret`.
+           - If neither available, throw `NomosError('auth_client_config_missing', ...)` with
+             message explaining how to provide them.
+        3. Create `OAuth2Client` with `{ clientId, clientSecret }`.
+        4. Create `AuthManager` with config.auth and logger.
+        5. Call `startLoopbackServer(oauth2Client, SCOPES, config.auth.redirect_port, logger)`.
+        6. On success: `authManager.saveCredentials(tokens)`.
+        7. Print: `✓ Logged in successfully. Credentials saved to <path>`.
+
+        **`arc auth logout` flow:**
+        1. Load config, create AuthManager.
+        2. Call `authManager.clearCredentials()`.
+        3. Print: `✓ Logged out. Credentials removed.`
+
+        **`arc auth status` flow:**
+        1. Load config, create AuthManager.
+        2. Check `authManager.isLoggedIn()`.
+        3. If logged in: load credentials, display token expiry (human-readable).
+        4. Check `process.env['GEMINI_API_KEY']` — display whether API key is set.
+        5. Print credential chain resolution order being used.
+
+        **Error handling:** Wrap each action in try/catch, matching the pattern
+        in `src/commands/index.ts` (lines 67-75): NomosError → `console.error` + exit 1.
+      inputs:
+        - "AuthManager from step 2.1"
+        - "startLoopbackServer from step 2.2"
+        - "Config with auth section from step 1.4"
+      outputs:
+        - "`arc auth login`, `arc auth logout`, `arc auth status` commands functional"
+      validation: |
+        `npx tsc --noEmit` passes.
+        `npx tsx src/cli.ts auth --help` lists login, logout, status.
+        `npx tsx src/cli.ts auth login --help` shows --client-id and --client-secret options.
+      depends_on: ["2.1", "2.2"]
+      can_parallel: false
+      risk_level: "medium"
+      rollback: |
+        Delete src/commands/auth.ts.
+
+    - step_id: "3.2"
+      title: "Register auth command in CLI entrypoint"
+      action: "MODIFY"
+      file_path: "src/cli.ts"
+      description: |
+        1. Add import at the top (after the existing command imports, around line 16):
+           ```typescript
+           import { registerAuthCommand } from './commands/auth.js';
+           ```
+
+        2. Add `registerAuthCommand` to the registration array (after
+           `registerSearchCommand`, around line 59):
+           ```typescript
+           registerAuthCommand,
+           ```
+      inputs:
+        - "registerAuthCommand function from step 3.1"
+      outputs:
+        - "`arc auth` appears in `arc --help` output"
+      validation: |
+        `npx tsc --noEmit` passes.
+        `npx tsx src/cli.ts --help` lists 'auth' command.
+      depends_on: ["3.1"]
+      can_parallel: false
+      risk_level: "low"
+      rollback: |
+        Remove the import line and the array entry from src/cli.ts.
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # PHASE 4: CREDENTIAL CHAIN INTEGRATION
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    - step_id: "4.1"
+      title: "Add async factory method to Embedder with credential chain"
+      action: "MODIFY"
+      file_path: "src/search/embedder.ts"
+      description: |
+        The Embedder constructor is currently synchronous and reads GEMINI_API_KEY
+        from process.env. The OAuth fallback requires async operations (file I/O,
+        token refresh). To avoid breaking the constructor contract, we introduce
+        a static factory method while keeping the constructor functional for the
+        API key path.
+
+        **Changes:**
+
+        1. Add a private constructor overload that accepts an API key string
+           directly (instead of reading from env):
+
+           Change the constructor to accept an optional `apiKey` parameter:
+           ```typescript
+           constructor(
+             private readonly config: NomosConfig['search'],
+             private readonly logger: Logger,
+             apiKey?: string,
+           ) {
+             const key = apiKey ?? process.env['GEMINI_API_KEY'];
+             if (!key) {
+               throw new NomosError(
+                 'search_api_key_missing',
+                 'No credentials found. Set GEMINI_API_KEY or run: arc auth login',
+               );
+             }
+             this.client = new GoogleGenerativeAI(key);
+           }
+           ```
+
+        2. Add a static async factory method:
+           ```typescript
+           static async create(
+             config: NomosConfig['search'],
+             logger: Logger,
+             authManager?: AuthManager | null,
+           ): Promise<Embedder> {
+             // Priority 1: GEMINI_API_KEY
+             const envKey = process.env['GEMINI_API_KEY'];
+             if (envKey) {
+               return new Embedder(config, logger, envKey);
+             }
+
+             // Priority 2: OAuth credentials
+             if (authManager?.isLoggedIn()) {
+               const token = await authManager.getAccessToken();
+               return new Embedder(config, logger, token);
+             }
+
+             // Priority 3: Neither — throw
+             throw new NomosError(
+               'search_api_key_missing',
+               'No credentials found. Set GEMINI_API_KEY or run: arc auth login',
+             );
+           }
+           ```
+
+        3. Add import for AuthManager:
+           ```typescript
+           import { AuthManager } from '../core/auth/manager.js';
+           ```
+
+        **Backward compatibility:** The existing `new Embedder(config, logger)`
+        constructor still works for any caller that doesn't need OAuth. The factory
+        method is the new preferred path.
+      inputs:
+        - "Existing Embedder class (src/search/embedder.ts)"
+        - "AuthManager from step 2.1"
+      outputs:
+        - "Embedder.create() factory method available"
+        - "Existing constructor still works for API key path"
+      validation: |
+        `npx tsc --noEmit` passes.
+        `new Embedder(config, logger)` still compiles (backward compat).
+        `Embedder.create(config, logger, authManager)` compiles.
+      depends_on: ["2.1"]
+      can_parallel: true
+      risk_level: "high"
+      rollback: |
+        Revert src/search/embedder.ts to original constructor.
+        Remove AuthManager import and create() method.
+
+    - step_id: "4.2"
+      title: "Add credential chain to SemanticEnricher"
+      action: "MODIFY"
+      file_path: "src/core/graph/enricher.ts"
+      description: |
+        Apply the same credential chain pattern to SemanticEnricher.
+
+        **Changes:**
+
+        1. Modify constructor to accept optional `apiKey` parameter:
+           ```typescript
+           constructor(
+             private readonly projectRoot: string,
+             private readonly config: NomosConfig['graph'],
+             private readonly logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void },
+             apiKey?: string,
+           ) {
+             const key = apiKey ?? process.env['GEMINI_API_KEY'];
+             if (!key && config.ai_enrichment) {
+               throw new NomosError(
+                 'graph_ai_key_missing',
+                 'No credentials found. Set GEMINI_API_KEY or run: arc auth login',
+               );
+             }
+             this.client = new GoogleGenerativeAI(key ?? '');
+             this.limit = pLimit(config.ai_concurrency);
+           }
+           ```
+
+        2. Add static async factory method:
+           ```typescript
+           static async create(
+             projectRoot: string,
+             config: NomosConfig['graph'],
+             logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void },
+             authManager?: AuthManager | null,
+           ): Promise<SemanticEnricher> {
+             const envKey = process.env['GEMINI_API_KEY'];
+             if (envKey) {
+               return new SemanticEnricher(projectRoot, config, logger, envKey);
+             }
+             if (authManager?.isLoggedIn()) {
+               const token = await authManager.getAccessToken();
+               return new SemanticEnricher(projectRoot, config, logger, token);
+             }
+             // No key and enrichment enabled — let constructor throw
+             return new SemanticEnricher(projectRoot, config, logger);
+           }
+           ```
+
+        3. Add import for AuthManager:
+           ```typescript
+           import { AuthManager } from '../auth/manager.js';
+           ```
+
+        **Backward compatibility:** `new SemanticEnricher(root, config, logger)`
+        still works exactly as before.
+      inputs:
+        - "Existing SemanticEnricher class (src/core/graph/enricher.ts)"
+        - "AuthManager from step 2.1"
+      outputs:
+        - "SemanticEnricher.create() factory method available"
+        - "Existing constructor still works"
+      validation: |
+        `npx tsc --noEmit` passes.
+        `new SemanticEnricher(root, config, logger)` still compiles.
+      depends_on: ["2.1"]
+      can_parallel: true
+      risk_level: "high"
+      rollback: |
+        Revert src/core/graph/enricher.ts to original constructor.
+
+    - step_id: "4.3"
+      title: "Update SearchIndexer to use Embedder.create() factory"
+      action: "MODIFY"
+      file_path: "src/search/indexer.ts"
+      description: |
+        The SearchIndexer uses a lazy `get embedder()` accessor that calls
+        `new Embedder(config, logger)`. Update it to support the credential chain.
+
+        **Changes:**
+
+        1. Add `AuthManager` to constructor parameters (optional):
+           ```typescript
+           constructor(
+             private readonly projectRoot: string,
+             private readonly config: NomosConfig,
+             private readonly logger: Logger,
+             private readonly authManager?: AuthManager | null,
+           )
+           ```
+
+        2. Change the lazy embedder accessor to async. Replace:
+           ```typescript
+           private get embedder(): Embedder {
+             if (!this._embedder) {
+               this._embedder = new Embedder(this.config.search, this.logger);
+             }
+             return this._embedder;
+           }
+           ```
+           With:
+           ```typescript
+           private async getEmbedder(): Promise<Embedder> {
+             if (!this._embedder) {
+               this._embedder = await Embedder.create(
+                 this.config.search, this.logger, this.authManager,
+               );
+             }
+             return this._embedder;
+           }
+           ```
+
+        3. Update all call sites within indexer.ts:
+           - `void this.embedder;` → `await this.getEmbedder();` (pre-check)
+           - `this.embedder.embedBatch(...)` → `(await this.getEmbedder()).embedBatch(...)`
+
+        **Backward compatibility:** Callers that don't pass `authManager` get the
+        same behavior as before (API key only).
+      inputs:
+        - "Existing SearchIndexer class (src/search/indexer.ts)"
+        - "Embedder.create() from step 4.1"
+      outputs:
+        - "SearchIndexer uses credential chain when authManager is provided"
+      validation: |
+        `npx tsc --noEmit` passes.
+        `new SearchIndexer(root, config, logger)` still compiles (authManager optional).
+      depends_on: ["4.1"]
+      can_parallel: false
+      risk_level: "medium"
+      rollback: |
+        Revert the lazy accessor and constructor changes in indexer.ts.
+
+    - step_id: "4.4"
+      title: "Update QueryEngine to use Embedder.create() factory"
+      action: "MODIFY"
+      file_path: "src/search/query-engine.ts"
+      description: |
+        Same pattern as step 4.3. The QueryEngine has an identical lazy `get embedder()`
+        accessor.
+
+        **Changes:**
+
+        1. Add `AuthManager` to constructor (optional):
+           ```typescript
+           constructor(
+             private readonly projectRoot: string,
+             private readonly config: NomosConfig,
+             private readonly logger: Logger,
+             private readonly authManager?: AuthManager | null,
+           )
+           ```
+
+        2. Change lazy accessor to async `getEmbedder()`.
+
+        3. Update `this.embedder.embedOne(query.trim())` in `search()` method to
+           `(await this.getEmbedder()).embedOne(query.trim())`.
+      inputs:
+        - "Existing QueryEngine class (src/search/query-engine.ts)"
+        - "Embedder.create() from step 4.1"
+      outputs:
+        - "QueryEngine uses credential chain when authManager is provided"
+      validation: |
+        `npx tsc --noEmit` passes.
+      depends_on: ["4.1"]
+      can_parallel: true
+      risk_level: "medium"
+      rollback: |
+        Revert query-engine.ts changes.
+
+    - step_id: "4.5"
+      title: "Update MapPipeline to use SemanticEnricher.create() factory"
+      action: "MODIFY"
+      file_path: "src/core/graph/pipeline.ts"
+      description: |
+        In the `run()` method, the enricher is instantiated at line 146:
+        ```typescript
+        const enricher = new SemanticEnricher(this.projectRoot, this.config.graph, this.logger);
+        ```
+
+        **Changes:**
+
+        1. Add `authManager` to MapPipeline constructor (optional):
+           ```typescript
+           constructor(
+             private readonly config: NomosConfig,
+             private readonly projectRoot: string,
+             private readonly logger: Logger,
+             private readonly authManager?: AuthManager | null,
+           )
+           ```
+
+        2. Replace direct instantiation with factory:
+           ```typescript
+           const enricher = await SemanticEnricher.create(
+             this.projectRoot, this.config.graph, this.logger, this.authManager,
+           );
+           ```
+
+        3. Add import:
+           ```typescript
+           import { AuthManager } from '../auth/manager.js';
+           ```
+           (Note: relative path from `src/core/graph/` to `src/core/auth/` is `../auth/`)
+      inputs:
+        - "Existing MapPipeline class (src/core/graph/pipeline.ts)"
+        - "SemanticEnricher.create() from step 4.2"
+      outputs:
+        - "MapPipeline passes authManager to SemanticEnricher"
+      validation: |
+        `npx tsc --noEmit` passes.
+      depends_on: ["4.2"]
+      can_parallel: false
+      risk_level: "medium"
+      rollback: |
+        Revert pipeline.ts to direct `new SemanticEnricher(...)` instantiation.
+
+    - step_id: "4.6"
+      title: "Wire AuthManager into command call sites"
+      action: "MODIFY"
+      file_path: "src/commands/index.ts"
+      description: |
+        Update the `arc index` command to create an `AuthManager` and pass it
+        to `SearchIndexer`.
+
+        **Changes to src/commands/index.ts:**
+
+        1. Add import:
+           ```typescript
+           import { AuthManager } from '../core/auth/manager.js';
+           ```
+
+        2. After `const logger = createLogger(...)`, create AuthManager:
+           ```typescript
+           const authManager = new AuthManager(config.auth, logger);
+           ```
+
+        3. Pass to SearchIndexer:
+           ```typescript
+           const indexer = new SearchIndexer(projectRoot, config, logger, authManager);
+           ```
+
+        **Also update src/commands/search.ts:**
+
+        Same pattern — create `AuthManager` and pass to `QueryEngine` constructor.
+
+        **Also update src/commands/map.ts:**
+
+        Same pattern — create `AuthManager` and pass to `MapPipeline` constructor.
+      inputs:
+        - "AuthManager from step 2.1"
+        - "Updated SearchIndexer from step 4.3"
+        - "Updated QueryEngine from step 4.4"
+        - "Updated MapPipeline from step 4.5"
+      outputs:
+        - "All Gemini-dependent commands use the credential chain"
+      validation: |
+        `npx tsc --noEmit` passes.
+        `arc index`, `arc search`, `arc map` commands work with GEMINI_API_KEY set
+        (backward compat).
+      depends_on: ["4.3", "4.4", "4.5"]
+      can_parallel: false
+      risk_level: "medium"
+      rollback: |
+        Remove AuthManager creation and parameter passing from all three command files.
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # PHASE 5: SECURITY — Sanitization Coverage
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    - step_id: "5.1"
+      title: "Verify sanitize.ts covers auth tokens in env deny list"
+      action: "MODIFY"
+      file_path: "src/utils/sanitize.ts"
+      description: |
+        Review the `ALWAYS_DENY` regex array in `sanitizeEnv()` (line 57-61).
+        The existing pattern already covers `GOOGLE_.*?(KEY|SECRET|TOKEN|...)`.
+        This would catch env vars like `GOOGLE_ACCESS_TOKEN` but NOT the
+        internal OAuth tokens (which are in a JSON file, not env vars).
+
+        **No code change needed if** the existing patterns already cover Google
+        credential env vars. Verify and confirm.
+
+        **If the patterns do NOT cover a scenario where tokens could leak into
+        env vars**, add coverage. But per the design, OAuth tokens live in
+        `~/.nomos/credentials.json` (file, not env) and are never set as env
+        vars by the auth module.
+
+        **Action:** Read the file, verify coverage, document finding. No modification
+        expected unless a gap is found.
+      inputs:
+        - "Existing sanitize.ts ALWAYS_DENY patterns"
+      outputs:
+        - "Confirmation that auth tokens are not leaked through env sanitization gaps"
+      validation: |
+        Manual review confirms ALWAYS_DENY covers GOOGLE_* secrets.
+        Auth tokens stored in file only — no env var leak path.
+      depends_on: []
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        N/A — review-only step.
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # PHASE 6: VALIDATION & TESTING
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    - step_id: "6.1"
+      title: "TypeScript compilation check"
+      action: "TEST"
+      file_path: ""
+      description: |
+        Run `npx tsc --noEmit` (or `npm run lint`) to verify all new and
+        modified files compile without errors. This catches:
+        - Missing imports
+        - Type mismatches between AuthCredentials, NomosConfig, NomosErrorCode
+        - Incorrect async/await usage in factory methods
+      inputs:
+        - "All files from steps 1.1 through 5.1"
+      outputs:
+        - "Zero TypeScript errors"
+      validation: |
+        `npm run lint` exits 0.
+      depends_on: ["1.1", "1.2", "1.3", "1.4", "2.1", "2.2", "3.1", "3.2", "4.1", "4.2", "4.3", "4.4", "4.5", "4.6"]
+      can_parallel: false
+      risk_level: "low"
+      rollback: |
+        Fix compilation errors identified.
+
+    - step_id: "6.2"
+      title: "Run existing test suite for regression"
+      action: "TEST"
+      file_path: ""
+      description: |
+        Run `npm test` to ensure all existing tests still pass. Key test files
+        to watch:
+        - `src/search/__tests__/embedder.test.ts` — may need update if constructor
+          signature changed (apiKey parameter added)
+        - `src/core/graph/__tests__/enricher.test.ts` — same concern
+        - `src/core/graph/__tests__/pipeline.test.ts` — if MapPipeline constructor
+          changed
+        - `src/search/__tests__/indexer.test.ts` — if SearchIndexer constructor changed
+
+        If tests fail due to constructor signature changes (new optional `apiKey`
+        or `authManager` params), these are expected and must be fixed:
+        - Tests using `new Embedder(config, logger)` → still valid (apiKey is optional)
+        - Tests using `new SearchIndexer(root, config, logger)` → still valid (authManager optional)
+
+        If any test fails for an unexpected reason, investigate before proceeding.
+      inputs:
+        - "All source changes from previous steps"
+      outputs:
+        - "All existing tests pass (or failures are expected and documented)"
+      validation: |
+        `npm test` exits 0 (or with only expected, documented failures).
+      depends_on: ["6.1"]
+      can_parallel: false
+      risk_level: "medium"
+      rollback: |
+        Fix test failures. If a test fails due to constructor changes,
+        update the test to pass the new optional parameter or verify
+        the default behavior hasn't changed.
+
+    - step_id: "6.3"
+      title: "Unit tests for AuthManager"
+      action: "CREATE"
+      file_path: "src/core/auth/__tests__/manager.test.ts"
+      description: |
+        Create unit tests for AuthManager covering:
+
+        1. **saveCredentials** — writes JSON to temp path, verifies file exists
+           and contains correct data, verifies file permissions are 0600.
+        2. **loadCredentials** — returns parsed object when file exists,
+           returns null when file doesn't exist, returns null on invalid JSON.
+        3. **isLoggedIn** — true when credentials file has refresh_token,
+           false when file missing.
+        4. **clearCredentials** — deletes file, doesn't throw if file missing.
+        5. **getAccessToken** — throws `auth_not_logged_in` when no credentials.
+
+        Use `vitest` (project's test runner). Mock the filesystem or use
+        a temp directory (`os.tmpdir()`) with cleanup in afterEach.
+
+        Do NOT mock google-auth-library for unit tests — test only the
+        file I/O and credential management logic. Integration with Google
+        is tested manually via `arc auth login`.
+      inputs:
+        - "AuthManager from step 2.1"
+      outputs:
+        - "Unit tests for AuthManager pass"
+      validation: |
+        `npx vitest run src/core/auth/__tests__/manager.test.ts` exits 0.
+      depends_on: ["2.1"]
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        Delete test file.
+
+    - step_id: "6.4"
+      title: "Unit tests for loopback server"
+      action: "CREATE"
+      file_path: "src/core/auth/__tests__/server.test.ts"
+      description: |
+        Create unit tests for the loopback server covering:
+
+        1. **Port binding** — server starts on specified port.
+        2. **Timeout** — server rejects after 120s timeout (use fake timers
+           via `vi.useFakeTimers()`).
+        3. **Callback handling** — mock an HTTP GET with `?code=test_code`,
+           verify the function resolves (mock `oauth2Client.getToken`).
+        4. **Cleanup** — server is closed after callback.
+
+        Mock `OAuth2Client.getToken()` to return fake tokens.
+        Mock `open` to prevent actual browser launch.
+      inputs:
+        - "startLoopbackServer from step 2.2"
+      outputs:
+        - "Unit tests for loopback server pass"
+      validation: |
+        `npx vitest run src/core/auth/__tests__/server.test.ts` exits 0.
+      depends_on: ["2.2"]
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        Delete test file.
+
+    - step_id: "6.5"
+      title: "Integration test — Embedder credential chain"
+      action: "CREATE"
+      file_path: "src/search/__tests__/embedder-auth.test.ts"
+      description: |
+        Test the credential chain in Embedder.create():
+
+        1. **API key takes priority** — set GEMINI_API_KEY env var, call
+           `Embedder.create(config, logger, authManager)`. Verify Embedder
+           is created using the env var (mock AuthManager, verify it's NOT called).
+        2. **OAuth fallback** — unset GEMINI_API_KEY, mock
+           `authManager.isLoggedIn()` → true, `authManager.getAccessToken()` →
+           'fake-token'. Verify Embedder is created.
+        3. **Neither available** — unset GEMINI_API_KEY, mock
+           `authManager.isLoggedIn()` → false. Verify `search_api_key_missing`
+           error is thrown with message mentioning both `GEMINI_API_KEY` and
+           `arc auth login`.
+      inputs:
+        - "Embedder.create() from step 4.1"
+        - "AuthManager from step 2.1"
+      outputs:
+        - "Credential chain works correctly in all priority scenarios"
+      validation: |
+        `npx vitest run src/search/__tests__/embedder-auth.test.ts` exits 0.
+      depends_on: ["4.1"]
+      can_parallel: true
+      risk_level: "low"
+      rollback: |
+        Delete test file.
+
+  risk_assessment:
+    overall_risk: "high"
+    critical_steps: ["2.2", "4.1", "4.2"]
+    failure_scenarios:
+      - scenario: "Google SDK rejects access_token passed as API key string"
+        impact: "OAuth tokens cannot authenticate Gemini API calls. Entire credential chain is non-functional."
+        mitigation: |
+          Step 4.1 description notes this is Risk 2 from the task spec. Start with
+          spike test: pass access_token as apiKey to GoogleGenerativeAI constructor.
+          If it fails, fall back to custom Authorization header injection (option 3
+          from task spec). The plan's architecture (factory method returning Embedder)
+          supports either approach without further refactoring.
+      - scenario: "Dynamic port breaks Google OAuth redirect URI matching"
+        impact: "OAuth callback fails with 'redirect_uri_mismatch' error."
+        mitigation: |
+          Fixed default port (3000) with configurable override via
+          `config.auth.redirect_port`. Users register `http://localhost:3000` in
+          Google Cloud Console. Fallback to random port only if 3000 is in use —
+          with clear warning that the user must register the actual port.
+      - scenario: "Sync-to-async constructor migration breaks existing callers"
+        impact: "SearchIndexer, QueryEngine, MapPipeline fail to compile or behave differently."
+        mitigation: |
+          Optional apiKey parameter preserves backward compatibility. The `new Embedder(config, logger)`
+          path is unchanged. Factory method is additive. Existing tests that use
+          the constructor directly continue to work. Step 6.2 explicitly validates this.
+      - scenario: "Token refresh fails silently, stale token used for API calls"
+        impact: "Gemini API returns 401, user sees cryptic error."
+        mitigation: |
+          AuthManager.getAuthenticatedClient() checks expiry_date and refreshes
+          proactively. If refresh fails, it throws auth_token_expired with clear
+          message to re-run `arc auth login`.
+      - scenario: "Loopback server hangs, blocking CLI process"
+        impact: "User's terminal is stuck, requires manual kill."
+        mitigation: |
+          120-second hard timeout with socket tracking and forced destroy.
+          Step 2.2 explicitly tracks sockets in a Set and destroys all on cleanup.
+
+  compliance:
+    rules_checked: true
+    violations: []
+    notes: |
+      - JSON source of truth: Token state in ~/.nomos/credentials.json (JSON). ✓
+      - NomosError codes: All auth failures use typed codes. ✓
+      - Commander.js pattern: registerAuthCommand(program) matches existing commands. ✓
+      - Config-driven: Auth config in .nomos-config.json with Zod schema. ✓
+      - Security: client_secret never logged. Sanitize pipeline reviewed. ✓
+      - No global state: AuthManager instantiated per-command. ✓
+      - Winston logging: All auth logs via injected logger. ✓
+      - Open/Closed: Existing constructor signatures preserved; factory methods are additive. ✓
+      - Backward compatibility: GEMINI_API_KEY path unchanged; OAuth is fallback only. ✓
+
+  summary:
+    total_steps: 18
+    estimated_files_changed: 10
+    estimated_files_created: 5
+    approach_justification: |
+      The plan uses additive factory methods (Embedder.create, SemanticEnricher.create)
+      rather than replacing synchronous constructors, preserving full backward
+      compatibility. The credential chain (env var → OAuth → error) is implemented
+      at the factory level, keeping the core Embedder/Enricher classes unaware of
+      auth complexity. AuthManager is instantiated per-command (no singleton), matching
+      the project's existing patterns. The loopback server uses a fixed default port
+      (3000) to simplify Google Cloud Console configuration while supporting fallback
+      to random ports. All new code follows existing conventions: NomosError codes,
+      Zod config schemas, Commander.js registration, Winston logging.