@better-forge/vault 0.1.0 → 0.1.1

package/src/secretFields.ts

@@ -1,177 +1,177 @@
-
-
-/**
- * Which parts of a configuration are secrets.
- *
- * Secrets never leave the API as stored: reads get a mask, and a write that sends the mask back means "keep the
- * stored value". The same table drives the config export, so a new secret field is declared in exactly one place.
- * Values read from a vault are references, not secrets, and are not listed here.
- *
- * The table is grouped by type for readability, but masking and restoring look at every secret field of the kind
- * whatever the object's type. A config can hold leftovers of another type (the type changed, or an API client sent
- * extra keys), and those must not read back in the clear.
- */
-
-import type { Sealer } from './sealed.js'
-
-export const SECRET_MASK = '••••••••'
-
-/** Three bullets in a row are never part of a real secret; they are a mask, or a mask somebody edited by hand. */
-const LOOKS_MASKED = /•{3}/
-
-export type SecretField =
-  /** A string at `path`; `tail` also shows its last 4 characters (long tokens only) so it can be recognised. */
-  | { path: readonly string[]; tail?: true }
-  /** Every entry of the object at `mapAt` whose key names a credential (Authorization, X-Api-Key, ...). */
-  | { mapAt: readonly string[] }
-
-/** Credential-looking header names. Wide on purpose: masking `X-Idempotency-Key` costs nothing, leaking `X-Auth` does. */
-export const SENSITIVE_HEADER = /auth|token|secret|key|pass|pwd|credential|cookie|session|signature/i
-
-export const uniqueSecretFields = (fields: readonly SecretField[]): SecretField[] => {
-  const seen = new Set<string>()
-  return fields.filter((field) => {
-    const id = 'mapAt' in field ? `map:${field.mapAt.join('.')}` : `path:${field.path.join('.')}`
-    return seen.has(id) ? false : (seen.add(id), true)
-  })
-}
-
-type Json = Record<string, unknown>
-
-const isObject = (value: unknown): value is Json => !!value && typeof value === 'object' && !Array.isArray(value)
-
-function valueAt(root: unknown, path: readonly string[]): unknown {
-  let current = root
-  for (const segment of path) {
-    if (!isObject(current)) return undefined
-    current = current[segment]
-  }
-  return current
-}
-
-/** One concrete secret value: the object holding it and its key, plus the dotted name used in messages. */
-interface Slot { holder: Json; key: string; label: string; tail: boolean }
-
-/** `••••••••`, plus the last 4 characters of a long token so it can be told apart from another one. */
-function mask(value: string, tail: boolean): string {
-  return `${SECRET_MASK}${tail && value.length >= 16 ? value.slice(-4) : ''}`
-}
-
-export type RestoreResult = { config: unknown } | { error: string }
-
-/** A switch that makes a destination less safe: a path whose value is `true`, or a path with the value that is the unsafe one (`verifyTls` off is `false`). */
-export type LooseningSwitch = readonly string[] | { path: readonly string[]; value: unknown }
-
-export function createSecretFields<Kind extends string>(kinds: Readonly<Record<Kind, {
-  fields: readonly SecretField[]
-  destinations: readonly (readonly string[])[]
-  /** Switches that make a destination less safe (certificate checks off): turning one on counts as a changed destination, turning it off does not. */
-  loosening?: readonly LooseningSwitch[]
-}>>) {
-  function slotsIn(config: unknown, kind: Kind): Slot[] {
-    const slots: Slot[] = []
-    for (const field of kinds[kind].fields) {
-      if ('mapAt' in field) {
-        const holder = valueAt(config, field.mapAt)
-        if (!isObject(holder)) continue
-        for (const key of Object.keys(holder)) {
-          if (SENSITIVE_HEADER.test(key)) slots.push({ holder, key, label: `${field.mapAt.join('.')}.${key}`, tail: false })
-        }
-      } else {
-        const holder = valueAt(config, field.path.slice(0, -1))
-        const key = field.path[field.path.length - 1]!
-        if (isObject(holder) && key in holder) slots.push({ holder, key, label: field.path.join('.'), tail: field.tail === true })
-      }
-    }
-    return slots
-  }
-
-  /** A copy of `config` with every secret replaced by its mask, whatever its type (a number is as secret as a string). */
-  function maskSecrets<T>(kind: Kind, config: T): T {
-    const copy = structuredClone(config)
-    for (const { holder, key, tail } of slotsIn(copy, kind)) {
-      const value = holder[key]
-      if (value !== null && value !== undefined && value !== '') holder[key] = mask(String(value), tail)
-    }
-    return copy
-  }
-
-  /**
-   * Resolves the secrets of an incoming config against the stored one: a mask that matches the stored secret becomes
-   * that secret again. Refused instead of saved:
-   *  - a mask, or something that looks like an edited mask, that matches nothing stored;
-   *  - a secret that is not text;
-   *  - a kept secret while the place it is sent to changed (URL, host, port), so it cannot be redirected.
-   * Pass `stored` as undefined for a new object (or one whose type changed), where any mask is a mistake.
-   */
-  function restoreSecrets(kind: Kind, incoming: unknown, stored: unknown): RestoreResult {
-    const copy = structuredClone(incoming)
-    const storedSlots = new Map(slotsIn(stored, kind).map((slot) => [slot.label, slot]))
-    let kept = false
-    for (const { holder, key, label, tail } of slotsIn(copy, kind)) {
-      const value = holder[key]
-      if (value === null || value === undefined) continue
-      if (typeof value !== 'string') return { error: `${label} must be text` }
-      if (!LOOKS_MASKED.test(value)) continue
-      const previous = storedSlots.get(label)
-      const original = previous?.holder[previous.key]
-      if (typeof original === 'string' && original && value === mask(original, tail)) {
-        holder[key] = original
-        kept = true
-      } else {
-        return { error: `${label} is a masked placeholder that does not match the stored value; enter the full value to replace it` }
-      }
-    }
-    if (kept) {
-      const moved = changedDestination(kind, copy, stored)
-      if (moved) return { error: `${moved} changed, so the stored secrets cannot be kept; enter them again` }
-    }
-    return { config: copy }
-  }
-
-  /** The first place a configuration is sent to (URL, host, port) that differs between `incoming` and `stored`, or null. */
-  function changedDestination(kind: Kind, incoming: unknown, stored: unknown): string | null {
-    for (const path of kinds[kind].destinations) {
-      // An empty value means the same as an absent one.
-      const normalised = (config: unknown) => valueAt(config, path) || null
-      if (JSON.stringify(normalised(incoming)) !== JSON.stringify(normalised(stored))) return path.join('.')
-    }
-    for (const entry of kinds[kind].loosening ?? []) {
-      const { path, value } = Array.isArray(entry) ? { path: entry as readonly string[], value: true } : entry as { path: readonly string[]; value: unknown }
-      if (valueAt(incoming, path) === value && valueAt(stored, path) !== value) return path.join('.')
-    }
-    return null
-  }
-
-  /** A copy of `config` with every secret that is text passed through `convert` (a vault reference or a number is not text and stays). */
-  function convertSecrets<T>(kind: Kind, config: T, convert: (value: string) => string): T {
-    const copy = structuredClone(config)
-    for (const { holder, key } of slotsIn(copy, kind)) {
-      const value = holder[key]
-      if (typeof value === 'string') holder[key] = convert(value)
-    }
-    return copy
-  }
-
-  /**
-   * The codec of a column that stores a configuration as JSON text: the secrets are encrypted on the way in and opened
-   * on the way out, so a copy of the database alone does not carry them. Text that is not JSON is passed through.
-   */
-  function configCodec(kind: Kind, sealer: Pick<Sealer, 'seal' | 'open'>): Pick<Sealer, 'seal' | 'open'> {
-    const through = (convert: (value: string) => string) => (json: string): string => {
-      let parsed: unknown
-      try { parsed = JSON.parse(json) } catch { return json }
-      // A config without a secret is returned as it was written, not as JSON.stringify would write it.
-      let changed = false
-      const converted = convertSecrets(kind, parsed, (value) => {
-        const result = convert(value)
-        if (result !== value) changed = true
-        return result
-      })
-      return changed ? JSON.stringify(converted) : json
-    }
-    return { seal: through(sealer.seal), open: through(sealer.open) }
-  }
-
-  return { maskSecrets, restoreSecrets, changedDestination, configCodec }
-}
+
+
+/**
+ * Which parts of a configuration are secrets.
+ *
+ * Secrets never leave the API as stored: reads get a mask, and a write that sends the mask back means "keep the
+ * stored value". The same table drives the config export, so a new secret field is declared in exactly one place.
+ * Values read from a vault are references, not secrets, and are not listed here.
+ *
+ * The table is grouped by type for readability, but masking and restoring look at every secret field of the kind
+ * whatever the object's type. A config can hold leftovers of another type (the type changed, or an API client sent
+ * extra keys), and those must not read back in the clear.
+ */
+
+import type { Sealer } from './sealed.js'
+
+export const SECRET_MASK = '••••••••'
+
+/** Three bullets in a row are never part of a real secret; they are a mask, or a mask somebody edited by hand. */
+const LOOKS_MASKED = /•{3}/
+
+export type SecretField =
+  /** A string at `path`; `tail` also shows its last 4 characters (long tokens only) so it can be recognised. */
+  | { path: readonly string[]; tail?: true }
+  /** Every entry of the object at `mapAt` whose key names a credential (Authorization, X-Api-Key, ...). */
+  | { mapAt: readonly string[] }
+
+/** Credential-looking header names. Wide on purpose: masking `X-Idempotency-Key` costs nothing, leaking `X-Auth` does. */
+export const SENSITIVE_HEADER = /auth|token|secret|key|pass|pwd|credential|cookie|session|signature/i
+
+export const uniqueSecretFields = (fields: readonly SecretField[]): SecretField[] => {
+  const seen = new Set<string>()
+  return fields.filter((field) => {
+    const id = 'mapAt' in field ? `map:${field.mapAt.join('.')}` : `path:${field.path.join('.')}`
+    return seen.has(id) ? false : (seen.add(id), true)
+  })
+}
+
+type Json = Record<string, unknown>
+
+const isObject = (value: unknown): value is Json => !!value && typeof value === 'object' && !Array.isArray(value)
+
+function valueAt(root: unknown, path: readonly string[]): unknown {
+  let current = root
+  for (const segment of path) {
+    if (!isObject(current)) return undefined
+    current = current[segment]
+  }
+  return current
+}
+
+/** One concrete secret value: the object holding it and its key, plus the dotted name used in messages. */
+interface Slot { holder: Json; key: string; label: string; tail: boolean }
+
+/** `••••••••`, plus the last 4 characters of a long token so it can be told apart from another one. */
+function mask(value: string, tail: boolean): string {
+  return `${SECRET_MASK}${tail && value.length >= 16 ? value.slice(-4) : ''}`
+}
+
+export type RestoreResult = { config: unknown } | { error: string }
+
+/** A switch that makes a destination less safe: a path whose value is `true`, or a path with the value that is the unsafe one (`verifyTls` off is `false`). */
+export type LooseningSwitch = readonly string[] | { path: readonly string[]; value: unknown }
+
+export function createSecretFields<Kind extends string>(kinds: Readonly<Record<Kind, {
+  fields: readonly SecretField[]
+  destinations: readonly (readonly string[])[]
+  /** Switches that make a destination less safe (certificate checks off): turning one on counts as a changed destination, turning it off does not. */
+  loosening?: readonly LooseningSwitch[]
+}>>) {
+  function slotsIn(config: unknown, kind: Kind): Slot[] {
+    const slots: Slot[] = []
+    for (const field of kinds[kind].fields) {
+      if ('mapAt' in field) {
+        const holder = valueAt(config, field.mapAt)
+        if (!isObject(holder)) continue
+        for (const key of Object.keys(holder)) {
+          if (SENSITIVE_HEADER.test(key)) slots.push({ holder, key, label: `${field.mapAt.join('.')}.${key}`, tail: false })
+        }
+      } else {
+        const holder = valueAt(config, field.path.slice(0, -1))
+        const key = field.path[field.path.length - 1]!
+        if (isObject(holder) && key in holder) slots.push({ holder, key, label: field.path.join('.'), tail: field.tail === true })
+      }
+    }
+    return slots
+  }
+
+  /** A copy of `config` with every secret replaced by its mask, whatever its type (a number is as secret as a string). */
+  function maskSecrets<T>(kind: Kind, config: T): T {
+    const copy = structuredClone(config)
+    for (const { holder, key, tail } of slotsIn(copy, kind)) {
+      const value = holder[key]
+      if (value !== null && value !== undefined && value !== '') holder[key] = mask(String(value), tail)
+    }
+    return copy
+  }
+
+  /**
+   * Resolves the secrets of an incoming config against the stored one: a mask that matches the stored secret becomes
+   * that secret again. Refused instead of saved:
+   *  - a mask, or something that looks like an edited mask, that matches nothing stored;
+   *  - a secret that is not text;
+   *  - a kept secret while the place it is sent to changed (URL, host, port), so it cannot be redirected.
+   * Pass `stored` as undefined for a new object (or one whose type changed), where any mask is a mistake.
+   */
+  function restoreSecrets(kind: Kind, incoming: unknown, stored: unknown): RestoreResult {
+    const copy = structuredClone(incoming)
+    const storedSlots = new Map(slotsIn(stored, kind).map((slot) => [slot.label, slot]))
+    let kept = false
+    for (const { holder, key, label, tail } of slotsIn(copy, kind)) {
+      const value = holder[key]
+      if (value === null || value === undefined) continue
+      if (typeof value !== 'string') return { error: `${label} must be text` }
+      if (!LOOKS_MASKED.test(value)) continue
+      const previous = storedSlots.get(label)
+      const original = previous?.holder[previous.key]
+      if (typeof original === 'string' && original && value === mask(original, tail)) {
+        holder[key] = original
+        kept = true
+      } else {
+        return { error: `${label} is a masked placeholder that does not match the stored value; enter the full value to replace it` }
+      }
+    }
+    if (kept) {
+      const moved = changedDestination(kind, copy, stored)
+      if (moved) return { error: `${moved} changed, so the stored secrets cannot be kept; enter them again` }
+    }
+    return { config: copy }
+  }
+
+  /** The first place a configuration is sent to (URL, host, port) that differs between `incoming` and `stored`, or null. */
+  function changedDestination(kind: Kind, incoming: unknown, stored: unknown): string | null {
+    for (const path of kinds[kind].destinations) {
+      // An empty value means the same as an absent one.
+      const normalised = (config: unknown) => valueAt(config, path) || null
+      if (JSON.stringify(normalised(incoming)) !== JSON.stringify(normalised(stored))) return path.join('.')
+    }
+    for (const entry of kinds[kind].loosening ?? []) {
+      const { path, value } = Array.isArray(entry) ? { path: entry as readonly string[], value: true } : entry as { path: readonly string[]; value: unknown }
+      if (valueAt(incoming, path) === value && valueAt(stored, path) !== value) return path.join('.')
+    }
+    return null
+  }
+
+  /** A copy of `config` with every secret that is text passed through `convert` (a vault reference or a number is not text and stays). */
+  function convertSecrets<T>(kind: Kind, config: T, convert: (value: string) => string): T {
+    const copy = structuredClone(config)
+    for (const { holder, key } of slotsIn(copy, kind)) {
+      const value = holder[key]
+      if (typeof value === 'string') holder[key] = convert(value)
+    }
+    return copy
+  }
+
+  /**
+   * The codec of a column that stores a configuration as JSON text: the secrets are encrypted on the way in and opened
+   * on the way out, so a copy of the database alone does not carry them. Text that is not JSON is passed through.
+   */
+  function configCodec(kind: Kind, sealer: Pick<Sealer, 'seal' | 'open'>): Pick<Sealer, 'seal' | 'open'> {
+    const through = (convert: (value: string) => string) => (json: string): string => {
+      let parsed: unknown
+      try { parsed = JSON.parse(json) } catch { return json }
+      // A config without a secret is returned as it was written, not as JSON.stringify would write it.
+      let changed = false
+      const converted = convertSecrets(kind, parsed, (value) => {
+        const result = convert(value)
+        if (result !== value) changed = true
+        return result
+      })
+      return changed ? JSON.stringify(converted) : json
+    }
+    return { seal: through(sealer.seal), open: through(sealer.open) }
+  }
+
+  return { maskSecrets, restoreSecrets, changedDestination, configCodec }
+}

package/src/tables.ts

@@ -1,23 +1,23 @@
-import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
-
-export const vaults = sqliteTable('vaults', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-  type: text('type').notNull().default('local'), // 'local' | 'hashicorp'
-  description: text('description'),
-  createdAt: integer('created_at').notNull(),
-  updatedAt: integer('updated_at').notNull(),
-  /** Encrypted JSON connection settings of a 'hashicorp' vault; NULL for 'local'. Never sent to the browser. */
-  connectionConfig: text('connection_config'),
-})
-
-export const vaultSecrets = sqliteTable('vault_secrets', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  vaultId: integer('vault_id').notNull(),
-  name: text('name').notNull(),
-  type: text('type').notNull(), // 'userpass' | 'value' | 'json'
-  /** Local vault: the encrypted value. HashiCorp vault: the encrypted reference `{ path, key? }`. */
-  encryptedValue: text('encrypted_value').notNull(),
-  createdAt: integer('created_at').notNull(),
-  updatedAt: integer('updated_at').notNull(),
-})
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
+
+export const vaults = sqliteTable('vaults', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  type: text('type').notNull().default('local'), // 'local' | 'hashicorp'
+  description: text('description'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+  /** Encrypted JSON connection settings of a 'hashicorp' vault; NULL for 'local'. Never sent to the browser. */
+  connectionConfig: text('connection_config'),
+})
+
+export const vaultSecrets = sqliteTable('vault_secrets', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  vaultId: integer('vault_id').notNull(),
+  name: text('name').notNull(),
+  type: text('type').notNull(), // 'userpass' | 'value' | 'json'
+  /** Local vault: the encrypted value. HashiCorp vault: the encrypted reference `{ path, key? }`. */
+  encryptedValue: text('encrypted_value').notNull(),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+})