@nomos-arc/arc 0.1.0

package/docs/auth/google_task.md

@@ -0,0 +1,235 @@
+# Blueprint: nomos-arc.ai Frictionless Authentication — OAuth 2.0 Login
+
+**Role:** Senior Full-Stack Engineer / CLI Specialist.
+**Objective:** Implement a "One-Click" Google Login for the `arc` CLI to replace manual `GEMINI_API_KEY` environment variable management.
+**Architecture:** OAuth 2.0 Authorization Code Flow with Local Loopback Server.
+
+---
+
+## 0. Motivation & Scope
+
+Currently, all Gemini API calls (`Embedder`, `enricher`) require `process.env['GEMINI_API_KEY']` to be set manually. This creates friction for onboarding and breaks the "local-first, offline-capable" developer experience.
+
+This task introduces an **OAuth 2.0 credential chain** that sits *behind* the existing API key check — if `GEMINI_API_KEY` is absent, the system transparently falls back to stored OAuth tokens. The API key path remains the primary, zero-config option for CI/CD and headless environments.
+
+**In scope:** `arc auth login`, `arc auth logout`, `arc auth status`, token persistence, credential chain fallback in `Embedder` and `enricher`.
+**Out of scope:** Google Cloud project provisioning, Vertex AI authentication, multi-account switching, UI/dashboard.
+
+---
+
+## 1. Technical Specifications
+
+| Feature | Specification |
+| :--- | :--- |
+| **Protocol** | OAuth 2.0 Authorization Code Flow (Desktop/CLI) |
+| **Scopes** | `https://www.googleapis.com/auth/generative-language` |
+| **Token Storage** | `~/.nomos/credentials.json` (file mode `0600`) |
+| **Client Config** | `~/.nomos/client_config.json` (user-provided `client_id` / `client_secret`) |
+| **Dependencies** | `google-auth-library`, `open` (browser launcher), Node.js built-in `http` |
+| **Auth Provider** | Google Generative Language API |
+| **Redirect URI** | `http://localhost:<dynamic-port>` (port selected at runtime) |
+
+---
+
+## 2. Design Constraints (Alignment with nomos-arc.ai Architecture)
+
+These constraints ensure the auth module integrates cleanly with existing patterns:
+
+1. **JSON is the source of truth.** Token state lives in `~/.nomos/credentials.json` (JSON). No Markdown side-files. Consistent with the project's "JSON source of truth; Markdown for humans" contract.
+2. **Error codes via `NomosError`.** All auth failures must use typed error codes registered in `src/core/errors.ts` (e.g., `auth_not_logged_in`, `auth_token_expired`, `auth_login_failed`). Never throw raw `Error`.
+3. **Commander.js registration pattern.** New commands follow the `registerXCommand(program)` pattern used by every existing command in `src/commands/`. Registered in `src/cli.ts`.
+4. **Config-driven.** OAuth client configuration should be loadable from `.nomos-config.json` under an `auth` key, with `~/.nomos/client_config.json` as the user-level override.
+5. **Security contract.** `client_secret` must never be logged. The sanitization pipeline (`src/utils/sanitize.ts`) must cover auth tokens if `security.sanitize_on` includes `"output"`.
+6. **No global state.** `AuthManager` is instantiated per-command, same as `Embedder`. No singletons, no module-level side effects.
+7. **Logging via Winston.** Use the project's existing `Logger` instance — no `console.log`.
+
+---
+
+## 3. Atomic Implementation Tasks
+
+### Task 0: Scaffolding & Types
+
+| Sub-task | Action | Validation |
+| :--- | :--- | :--- |
+| **0.1** | Install dependency: `npm install google-auth-library open` | `package.json` updated |
+| **0.2** | Add `AuthCredentials` interface to `src/types/index.ts`: `{ access_token, refresh_token, expiry_date, token_type, scope }` | TypeScript compiles |
+| **0.3** | Add `auth` section to `NomosConfig` in `src/types/index.ts`: `{ client_id?: string, client_secret?: string, credentials_path: string }` with default `~/.nomos/credentials.json` | Config schema validates |
+| **0.4** | Register new error codes in `src/core/errors.ts`: `auth_not_logged_in`, `auth_token_expired`, `auth_login_failed`, `auth_client_config_missing` | Type-checks pass |
+| **0.5** | Create directory: `src/core/auth/` | Directory exists |
+
+### Task 1: Auth Manager (`src/core/auth/manager.ts`)
+
+| Sub-task | Action | Validation |
+| :--- | :--- | :--- |
+| **1.1** | Implement `AuthManager` class accepting `NomosConfig['auth']` and `Logger` | Constructor doesn't throw |
+| **1.2** | Method `saveCredentials(tokens: AuthCredentials): Promise<void>` — write JSON to `credentials_path` with `fs.chmod(path, 0o600)` | File written with mode 600 |
+| **1.3** | Method `loadCredentials(): AuthCredentials \| null` — read and parse JSON, return `null` if file missing | Returns null on clean system |
+| **1.4** | Method `getAuthenticatedClient(): Promise<OAuth2Client>` — load tokens, check `expiry_date < Date.now()`, auto-refresh if expired via `oauth2Client.refreshAccessToken()`, persist new tokens | Refreshed token persisted |
+| **1.5** | Method `isLoggedIn(): boolean` — check file exists and contains `refresh_token` | Returns boolean |
+| **1.6** | Method `clearCredentials(): Promise<void>` — delete credentials file | File removed |
+
+### Task 2: Loopback Server (`src/core/auth/server.ts`)
+
+| Sub-task | Action | Validation |
+| :--- | :--- | :--- |
+| **2.1** | Implement `startLoopbackServer(oauth2Client, logger): Promise<AuthCredentials>` using Node.js built-in `http` module | Function signature correct |
+| **2.2** | Dynamically select an available port using `net.createServer().listen(0)` pattern (no external dependency needed) | Port assigned without conflict |
+| **2.3** | Generate auth URL: `oauth2Client.generateAuthUrl({ access_type: 'offline', scope: SCOPES, redirect_uri })` | URL contains correct params |
+| **2.4** | Open browser via `open(authUrl)` — log the URL as fallback if browser launch fails | Browser opens or URL printed |
+| **2.5** | Handle callback: extract `code` from `req.url`, exchange via `oauth2Client.getToken(code)`, respond with success HTML, destroy server | Tokens returned |
+| **2.6** | Implement 120-second timeout — if no callback received, destroy server and throw `auth_login_failed` | Server cleaned up on timeout |
+| **2.7** | Use `server.close()` + `socket.destroy()` pattern (track open sockets) to ensure no hanging connections | Process exits cleanly |
+
+### Task 3: CLI Commands (`src/commands/auth.ts`)
+
+Commands are registered as a **subcommand group** under `arc auth`:
+
+```
+arc auth login     # OAuth login flow
+arc auth logout    # Remove stored credentials
+arc auth status    # Show current auth state
+```
+
+| Sub-task | Action | Validation |
+| :--- | :--- | :--- |
+| **3.1** | Create `auth` subcommand group using Commander.js `.command('auth').description(...)` with nested `.command('login')`, `.command('logout')`, `.command('status')` | `arc auth --help` lists all subcommands |
+| **3.2** | `arc auth login` — create `OAuth2Client` from config, call `startLoopbackServer()`, save tokens via `AuthManager.saveCredentials()`, print success message | `credentials.json` created after login |
+| **3.3** | `arc auth login` — if `client_id` / `client_secret` not in config, prompt user interactively (or accept via `--client-id` / `--client-secret` flags) | Works with flags and interactive prompt |
+| **3.4** | `arc auth logout` — call `AuthManager.clearCredentials()`, confirm deletion to user | File removed, confirmation printed |
+| **3.5** | `arc auth status` — display login state: logged in (email, token expiry) or not logged in, and whether `GEMINI_API_KEY` is set | Accurate status printed |
+| **3.6** | Register in `src/cli.ts` via `registerAuthCommand(program)` pattern | `arc auth` appears in `arc --help` |
+
+### Task 4: Credential Chain Integration
+
+| Sub-task | Action | Validation |
+| :--- | :--- | :--- |
+| **4.1** | Modify `src/search/embedder.ts` constructor: if `GEMINI_API_KEY` is absent, attempt `AuthManager.getAuthenticatedClient()` | Embedder initializes without env var |
+| **4.2** | Modify `src/core/graph/enricher.ts` constructor: same credential chain fallback | Enricher initializes without env var |
+| **4.3** | Throw `search_api_key_missing` **only** if both API key and OAuth credentials are unavailable. Update error message: `"No credentials found. Set GEMINI_API_KEY or run: arc auth login"` | Error message updated |
+| **4.4** | Ensure `GoogleGenerativeAI` client can accept `OAuth2Client` auth — if SDK requires API key string only, use `oauth2Client.getAccessToken()` and pass as key | API calls succeed with OAuth token |
+
+### Task 5: Testing
+
+| Sub-task | Action | Validation |
+| :--- | :--- | :--- |
+| **5.1** | Unit tests for `AuthManager`: save/load/clear/isLoggedIn/refresh cycle | All pass |
+| **5.2** | Unit test for loopback server: mock HTTP callback, verify token exchange | Pass |
+| **5.3** | Integration test: credential chain in `Embedder` — mock OAuth path when no API key | Embedder constructs without `GEMINI_API_KEY` |
+| **5.4** | Test file permissions: verify `credentials.json` is written with mode `0600` | Permission check passes |
+
+---
+
+## 4. Authentication Flow (Sequence)
+
+```
+User                    CLI (arc auth login)         Browser              Google OAuth
+  |                          |                          |                      |
+  |--- arc auth login ------>|                          |                      |
+  |                          |-- start HTTP server      |                      |
+  |                          |   (localhost:<port>)      |                      |
+  |                          |-- open(authUrl) -------->|                      |
+  |                          |                          |--- user approves --->|
+  |                          |                          |<-- redirect ---------|
+  |                          |                          |   ?code=XYZ          |
+  |                          |<-- GET /?code=XYZ -------|                      |
+  |                          |-- exchange code -------->|--------------------->|
+  |                          |<-- tokens ---------------|<---------------------|
+  |                          |-- save credentials.json  |                      |
+  |                          |-- destroy server         |                      |
+  |<-- "Logged in!" ---------|                          |                      |
+  |                          |                          |                      |
+  |--- arc search "query" -->|                          |                      |
+  |                          |-- no GEMINI_API_KEY      |                      |
+  |                          |-- load credentials.json  |                      |
+  |                          |-- use OAuth2Client ----->|--------------------->|
+  |                          |<-- embeddings -----------|<---------------------|
+  |<-- search results -------|                          |                      |
+```
+
+---
+
+## 5. Credential Chain Resolution Order
+
+The following priority chain applies in `Embedder` and `enricher` constructors:
+
+```
+1. process.env['GEMINI_API_KEY']     →  GoogleGenerativeAI(apiKey)     [existing path]
+2. ~/.nomos/credentials.json          →  OAuth2Client(accessToken)      [new path]
+3. Neither available                  →  throw NomosError('search_api_key_missing', ...)
+```
+
+This preserves full backward compatibility. Existing users with `GEMINI_API_KEY` set see zero behavior change.
+
+---
+
+## 6. Known Risks & Migration Notes
+
+### Risk 1: Sync → Async Constructor (High Impact)
+
+`Embedder` and `SemanticEnricher` currently have **synchronous constructors** that read `GEMINI_API_KEY` from `process.env`. The OAuth fallback requires async operations (file I/O, token refresh). This means the constructor cannot remain synchronous.
+
+**Mitigation:** Introduce a static async factory method `Embedder.create(config, logger, authManager?)` and update all call sites. The existing `new Embedder(config, logger)` pattern must be replaced project-wide. All existing tests that use `new Embedder(...)` must be updated.
+
+**Affected call sites:** `src/search/indexer.ts`, `src/search/query-engine.ts`, `src/core/graph/pipeline.ts`, and their test files.
+
+### Risk 2: `@google/generative-ai` SDK + OAuth Token Compatibility (Medium Impact)
+
+The current SDK (`@google/generative-ai: ^0.24.1`) accepts an **API key string** in its constructor — not an `OAuth2Client`. There is no documented way to pass OAuth bearer tokens directly.
+
+**Mitigation options (investigate during Task 4):**
+1. Pass `access_token` as the API key string — some Google APIs accept this, but it's undocumented for this SDK. **Requires a spike test.**
+2. Switch to `@google-ai/generativelanguage` (lower-level SDK) which accepts `authClient` directly — but this changes the API surface for embedding and enrichment calls.
+3. Use `google-auth-library`'s `OAuth2Client` to manually set `Authorization: Bearer <token>` headers via a custom request interceptor.
+
+**Recommendation:** Start with option 1 (spike test). If it fails, fall back to option 3 which is non-invasive. Option 2 is last resort as it requires rewriting `Embedder` and `SemanticEnricher` internals.
+
+### Risk 3: Dynamic Port + Google Cloud Console Redirect URI
+
+Google OAuth requires the redirect URI to **exactly match** what's configured in the Cloud Console. A dynamic port (`listen(0)`) means the URI changes every time.
+
+**Mitigation:** Use a **fixed default port** (e.g., `3000`) with automatic fallback to a random port. Document that users should register `http://localhost:3000` in their Cloud Console. Alternatively, support a configurable `auth.redirect_port` in `.nomos-config.json`. Google Cloud Console also supports `http://localhost` (without port) for desktop apps — verify this during implementation.
+
+---
+
+## 7. Acceptance Criteria
+
+- [ ] `arc auth login` opens the default system browser and completes OAuth flow end-to-end.
+- [ ] After Google approval, `~/.nomos/credentials.json` is written with `refresh_token` for persistent sessions.
+- [ ] File permissions for `credentials.json` are `0600` (owner-only read/write).
+- [ ] `arc search` and `arc map` (with `--ai-enrichment`) work without `GEMINI_API_KEY` when OAuth credentials exist.
+- [ ] `arc search` and `arc map` still work with `GEMINI_API_KEY` (backward compatible, takes priority).
+- [ ] `arc auth logout` removes `credentials.json` and confirms to user.
+- [ ] `arc auth status` accurately reports login state and API key presence.
+- [ ] If both API key and OAuth are missing, error message mentions both `GEMINI_API_KEY` and `arc auth login`.
+- [ ] Loopback server self-destructs after receiving callback or after 120s timeout.
+- [ ] No `client_secret` or token values appear in Winston logs.
+- [ ] All new code follows existing patterns: `NomosError` codes, Commander.js registration, Winston logger injection.
+- [ ] Existing tests pass without modification (unless they touch refactored constructor signatures).
+
+---
+
+## 8. Files Modified / Created
+
+| File | Action | Description |
+| :--- | :--- | :--- |
+| `src/types/index.ts` | **Modify** | Add `AuthCredentials` interface, `auth` config section |
+| `src/core/errors.ts` | **Modify** | Add `auth_*` error codes to `NomosErrorCode` union |
+| `src/core/auth/manager.ts` | **Create** | Token persistence, refresh, credential chain |
+| `src/core/auth/server.ts` | **Create** | OAuth loopback HTTP server |
+| `src/commands/auth.ts` | **Create** | `arc auth` subcommand group (login / logout / status) |
+| `src/cli.ts` | **Modify** | Register `registerAuthCommand` |
+| `src/core/config.ts` | **Modify** | Add `AuthSchema` with defaults to Zod config |
+| `src/search/embedder.ts` | **Modify** | Credential chain fallback in constructor |
+| `src/core/graph/enricher.ts` | **Modify** | Credential chain fallback in constructor |
+| `package.json` | **Modify** | Add `google-auth-library`, `open` dependencies |
+
+---
+
+## 9. Implementation Notes
+
+- **No `portfinder` dependency.** Use Node.js built-in `net.createServer().listen(0)` to get a random available port. Fewer dependencies = smaller attack surface.
+- **`client_id` / `client_secret` handling:** These are user-provided (from their own Google Cloud Console project). They are NOT embedded in the CLI binary. Users provide them on first `arc auth login` or via `.nomos-config.json`.
+- **Socket tracking for clean shutdown:** Track connected sockets in a `Set<net.Socket>`, destroy all on server close. This replaces the need for `server-destroy`.
+- **`open` package:** Used only for browser launch. If it fails (headless server), log the URL for manual copy-paste.
+- **Token refresh is transparent:** `getAuthenticatedClient()` checks `expiry_date` and refreshes before returning. Callers never deal with expiry logic.
+- **Redirect URI must match exactly** what is configured in the Google Cloud Console (e.g., `http://localhost:PORT`). Since the port is dynamic, the Google Cloud Console OAuth config must use `http://localhost` with the port registered as a wildcard or the user must configure a fixed port.