@better-forge/vault 0.1.0 → 0.1.1

package/src/index.ts

@@ -1,9 +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'
+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

@@ -1,29 +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' },
-]
+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

@@ -1,6 +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
+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

@@ -1,96 +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>
+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

@@ -1,38 +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>
+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>

package/src/secretBox.ts

@@ -1,72 +1,72 @@
-import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
-
-const ALGORITHM = 'aes-256-gcm'
-const IV_BYTES = 12
-const TAG_BYTES = 16
-
-export interface SecretBox {
-  /** Encrypts plaintext with AES-256-GCM. Returns `iv:authTag:ciphertext` (all hex). */
-  encrypt(plaintext: string): string
-  /** Decrypts a value produced by `encrypt`. Throws on tampered data. */
-  decrypt(ciphertext: string): string
-}
-
-/**
- * Encryption of the secrets an application stores, with the key from `VAULT_ENCRYPTION_KEY` (64 hex characters).
- * The key is read on first use, so the warning about the development fallback appears once per box.
- * `env` is read at that moment, not captured, so a test may change it before first use.
- */
-export function createSecretBox(options: { env?: NodeJS.ProcessEnv } = {}): SecretBox {
-  const env = options.env ?? process.env
-  let cachedKey: Buffer | null = null
-
-  function getKey(): Buffer {
-    const raw = env['VAULT_ENCRYPTION_KEY']
-    if (!raw) {
-      if (env['NODE_ENV'] === 'production') {
-        throw new Error('VAULT_ENCRYPTION_KEY environment variable must be set in production')
-      }
-      // Dev fallback — 32-byte zero key with warning
-      console.warn('⚠ VAULT_ENCRYPTION_KEY not set — using insecure dev key (development only)')
-      return Buffer.alloc(32, 0)
-    }
-    const buf = Buffer.from(raw, 'hex')
-    if (buf.length !== 32) {
-      throw new Error('VAULT_ENCRYPTION_KEY must be a 64-character hex string (32 bytes)')
-    }
-    return buf
-  }
-
-  const key = () => (cachedKey ??= getKey())
-
-  return {
-    encrypt(plaintext) {
-      const iv = randomBytes(IV_BYTES)
-      const cipher = createCipheriv(ALGORITHM, key(), iv)
-      const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
-      const tag = cipher.getAuthTag()
-      return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`
-    },
-    decrypt(ciphertext) {
-      const parts = ciphertext.split(':')
-      if (parts.length !== 3) throw new Error('Invalid ciphertext format')
-      const [ivHex, tagHex, encHex] = parts as [string, string, string]
-      const iv = Buffer.from(ivHex, 'hex')
-      const tag = Buffer.from(tagHex, 'hex')
-      const enc = Buffer.from(encHex, 'hex')
-      if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) throw new Error('Invalid ciphertext length')
-      const decipher = createDecipheriv(ALGORITHM, key(), iv)
-      decipher.setAuthTag(tag)
-      return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8')
-    },
-  }
-}
-
-/** In production the key must be exactly 64 hexadecimal characters; refuses to start otherwise. Elsewhere anything goes. */
-export function validateEncryptionKey(env: NodeJS.ProcessEnv = process.env): void {
-  if (env['NODE_ENV'] !== 'production') return
-  const key = env['VAULT_ENCRYPTION_KEY']
-  if (!key || !/^[0-9a-fA-F]{64}$/.test(key)) {
-    throw new Error('VAULT_ENCRYPTION_KEY must be set to exactly 64 hexadecimal characters in production')
-  }
-}
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+
+const ALGORITHM = 'aes-256-gcm'
+const IV_BYTES = 12
+const TAG_BYTES = 16
+
+export interface SecretBox {
+  /** Encrypts plaintext with AES-256-GCM. Returns `iv:authTag:ciphertext` (all hex). */
+  encrypt(plaintext: string): string
+  /** Decrypts a value produced by `encrypt`. Throws on tampered data. */
+  decrypt(ciphertext: string): string
+}
+
+/**
+ * Encryption of the secrets an application stores, with the key from `VAULT_ENCRYPTION_KEY` (64 hex characters).
+ * The key is read on first use, so the warning about the development fallback appears once per box.
+ * `env` is read at that moment, not captured, so a test may change it before first use.
+ */
+export function createSecretBox(options: { env?: NodeJS.ProcessEnv } = {}): SecretBox {
+  const env = options.env ?? process.env
+  let cachedKey: Buffer | null = null
+
+  function getKey(): Buffer {
+    const raw = env['VAULT_ENCRYPTION_KEY']
+    if (!raw) {
+      if (env['NODE_ENV'] === 'production') {
+        throw new Error('VAULT_ENCRYPTION_KEY environment variable must be set in production')
+      }
+      // Dev fallback — 32-byte zero key with warning
+      console.warn('⚠ VAULT_ENCRYPTION_KEY not set — using insecure dev key (development only)')
+      return Buffer.alloc(32, 0)
+    }
+    const buf = Buffer.from(raw, 'hex')
+    if (buf.length !== 32) {
+      throw new Error('VAULT_ENCRYPTION_KEY must be a 64-character hex string (32 bytes)')
+    }
+    return buf
+  }
+
+  const key = () => (cachedKey ??= getKey())
+
+  return {
+    encrypt(plaintext) {
+      const iv = randomBytes(IV_BYTES)
+      const cipher = createCipheriv(ALGORITHM, key(), iv)
+      const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+      const tag = cipher.getAuthTag()
+      return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`
+    },
+    decrypt(ciphertext) {
+      const parts = ciphertext.split(':')
+      if (parts.length !== 3) throw new Error('Invalid ciphertext format')
+      const [ivHex, tagHex, encHex] = parts as [string, string, string]
+      const iv = Buffer.from(ivHex, 'hex')
+      const tag = Buffer.from(tagHex, 'hex')
+      const enc = Buffer.from(encHex, 'hex')
+      if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) throw new Error('Invalid ciphertext length')
+      const decipher = createDecipheriv(ALGORITHM, key(), iv)
+      decipher.setAuthTag(tag)
+      return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8')
+    },
+  }
+}
+
+/** In production the key must be exactly 64 hexadecimal characters; refuses to start otherwise. Elsewhere anything goes. */
+export function validateEncryptionKey(env: NodeJS.ProcessEnv = process.env): void {
+  if (env['NODE_ENV'] !== 'production') return
+  const key = env['VAULT_ENCRYPTION_KEY']
+  if (!key || !/^[0-9a-fA-F]{64}$/.test(key)) {
+    throw new Error('VAULT_ENCRYPTION_KEY must be set to exactly 64 hexadecimal characters in production')
+  }
+}