@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/utils/secret-validation.ts

@@ -0,0 +1,273 @@
+/**
+ * Secret Validation Utilities
+ *
+ * Provides validation functions for various secret formats and types.
+ * Used during startup and secret rotation to ensure secret quality.
+ */
+
+import { randomBytes } from 'crypto'
+import { ValidationError } from './errors.js'
+
+/** API key format patterns for common providers */
+const API_KEY_PATTERNS = {
+  generic: /^[a-zA-Z0-9_-]{20,64}$/,
+  anthropic: /^sk-ant-[a-zA-Z0-9-_]{95,}$/,
+  openai: /^sk-[a-zA-Z0-9]{48,}$/,
+  stripe: /^sk_(live|test)_[a-zA-Z0-9]{24,}$/,
+  aws: /^AKIA[0-9A-Z]{16}$/,
+  google: /^AIza[0-9A-Za-z_-]{35}$/,
+} as const
+
+/** Database URL patterns */
+const DATABASE_URL_PATTERNS = {
+  postgresql: /^postgresql:\/\/([^:]+):([^@]+)@([^:]+):(\d+)\/(.+)$/,
+  mysql: /^mysql:\/\/([^:]+):([^@]+)@([^:]+):(\d+)\/(.+)$/,
+  mongodb: /^mongodb(?:\+srv)?:\/\/([^:]+):([^@]+)@([^/]+)\/(.+)$/,
+} as const
+
+const JWT_PATTERN = /^eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+$/
+
+export interface ApiKeyValidation {
+  valid: boolean
+  format?: keyof typeof API_KEY_PATTERNS
+  error?: string
+}
+
+export interface DatabaseUrlComponents {
+  type: 'postgresql' | 'mysql' | 'mongodb'
+  username: string
+  password: string
+  host: string
+  port: number
+  database: string
+}
+
+export interface SecretStrength {
+  entropy: number
+  strength: 'weak' | 'fair' | 'good' | 'strong'
+  diversity: {
+    hasLowercase: boolean
+    hasUppercase: boolean
+    hasNumbers: boolean
+    hasSymbols: boolean
+    uniqueChars: number
+  }
+  recommendations: string[]
+}
+
+/**
+ * Validate API key format
+ * @param apiKey - API key to validate
+ * @param expectedFormat - Optional expected format
+ * @returns Validation result
+ */
+export function validateApiKey(apiKey: string, expectedFormat?: keyof typeof API_KEY_PATTERNS): ApiKeyValidation {
+  if (!apiKey || apiKey.trim().length === 0) {
+    return { valid: false, error: 'API key cannot be empty' }
+  }
+
+  // If specific format expected, check only that format
+  if (expectedFormat) {
+    const pattern = API_KEY_PATTERNS[expectedFormat]
+    if (pattern.test(apiKey)) {
+      return { valid: true, format: expectedFormat }
+    }
+    return {
+      valid: false,
+      error: `API key does not match ${expectedFormat} format`,
+    }
+  }
+
+  // Check all known formats
+  for (const [format, pattern] of Object.entries(API_KEY_PATTERNS)) {
+    if (pattern.test(apiKey)) {
+      return {
+        valid: true,
+        format: format as keyof typeof API_KEY_PATTERNS,
+      }
+    }
+  }
+
+  // Not matching any known format
+  return {
+    valid: false,
+    error: 'API key format not recognized',
+  }
+}
+
+/**
+ * Validate and parse database URL
+ * @param url - Database connection URL
+ * @returns Parsed components
+ * @throws ValidationError if URL is invalid
+ */
+export function validateDatabaseUrl(url: string): DatabaseUrlComponents {
+  if (!url || url.trim().length === 0) {
+    throw new ValidationError('Database URL cannot be empty')
+  }
+
+  const parsers: Array<{
+    type: DatabaseUrlComponents['type']
+    pattern: RegExp
+    defaultPort?: number
+  }> = [
+    { type: 'postgresql', pattern: DATABASE_URL_PATTERNS.postgresql },
+    { type: 'mysql', pattern: DATABASE_URL_PATTERNS.mysql },
+    { type: 'mongodb', pattern: DATABASE_URL_PATTERNS.mongodb, defaultPort: 27017 },
+  ]
+
+  for (const { type, pattern, defaultPort } of parsers) {
+    const match = url.match(pattern)
+    if (match) {
+      return {
+        type,
+        username: decodeURIComponent(match[1]!),
+        password: decodeURIComponent(match[2]!),
+        host: match[3]!,
+        port: defaultPort ?? parseInt(match[4]!, 10),
+        database: type === 'mongodb' ? match[4]! : match[5]!,
+      }
+    }
+  }
+
+  throw new ValidationError('Invalid database URL format', {
+    url: ['URL must be in format: protocol://username:password@host:port/database'],
+  })
+}
+
+/**
+ * Check secret strength based on entropy and character diversity
+ * @param secret - Secret to check
+ * @returns Strength analysis
+ */
+export function checkSecretStrength(secret: string): SecretStrength {
+  const entropy = calculateEntropy(secret)
+  const diversity = analyzeCharacterDiversity(secret)
+  const recommendations: string[] = []
+
+  let strength: SecretStrength['strength']
+  if (entropy < 64) {
+    strength = 'weak'
+    recommendations.push('Increase length to at least 16 characters')
+  } else if (entropy < 96) {
+    strength = 'fair'
+    recommendations.push('Consider using at least 24 characters for better security')
+  } else if (entropy < 128) {
+    strength = 'good'
+  } else {
+    strength = 'strong'
+  }
+
+  if (!diversity.hasLowercase) recommendations.push('Add lowercase letters')
+  if (!diversity.hasUppercase) recommendations.push('Add uppercase letters')
+  if (!diversity.hasNumbers) recommendations.push('Add numbers')
+  if (!diversity.hasSymbols) recommendations.push('Add symbols for maximum security')
+  if (diversity.uniqueChars < secret.length * 0.5) {
+    recommendations.push('Increase character diversity (too many repeated characters)')
+  }
+
+  return { entropy, strength, diversity, recommendations }
+}
+
+/**
+ * Generate a cryptographically secure secret
+ * @param length - Length in bytes (default: 32)
+ * @param encoding - Output encoding (default: base64url)
+ * @returns Generated secret
+ */
+export function generateSecret(length: number = 32, encoding: 'hex' | 'base64' | 'base64url' = 'base64url'): string {
+  if (length < 16) {
+    throw new ValidationError('Secret length must be at least 16 bytes')
+  }
+
+  return randomBytes(length).toString(encoding)
+}
+
+/**
+ * Validate JWT token format
+ * @param token - Token to validate
+ * @returns True if valid JWT format
+ */
+export function validateJwtFormat(token: string): boolean {
+  return JWT_PATTERN.test(token)
+}
+
+/**
+ * Sanitize database URL for logging (hide credentials)
+ * @param url - Database URL
+ * @returns Sanitized URL with hidden credentials
+ */
+export function sanitizeDatabaseUrl(url: string): string {
+  try {
+    const parsed = validateDatabaseUrl(url)
+    return `${parsed.type}://[REDACTED]:[REDACTED]@${parsed.host}:${parsed.port}/${parsed.database}`
+  } catch {
+    return '[INVALID_DATABASE_URL]'
+  }
+}
+
+/**
+ * Check if a string appears to be a secret (high entropy, base64-like)
+ * @param value - String to check
+ * @returns True if likely a secret
+ */
+export function looksLikeSecret(value: string): boolean {
+  // Must be at least 16 chars
+  if (value.length < 16) {
+    return false
+  }
+
+  // Check entropy threshold
+  const entropy = calculateEntropy(value)
+  if (entropy < 64) {
+    return false
+  }
+
+  // Check if it's base64-like (alphanumeric + special chars)
+  const base64Like = /^[a-zA-Z0-9+/=_-]+$/
+  if (!base64Like.test(value)) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Calculate Shannon entropy of a string
+ * @param str - Input string
+ * @returns Entropy in bits
+ */
+export function calculateEntropy(str: string): number {
+  const len = str.length
+  if (len === 0) return 0
+
+  const frequencies = new Map<string, number>()
+  for (const char of str) {
+    frequencies.set(char, (frequencies.get(char) || 0) + 1)
+  }
+
+  let entropy = 0
+  for (const count of frequencies.values()) {
+    const p = count / len
+    entropy -= p * Math.log2(p)
+  }
+
+  return entropy * len
+}
+
+function analyzeCharacterDiversity(str: string) {
+  return {
+    hasLowercase: /[a-z]/.test(str),
+    hasUppercase: /[A-Z]/.test(str),
+    hasNumbers: /[0-9]/.test(str),
+    hasSymbols: /[^a-zA-Z0-9]/.test(str),
+    uniqueChars: new Set(str).size,
+  }
+}
+
+/** Export secret patterns for use in secret detection */
+export const SECRET_FORMAT_PATTERNS = {
+  apiKey: API_KEY_PATTERNS,
+  databaseUrl: DATABASE_URL_PATTERNS,
+  jwt: JWT_PATTERN,
+} as const

package/src/utils/synonyms.ts

@@ -0,0 +1,188 @@
+/**
+ * Shared Synonym and Query Expansion Utilities
+ *
+ * Provides centralized synonym mappings and abbreviation expansions
+ * for use across search and profile services.
+ */
+
+/**
+ * Common action/verb synonyms for query expansion.
+ * Keys are the base term, values are arrays of synonyms.
+ */
+export const ACTION_SYNONYMS: Readonly<Record<string, readonly string[]>> = {
+  create: ['make', 'build', 'generate', 'construct', 'establish'],
+  delete: ['remove', 'destroy', 'erase', 'eliminate', 'clear'],
+  update: ['modify', 'change', 'edit', 'revise', 'alter'],
+  search: ['find', 'look', 'query', 'seek', 'locate'],
+  get: ['retrieve', 'fetch', 'obtain', 'acquire', 'access'],
+  list: ['show', 'display', 'enumerate', 'view', 'browse'],
+  error: ['bug', 'issue', 'problem', 'fault', 'defect'],
+  fix: ['solve', 'resolve', 'repair', 'correct', 'patch'],
+  add: ['insert', 'append', 'include', 'attach', 'incorporate'],
+  start: ['begin', 'launch', 'initiate', 'commence', 'activate'],
+  stop: ['end', 'halt', 'terminate', 'cease', 'pause'],
+  send: ['transmit', 'dispatch', 'deliver', 'forward', 'submit'],
+} as const
+
+/**
+ * Common technical abbreviations with their full forms.
+ * Used for expanding abbreviated terms in queries.
+ */
+export const ABBREVIATION_EXPANSIONS: Readonly<Record<string, string>> = {
+  api: 'application programming interface',
+  db: 'database',
+  auth: 'authentication',
+  config: 'configuration',
+  env: 'environment',
+  var: 'variable',
+  func: 'function',
+  impl: 'implementation',
+  repo: 'repository',
+  deps: 'dependencies',
+  pkg: 'package',
+  src: 'source',
+  lib: 'library',
+  util: 'utility',
+  req: 'request',
+  res: 'response',
+  msg: 'message',
+  err: 'error',
+  doc: 'document',
+  docs: 'documentation',
+  dev: 'development',
+  prod: 'production',
+  ui: 'user interface',
+  ux: 'user experience',
+} as const
+
+/**
+ * Options for query expansion
+ */
+export interface QueryExpansionOptions {
+  /** Include synonym expansions (default: true) */
+  includeSynonyms?: boolean
+  /** Expand abbreviations (default: true) */
+  expandAbbreviations?: boolean
+  /** Maximum synonyms to include per term (default: 2) */
+  maxSynonymsPerTerm?: number
+  /** Custom synonym mappings to merge with defaults */
+  customSynonyms?: Record<string, string[]>
+  /** Custom abbreviation expansions to merge with defaults */
+  customAbbreviations?: Record<string, string>
+}
+
+/**
+ * Get synonyms for a given term.
+ *
+ * @param term - The term to find synonyms for (case-insensitive)
+ * @param limit - Maximum number of synonyms to return (default: all)
+ * @param customSynonyms - Additional synonyms to check
+ * @returns Array of synonyms, empty if none found
+ *
+ * @example
+ * ```typescript
+ * getSynonyms('create'); // ['make', 'build', 'generate', ...]
+ * getSynonyms('create', 2); // ['make', 'build']
+ * ```
+ */
+export function getSynonyms(term: string, limit?: number, customSynonyms?: Record<string, string[]>): string[] {
+  const lowerTerm = term.toLowerCase()
+  const allSynonyms = { ...ACTION_SYNONYMS, ...customSynonyms }
+  const synonyms = allSynonyms[lowerTerm]
+
+  if (!synonyms) {
+    return []
+  }
+
+  return limit !== undefined ? [...synonyms].slice(0, limit) : [...synonyms]
+}
+
+/**
+ * Expand an abbreviation to its full form.
+ *
+ * @param abbreviation - The abbreviation to expand (case-insensitive)
+ * @param customAbbreviations - Additional abbreviations to check
+ * @returns The expanded form, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * expandAbbreviation('api'); // 'application programming interface'
+ * expandAbbreviation('unknown'); // undefined
+ * ```
+ */
+export function expandAbbreviation(
+  abbreviation: string,
+  customAbbreviations?: Record<string, string>
+): string | undefined {
+  const lowerAbbr = abbreviation.toLowerCase()
+  const allAbbreviations = { ...ABBREVIATION_EXPANSIONS, ...customAbbreviations }
+  return allAbbreviations[lowerAbbr]
+}
+
+/**
+ * Expand a query by adding synonyms and expanding abbreviations.
+ *
+ * @param query - The original query string
+ * @param options - Expansion options
+ * @returns Expanded query string with additional terms
+ *
+ * @example
+ * ```typescript
+ * expandQuery('create api'); // 'create api make build application programming interface'
+ * expandQuery('fix db error', { maxSynonymsPerTerm: 1 }); // 'fix db error solve database bug'
+ * ```
+ */
+export function expandQuery(query: string, options: QueryExpansionOptions = {}): string {
+  const {
+    includeSynonyms = true,
+    expandAbbreviations = true,
+    maxSynonymsPerTerm = 2,
+    customSynonyms,
+    customAbbreviations,
+  } = options
+
+  const tokens = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((t) => t.length > 0)
+  const expanded: string[] = [...tokens]
+
+  if (includeSynonyms) {
+    for (const token of tokens) {
+      const synonyms = getSynonyms(token, maxSynonymsPerTerm, customSynonyms)
+      expanded.push(...synonyms)
+    }
+  }
+
+  if (expandAbbreviations) {
+    for (const token of tokens) {
+      const expansion = expandAbbreviation(token, customAbbreviations)
+      if (expansion) {
+        expanded.push(expansion)
+      }
+    }
+  }
+
+  // Remove duplicates and return
+  return [...new Set(expanded)].join(' ')
+}
+
+/**
+ * Check if a term has known synonyms.
+ *
+ * @param term - The term to check
+ * @returns True if synonyms exist for this term
+ */
+export function hasSynonyms(term: string): boolean {
+  return term.toLowerCase() in ACTION_SYNONYMS
+}
+
+/**
+ * Check if a term is a known abbreviation.
+ *
+ * @param term - The term to check
+ * @returns True if this is a known abbreviation
+ */
+export function isAbbreviation(term: string): boolean {
+  return term.toLowerCase() in ABBREVIATION_EXPANSIONS
+}