@nomos-arc/arc 0.1.0

package/src/core/auth/__tests__/server.test.ts

@@ -0,0 +1,220 @@
+import * as http from 'node:http';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { Logger } from 'winston';
+
+// ─── Mocks ────────────────────────────────────────────────────────────────────
+
+const FIXED_STATE = 'deadbeef'.repeat(8); // 64-char hex — deterministic state for tests
+
+vi.mock('node:crypto', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:crypto')>();
+  return {
+    ...actual,
+    randomBytes: vi.fn((size: number) => {
+      // Return a buffer whose .toString('hex') yields FIXED_STATE
+      return Buffer.from(FIXED_STATE.slice(0, size * 2), 'hex');
+    }),
+  };
+});
+
+// Prevent actual browser launch in tests
+vi.mock('open', () => ({ default: vi.fn().mockResolvedValue(undefined) }));
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger(): Logger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+function makeMockOAuth2Client(tokenOverrides = {}) {
+  return {
+    generateAuthUrl: vi.fn().mockReturnValue('https://accounts.google.com/o/oauth2/auth?test=1'),
+    getToken: vi.fn().mockResolvedValue({
+      tokens: {
+        access_token: 'mock-access-token',
+        refresh_token: 'mock-refresh-token',
+        expiry_date: Date.now() + 3600_000,
+        token_type: 'Bearer',
+        scope: 'https://www.googleapis.com/auth/generative-language.retriever',
+        ...tokenOverrides,
+      },
+    }),
+    setCredentials: vi.fn(),
+  };
+}
+
+/** Make an HTTP GET request to the loopback server. Returns status + body. */
+async function httpGet(port: number, queryString: string): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    const req = http.get(`http://127.0.0.1:${port}/?${queryString}`, (res) => {
+      let body = '';
+      res.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+      res.on('end', () => resolve({ status: res.statusCode ?? 0, body }));
+    });
+    req.on('error', reject);
+  });
+}
+
+/** Find a free port by letting the OS assign one. */
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = http.createServer();
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address() as { port: number };
+      srv.close(() => resolve(addr.port));
+    });
+    srv.on('error', reject);
+  });
+}
+
+/** Wait a short tick for the server's listen callback to fire. */
+const tick = (ms = 50) => new Promise<void>(resolve => setTimeout(resolve, ms));
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('startLoopbackServer', () => {
+  let startLoopbackServer: (typeof import('../server.js'))['startLoopbackServer'];
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    ({ startLoopbackServer } = await import('../server.js'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // ─── 1. Port binding ──────────────────────────────────────────────────────
+
+  it('binds to the specified port and resolves with credentials', async () => {
+    const port = await getFreePort();
+    const oauth2Client = makeMockOAuth2Client();
+
+    const serverPromise = startLoopbackServer(
+      oauth2Client as never,
+      ['scope1'],
+      port,
+      makeLogger(),
+    );
+
+    await tick();
+    await httpGet(port, `code=auth-code-123&state=${FIXED_STATE}`);
+    const credentials = await serverPromise;
+
+    expect(credentials.access_token).toBe('mock-access-token');
+    expect(credentials.refresh_token).toBe('mock-refresh-token');
+  });
+
+  // ─── 2. Timeout ──────────────────────────────────────────────────────────
+
+  it('rejects after 120s timeout', async () => {
+    // getFreePort must be called before useFakeTimers (it uses real async I/O)
+    const port = await getFreePort();
+    vi.useFakeTimers();
+
+    const oauth2Client = makeMockOAuth2Client();
+    const serverPromise = startLoopbackServer(
+      oauth2Client as never,
+      ['scope1'],
+      port,
+      makeLogger(),
+    );
+
+    // Attach a rejection sink BEFORE advancing timers to avoid unhandled-rejection warning.
+    // The actual error is captured via `caught` below.
+    const caught = serverPromise.catch((e: unknown) => e);
+
+    // Advance past the 120s timeout — use async variant to flush the promise chain
+    await vi.advanceTimersByTimeAsync(120_001);
+
+    const err = await caught;
+    expect(err).toSatisfy(
+      (e: unknown) => e instanceof Error && /timed out/i.test((e as Error).message),
+    );
+  });
+
+  // ─── 3. Callback handling — valid code + state ────────────────────────────
+
+  it('resolves with credentials when code and state are valid', async () => {
+    const port = await getFreePort();
+    const oauth2Client = makeMockOAuth2Client({ access_token: 'correct-token' });
+
+    const serverPromise = startLoopbackServer(
+      oauth2Client as never,
+      ['scope1'],
+      port,
+      makeLogger(),
+    );
+
+    await tick();
+    const { status } = await httpGet(port, `code=valid-code&state=${FIXED_STATE}`);
+
+    expect(status).toBe(200);
+    const credentials = await serverPromise;
+    expect(credentials.access_token).toBe('correct-token');
+    expect(oauth2Client.getToken).toHaveBeenCalledWith('valid-code');
+  });
+
+  // ─── 4. CSRF state validation (F-002) ─────────────────────────────────────
+
+  it('returns 403 and does NOT exchange the code when state is wrong', async () => {
+    const port = await getFreePort();
+    const oauth2Client = makeMockOAuth2Client();
+
+    const serverPromise = startLoopbackServer(
+      oauth2Client as never,
+      ['scope1'],
+      port,
+      makeLogger(),
+    );
+
+    await tick();
+
+    const { status, body } = await httpGet(port, `code=stolen-code&state=wrong-state`);
+
+    expect(status).toBe(403);
+    expect(body).toMatch(/state mismatch/i);
+    // The code must NOT have been exchanged (F-002 validation)
+    expect(oauth2Client.getToken).not.toHaveBeenCalled();
+
+    // Server is still waiting for a valid callback — verify it hasn't resolved
+    const raceResult = await Promise.race([
+      serverPromise.then(() => 'resolved' as const),
+      tick(100).then(() => 'still-pending' as const),
+    ]);
+    expect(raceResult).toBe('still-pending');
+
+    // Clean up: send a valid request so the server can shut down gracefully
+    await httpGet(port, `code=cleanup-code&state=${FIXED_STATE}`);
+    await serverPromise;
+  });
+
+  // ─── 5. Cleanup — server is closed after successful callback ──────────────
+
+  it('closes the server after a successful callback', async () => {
+    const port = await getFreePort();
+    const oauth2Client = makeMockOAuth2Client();
+
+    const serverPromise = startLoopbackServer(
+      oauth2Client as never,
+      ['scope1'],
+      port,
+      makeLogger(),
+    );
+
+    await tick();
+    await httpGet(port, `code=cleanup-code&state=${FIXED_STATE}`);
+    await serverPromise;
+
+    // Give the server time to fully close
+    await tick(100);
+
+    // After resolution the port should be free — connecting should fail
+    await expect(httpGet(port, 'test=1')).rejects.toThrow();
+  });
+});

package/src/core/auth/gcp-projects.ts

@@ -0,0 +1,160 @@
+import * as readline from 'node:readline';
+import { NomosError } from '../errors.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface GcpProject {
+  projectId: string;
+  displayName: string;
+  state: string;
+}
+
+interface ProjectsListResponse {
+  projects?: Array<{
+    projectId: string;
+    displayName: string;
+    name: string;
+    state: string;
+  }>;
+  nextPageToken?: string;
+}
+
+// ─── List GCP Projects ───────────────────────────────────────────────────────
+
+/**
+ * Fetches all ACTIVE GCP projects accessible to the authenticated user.
+ * Uses the Cloud Resource Manager REST API directly (no googleapis dependency).
+ */
+export async function listGcpProjects(accessToken: string): Promise<GcpProject[]> {
+  const allProjects: GcpProject[] = [];
+  let pageToken: string | undefined;
+  const MAX_PAGES = 10; // safety cap
+
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const url = new URL('https://cloudresourcemanager.googleapis.com/v3/projects');
+    if (pageToken) url.searchParams.set('pageToken', pageToken);
+
+    const res = await fetch(url.toString(), {
+      headers: { 'Authorization': `Bearer ${accessToken}` },
+    });
+
+    if (!res.ok) {
+      if (res.status === 403 || res.status === 401) {
+        throw new NomosError(
+          'auth_gcp_projects_failed',
+          `Failed to list GCP projects (${res.status}). ` +
+          `Ensure your account has access to Google Cloud projects and the cloud-platform.read-only scope was granted.`,
+        );
+      }
+      throw new NomosError(
+        'auth_gcp_projects_failed',
+        `Failed to list GCP projects: ${res.status} ${res.statusText}`,
+      );
+    }
+
+    const data = (await res.json()) as ProjectsListResponse;
+    if (data.projects) {
+      for (const p of data.projects) {
+        if (p.state === 'ACTIVE') {
+          allProjects.push({
+            projectId: p.projectId,
+            displayName: p.displayName || p.projectId,
+            state: p.state,
+          });
+        }
+      }
+    }
+
+    if (!data.nextPageToken) break;
+    pageToken = data.nextPageToken;
+  }
+
+  // Sort alphabetically by display name
+  allProjects.sort((a, b) => a.displayName.localeCompare(b.displayName));
+  return allProjects;
+}
+
+// ─── Interactive Project Picker ──────────────────────────────────────────────
+
+/**
+ * Displays a numbered list of GCP projects and prompts the user to select one.
+ * Returns the selected projectId.
+ */
+export async function promptProjectSelection(
+  projects: GcpProject[],
+): Promise<string> {
+  console.log('\n  #   Project ID                        Display Name');
+  console.log('  ─── ──────────────────────────────── ────────────────────────');
+  for (let i = 0; i < projects.length; i++) {
+    const p = projects[i]!;
+    const num = String(i + 1).padStart(3);
+    const id = p.projectId.padEnd(36);
+    console.log(`  ${num} ${id} ${p.displayName}`);
+  }
+  console.log('');
+
+  const MAX_ATTEMPTS = 3;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const answer = await askQuestion(`Select project [1-${projects.length}]: `);
+    const index = parseInt(answer.trim(), 10);
+    if (!isNaN(index) && index >= 1 && index <= projects.length) {
+      return projects[index - 1]!.projectId;
+    }
+    console.log(`  Invalid selection. Enter a number between 1 and ${projects.length}.`);
+  }
+
+  throw new NomosError(
+    'auth_gcp_projects_failed',
+    'Project selection failed after 3 invalid attempts.',
+  );
+}
+
+// ─── Gemini API Health Check ─────────────────────────────────────────────────
+
+/**
+ * Verifies that the selected GCP project can be used for Gemini API billing.
+ * Makes a lightweight models.list call with the x-goog-user-project header.
+ * Throws a descriptive error on 403 (API not enabled) with a direct enable link.
+ */
+export async function verifyGeminiAccess(
+  accessToken: string,
+  quotaProjectId: string,
+): Promise<void> {
+  const res = await fetch(
+    'https://generativelanguage.googleapis.com/v1beta/models',
+    {
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'x-goog-user-project': quotaProjectId,
+      },
+    },
+  );
+
+  if (res.ok) return;
+
+  if (res.status === 403) {
+    throw new NomosError(
+      'auth_gemini_not_enabled',
+      `Generative Language API is not enabled on project "${quotaProjectId}".\n` +
+      `  Enable it: https://console.cloud.google.com/apis/library/generativelanguage.googleapis.com?project=${quotaProjectId}`,
+    );
+  }
+
+  // Non-403 errors are warnings, not blockers
+  // (the project may still work for billing even if this endpoint has issues)
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function askQuestion(prompt: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}

package/src/core/auth/manager.ts

@@ -0,0 +1,114 @@
+import * as fs from 'node:fs';
+import * as fsPromises from 'node:fs/promises';
+import * as path from 'node:path';
+import { OAuth2Client } from 'google-auth-library';
+import type { Logger } from 'winston';
+import { NomosError } from '../errors.js';
+import type { AuthCredentials, NomosConfig } from '../../types/index.js';
+
+export class AuthManager {
+  constructor(
+    private readonly authConfig: NomosConfig['auth'],
+    private readonly logger: Logger,
+  ) {}
+
+  async saveCredentials(tokens: AuthCredentials): Promise<void> {
+    const dir = path.dirname(this.authConfig.credentials_path);
+    await fsPromises.mkdir(dir, { recursive: true });
+    await fsPromises.writeFile(
+      this.authConfig.credentials_path,
+      JSON.stringify(tokens, null, 2),
+      { encoding: 'utf8' },
+    );
+    await fsPromises.chmod(this.authConfig.credentials_path, 0o600);
+    this.logger.info(`[nomos:auth:info] Credentials saved to ${this.authConfig.credentials_path}`);
+  }
+
+  // CONSTRAINT: DO NOT use readFileSync in any method that could be called in a loop
+  // or hot path. loadCredentials() is acceptable because it is only called during CLI
+  // startup (non-hot-path). (ref: F-008)
+  loadCredentials(): AuthCredentials | null {
+    try {
+      const raw = fs.readFileSync(this.authConfig.credentials_path, 'utf8');
+      const parsed = JSON.parse(raw) as unknown;
+      if (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        'access_token' in parsed &&
+        'refresh_token' in parsed &&
+        'expiry_date' in parsed &&
+        'token_type' in parsed &&
+        'scope' in parsed
+      ) {
+        return parsed as AuthCredentials;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  async getAuthenticatedClient(): Promise<OAuth2Client> {
+    const credentials = this.loadCredentials();
+    if (!credentials) {
+      throw new NomosError('auth_not_logged_in', 'Not logged in. Run `arc auth login` first.');
+    }
+
+    // SECURITY: client_id/secret are read from the credentials file (~/.nomos/credentials.json),
+    // NOT from project config (.nomos-config.json). They are saved there during `arc auth login`.
+    const oauth2Client = new OAuth2Client({
+      clientId: credentials.client_id ?? this.authConfig.client_id,
+      clientSecret: credentials.client_secret,
+    });
+
+    oauth2Client.setCredentials({
+      access_token: credentials.access_token,
+      refresh_token: credentials.refresh_token,
+      expiry_date: credentials.expiry_date,
+      token_type: credentials.token_type,
+      scope: credentials.scope,
+    });
+
+    if (credentials.expiry_date < Date.now()) {
+      const { credentials: refreshed } = await oauth2Client.refreshAccessToken();
+      const updatedTokens: AuthCredentials = {
+        access_token: refreshed.access_token ?? credentials.access_token,
+        refresh_token: refreshed.refresh_token ?? credentials.refresh_token,
+        expiry_date: refreshed.expiry_date ?? credentials.expiry_date,
+        token_type: refreshed.token_type ?? credentials.token_type,
+        scope: refreshed.scope ?? credentials.scope,
+      };
+      await this.saveCredentials(updatedTokens);
+      oauth2Client.setCredentials(updatedTokens);
+    }
+
+    return oauth2Client;
+  }
+
+  isLoggedIn(): boolean {
+    const credentials = this.loadCredentials();
+    return credentials !== null && typeof credentials.refresh_token === 'string' && credentials.refresh_token.length > 0;
+  }
+
+  async clearCredentials(): Promise<void> {
+    try {
+      await fsPromises.unlink(this.authConfig.credentials_path);
+      this.logger.info(`[nomos:auth:info] Credentials removed from ${this.authConfig.credentials_path}`);
+    } catch (err: unknown) {
+      if (typeof err === 'object' && err !== null && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
+        this.logger.info('[nomos:auth:info] No credentials file found — already logged out.');
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  async getAccessToken(): Promise<string> {
+    const client = await this.getAuthenticatedClient();
+    const tokenResponse = await client.getAccessToken();
+    if (!tokenResponse.token) {
+      throw new NomosError('auth_token_expired', 'Failed to retrieve access token from OAuth client.');
+    }
+    return tokenResponse.token;
+  }
+}

package/src/core/auth/server.ts

@@ -0,0 +1,141 @@
+import * as http from 'node:http';
+import * as net from 'node:net';
+import * as crypto from 'node:crypto';
+import { URL } from 'node:url';
+import open from 'open';
+import { OAuth2Client } from 'google-auth-library';
+import type { Logger } from 'winston';
+import { NomosError } from '../errors.js';
+import type { AuthCredentials } from '../../types/index.js';
+
+export async function startLoopbackServer(
+  oauth2Client: OAuth2Client,
+  scopes: string[],
+  port: number,
+  logger: Logger,
+): Promise<AuthCredentials> {
+  return new Promise((resolve, reject) => {
+    const sockets = new Set<net.Socket>();
+
+    // CSRF state parameter — CONSTRAINT: DO NOT exchange auth codes without
+    // validating state parameter (ref: F-002)
+    const state = crypto.randomBytes(32).toString('hex');
+
+    let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+
+    const cleanup = (): void => {
+      if (timeoutHandle !== null) {
+        clearTimeout(timeoutHandle);
+        timeoutHandle = null;
+      }
+      for (const socket of sockets) {
+        socket.destroy();
+      }
+      sockets.clear();
+      server.close();
+    };
+
+    const server = http.createServer((req, res) => {
+      if (!req.url) {
+        res.writeHead(400);
+        res.end('Bad Request');
+        return;
+      }
+
+      let parsedUrl: URL;
+      try {
+        parsedUrl = new URL(req.url, 'http://localhost');
+      } catch {
+        res.writeHead(400);
+        res.end('Bad Request');
+        return;
+      }
+
+      const receivedState = parsedUrl.searchParams.get('state');
+      const code = parsedUrl.searchParams.get('code');
+
+      // Validate CSRF state parameter
+      if (receivedState !== state) {
+        res.writeHead(403);
+        res.end('Authentication failed: state mismatch (possible CSRF attack).');
+        logger.warn('[nomos:auth:warn] OAuth callback rejected — state parameter mismatch.');
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400);
+        res.end('Missing authorization code.');
+        return;
+      }
+
+      oauth2Client.getToken(code)
+        .then(({ tokens }) => {
+          // CONSTRAINT: DO NOT log access_token, refresh_token, or client_secret (ref: audit)
+          const credentials: AuthCredentials = {
+            access_token: tokens.access_token ?? '',
+            refresh_token: tokens.refresh_token ?? '',
+            expiry_date: tokens.expiry_date ?? 0,
+            token_type: tokens.token_type ?? 'Bearer',
+            scope: tokens.scope ?? scopes.join(' '),
+          };
+
+          res.writeHead(200, {
+            'Content-Type': 'text/html',
+            'Connection': 'close',
+          });
+          res.end('<html><body><h1>Login successful!</h1><p>You can close this tab.</p></body></html>', () => {
+            cleanup();
+          });
+
+          resolve(credentials);
+        })
+        .catch((err: unknown) => {
+          res.writeHead(500);
+          res.end('Token exchange failed.');
+          cleanup();
+          reject(new NomosError('auth_login_failed', `OAuth token exchange failed: ${String(err)}`));
+        });
+    });
+
+    server.on('connection', (socket: net.Socket) => {
+      sockets.add(socket);
+      socket.once('close', () => sockets.delete(socket));
+    });
+
+    // Attempt to listen on requested port; fall back to random port on EADDRINUSE
+    server.listen(port, '127.0.0.1', () => {
+      const address = server.address() as net.AddressInfo;
+      const actualPort = address.port;
+      logger.info(`[nomos:auth:info] OAuth loopback server listening on port ${actualPort}`);
+
+      const redirectUri = `http://localhost:${actualPort}`;
+
+      const authUrl = oauth2Client.generateAuthUrl({
+        access_type: 'offline',
+        scope: scopes,
+        redirect_uri: redirectUri,
+        state,  // CSRF protection per RFC 6749 Section 10.12
+      });
+
+      // 120-second timeout
+      timeoutHandle = setTimeout(() => {
+        cleanup();
+        reject(new NomosError('auth_login_failed', 'Login timed out after 120 seconds.'));
+      }, 120_000);
+
+      open(authUrl).catch(() => {
+        logger.info(`[nomos:auth:info] Open this URL in your browser: ${authUrl}`);
+      });
+    });
+
+    server.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE') {
+        // Retry on a random port
+        server.listen(0, '127.0.0.1');
+      } else {
+        cleanup();
+        reject(new NomosError('auth_login_failed', `OAuth server error: ${err.message}`));
+      }
+    });
+  });
+}