spindb 0.31.4 → 0.33.1

package/core/credential-manager.ts

@@ -0,0 +1,257 @@
+/**
+ * Credential Manager
+ *
+ * Manages saved database credentials on disk.
+ * Credentials are stored as .env files in the container's credentials/ directory.
+ */
+
+import { existsSync } from 'fs'
+import { readFile, writeFile, readdir, mkdir, chmod } from 'fs/promises'
+import { join } from 'path'
+import { paths } from '../config/paths'
+import { Engine, type UserCredentials } from '../types'
+import { isValidUsername } from './error-handler'
+
+/**
+ * Get the credentials directory for a container.
+ */
+function getCredentialsDir(containerName: string, engine: Engine): string {
+  const containerPath = paths.getContainerPath(containerName, { engine })
+  return join(containerPath, 'credentials')
+}
+
+/**
+ * Get the credential file path for a specific username.
+ * Validates the username to prevent path traversal (same rules as assertValidUsername).
+ */
+function getCredentialFilePath(
+  containerName: string,
+  engine: Engine,
+  username: string,
+): string {
+  if (!isValidUsername(username)) {
+    throw new Error(
+      `Invalid username for credential file: "${username}". Must match ^[a-zA-Z][a-zA-Z0-9_]{0,62}$`,
+    )
+  }
+  return join(getCredentialsDir(containerName, engine), `.env.${username}`)
+}
+
+/**
+ * Format credentials as .env file content.
+ */
+function encodeEnvValue(value: string): string {
+  if (/[\n\r=\\]/.test(value)) {
+    return JSON.stringify(value)
+  }
+  return value
+}
+
+function decodeEnvValue(raw: string): string {
+  if (raw.startsWith('"') && raw.endsWith('"')) {
+    try {
+      return JSON.parse(raw) as string
+    } catch {
+      return raw
+    }
+  }
+  return raw
+}
+
+function formatCredentials(credentials: UserCredentials): string {
+  const lines: string[] = []
+
+  if (credentials.apiKey) {
+    lines.push(`API_KEY_NAME=${encodeEnvValue(credentials.username)}`)
+    lines.push(`API_KEY=${encodeEnvValue(credentials.apiKey)}`)
+    lines.push(`API_URL=${encodeEnvValue(credentials.connectionString)}`)
+  } else {
+    lines.push(`DB_USER=${encodeEnvValue(credentials.username)}`)
+    lines.push(`DB_PASSWORD=${encodeEnvValue(credentials.password)}`)
+    // Extract host and port from the connection string.
+    // Use URL parsing when possible; fall back to a regex targeting host:port.
+    let extractedHost: string | undefined
+    let extractedPort: string | undefined
+    try {
+      const url = new URL(credentials.connectionString)
+      if (url.hostname) {
+        extractedHost = url.hostname
+      }
+      if (url.port) {
+        extractedPort = url.port
+      }
+    } catch {
+      // Not a valid URL (e.g. custom scheme). Use regex targeting host:port segment.
+      const hostPortMatch = credentials.connectionString.match(
+        /@(\[[^\]]+\]|[^:/?#]+):(\d+)(?:\/|$)/,
+      )
+      if (hostPortMatch) {
+        extractedHost = hostPortMatch[1].replace(/^\[|\]$/g, '')
+        extractedPort = hostPortMatch[2]
+      }
+    }
+    lines.push(`DB_HOST=${extractedHost || '127.0.0.1'}`)
+    if (extractedPort) {
+      lines.push(`DB_PORT=${extractedPort}`)
+    }
+    if (credentials.database) {
+      lines.push(`DB_NAME=${encodeEnvValue(credentials.database)}`)
+    }
+    lines.push(`DB_URL=${encodeEnvValue(credentials.connectionString)}`)
+  }
+
+  return lines.join('\n') + '\n'
+}
+
+/**
+ * Parse a .env credential file back into UserCredentials.
+ */
+function parseCredentialFile(
+  content: string,
+  containerName: string,
+  engine: Engine,
+): UserCredentials {
+  const vars: Record<string, string> = {}
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    const rawValue = trimmed.slice(eqIdx + 1).trim()
+    vars[key] = decodeEnvValue(rawValue)
+  }
+
+  // API key credentials: password is intentionally empty (auth uses API key, not password)
+  if (vars.API_KEY) {
+    if (!vars.API_KEY_NAME || !vars.API_URL) {
+      throw new Error(
+        `Corrupt credential file for container "${containerName}": missing API_KEY_NAME or API_URL`,
+      )
+    }
+    return {
+      username: vars.API_KEY_NAME,
+      password: '', // API-based auth does not use a password
+      connectionString: vars.API_URL,
+      engine,
+      container: containerName,
+      apiKey: vars.API_KEY,
+    }
+  }
+
+  // Empty string DB_PASSWORD is intentionally allowed (some DBs permit passwordless connections)
+  if (!vars.DB_USER || vars.DB_PASSWORD === undefined || !vars.DB_URL) {
+    throw new Error(
+      `Corrupt credential file for container "${containerName}": missing DB_USER, DB_PASSWORD, or DB_URL`,
+    )
+  }
+
+  return {
+    username: vars.DB_USER,
+    password: vars.DB_PASSWORD,
+    connectionString: vars.DB_URL,
+    engine,
+    container: containerName,
+    database: vars.DB_NAME,
+  }
+}
+
+/**
+ * Save credentials to disk as a .env file.
+ * Creates the credentials/ directory if it doesn't exist.
+ * @returns The path to the saved credential file.
+ */
+export async function saveCredentials(
+  containerName: string,
+  engine: Engine,
+  credentials: UserCredentials,
+): Promise<string> {
+  const credDir = getCredentialsDir(containerName, engine)
+  if (!existsSync(credDir)) {
+    await mkdir(credDir, { recursive: true, mode: 0o700 })
+  }
+
+  const filePath = getCredentialFilePath(
+    containerName,
+    engine,
+    credentials.username,
+  )
+  await writeFile(filePath, formatCredentials(credentials), {
+    encoding: 'utf-8',
+    mode: 0o600,
+  })
+
+  // POSIX file permissions are no-ops on Windows
+  if (process.platform !== 'win32') {
+    await chmod(credDir, 0o700)
+    await chmod(filePath, 0o600)
+  }
+  return filePath
+}
+
+/**
+ * Load credentials for a specific username from disk.
+ * Returns null if the credential file doesn't exist.
+ */
+export async function loadCredentials(
+  containerName: string,
+  engine: Engine,
+  username: string,
+): Promise<UserCredentials | null> {
+  const filePath = getCredentialFilePath(containerName, engine, username)
+  try {
+    const content = await readFile(filePath, 'utf-8')
+    return parseCredentialFile(content, containerName, engine)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null
+    }
+    throw error
+  }
+}
+
+/**
+ * List all saved credential usernames for a container.
+ * Returns an empty array if no credentials directory exists.
+ */
+export async function listCredentials(
+  containerName: string,
+  engine: Engine,
+): Promise<string[]> {
+  const credDir = getCredentialsDir(containerName, engine)
+  if (!existsSync(credDir)) {
+    return []
+  }
+
+  const files = await readdir(credDir)
+  return files
+    .filter((f) => f.startsWith('.env.'))
+    .map((f) => f.slice(5)) // Remove '.env.' prefix
+    .sort()
+}
+
+/**
+ * Check if credentials exist for a specific username.
+ */
+export function credentialsExist(
+  containerName: string,
+  engine: Engine,
+  username: string,
+): boolean {
+  return existsSync(getCredentialFilePath(containerName, engine, username))
+}
+
+/**
+ * Get the default username for a given engine.
+ * API key engines use 'search_key' or 'api_key', all others use 'spindb'.
+ */
+export function getDefaultUsername(engine: Engine): string {
+  switch (engine) {
+    case Engine.Meilisearch:
+      return 'search_key'
+    case Engine.Qdrant:
+      return 'api_key'
+    default:
+      return 'spindb'
+  }
+}

package/core/dependency-manager.ts

@@ -81,6 +81,11 @@ const KNOWN_BINARY_TOOLS: readonly BinaryTool[] = [
   'surreal',
   // QuestDB
   'questdb',
+  // TypeDB
+  'typedb',
+  'typedb_console_bin',
+  // InfluxDB
+  'influxdb3',
   // Enhanced shells (optional)
   'pgcli',
   'mycli',

package/core/docker-exporter.ts

@@ -70,6 +70,8 @@ function getEngineDisplayName(engine: Engine): string {
     [Engine.CockroachDB]: 'CockroachDB',
     [Engine.SurrealDB]: 'SurrealDB',
     [Engine.QuestDB]: 'QuestDB',
+    [Engine.TypeDB]: 'TypeDB',
+    [Engine.InfluxDB]: 'InfluxDB',
   }
   return displayNames[engine] || engine
 }
@@ -137,6 +139,12 @@ const _ENGINE_BINARY_CONFIG: Record<
   [Engine.QuestDB]: {
     primaryBinaries: [], // Uses psql from PostgreSQL for connections
   },
+  [Engine.TypeDB]: {
+    primaryBinaries: ['typedb', 'typedb_console_bin'],
+  },
+  [Engine.InfluxDB]: {
+    primaryBinaries: [], // REST API only, no CLI tools
+  },
 }
 
 /**
@@ -189,6 +197,7 @@ function getConnectionStringTemplate(
       return useTLS ? `https://<host>:${port}` : `http://<host>:${port}`
 
     case Engine.Meilisearch:
+    case Engine.InfluxDB:
       return useTLS ? `https://<host>:${port}` : `http://<host>:${port}`
 
     case Engine.CouchDB:
@@ -201,6 +210,9 @@ function getConnectionStringTemplate(
         ? `wss://\${SPINDB_USER}:\${SPINDB_PASSWORD}@<host>:${port}`
         : `ws://\${SPINDB_USER}:\${SPINDB_PASSWORD}@<host>:${port}`
 
+    case Engine.TypeDB:
+      return `typedb://<host>:${port}`
+
     case Engine.SQLite:
     case Engine.DuckDB:
       return `File-based database (no network connection)`
@@ -485,6 +497,20 @@ echo "User configured via server settings"
       userCreationCommands = `
 # API key is configured at server start
 echo "API key configured via server settings"
+`
+      break
+
+    case Engine.InfluxDB:
+      userCreationCommands = `
+# InfluxDB 3.x local dev runs without authentication
+echo "No authentication required for local InfluxDB 3.x"
+`
+      break
+
+    case Engine.TypeDB:
+      userCreationCommands = `
+# TypeDB community edition does not support user management
+echo "No authentication required"
 `
       break
 
@@ -1270,6 +1296,7 @@ export async function getDockerConnectionString(
       return `http://${host}:${port}`
 
     case Engine.Meilisearch:
+    case Engine.InfluxDB:
       return `http://${host}:${port}`
 
     case Engine.CouchDB:
@@ -1278,6 +1305,9 @@ export async function getDockerConnectionString(
     case Engine.SurrealDB:
       return `ws://${username}:${password}@${host}:${port}`
 
+    case Engine.TypeDB:
+      return `typedb://${host}:${port}`
+
     case Engine.SQLite:
     case Engine.DuckDB:
       return `File-based database (no network connection)`

package/core/error-handler.ts

@@ -57,6 +57,8 @@ export const ErrorCodes = {
   INIT_FAILED: 'INIT_FAILED',
   DATABASE_CREATE_FAILED: 'DATABASE_CREATE_FAILED',
   INVALID_DATABASE_NAME: 'INVALID_DATABASE_NAME',
+  INVALID_USERNAME: 'INVALID_USERNAME',
+  USER_ALREADY_EXISTS: 'USER_ALREADY_EXISTS',
 
   // Dependency errors
   DEPENDENCY_MISSING: 'DEPENDENCY_MISSING',
@@ -333,6 +335,23 @@ export function assertValidDatabaseName(name: string): void {
   }
 }
 
+// Validates a username to prevent SQL injection.
+export function isValidUsername(name: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9_]{0,62}$/.test(name)
+}
+
+export function assertValidUsername(name: string): void {
+  if (!isValidUsername(name)) {
+    throw new SpinDBError(
+      ErrorCodes.INVALID_USERNAME,
+      `Invalid username: "${name}"`,
+      'error',
+      'Usernames must start with a letter, contain only letters, numbers, and underscores, and be at most 63 characters',
+      { username: name },
+    )
+  }
+}
+
 /**
  * Check if the current process is running in an interactive terminal.
  * Returns true if stdin is a TTY (user can interact with prompts).

package/engines/base-engine.ts

@@ -9,6 +9,8 @@ import type {
   StatusResult,
   QueryResult,
   QueryOptions,
+  CreateUserOptions,
+  UserCredentials,
 } from '../types'
 import { UnsupportedOperationError } from '../core/error-handler'
 
@@ -150,6 +152,14 @@ export abstract class BaseEngine {
     throw new Error('surreal not found')
   }
 
+  /**
+   * Get the path to the typedb console binary if available
+   * Default implementation throws; TypeDB engine overrides this method.
+   */
+  async getTypeDBConsolePath(_version?: string): Promise<string> {
+    throw new Error('typedb_console_bin not found')
+  }
+
   /**
    * Get the path to the sqlite3 client if available
    * Default implementation returns null; SQLite engine overrides this method.
@@ -235,7 +245,12 @@ export abstract class BaseEngine {
    */
   abstract runScript(
     container: ContainerConfig,
-    options: { file?: string; sql?: string; database?: string },
+    options: {
+      file?: string
+      sql?: string
+      database?: string
+      transactionType?: 'read' | 'write' | 'schema'
+    },
   ): Promise<void>
 
   /**
@@ -281,4 +296,20 @@ export abstract class BaseEngine {
   async listDatabases(_container: ContainerConfig): Promise<string[]> {
     throw new UnsupportedOperationError('listDatabases', this.displayName)
   }
+
+  /**
+   * Create a database user with the given credentials.
+   * Returns credentials including connection string.
+   *
+   * @param container - The container configuration
+   * @param options - Username, password, and optional target database
+   * @returns UserCredentials with connection info
+   * @throws UnsupportedOperationError for engines that don't support users (SQLite, DuckDB, QuestDB)
+   */
+  async createUser(
+    _container: ContainerConfig,
+    _options: CreateUserOptions,
+  ): Promise<UserCredentials> {
+    throw new UnsupportedOperationError('createUser', this.displayName)
+  }
 }

package/engines/clickhouse/index.ts

@@ -1,13 +1,17 @@
 import { spawn, type SpawnOptions } from 'child_process'
 import { existsSync } from 'fs'
-import { mkdir, writeFile, readFile, unlink } from 'fs/promises'
+import { mkdir, writeFile, readFile, unlink, chmod } from 'fs/promises'
 import { join } from 'path'
 import { BaseEngine } from '../base-engine'
 import { paths } from '../../config/paths'
 import { getEngineDefaults } from '../../config/defaults'
 import { platformService } from '../../core/platform-service'
 import { configManager } from '../../core/config-manager'
-import { logDebug, logWarning } from '../../core/error-handler'
+import {
+  logDebug,
+  logWarning,
+  assertValidUsername,
+} from '../../core/error-handler'
 import { processManager } from '../../core/process-manager'
 import { clickhouseBinaryManager } from './binary-manager'
 import { getBinaryUrl } from './binary-urls'
@@ -39,6 +43,8 @@ import {
   type StatusResult,
   type QueryResult,
   type QueryOptions,
+  type CreateUserOptions,
+  type UserCredentials,
 } from '../../types'
 import { parseClickHouseJSONResult } from '../../core/query-parser'
 
@@ -86,6 +92,15 @@ function generateClickHouseConfig(options: {
 
     <mark_cache_size>5368709120</mark_cache_size>
     <max_concurrent_queries>100</max_concurrent_queries>
+
+    <user_directories>
+        <users_xml>
+            <path>users.xml</path>
+        </users_xml>
+        <local_directory>
+            <path>${dataDir}/access/</path>
+        </local_directory>
+    </user_directories>
 </clickhouse>
 `
 }
@@ -297,6 +312,11 @@ export class ClickHouseEngine extends BaseEngine {
     await mkdir(dataDir, { recursive: true })
     await mkdir(tmpDir, { recursive: true })
     await mkdir(join(dataDir, 'user_files'), { recursive: true })
+    const accessDir = join(dataDir, 'access')
+    await mkdir(accessDir, { recursive: true, mode: 0o700 })
+    await chmod(accessDir, 0o700).catch((err) => {
+      logDebug(`Failed to chmod ${accessDir}: ${err}`)
+    })
 
     logDebug(`Created ClickHouse data directory: ${dataDir}`)
 
@@ -338,6 +358,18 @@ export class ClickHouseEngine extends BaseEngine {
     const tmpDir = join(dataDir, 'tmp')
     const httpPort = port + 1
 
+    const accessDir = join(dataDir, 'access')
+    try {
+      await mkdir(accessDir, { recursive: true, mode: 0o700 })
+      await chmod(accessDir, 0o700).catch((err) => {
+        logDebug(`Failed to chmod ${accessDir}: ${err}`)
+      })
+    } catch (error) {
+      logWarning(
+        `Failed to create ClickHouse access directory ${accessDir}: ${error}`,
+      )
+    }
+
     const configPath = join(containerDir, 'config.xml')
     const pidFile = join(containerDir, engineDef.pidFileName)
     const configContent = generateClickHouseConfig({
@@ -528,7 +560,7 @@ export class ClickHouseEngine extends BaseEngine {
   private async waitForReady(
     port: number,
     version: string,
-    timeoutMs = 90000,
+    timeoutMs = 120000,
   ): Promise<boolean> {
     logDebug(`waitForReady called for port ${port}, version ${version}`)
     const startTime = Date.now()
@@ -1244,6 +1276,70 @@ export class ClickHouseEngine extends BaseEngine {
       })
     })
   }
+
+  async createUser(
+    container: ContainerConfig,
+    options: CreateUserOptions,
+  ): Promise<UserCredentials> {
+    const { username, password, database } = options
+    assertValidUsername(username)
+    const { port, version } = container
+    const db = database || container.database || 'default'
+
+    validateClickHouseIdentifier(username, 'username')
+    validateClickHouseIdentifier(db, 'database')
+    const escapedUser = escapeClickHouseIdentifier(username)
+    const escapedDb = escapeClickHouseIdentifier(db)
+
+    const clickhouse = await this.getClickHouseClientPath(version)
+
+    const escapedPass = password.replace(/\\/g, '\\\\').replace(/'/g, "''")
+    const sql = `CREATE USER IF NOT EXISTS ${escapedUser} IDENTIFIED BY '${escapedPass}'; ALTER USER ${escapedUser} IDENTIFIED BY '${escapedPass}'; GRANT ALL ON ${escapedDb}.* TO ${escapedUser};`
+
+    const args = [
+      'client',
+      '--host',
+      '127.0.0.1',
+      '--port',
+      String(port),
+      '--multiquery',
+    ]
+
+    await new Promise<void>((resolve, reject) => {
+      const proc = spawn(clickhouse, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+
+      let stderr = ''
+      proc.stderr?.on('data', (data: Buffer) => {
+        stderr += data.toString()
+      })
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          logDebug(`Created ClickHouse user: ${username}`)
+          resolve()
+        } else {
+          reject(new Error(`Failed to create user: ${stderr}`))
+        }
+      })
+      proc.on('error', reject)
+
+      proc.stdin?.write(sql)
+      proc.stdin?.end()
+    })
+
+    const connectionString = `clickhouse://${encodeURIComponent(username)}:${encodeURIComponent(password)}@127.0.0.1:${port}/${db}`
+
+    return {
+      username,
+      password,
+      connectionString,
+      engine: container.engine,
+      container: container.name,
+      database: db,
+    }
+  }
 }
 
 export const clickhouseEngine = new ClickHouseEngine()

package/engines/cockroachdb/index.ts

@@ -22,7 +22,11 @@ import { paths } from '../../config/paths'
 import { getEngineDefaults } from '../../config/defaults'
 import { platformService } from '../../core/platform-service'
 import { configManager } from '../../core/config-manager'
-import { logDebug, logWarning } from '../../core/error-handler'
+import {
+  logDebug,
+  logWarning,
+  assertValidUsername,
+} from '../../core/error-handler'
 import { findBinary } from '../../core/dependency-manager'
 import { processManager } from '../../core/process-manager'
 import { cockroachdbBinaryManager } from './binary-manager'
@@ -59,6 +63,8 @@ import {
   type StatusResult,
   type QueryResult,
   type QueryOptions,
+  type CreateUserOptions,
+  type UserCredentials,
 } from '../../types'
 import { parseCSVToQueryResult } from '../../core/query-parser'
 
@@ -347,7 +353,7 @@ export class CockroachDBEngine extends BaseEngine {
 
     // Wait for server to be ready
     // Windows needs a longer timeout since CockroachDB initialization takes more time
-    const timeout = isWindows ? 90000 : 60000
+    const timeout = isWindows ? 120000 : 60000
     logDebug(
       `Waiting for CockroachDB server to be ready on port ${port}... (timeout: ${timeout}ms)`,
     )
@@ -1201,6 +1207,67 @@ export class CockroachDBEngine extends BaseEngine {
       })
     })
   }
+
+  async createUser(
+    container: ContainerConfig,
+    options: CreateUserOptions,
+  ): Promise<UserCredentials> {
+    const { username, password, database } = options
+    assertValidUsername(username)
+    const { port, version } = container
+    const db = database || container.database || 'defaultdb'
+
+    validateCockroachIdentifier(username, 'user')
+    validateCockroachIdentifier(db, 'database')
+    const escapedUser = escapeCockroachIdentifier(username)
+    const escapedDb = escapeCockroachIdentifier(db)
+
+    const cockroach = await this.getCockroachPath(version)
+
+    // CockroachDB in insecure mode doesn't support passwords.
+    // Create user without password and grant privileges.
+    // SQL is sent via stdin to avoid shell escaping issues with --execute.
+    const sql = `CREATE USER IF NOT EXISTS ${escapedUser}; GRANT ALL ON DATABASE ${escapedDb} TO ${escapedUser};`
+
+    const args = ['sql', '--insecure', '--host', `127.0.0.1:${port}`]
+
+    await new Promise<void>((resolve, reject) => {
+      const proc = spawn(cockroach, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+
+      let stderr = ''
+      proc.stderr?.on('data', (data: Buffer) => {
+        stderr += data.toString()
+      })
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve()
+        } else {
+          reject(new Error(`Failed to create user: ${stderr}`))
+        }
+      })
+      proc.on('error', reject)
+
+      proc.stdin?.write(sql)
+      proc.stdin?.end()
+    })
+
+    // In insecure mode, connections don't use passwords
+    const connectionString = `postgresql://${encodeURIComponent(username)}@127.0.0.1:${port}/${db}?sslmode=disable`
+
+    return {
+      username,
+      // CockroachDB insecure mode does not enforce password authentication,
+      // but we return the caller-provided password for credential file consistency.
+      password,
+      connectionString,
+      engine: container.engine,
+      container: container.name,
+      database: db,
+    }
+  }
 }
 
 export const cockroachdbEngine = new CockroachDBEngine()