@better-forge/vault 0.0.0-stage → 0.1.0

package/src/hashicorp.ts

@@ -0,0 +1,466 @@
+import { Agent, fetch as httpFetch } from 'undici'
+import { and, eq } from 'drizzle-orm'
+import type { SqliteDatabase } from '@better-forge/db'
+import { vaults, vaultSecrets } from './tables.js'
+import type { SecretBox } from './secretBox.js'
+
+/**
+ * Client for HashiCorp Vault (KV v2). A vault of type `hashicorp` keeps only the
+ * connection settings (encrypted); secret values are read live on every use and never stored.
+ *
+ * The Vault address is private-network by nature, so unlike webhooks no public-IP guard applies.
+ * Instead the token is protected by: no redirects, strict path-segment validation, a response size
+ * cap and fixed error messages that never echo request headers, bodies or credentials.
+ */
+
+export type HashicorpAuthMethod = 'token' | 'approle'
+
+export interface HashicorpConfig {
+  address: string
+  namespace?: string
+  mount: string
+  authMethod: HashicorpAuthMethod
+  token?: string | undefined
+  roleId?: string
+  secretId?: string
+  approleMount: string
+  caCert?: string
+  /**
+   * Reads the credentials from a secret in a local vault instead of storing them here: a Secure Value or JSON
+   * secret holding the token, or a User / Password (Role ID and Secret ID) or JSON secret for AppRole.
+   */
+  credentialsRef?: CredentialsRef
+}
+
+export interface CredentialsRef {
+  vaultId: number
+  secretId: number
+  /** For a JSON secret: the JSON key holding each credential (`token`, or `roleId` and `secretId`); the key defaults to that name. */
+  fieldMapping?: Record<string, string>
+}
+
+/** The credentials in effect for one request, whether stored in the connection or read from a local vault. */
+interface Credentials { token?: string | undefined; roleId?: string | undefined; secretId?: string | undefined }
+
+/** Message is always safe to return to the browser. */
+export class HashicorpVaultError extends Error {}
+
+/** Mutable so tests can shorten the timeout. */
+export const hashicorpLimits = {
+  timeoutMs: 10_000,
+  maxBodyBytes: 1024 * 1024,
+  /** A 403 for a token younger than this is a policy denial, not an expired token: no new login. */
+  freshTokenMs: 10_000,
+  /** Grace period before a replaced connection pool is closed, so in-flight requests can finish. */
+  agentCloseDelayMs: 30_000,
+}
+
+const MAX_FIELD = 2048
+
+const MAX_CA = 64 * 1024
+
+function text(value: unknown, label: string, max = MAX_FIELD): string | undefined {
+  if (value === undefined || value === null || value === '') return undefined
+  if (typeof value !== 'string') throw new HashicorpVaultError(`${label} must be a string`)
+  const trimmed = value.trim()
+  if (trimmed.length > max) throw new HashicorpVaultError(`${label} is too long`)
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(trimmed)) throw new HashicorpVaultError(`${label} contains invalid characters`)
+  return trimmed || undefined
+}
+
+/** Validates a slash-separated Vault path and returns it URL-encoded per segment. */
+export function encodePath(raw: string, label: string): string {
+  const segments = raw.trim().replace(/^\/+|\/+$/g, '').split('/')
+  if (segments.length === 0 || segments.some((s) => s === '')) {
+    throw new HashicorpVaultError(`${label} is invalid`)
+  }
+  return segments.map((segment) => {
+    let decoded: string
+    try { decoded = decodeURIComponent(segment) } catch { throw new HashicorpVaultError(`${label} is invalid`) }
+    if (decoded === '.' || decoded === '..' || decoded.includes('/') || decoded.includes('\\')) {
+      throw new HashicorpVaultError(`${label} is invalid`)
+    }
+    return encodeURIComponent(decoded)
+  }).join('/')
+}
+
+function requiredText(value: unknown, label: string): string {
+  const v = text(value, label)
+  if (!v) throw new HashicorpVaultError(`${label} is required`)
+  return v
+}
+
+function normalizeAddress(raw: string): string {
+  let url: URL
+  try { url = new URL(raw) } catch { throw new HashicorpVaultError('Address must be a valid URL') }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new HashicorpVaultError('Address must start with http:// or https://')
+  }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/') {
+    throw new HashicorpVaultError('Address must be a plain URL such as https://vault.example.com:8200')
+  }
+  return url.origin
+}
+
+/** True when changing these fields would redirect stored credentials somewhere else. */
+const IDENTITY_FIELDS = ['address', 'namespace', 'mount', 'authMethod', 'approleMount', 'caCert'] as const
+
+/**
+ * Validates connection input from the admin API. With `existing`, blank credentials keep the stored
+ * ones, except when the address, namespace, auth method or AppRole mount changes: credentials must
+ * then be sent again, so a changed address cannot receive a stored token.
+ */
+export function parseConnection(input: unknown, existing?: HashicorpConfig): HashicorpConfig {
+  if (!input || typeof input !== 'object') throw new HashicorpVaultError('Connection settings are required')
+  const body = input as Record<string, unknown>
+
+  const authMethod = body['authMethod'] ?? existing?.authMethod
+  if (authMethod !== 'token' && authMethod !== 'approle') {
+    throw new HashicorpVaultError('Auth method must be token or approle')
+  }
+  const namespace = text(body['namespace'], 'Namespace')
+  const cfg: HashicorpConfig = {
+    address: normalizeAddress(requiredText(body['address'], 'Address')),
+    mount: requiredText(body['mount'] ?? 'secret', 'KV mount'),
+    authMethod,
+    approleMount: text(body['approleMount'], 'AppRole mount') ?? 'approle',
+  }
+  if (namespace) cfg.namespace = namespace
+  encodePath(cfg.mount, 'KV mount')
+  encodePath(cfg.approleMount, 'AppRole mount')
+  if (cfg.namespace) encodePath(cfg.namespace, 'Namespace')
+
+  const caCert = text(body['caCert'], 'CA certificate', MAX_CA)
+  if (caCert) {
+    if (!caCert.includes('BEGIN CERTIFICATE')) throw new HashicorpVaultError('CA certificate must be PEM encoded')
+    cfg.caCert = caCert
+  }
+
+  const identityChanged = existing ? IDENTITY_FIELDS.some((f) => (existing[f] ?? '') !== (cfg[f] ?? '')) : false
+  const keep = existing && !identityChanged ? existing : undefined
+  // An object picks a local vault secret; null means direct input; absent keeps what is saved.
+  const refInput = body['credentialsRef']
+  if (refInput !== undefined && refInput !== null) {
+    cfg.credentialsRef = parseCredentialsRef(refInput, authMethod)
+    return cfg
+  }
+  const keptRef = refInput === undefined ? keep?.credentialsRef : undefined
+  if (authMethod === 'token') {
+    const typed = text(body['token'], 'Token')
+    if (!typed && keptRef) { cfg.credentialsRef = keptRef; return cfg }
+    const token = typed ?? keep?.token
+    if (!token) throw new HashicorpVaultError(identityChanged ? 'Re-enter the token after changing the connection target' : 'Token is required')
+    cfg.token = token
+  } else {
+    const typedSecretId = text(body['secretId'], 'Secret ID')
+    const typedRoleId = text(body['roleId'], 'Role ID')
+    if (!typedSecretId && !typedRoleId && keptRef) { cfg.credentialsRef = keptRef; return cfg }
+    const roleId = typedRoleId ?? keep?.roleId
+    const secretId = typedSecretId ?? keep?.secretId
+    if (!roleId || !secretId) {
+      throw new HashicorpVaultError(identityChanged ? 'Re-enter the Role ID and Secret ID after changing the connection target' : 'Role ID and Secret ID are required')
+    }
+    cfg.roleId = roleId
+    cfg.secretId = secretId
+  }
+  return cfg
+}
+
+function parseCredentialsRef(input: unknown, authMethod: HashicorpAuthMethod): CredentialsRef {
+  const { vaultId, secretId, fieldMapping } = (typeof input === 'object' ? input : {}) as Record<string, unknown>
+  if (!Number.isInteger(vaultId) || !Number.isInteger(secretId) || (vaultId as number) <= 0 || (secretId as number) <= 0) {
+    throw new HashicorpVaultError('Select a secret from a local vault for the credentials')
+  }
+  const ref: CredentialsRef = { vaultId: vaultId as number, secretId: secretId as number }
+  const mapping: Record<string, string> = {}
+  for (const field of authMethod === 'token' ? ['token'] : ['roleId', 'secretId']) {
+    const key = text((fieldMapping as Record<string, unknown> | undefined)?.[field], 'JSON key', 200)
+    if (key) mapping[field] = key
+  }
+  if (Object.keys(mapping).length) ref.fieldMapping = mapping
+  return ref
+}
+
+/** Connection settings safe to return to admins: credentials are reported only as present or not. */
+export function publicConnection(cfg: HashicorpConfig) {
+  return {
+    address: cfg.address,
+    namespace: cfg.namespace ?? '',
+    mount: cfg.mount,
+    authMethod: cfg.authMethod,
+    approleMount: cfg.approleMount,
+    roleId: cfg.roleId ?? '',
+    caCert: cfg.caCert ?? '',
+    hasToken: !!cfg.token,
+    hasSecretId: !!cfg.secretId,
+    credentialsRef: cfg.credentialsRef ?? null,
+  }
+}
+
+// ── Requests ──────────────────────────────────────────────────────────────────
+
+export interface HashicorpVaultRow {
+  id: number
+  updatedAt: number
+  connectionConfig: string | null
+}
+
+interface Session {
+  fingerprint: number
+  cfg: HashicorpConfig
+  agent?: Agent | undefined
+  token?: string | undefined
+  expiresAt: number
+  loginAt: number
+  login?: Promise<string> | undefined
+  /** The credentials last used, kept only to scrub them from error messages. */
+  creds?: Credentials | undefined
+}
+
+export function createHashicorp(ctx: { db: SqliteDatabase; secretBox: SecretBox }) {
+  const { db } = ctx
+  const { encrypt, decrypt } = ctx.secretBox
+
+  function sealConnection(cfg: HashicorpConfig): string {
+    return encrypt(JSON.stringify(cfg))
+  }
+
+  function openConnection(sealed: string | null): HashicorpConfig {
+    if (!sealed) throw new HashicorpVaultError('Vault connection is not configured')
+    try {
+      return JSON.parse(decrypt(sealed)) as HashicorpConfig
+    } catch {
+      throw new HashicorpVaultError('Failed to decrypt vault connection')
+    }
+  }
+
+  const sessions = new Map<number, Session>()
+
+  /** Drops the cached token and closes the connection pool; call after the vault is changed or deleted. */
+  function forgetHashicorpVault(vaultId: number): void {
+    const session = sessions.get(vaultId)
+    sessions.delete(vaultId)
+    const agent = session?.agent
+    if (agent) setTimeout(() => void agent.close().catch(() => undefined), hashicorpLimits.agentCloseDelayMs).unref()
+  }
+
+  /**
+   * Drops the cached sessions of HashiCorp vaults that read their credentials from this local vault (or one
+   * of its secrets), so a rotated or deleted secret is used from the next request, also for AppRole.
+   */
+  function forgetCredentialDependents(vaultId: number, secretId?: number): void {
+    for (const [id, session] of sessions) {
+      const ref = session.cfg.credentialsRef
+      if (ref && ref.vaultId === vaultId && (secretId === undefined || ref.secretId === secretId)) forgetHashicorpVault(id)
+    }
+  }
+
+  function sessionFor(vault: HashicorpVaultRow): Session {
+    const existing = sessions.get(vault.id)
+    if (existing && existing.fingerprint === vault.updatedAt) return existing
+    forgetHashicorpVault(vault.id)
+    const cfg = openConnection(vault.connectionConfig)
+    const session: Session = {
+      fingerprint: vault.updatedAt,
+      cfg,
+      agent: cfg.caCert ? new Agent({ connect: { ca: cfg.caCert } }) : undefined,
+      expiresAt: 0,
+      loginAt: 0,
+    }
+    sessions.set(vault.id, session)
+    return session
+  }
+
+  function scrub(message: string, creds: Credentials | undefined): string {
+    let out = message
+    for (const secret of [creds?.token, creds?.secretId]) if (secret) out = out.split(secret).join('[redacted]')
+    return out
+  }
+
+  /**
+   * Returns the credentials to use now. A referenced local vault secret is read on every call, so a
+   * rotation there takes effect on the next request; it must still exist, live in a local vault and
+   * have the type the auth method needs.
+   */
+  async function credentialsFor(session: Session): Promise<Credentials> {
+    const { cfg } = session
+    const ref = cfg.credentialsRef
+    if (!ref) return (session.creds = { token: cfg.token, roleId: cfg.roleId, secretId: cfg.secretId })
+    const [row] = await db.select().from(vaultSecrets).where(and(eq(vaultSecrets.id, ref.secretId), eq(vaultSecrets.vaultId, ref.vaultId)))
+    const [owner] = row ? await db.select({ type: vaults.type }).from(vaults).where(eq(vaults.id, ref.vaultId)) : []
+    if (!row || owner?.type !== 'local') throw new HashicorpVaultError('the credentials secret no longer exists in a local vault')
+    let payload: Record<string, unknown>
+    try { payload = JSON.parse(decrypt(row.encryptedValue)) as Record<string, unknown> } catch { throw new HashicorpVaultError('the credentials secret cannot be decrypted') }
+    // Same trimming and character checks as typed credentials, so a stray newline is a clear error, not a failed request.
+    const clean = (value: unknown) => { try { return text(value, 'The credentials secret') } catch { return undefined } }
+    // A JSON secret holds an object; the mapping (or the default key names) picks each credential from it.
+    let fields: Record<string, unknown> = {}
+    if (row.type === 'json') {
+      try { fields = JSON.parse(String(payload['value'] ?? '')) as Record<string, unknown> } catch { /* reported below as a missing credential */ }
+    }
+    const pick = (field: string) => clean(fields[ref.fieldMapping?.[field] ?? field])
+    if (cfg.authMethod === 'token') {
+      const token = row.type === 'value' ? clean(payload['value']) : row.type === 'json' ? pick('token') : undefined
+      if (!token) throw new HashicorpVaultError('the credentials secret must be a Secure Value, or a JSON secret with the token key')
+      return (session.creds = { token })
+    }
+    const roleId = row.type === 'userpass' ? clean(payload['username']) : row.type === 'json' ? pick('roleId') : undefined
+    const secretId = row.type === 'userpass' ? clean(payload['password']) : row.type === 'json' ? pick('secretId') : undefined
+    if (!roleId || !secretId) {
+      throw new HashicorpVaultError('the credentials secret must be a User / Password secret, or a JSON secret with the Role ID and Secret ID keys')
+    }
+    return (session.creds = { roleId, secretId })
+  }
+
+  function describeNetworkError(err: unknown): string {
+    const e = err as { name?: string; message?: string; cause?: { code?: string; message?: string } }
+    if (e?.name === 'TimeoutError' || e?.name === 'AbortError') {
+      return `timed out after ${Math.round(hashicorpLimits.timeoutMs / 1000)} s`
+    }
+    const code = e?.cause?.code ?? ''
+    if (/redirect/i.test(e?.cause?.message ?? e?.message ?? '')) return 'redirects are not followed'
+    if (/^(UNABLE_TO|CERT_|DEPTH_ZERO|SELF_SIGNED|ERR_TLS|ERR_SSL|HOSTNAME_MISMATCH)/.test(code)) {
+      return `TLS certificate not trusted (${code})`
+    }
+    return code ? `cannot connect (${code})` : 'cannot connect'
+  }
+
+  async function readCapped(res: Awaited<ReturnType<typeof httpFetch>>): Promise<unknown> {
+    const reader = res.body?.getReader()
+    if (!reader) return null
+    const chunks: Uint8Array[] = []
+    let size = 0
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > hashicorpLimits.maxBodyBytes) {
+        void reader.cancel()
+        throw new HashicorpVaultError('response from Vault is too large')
+      }
+      chunks.push(value)
+    }
+    try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { return null }
+  }
+
+  async function call(
+    session: Session,
+    method: 'GET' | 'POST',
+    apiPath: string,
+    token: string | undefined,
+    body?: unknown,
+  ): Promise<{ status: number; json: unknown }> {
+    const { cfg } = session
+    const headers: Record<string, string> = { 'X-Vault-Request': 'true' }
+    if (token) headers['X-Vault-Token'] = token
+    if (cfg.namespace) headers['X-Vault-Namespace'] = cfg.namespace
+    if (body !== undefined) headers['Content-Type'] = 'application/json'
+    try {
+      const res = await httpFetch(`${cfg.address}/v1/${apiPath}`, {
+        method,
+        headers,
+        ...(body !== undefined && { body: JSON.stringify(body) }),
+        redirect: 'error',
+        signal: AbortSignal.timeout(hashicorpLimits.timeoutMs),
+        ...(session.agent && { dispatcher: session.agent }),
+      })
+      return { status: res.status, json: await readCapped(res) }
+    } catch (err) {
+      if (err instanceof HashicorpVaultError) throw err
+      throw new HashicorpVaultError(scrub(describeNetworkError(err), session.creds))
+    }
+  }
+
+  function login(session: Session): Promise<string> {
+    session.login ??= (async () => {
+      const { cfg } = session
+      const creds = await credentialsFor(session)
+      const { status, json } = await call(session, 'POST', `auth/${encodePath(cfg.approleMount, 'AppRole mount')}/login`, undefined,
+        { role_id: creds.roleId, secret_id: creds.secretId })
+      const auth = (json as { auth?: { client_token?: string; lease_duration?: number } } | null)?.auth
+      if (status !== 200 || !auth?.client_token) {
+        throw new HashicorpVaultError(status === 400 || status === 403 ? 'AppRole login was rejected' : `AppRole login failed (HTTP ${status})`)
+      }
+      const ttlMs = (auth.lease_duration ?? 0) * 1000
+      session.token = auth.client_token
+      session.loginAt = Date.now()
+      // A lease of 0 means the token does not expire; a 403 then decides when to log in again.
+      session.expiresAt = ttlMs > 0 ? session.loginAt + ttlMs - Math.min(60_000, ttlMs * 0.1) : Infinity
+      return auth.client_token
+    })().finally(() => { session.login = undefined })
+    return session.login
+  }
+
+  async function tokenFor(session: Session): Promise<string> {
+    if (session.cfg.authMethod === 'token') return (await credentialsFor(session)).token!
+    if (session.token && Date.now() < session.expiresAt) return session.token
+    return login(session)
+  }
+
+  /** Authenticated request; with AppRole a 403 triggers one fresh login and retry. */
+  async function authed(session: Session, method: 'GET' | 'POST', apiPath: string) {
+    const used = await tokenFor(session)
+    let res = await call(session, method, apiPath, used)
+    const expired = session.cfg.authMethod === 'approle' && session.token === used
+      && Date.now() - session.loginAt >= hashicorpLimits.freshTokenMs
+    if (res.status === 403 && expired) {
+      session.token = undefined
+      res = await call(session, method, apiPath, await tokenFor(session))
+    }
+    return res
+  }
+
+  /** Reads the data of a KV v2 secret (latest version). */
+  async function readKvSecret(vault: HashicorpVaultRow, path: string): Promise<Record<string, unknown>> {
+    const session = sessionFor(vault)
+    const kvPath = encodePath(path, 'Path')
+    const { status, json } = await authed(session, 'GET', `${encodePath(session.cfg.mount, 'KV mount')}/data/${kvPath}`)
+    if (status === 404) throw new HashicorpVaultError(`secret not found at ${session.cfg.mount}/${path.replace(/^\/+|\/+$/g, '')}`)
+    if (status === 403) throw new HashicorpVaultError('permission denied (HTTP 403)')
+    const data = (json as { data?: { data?: unknown } } | null)?.data?.data
+    if (status !== 200 || !data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new HashicorpVaultError(`unexpected response from Vault (HTTP ${status})`)
+    }
+    return data as Record<string, unknown>
+  }
+
+  /** Fails unless the connection's credentials secret (if any) exists in a local vault with the type its auth method needs. */
+  async function verifyCredentialsRef(cfg: HashicorpConfig): Promise<void> {
+    if (cfg.credentialsRef) await credentialsFor({ fingerprint: 0, cfg, expiresAt: 0, loginAt: 0 })
+  }
+
+  /** Verifies the saved credentials. Returns the remaining token TTL when Vault reports one. */
+  async function testConnection(vault: HashicorpVaultRow): Promise<{ authMethod: HashicorpAuthMethod; ttlSeconds: number | null }> {
+    return verifySession(sessionFor(vault))
+  }
+
+  /** Verifies connection settings that are not saved yet, without touching the session cache. */
+  async function testDraftConnection(cfg: HashicorpConfig): Promise<{ authMethod: HashicorpAuthMethod; ttlSeconds: number | null }> {
+    const agent = cfg.caCert ? new Agent({ connect: { ca: cfg.caCert } }) : undefined
+    try {
+      return await verifySession({ fingerprint: 0, cfg, agent, expiresAt: 0, loginAt: 0 })
+    } finally {
+      void agent?.close()
+    }
+  }
+
+  async function verifySession(session: Session): Promise<{ authMethod: HashicorpAuthMethod; ttlSeconds: number | null }> {
+    session.token = undefined
+    session.loginAt = 0
+    const { cfg } = session
+    if (cfg.authMethod === 'approle') {
+      await login(session)
+      return { authMethod: 'approle', ttlSeconds: Math.max(0, Math.round((session.expiresAt - Date.now()) / 1000)) }
+    }
+    const { status, json } = await call(session, 'GET', 'auth/token/lookup-self', (await credentialsFor(session)).token)
+    if (status === 403) throw new HashicorpVaultError('token was rejected (HTTP 403)')
+    if (status !== 200) throw new HashicorpVaultError(`unexpected response from Vault (HTTP ${status})`)
+    const ttl = (json as { data?: { ttl?: number } } | null)?.data?.ttl
+    return { authMethod: 'token', ttlSeconds: typeof ttl === 'number' && ttl > 0 ? ttl : null }
+  }
+
+  return { sealConnection, openConnection, forgetHashicorpVault, forgetCredentialDependents, readKvSecret, verifyCredentialsRef, testConnection, testDraftConnection }
+}
+
+export type Hashicorp = ReturnType<typeof createHashicorp>

package/src/index.ts

@@ -0,0 +1,9 @@
+export { createVault, type Vault, type VaultOptions } from './createVault.js'
+export { vaultDbModule } from './module.js'
+export { vaults, vaultSecrets } from './tables.js'
+export { createSecretBox, validateEncryptionKey, type SecretBox } from './secretBox.js'
+export { createSealer, sealedText, SEALED_PREFIX, type Sealer, type SealedText } from './sealed.js'
+export { canonical, createVaultUseGuard } from './vaultUse.js'
+export { createSecretFields, SECRET_MASK, SENSITIVE_HEADER, uniqueSecretFields, type LooseningSwitch, type RestoreResult, type SecretField } from './secretFields.js'
+export { HashicorpVaultError, hashicorpLimits, type HashicorpAuthMethod, type HashicorpConfig, type CredentialsRef, type HashicorpVaultRow } from './hashicorp.js'
+export type { VaultAudit } from './vaultRoutes.js'

package/src/migrations.ts

@@ -0,0 +1,29 @@
+import type { MigrationStep } from '@better-forge/db'
+
+/** Vaults and the secrets in them. Steps run in this order. */
+export const vaultMigrations: readonly MigrationStep[] = [
+  { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS vaults (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL DEFAULT 'local',
+  description TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+` },
+  { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS vault_secrets (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  vault_id INTEGER NOT NULL,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL,
+  encrypted_value TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (vault_id) REFERENCES vaults(id) ON DELETE CASCADE,
+  UNIQUE (vault_id, name)
+);
+` },
+  { kind: 'column', sql: `ALTER TABLE vaults ADD COLUMN connection_config TEXT`, desc: 'vaults.connection_config' },
+]

package/src/module.ts

@@ -0,0 +1,6 @@
+import type { DbModule } from '@better-forge/db'
+import * as tables from './tables.js'
+import { vaultMigrations } from './migrations.js'
+
+/** The tables of vaults and their secrets, with their migrations, for the application's list of database modules. */
+export const vaultDbModule = { id: 'vault', tables, migrations: vaultMigrations } satisfies DbModule

package/src/resolveSecret.ts

@@ -0,0 +1,96 @@
+import { and, eq } from 'drizzle-orm'
+import type { VaultRef } from '@better-forge/contracts'
+import type { SqliteDatabase } from '@better-forge/db'
+import { vaults, vaultSecrets } from './tables.js'
+import { HashicorpVaultError, type Hashicorp } from './hashicorp.js'
+import type { SecretBox } from './secretBox.js'
+
+type VaultRow = typeof vaults.$inferSelect
+
+type SecretRow = typeof vaultSecrets.$inferSelect
+
+export function createSecretResolver(ctx: { db: SqliteDatabase; secretBox: SecretBox }, hashicorp: Hashicorp) {
+  const { db } = ctx
+  const { decrypt } = ctx.secretBox
+  const { readKvSecret } = hashicorp
+
+  /**
+   * Returns the stored payload of a secret in the shape `decrypt` yields for local vaults
+   * (`{ username, password }`, `{ value }` where json holds a JSON string). HashiCorp vaults keep only a
+   * reference `{ path, key? }`; the value is read live from Vault and shaped to match.
+   */
+  async function loadSecretPayload(secret: SecretRow, vault: VaultRow): Promise<Record<string, unknown>> {
+    if (vault.type !== 'hashicorp') return JSON.parse(decrypt(secret.encryptedValue)) as Record<string, unknown>
+    try {
+      const ref = JSON.parse(decrypt(secret.encryptedValue)) as { path: string; key?: string }
+      const kv = await readKvSecret(vault, ref.path)
+      if (secret.type === 'userpass') {
+        if (typeof kv['username'] !== 'string' || typeof kv['password'] !== 'string') {
+          throw new HashicorpVaultError('keys "username" and "password" are required at the path')
+        }
+        return { username: kv['username'], password: kv['password'] }
+      }
+      if (secret.type === 'value') {
+        const found = ref.key ? kv[ref.key] : undefined
+        if (found === undefined || found === null) throw new HashicorpVaultError(`key "${ref.key ?? ''}" not found`)
+        return { value: typeof found === 'string' ? found : JSON.stringify(found) }
+      }
+      return { value: JSON.stringify(kv) }
+    } catch (e) {
+      if (e instanceof HashicorpVaultError) throw new Error(`HashiCorp Vault "${vault.name}": ${e.message}`, { cause: e })
+      throw e
+    }
+  }
+
+  /**
+   * Resolves a vault secret reference to a flat string map.
+   *
+   * - userpass → { username, password }
+   * - value    → { value }
+   * - json     → all keys as strings, or filtered/renamed via fieldMapping
+   *              e.g. fieldMapping = { clientId: 'client_id' } → { clientId: <json.client_id> }
+   */
+  async function resolveVaultSecret(ref: VaultRef): Promise<Record<string, string>> {
+    const [secret] = await db
+      .select()
+      .from(vaultSecrets)
+      .where(and(eq(vaultSecrets.id, ref.secretId), eq(vaultSecrets.vaultId, ref.vaultId)))
+
+    const [vault] = secret ? await db.select().from(vaults).where(eq(vaults.id, ref.vaultId)) : []
+    if (!secret || !vault) {
+      throw new Error(`Vault secret ${ref.secretId} not found in vault ${ref.vaultId}`)
+    }
+
+    const decrypted = await loadSecretPayload(secret, vault)
+
+    if (secret.type === 'userpass') {
+      return {
+        username: String(decrypted['username'] ?? ''),
+        password: String(decrypted['password'] ?? ''),
+      }
+    }
+
+    if (secret.type === 'value') {
+      return { value: String(decrypted['value'] ?? '') }
+    }
+
+    if (secret.type === 'json') {
+      const raw = JSON.parse(String(decrypted['value'] ?? '{}')) as Record<string, unknown>
+      const { fieldMapping } = ref
+      if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+        return Object.fromEntries(
+          Object.entries(fieldMapping)
+            .filter(([, jsonKey]) => !!jsonKey)
+            .map(([ourField, jsonKey]) => [ourField, String(raw[jsonKey] ?? '')]),
+        )
+      }
+      return Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, String(v ?? '')]))
+    }
+
+    throw new Error(`Unknown vault secret type: ${secret.type}`)
+  }
+
+  return { loadSecretPayload, resolveVaultSecret }
+}
+
+export type SecretResolver = ReturnType<typeof createSecretResolver>

package/src/sealed.ts

@@ -0,0 +1,38 @@
+import { customType } from 'drizzle-orm/sqlite-core'
+import type { SecretBox } from './secretBox.js'
+
+/** Marks a stored value as encrypted, so a column can hold rows from before it was sealed. */
+export const SEALED_PREFIX = 'enc:v1:'
+
+/** Turns a secret into what is stored and back. */
+export interface Sealer {
+  /**
+   * Always encrypts, whatever the value looks like: a value that merely starts with the prefix is somebody's text, or a
+   * ciphertext offered to be decrypted by the next read, and must never be taken for one already sealed. Empty stays empty.
+   */
+  seal(value: string): string
+  /** Like `seal`, but leaves a value that is already sealed alone. Only for upgrading rows that may hold either. */
+  sealPlain(value: string): string
+  /** Opens a sealed value; a value without the prefix is a row from before sealing and is returned as it is. Throws when the key does not fit. */
+  open(value: string): string
+}
+
+export function createSealer(box: Pick<SecretBox, 'encrypt' | 'decrypt'>): Sealer {
+  const seal = (value: string) => (value === '' ? value : `${SEALED_PREFIX}${box.encrypt(value)}`)
+  return {
+    seal,
+    sealPlain: (value) => (value.startsWith(SEALED_PREFIX) ? value : seal(value)),
+    open: (value) => (value.startsWith(SEALED_PREFIX) ? box.decrypt(value.slice(SEALED_PREFIX.length)) : value),
+  }
+}
+
+/** A text column whose value goes through `codec` on its way to and from the database; the rest of the code sees the open value. */
+export function sealedText(codec: Pick<Sealer, 'seal' | 'open'>) {
+  return customType<{ data: string; driverData: string }>({
+    dataType: () => 'text',
+    toDriver: codec.seal,
+    fromDriver: codec.open,
+  })
+}
+
+export type SealedText = ReturnType<typeof sealedText>