@brainfish-ai/devdoc 0.1.21

package/renderer/lib/api-docs/agent/types.ts

@@ -0,0 +1,116 @@
+/**
+ * Agent Mode Types
+ * Types for the AI-powered API documentation assistant
+ */
+
+import type { BrainfishRESTRequest } from '../types'
+
+// Chat message types
+export interface AgentMessage {
+  id: string
+  role: 'user' | 'assistant' | 'system'
+  content: string
+  createdAt: Date
+  toolInvocations?: ToolInvocation[]
+}
+
+export interface ToolInvocation {
+  toolCallId: string
+  toolName: string
+  args: Record<string, unknown>
+  result?: unknown
+  state: 'pending' | 'result' | 'error'
+}
+
+// Endpoint index for AI context
+export interface EndpointIndex {
+  id: string
+  name: string
+  method: string
+  path: string
+  description: string | null
+  parameters: string[]
+  hasBody: boolean
+  tags: string[]
+}
+
+// Prefill data from agent
+export interface PrefillData {
+  params?: Array<{ key: string; value: string }>
+  headers?: Array<{ key: string; value: string }>
+  body?: string
+  pathVariables?: Array<{ key: string; value: string }>
+}
+
+// Agent context state
+export interface AgentState {
+  mode: 'agent' | 'docs'
+  messages: AgentMessage[]
+  isLoading: boolean
+  currentEndpoint: BrainfishRESTRequest | null
+}
+
+// Tool definitions
+export type AgentToolName = 
+  | 'search_endpoints'
+  | 'navigate_to_endpoint'
+  | 'prefill_parameters'
+  | 'get_endpoint_details'
+  | 'get_current_request'
+  | 'check_request_validity'
+  | 'send_request'
+  | 'switch_to_notes'
+  | 'list_notes'
+  | 'open_file'
+  | 'create_folder'
+  | 'create_file'
+  | 'write_file'
+  | 'delete_file'
+
+// Request validation result
+export interface RequestValidationResult {
+  isValid: boolean
+  endpoint: {
+    id: string
+    name: string
+    method: string
+    path: string
+  }
+  validation: {
+    pathParams: {
+      required: string[]
+      filled: string[]
+      missing: string[]
+    }
+    queryParams: {
+      required: string[]
+      filled: string[]
+      missing: string[]
+    }
+    body: {
+      required: boolean
+      hasContent: boolean
+      requiredFields: string[]
+      missingFields: string[]
+    }
+    auth: {
+      required: boolean
+      configured: boolean
+      type: string | null
+    }
+  }
+  summary: string
+}
+
+// Search results
+export interface EndpointSearchResult {
+  endpoint: EndpointIndex
+  score: number
+  matchReason: string
+}
+
+// Navigation action
+export interface NavigationAction {
+  endpointId: string
+  reason: string
+}

package/renderer/lib/api-docs/auth/auth-context.tsx

@@ -0,0 +1,225 @@
+'use client'
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+  type ReactNode,
+} from 'react'
+import type { BrainfishRESTAuth } from '../types'
+import { authStorage, fetchDeviceId } from './auth-storage'
+
+/** Security scheme info from OpenAPI spec */
+export interface SpecSecurityScheme {
+  name: string
+  type: 'basic' | 'bearer' | 'api-key' | 'oauth2' | 'none'
+  auth: BrainfishRESTAuth
+  description?: string
+}
+
+interface AuthContextValue {
+  /** Current global authentication configuration */
+  globalAuth: BrainfishRESTAuth | null
+  /** Whether global auth is configured and active */
+  isAuthenticated: boolean
+  /** Set the global authentication */
+  setGlobalAuth: (auth: BrainfishRESTAuth) => void
+  /** Clear the global authentication */
+  clearAuth: () => void
+  /** Get effective auth for an endpoint (global or override) */
+  getEffectiveAuth: (endpointAuth: BrainfishRESTAuth) => BrainfishRESTAuth
+  /** Check if using global auth for an endpoint */
+  isUsingGlobalAuth: (endpointAuth: BrainfishRESTAuth) => boolean
+  /** Security schemes from the OpenAPI spec */
+  specSchemes: SpecSecurityScheme[]
+  /** Default auth recommended by the spec */
+  specDefaultAuth: BrainfishRESTAuth | null
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null)
+
+const DEFAULT_AUTH: BrainfishRESTAuth = { authType: 'none', authActive: true }
+
+interface AuthProviderProps {
+  children: ReactNode
+}
+
+export function AuthProvider({ children }: AuthProviderProps) {
+  const [globalAuth, setGlobalAuthState] = useState<BrainfishRESTAuth | null>(null)
+  const [isInitialized, setIsInitialized] = useState(false)
+  const [specSchemes, setSpecSchemes] = useState<SpecSecurityScheme[]>([])
+  const [specDefaultAuth, setSpecDefaultAuth] = useState<BrainfishRESTAuth | null>(null)
+  const deviceIdRef = useRef<string | null>(null)
+
+  // Load auth from localStorage on mount (async with encryption)
+  useEffect(() => {
+    async function initializeAuth() {
+      try {
+        // Fetch device ID from backend (required for encryption)
+        const deviceId = await fetchDeviceId()
+        deviceIdRef.current = deviceId
+
+        // Load encrypted auth from storage
+        const stored = await authStorage.load(deviceId)
+        if (stored) {
+          setGlobalAuthState(stored)
+        }
+
+        // Fetch security schemes from the spec
+        const schemesResponse = await fetch('/api/auth-schemes')
+        if (schemesResponse.ok) {
+          const data = await schemesResponse.json()
+          setSpecSchemes(data.schemes || [])
+          setSpecDefaultAuth(data.defaultAuth || null)
+        }
+      } catch (error) {
+        console.error('[AuthProvider] Failed to initialize auth:', error)
+        // Clear any potentially corrupted data
+        authStorage.clear()
+      } finally {
+        setIsInitialized(true)
+      }
+    }
+
+    initializeAuth()
+  }, [])
+
+  const setGlobalAuth = useCallback(async (auth: BrainfishRESTAuth) => {
+    if (!deviceIdRef.current) {
+      console.error('[AuthProvider] Cannot save auth: no device ID')
+      return
+    }
+    setGlobalAuthState(auth)
+    await authStorage.save(auth, deviceIdRef.current)
+  }, [])
+
+  const clearAuth = useCallback(() => {
+    setGlobalAuthState(null)
+    authStorage.clear()
+  }, [])
+
+  /**
+   * Get effective auth for an endpoint
+   * - If endpoint has 'inherit' auth type, use global auth
+   * - If endpoint has 'none' auth type and global is set, use global
+   * - Otherwise use endpoint's own auth
+   */
+  const getEffectiveAuth = useCallback(
+    (endpointAuth: BrainfishRESTAuth): BrainfishRESTAuth => {
+      // If endpoint explicitly wants to inherit, use global
+      if (endpointAuth.authType === 'inherit') {
+        return globalAuth || DEFAULT_AUTH
+      }
+
+      // If endpoint has no auth but global is configured, suggest global
+      // but don't override - this allows explicit "no auth" endpoints
+      if (endpointAuth.authType === 'none' && globalAuth && globalAuth.authType !== 'none') {
+        // Return global auth but the UI should indicate it's using global
+        return globalAuth
+      }
+
+      // Use endpoint's own auth
+      return endpointAuth
+    },
+    [globalAuth]
+  )
+
+  /**
+   * Check if an endpoint is using global auth
+   */
+  const isUsingGlobalAuth = useCallback(
+    (endpointAuth: BrainfishRESTAuth): boolean => {
+      if (!globalAuth || globalAuth.authType === 'none') {
+        return false
+      }
+
+      // Using global if inheriting or if endpoint has no auth
+      return (
+        endpointAuth.authType === 'inherit' ||
+        endpointAuth.authType === 'none'
+      )
+    },
+    [globalAuth]
+  )
+
+  const isAuthenticated =
+    globalAuth !== null && globalAuth.authType !== 'none'
+
+  const value: AuthContextValue = {
+    globalAuth,
+    isAuthenticated,
+    setGlobalAuth,
+    clearAuth,
+    getEffectiveAuth,
+    isUsingGlobalAuth,
+    specSchemes,
+    specDefaultAuth,
+  }
+
+  // Don't render until we've checked sessionStorage
+  if (!isInitialized) {
+    return null
+  }
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext)
+  if (!context) {
+    throw new Error('useAuth must be used within an AuthProvider')
+  }
+  return context
+}
+
+/**
+ * Get a human-readable label for auth type
+ */
+export function getAuthTypeLabel(auth: BrainfishRESTAuth | null | undefined): string {
+  if (!auth || !auth.authType) {
+    return 'Not configured'
+  }
+  
+  switch (auth.authType) {
+    case 'none':
+      return 'No Auth'
+    case 'inherit':
+      return 'Inherited'
+    case 'basic':
+      return 'Basic Auth'
+    case 'bearer':
+      return 'Bearer Token'
+    case 'api-key':
+      return `API Key (${auth.key || 'key'})`
+    case 'oauth-2':
+      return 'OAuth 2.0'
+    default:
+      return 'Not configured'
+  }
+}
+
+/**
+ * Get a masked preview of auth value
+ */
+export function getAuthPreview(auth: BrainfishRESTAuth): string {
+  switch (auth.authType) {
+    case 'none':
+    case 'inherit':
+      return ''
+    case 'basic':
+      return auth.username ? `${auth.username}:****` : ''
+    case 'bearer':
+      return auth.token ? `${auth.token.slice(0, 8)}••••` : ''
+    case 'api-key':
+      return auth.value ? `${auth.value.slice(0, 4)}••••` : ''
+    case 'oauth-2':
+      return auth.grantTypeInfo.token
+        ? `${auth.grantTypeInfo.token.slice(0, 8)}••••`
+        : ''
+    default:
+      return ''
+  }
+}

package/renderer/lib/api-docs/auth/auth-storage.ts

@@ -0,0 +1,87 @@
+'use client'
+
+import type { BrainfishRESTAuth } from '../types'
+import { encrypt, decrypt } from './crypto'
+
+const AUTH_STORAGE_KEY = 'brainfish-api-global-auth'
+
+export interface StoredAuth {
+  globalAuth: BrainfishRESTAuth
+  timestamp: number
+}
+
+/**
+ * Fetch device ID from backend API
+ * The device ID is stored in an httpOnly cookie
+ * Throws error if device ID cannot be fetched (no fallback)
+ */
+export async function fetchDeviceId(): Promise<string> {
+  const response = await fetch('/api/device', {
+    credentials: 'include',
+  })
+  if (!response.ok) {
+    throw new Error('Failed to fetch device ID')
+  }
+  const data = await response.json()
+  if (!data.deviceId) {
+    throw new Error('No device ID returned from server')
+  }
+  return data.deviceId
+}
+
+/**
+ * Encrypted localStorage wrapper for global authentication
+ * Uses device ID from backend as encryption key
+ * No fallbacks - encryption is required
+ */
+export const authStorage = {
+  /**
+   * Save auth configuration to localStorage (encrypted)
+   * Requires valid device ID - throws if missing
+   */
+  async save(auth: BrainfishRESTAuth, deviceId: string): Promise<void> {
+    if (!deviceId) {
+      throw new Error('Device ID required for secure storage')
+    }
+    const data: StoredAuth = {
+      globalAuth: auth,
+      timestamp: Date.now(),
+    }
+    const encrypted = await encrypt(JSON.stringify(data), deviceId)
+    localStorage.setItem(AUTH_STORAGE_KEY, encrypted)
+  },
+
+  /**
+   * Load auth configuration from localStorage (decrypted)
+   * Returns null if no data or decryption fails
+   */
+  async load(deviceId: string): Promise<BrainfishRESTAuth | null> {
+    if (!deviceId) return null
+    
+    const stored = localStorage.getItem(AUTH_STORAGE_KEY)
+    if (!stored) return null
+
+    try {
+      const jsonData = await decrypt(stored, deviceId)
+      const data = JSON.parse(jsonData) as StoredAuth
+      
+      if (!data.globalAuth?.authType) {
+        localStorage.removeItem(AUTH_STORAGE_KEY)
+        return null
+      }
+      
+      return data.globalAuth
+    } catch {
+      // Decryption failed - clear corrupted/invalid data
+      localStorage.removeItem(AUTH_STORAGE_KEY)
+      return null
+    }
+  },
+
+  /**
+   * Clear stored auth configuration
+   */
+  clear(): void {
+    localStorage.removeItem(AUTH_STORAGE_KEY)
+  },
+}

package/renderer/lib/api-docs/auth/crypto.ts

@@ -0,0 +1,89 @@
+'use client'
+
+/**
+ * Web Crypto API utilities for encrypting/decrypting auth credentials
+ * Uses AES-GCM with a key derived from device ID
+ */
+
+const ALGORITHM = 'AES-GCM'
+const KEY_LENGTH = 256
+const IV_LENGTH = 12 // 96 bits for AES-GCM
+
+/**
+ * Derive a crypto key from a device ID using PBKDF2
+ */
+async function deriveKey(deviceId: string): Promise<CryptoKey> {
+  const encoder = new TextEncoder()
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(deviceId),
+    'PBKDF2',
+    false,
+    ['deriveKey']
+  )
+
+  // Use a fixed salt (could be made dynamic per-user if needed)
+  const salt = encoder.encode('brainfish-api-docs-v1')
+
+  return crypto.subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt,
+      iterations: 100000,
+      hash: 'SHA-256',
+    },
+    keyMaterial,
+    { name: ALGORITHM, length: KEY_LENGTH },
+    false,
+    ['encrypt', 'decrypt']
+  )
+}
+
+/**
+ * Encrypt a string using AES-GCM with device ID as key
+ */
+export async function encrypt(plaintext: string, deviceId: string): Promise<string> {
+  const key = await deriveKey(deviceId)
+  const encoder = new TextEncoder()
+  const data = encoder.encode(plaintext)
+
+  // Generate random IV
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH))
+
+  const encrypted = await crypto.subtle.encrypt(
+    { name: ALGORITHM, iv },
+    key,
+    data
+  )
+
+  // Combine IV + encrypted data and encode as base64
+  const combined = new Uint8Array(iv.length + encrypted.byteLength)
+  combined.set(iv)
+  combined.set(new Uint8Array(encrypted), iv.length)
+
+  return btoa(String.fromCharCode(...combined))
+}
+
+/**
+ * Decrypt a string using AES-GCM with device ID as key
+ */
+export async function decrypt(ciphertext: string, deviceId: string): Promise<string> {
+  const key = await deriveKey(deviceId)
+
+  // Decode base64
+  const combined = Uint8Array.from(atob(ciphertext), (c) => c.charCodeAt(0))
+
+  // Extract IV and encrypted data
+  const iv = combined.slice(0, IV_LENGTH)
+  const encrypted = combined.slice(IV_LENGTH)
+
+  const decrypted = await crypto.subtle.decrypt(
+    { name: ALGORITHM, iv },
+    key,
+    encrypted
+  )
+
+  const decoder = new TextDecoder()
+  return decoder.decode(decrypted)
+}
+

package/renderer/lib/api-docs/auth/index.ts

@@ -0,0 +1,4 @@
+export { AuthProvider, useAuth, getAuthTypeLabel, getAuthPreview } from './auth-context'
+export type { SpecSecurityScheme } from './auth-context'
+export { authStorage, fetchDeviceId } from './auth-storage'
+export { encrypt, decrypt } from './crypto'

package/renderer/lib/api-docs/code-editor/db.ts

@@ -0,0 +1,164 @@
+import Dexie, { type Table } from 'dexie'
+import type { Workspace, NoteFile, EditorState } from './types'
+
+/**
+ * Simplified database for Notes workspace
+ * - One workspace per API (not multiple projects)
+ * - Notes are files for brainstorming (code, diagrams, markdown)
+ */
+class NotesDatabase extends Dexie {
+  workspaces!: Table<Workspace>
+  notes!: Table<NoteFile>
+  editorStates!: Table<EditorState>
+
+  constructor() {
+    super('brainfish-notes')
+    
+    this.version(1).stores({
+      // Single workspace per API
+      workspaces: 'id, apiSpecUrl, updatedAt',
+      
+      // Notes/files in workspace
+      notes: 'id, workspaceId, [workspaceId+path], updatedAt',
+      
+      // Editor state per workspace
+      editorStates: 'workspaceId',
+    })
+  }
+}
+
+// Singleton database instance
+export const db = new NotesDatabase()
+
+/**
+ * Generate a workspace ID from API spec URL
+ */
+export function getWorkspaceId(apiSpecUrl: string): string {
+  // Simple hash for consistent ID
+  let hash = 0
+  for (let i = 0; i < apiSpecUrl.length; i++) {
+    const char = apiSpecUrl.charCodeAt(i)
+    hash = ((hash << 5) - hash) + char
+    hash = hash & hash // Convert to 32-bit integer
+  }
+  return `ws-${Math.abs(hash).toString(16)}`
+}
+
+/**
+ * Database operations - simplified for notes workspace
+ */
+export const dbOperations = {
+  // Workspace operations (auto-created, one per API)
+  
+  async getOrCreateWorkspace(apiSpecUrl: string, name: string): Promise<Workspace> {
+    const id = getWorkspaceId(apiSpecUrl)
+    
+    let workspace = await db.workspaces.get(id)
+    
+    if (!workspace) {
+      workspace = {
+        id,
+        name,
+        apiSpecUrl,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }
+      await db.workspaces.add(workspace)
+    }
+    
+    return workspace
+  },
+
+  async getWorkspace(id: string): Promise<Workspace | undefined> {
+    return db.workspaces.get(id)
+  },
+
+  async updateWorkspace(id: string, updates: Partial<Workspace>): Promise<void> {
+    await db.workspaces.update(id, {
+      ...updates,
+      updatedAt: new Date(),
+    })
+  },
+
+  // Note/file operations
+  
+  async createNote(workspaceId: string, path: string, content: string = ''): Promise<NoteFile> {
+    const note: NoteFile = {
+      id: crypto.randomUUID(),
+      workspaceId,
+      path,
+      content,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }
+    await db.notes.add(note)
+    
+    // Update workspace timestamp
+    await db.workspaces.update(workspaceId, { updatedAt: new Date() })
+    
+    return note
+  },
+
+  async getNote(workspaceId: string, path: string): Promise<NoteFile | undefined> {
+    return db.notes
+      .where('[workspaceId+path]')
+      .equals([workspaceId, path])
+      .first()
+  },
+
+  async listNotes(workspaceId: string): Promise<NoteFile[]> {
+    return db.notes
+      .where('workspaceId')
+      .equals(workspaceId)
+      .toArray()
+  },
+
+  async updateNote(workspaceId: string, path: string, content: string): Promise<void> {
+    await db.notes
+      .where('[workspaceId+path]')
+      .equals([workspaceId, path])
+      .modify({
+        content,
+        updatedAt: new Date(),
+      })
+    
+    await db.workspaces.update(workspaceId, { updatedAt: new Date() })
+  },
+
+  async deleteNote(workspaceId: string, path: string): Promise<void> {
+    await db.notes
+      .where('[workspaceId+path]')
+      .equals([workspaceId, path])
+      .delete()
+    
+    await db.workspaces.update(workspaceId, { updatedAt: new Date() })
+  },
+
+  async renameNote(workspaceId: string, oldPath: string, newPath: string): Promise<void> {
+    await db.notes
+      .where('[workspaceId+path]')
+      .equals([workspaceId, oldPath])
+      .modify({
+        path: newPath,
+        updatedAt: new Date(),
+      })
+    
+    await db.workspaces.update(workspaceId, { updatedAt: new Date() })
+  },
+
+  // Editor state operations
+  
+  async getEditorState(workspaceId: string): Promise<EditorState | undefined> {
+    return db.editorStates.get(workspaceId)
+  },
+
+  async saveEditorState(state: EditorState): Promise<void> {
+    await db.editorStates.put(state)
+  },
+
+  // Clear all notes in workspace (reset)
+  async clearWorkspace(workspaceId: string): Promise<void> {
+    await db.notes.where('workspaceId').equals(workspaceId).delete()
+    await db.editorStates.delete(workspaceId)
+  },
+}