@build-astron-co/nimbus 0.2.0

package/src/enterprise/audit.ts

@@ -0,0 +1,348 @@
+/**
+ * Enterprise Audit - Audit logging and export.
+ *
+ * Embedded replacement for services/audit-service.
+ * All business logic is preserved verbatim from:
+ *   - services/audit-service/src/routes/logs.ts
+ *   - services/audit-service/src/routes/export.ts
+ *
+ * HTTP handlers, routes, and per-service SQLite are stripped.
+ * State is read/written through the unified database via ../state/audit.
+ *
+ * IMPORTANT: The unified audit schema (src/state/audit.ts) uses a different
+ * column layout from the audit-service schema.  The audit-service stored
+ * (team_id, user_id, action, resource_type, resource_id, status, details,
+ * ip_address) whereas the unified schema stores (user_id, action,
+ * resource_type, resource_id, input, output, status, duration_ms, metadata).
+ *
+ * This module adapts to the unified schema:
+ *   - "details" from the service is stored in "metadata" in the unified DB
+ *   - "ip_address" and "team_id" are stored inside "metadata" JSON
+ *   - The public return types mirror the original service API for callers
+ */
+
+import {
+  logAuditEvent as stateLogAuditEvent,
+  getAuditLogs as stateGetAuditLogs,
+  type AuditEventInput,
+  type AuditLogRecord as StateAuditLogRecord,
+  type AuditLogFilter,
+} from '../state/audit';
+
+// ---------------------------------------------------------------------------
+// Response type definitions (mirrors @nimbus/shared-types shapes and the
+// original audit-service AuditLogRecord used in export)
+// ---------------------------------------------------------------------------
+
+export interface AuditLog {
+  id: string;
+  timestamp: string;
+  teamId?: string;
+  userId?: string;
+  action: string;
+  resourceType?: string;
+  resourceId?: string;
+  status: string;
+  details?: Record<string, unknown>;
+  ipAddress?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Request type definitions
+// ---------------------------------------------------------------------------
+
+export interface CreateLogRequest {
+  action: string;
+  status: string;
+  teamId?: string;
+  userId?: string;
+  resourceType?: string;
+  resourceId?: string;
+  details?: Record<string, unknown>;
+  ipAddress?: string;
+}
+
+export interface QueryLogsParams {
+  teamId?: string;
+  userId?: string;
+  action?: string;
+  status?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ExportQueryParams {
+  teamId?: string;
+  userId?: string;
+  action?: string;
+  since?: string;
+  until?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a state AuditLogRecord to the public AuditLog API shape.
+ *
+ * The unified state module stores extra fields (team_id, ip_address, original
+ * service "details") inside the metadata JSON blob.  We unpack them here to
+ * reconstruct the original API surface.
+ */
+function stateRecordToLog(record: StateAuditLogRecord): AuditLog {
+  // Unpack metadata to recover service-level fields stored there
+  const meta: Record<string, unknown> =
+    typeof record.metadata === 'object' && record.metadata !== null
+      ? (record.metadata as Record<string, unknown>)
+      : {};
+
+  return {
+    id: record.id,
+    timestamp: record.timestamp,
+    teamId: (meta._teamId as string | undefined) ?? undefined,
+    userId: record.userId ?? undefined,
+    action: record.action,
+    resourceType: record.resourceType ?? undefined,
+    resourceId: record.resourceId ?? undefined,
+    status: record.status,
+    details: (meta._details as Record<string, unknown> | undefined) ?? undefined,
+    ipAddress: (meta._ipAddress as string | undefined) ?? undefined,
+  };
+}
+
+/**
+ * Build the metadata object that bundles service-level fields not present
+ * in the unified audit schema as top-level columns.
+ */
+function buildMetadata(
+  teamId?: string,
+  ipAddress?: string,
+  details?: Record<string, unknown>
+): Record<string, unknown> | undefined {
+  const meta: Record<string, unknown> = {};
+  let hasData = false;
+
+  if (teamId) {
+    meta._teamId = teamId;
+    hasData = true;
+  }
+  if (ipAddress) {
+    meta._ipAddress = ipAddress;
+    hasData = true;
+  }
+  if (details && Object.keys(details).length > 0) {
+    meta._details = details;
+    hasData = true;
+  }
+
+  return hasData ? meta : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// CSV / JSON export helpers (preserved verbatim from audit-service/src/routes/export.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape a field value for RFC 4180-compliant CSV output.
+ */
+function escapeCsvField(field: string): string {
+  if (field.includes(',') || field.includes('"') || field.includes('\n')) {
+    return `"${field.replace(/"/g, '""')}"`;
+  }
+  return field;
+}
+
+/**
+ * Serialize a list of AuditLog entries to CSV format.
+ */
+function exportToCsv(logs: AuditLog[]): string {
+  const headers = [
+    'id',
+    'timestamp',
+    'team_id',
+    'user_id',
+    'action',
+    'resource_type',
+    'resource_id',
+    'status',
+    'details',
+    'ip_address',
+  ];
+
+  const rows = logs.map(log => {
+    return [
+      escapeCsvField(log.id),
+      escapeCsvField(log.timestamp),
+      escapeCsvField(log.teamId || ''),
+      escapeCsvField(log.userId || ''),
+      escapeCsvField(log.action),
+      escapeCsvField(log.resourceType || ''),
+      escapeCsvField(log.resourceId || ''),
+      escapeCsvField(log.status),
+      escapeCsvField(log.details ? JSON.stringify(log.details) : ''),
+      escapeCsvField(log.ipAddress || ''),
+    ].join(',');
+  });
+
+  return [headers.join(','), ...rows].join('\n');
+}
+
+/**
+ * Serialize a list of AuditLog entries to pretty-printed JSON format.
+ */
+function exportToJson(logs: AuditLog[]): string {
+  return JSON.stringify({ logs, exportedAt: new Date().toISOString() }, null, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Public API - Log creation and querying
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an audit log entry.
+ *
+ * Writes to the unified audit_logs table via the state layer.
+ * Returns the created log entry with the generated ID and timestamp.
+ */
+export async function createLog(request: CreateLogRequest): Promise<AuditLog> {
+  const { action, status, teamId, userId, resourceType, resourceId, details, ipAddress } = request;
+
+  if (!action || !status) {
+    throw new Error('Action and status are required');
+  }
+
+  const id = crypto.randomUUID();
+  const metadata = buildMetadata(teamId, ipAddress, details);
+
+  const event: AuditEventInput = {
+    id,
+    userId,
+    action,
+    resourceType,
+    resourceId,
+    status,
+    metadata,
+  };
+
+  stateLogAuditEvent(event);
+
+  return {
+    id,
+    timestamp: new Date().toISOString(),
+    action,
+    status,
+    teamId,
+    userId,
+    resourceType,
+    resourceId,
+    details,
+    ipAddress,
+  };
+}
+
+/**
+ * Query audit logs with optional filters.
+ *
+ * Supports filtering by teamId, userId, action, status, and date range.
+ * Returns paginated results with a total count.
+ */
+export async function queryLogs(query: QueryLogsParams): Promise<{
+  logs: AuditLog[];
+  total: number;
+  limit: number;
+  offset: number;
+}> {
+  const limit = query.limit || 100;
+  const offset = query.offset || 0;
+
+  const filter: AuditLogFilter = {
+    userId: query.userId,
+    action: query.action,
+    status: query.status,
+    startDate: query.since ? new Date(query.since) : undefined,
+    endDate: query.until ? new Date(query.until) : undefined,
+    limit,
+    offset,
+  };
+
+  let records = stateGetAuditLogs(filter);
+
+  // If teamId is provided, post-filter by the _teamId stored in metadata,
+  // since the unified schema does not have a top-level team_id column.
+  if (query.teamId) {
+    records = records.filter(rec => {
+      const meta: Record<string, unknown> =
+        typeof rec.metadata === 'object' && rec.metadata !== null
+          ? (rec.metadata as Record<string, unknown>)
+          : {};
+      return meta._teamId === query.teamId;
+    });
+  }
+
+  // Count total matching records (without pagination) for the response envelope
+  const allRecords = stateGetAuditLogs({ ...filter, limit: 100_000, offset: 0 });
+  const filteredAll = query.teamId
+    ? allRecords.filter(rec => {
+        const meta: Record<string, unknown> =
+          typeof rec.metadata === 'object' && rec.metadata !== null
+            ? (rec.metadata as Record<string, unknown>)
+            : {};
+        return meta._teamId === query.teamId;
+      })
+    : allRecords;
+
+  return {
+    logs: records.map(stateRecordToLog),
+    total: filteredAll.length,
+    limit,
+    offset,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API - Export
+// ---------------------------------------------------------------------------
+
+/**
+ * Export audit logs in CSV or JSON format.
+ *
+ * Fetches up to 10,000 matching records (no pagination) and serializes them
+ * to the requested format string.
+ */
+export async function exportLogs(
+  format: 'csv' | 'json',
+  query: ExportQueryParams
+): Promise<string> {
+  const filter: AuditLogFilter = {
+    userId: query.userId,
+    action: query.action,
+    startDate: query.since ? new Date(query.since) : undefined,
+    endDate: query.until ? new Date(query.until) : undefined,
+    limit: 10_000,
+    offset: 0,
+  };
+
+  let records = stateGetAuditLogs(filter);
+
+  // Post-filter by teamId if provided (stored in metadata)
+  if (query.teamId) {
+    records = records.filter(rec => {
+      const meta: Record<string, unknown> =
+        typeof rec.metadata === 'object' && rec.metadata !== null
+          ? (rec.metadata as Record<string, unknown>)
+          : {};
+      return meta._teamId === query.teamId;
+    });
+  }
+
+  const logs = records.map(stateRecordToLog);
+
+  if (format === 'csv') {
+    return exportToCsv(logs);
+  }
+
+  return exportToJson(logs);
+}

package/src/enterprise/auth.ts

@@ -0,0 +1,270 @@
+/**
+ * Enterprise Auth - Device authorization flow and token management.
+ *
+ * Embedded replacement for services/auth-service.
+ * All business logic is preserved verbatim from:
+ *   - services/auth-service/src/routes/device-code.ts
+ *   - services/auth-service/src/routes/token.ts
+ *
+ * HTTP handlers, routes, and per-service SQLite are stripped.
+ * State is read/written through the unified database via ../state/credentials.
+ */
+
+import {
+  saveDeviceCode,
+  getDeviceCode,
+  updateDeviceCodeStatus,
+  saveToken,
+  getToken,
+  deleteToken,
+  type DeviceCodeRecord,
+  type TokenRecord,
+} from '../state/credentials';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEVICE_CODE_EXPIRY_SECONDS = 900; // 15 minutes
+const POLLING_INTERVAL_SECONDS = 5;
+
+// ---------------------------------------------------------------------------
+// Response type definitions (mirrors @nimbus/shared-types shapes)
+// ---------------------------------------------------------------------------
+
+export interface DeviceCodeResponse {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  expiresIn: number;
+  interval: number;
+}
+
+export interface DevicePollResponse {
+  accessToken?: string;
+  error?: string;
+  errorDescription?: string;
+}
+
+export interface DeviceVerifyRequest {
+  userCode: string;
+  userId: string;
+}
+
+export interface TokenValidateRequest {
+  accessToken: string;
+}
+
+export interface TokenValidateResponse {
+  valid: boolean;
+  userId?: string;
+  teamId?: string;
+  expiresAt?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a user-friendly code like "ABCD-1234".
+ * Excludes I and O to avoid visual confusion with 1 and 0.
+ */
+function generateUserCode(): string {
+  const letters = 'ABCDEFGHJKLMNPQRSTUVWXYZ';
+  const digits = '0123456789';
+
+  let code = '';
+  for (let i = 0; i < 4; i++) {
+    code += letters.charAt(Math.floor(Math.random() * letters.length));
+  }
+  code += '-';
+  for (let i = 0; i < 4; i++) {
+    code += digits.charAt(Math.floor(Math.random() * digits.length));
+  }
+  return code;
+}
+
+/**
+ * Generate a cryptographically secure device code (UUID v4).
+ */
+function generateDeviceCode(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Generate a 64-character hex access token using the Web Crypto API.
+ */
+function generateAccessToken(): string {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return Array.from(array, b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Delete a device code by transitioning it to the 'consumed' status.
+ * The unified credentials module uses status transitions rather than hard
+ * deletes so that `updateDeviceCodeStatus` covers both verification and
+ * consumption in a single call.
+ */
+function consumeDeviceCode(deviceCode: string): void {
+  updateDeviceCodeStatus(deviceCode, 'consumed');
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Initiate the OAuth 2.0 Device Authorization Grant flow (RFC 8628).
+ *
+ * Creates a new device code / user code pair in the unified database and
+ * returns the payload the CLI must display to the user.
+ */
+export async function initiateDeviceFlow(): Promise<DeviceCodeResponse> {
+  const deviceCode = generateDeviceCode();
+  const userCode = generateUserCode();
+  const expiresAt = new Date(Date.now() + DEVICE_CODE_EXPIRY_SECONDS * 1000);
+
+  saveDeviceCode(deviceCode, userCode, expiresAt);
+
+  return {
+    deviceCode,
+    userCode,
+    verificationUri: process.env.VERIFICATION_URI || 'https://nimbus.dev/device',
+    expiresIn: DEVICE_CODE_EXPIRY_SECONDS,
+    interval: POLLING_INTERVAL_SECONDS,
+  };
+}
+
+/**
+ * Poll for device code authorization.
+ *
+ * Returns an access token when the user has verified the code, or a
+ * structured error object while authorization is still pending / expired.
+ */
+export async function pollDeviceCode(deviceCode: string): Promise<DevicePollResponse> {
+  const record: DeviceCodeRecord | null = getDeviceCode(deviceCode);
+
+  if (!record) {
+    return {
+      error: 'expired_token',
+      errorDescription: 'The device code has expired or does not exist',
+    };
+  }
+
+  // Check expiry
+  if (new Date(record.expiresAt) < new Date()) {
+    // Mark consumed so subsequent polls return a consistent error
+    consumeDeviceCode(deviceCode);
+    return {
+      error: 'expired_token',
+      errorDescription: 'The device code has expired',
+    };
+  }
+
+  // The unified credentials module stores status as a string field.
+  // 'verified' status is set by verifyDeviceCode(); the associated userId
+  // is stored in the token field after verification.
+  if (record.status !== 'verified' || !record.token) {
+    return {
+      error: 'authorization_pending',
+      errorDescription: 'The user has not yet authorized this device',
+    };
+  }
+
+  // Generate access token
+  const accessToken = generateAccessToken();
+  const tokenExpiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+  const tokenId = crypto.randomUUID();
+  const userId = record.token; // userId was stored in the token field during verification
+
+  saveToken(tokenId, accessToken, 'access', userId, tokenExpiresAt);
+
+  // Consume the device code so it cannot be polled again
+  consumeDeviceCode(deviceCode);
+
+  return {
+    accessToken,
+  };
+}
+
+/**
+ * Verify a user code entered on the web verification page.
+ *
+ * Associates the given userId with the device code so that the next poll
+ * by the CLI will yield an access token.
+ */
+export async function verifyDeviceCode(
+  request: DeviceVerifyRequest
+): Promise<{ verified: boolean }> {
+  const { userCode, userId } = request;
+
+  if (!userCode || !userId) {
+    throw new Error('User code and user ID are required');
+  }
+
+  // Find the pending device code record by user code
+  // The unified credentials module looks up by device_code; we need to scan
+  // by user_code. We look it up directly via the state layer using a
+  // getDeviceCode call after resolving user_code -> device_code through a
+  // status update that embeds the userId in the token field.
+  //
+  // The unified state module's updateDeviceCodeStatus accepts (deviceCode,
+  // status, token?) and applies it by device_code PK. We cannot look up by
+  // user_code through this API alone, so we use the low-level getDb approach
+  // by importing the raw db helper and running the query ourselves, mirroring
+  // exactly what verifyDeviceCodeRecord() did in the original auth-service.
+  const { getDb } = await import('../state/db');
+  const db = getDb();
+
+  const stmt = db.prepare(
+    `UPDATE device_codes
+        SET status = 'verified', token = ?
+      WHERE user_code = ?
+        AND status = 'pending'
+        AND expires_at > CURRENT_TIMESTAMP`
+  );
+
+  const result = stmt.run(userId, userCode.toUpperCase()) as { changes: number };
+
+  if (result.changes === 0) {
+    throw new Error('Invalid or expired user code');
+  }
+
+  return { verified: true };
+}
+
+/**
+ * Validate an access token.
+ *
+ * Returns validity status plus the associated userId and optional teamId.
+ */
+export async function validateToken(request: TokenValidateRequest): Promise<TokenValidateResponse> {
+  const { accessToken } = request;
+
+  if (!accessToken) {
+    return { valid: false };
+  }
+
+  const record: TokenRecord | null = getToken(accessToken);
+
+  if (!record) {
+    return { valid: false };
+  }
+
+  // Check expiry if the token carries an expiry timestamp
+  if (record.expiresAt && new Date(record.expiresAt) < new Date()) {
+    deleteToken(accessToken);
+    return { valid: false };
+  }
+
+  return {
+    valid: true,
+    userId: record.userId ?? undefined,
+    // The unified token record does not store teamId; callers that need team
+    // context should resolve it via the teams module after token validation.
+    teamId: undefined,
+    expiresAt: record.expiresAt,
+  };
+}