fix(sim-setup): refuse an ambiguous or unstorable shell POSTGRES_PASSWORD

An empty export, one that differs from .env, or one .env cannot hold verbatim now stops setup with instructions instead of silently picking a value the database may not have been created with.

Author: waleedlatif1

packages/sim-setup/src/compose-database.test.ts

@@ -8,6 +8,7 @@ import {
   LEGACY_POSTGRES_PASSWORD,
   postgresUser,
 } from './compose-database'
+import { SetupError } from './errors'
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..')
 const COMPOSE_FILES = [
@@ -34,43 +35,77 @@ afterEach(() => {
 })
 
 describe('choosePostgresPassword', () => {
+  const noShell = {}
+
   it('leaves a password already in .env alone without looking for a volume', () => {
     const hasDatabaseVolume = vi.fn(() => true)
     expect(
-      choosePostgresPassword('in-env-file', 'sim-abc', {
-        shellValue: 'in-shell',
-        hasDatabaseVolume,
-      })
+      choosePostgresPassword('in-env-file', 'sim-abc', { shell: noShell, hasDatabaseVolume })
     ).toBeNull()
     expect(hasDatabaseVolume).not.toHaveBeenCalled()
   })
 
-  it('persists a shell-exported password, which is what Compose is using', () => {
-    const hasDatabaseVolume = vi.fn(() => true)
-    expect(
-      choosePostgresPassword(undefined, 'sim-abc', { shellValue: 'in-shell', hasDatabaseVolume })
-    ).toEqual({ value: 'in-shell', source: 'environment' })
-    expect(hasDatabaseVolume).not.toHaveBeenCalled()
-  })
-
   it('generates a password for a project with no database volume yet', () => {
     const hasDatabaseVolume = vi.fn(() => false)
-    const choice = choosePostgresPassword('', 'sim-abc', { shellValue: '', hasDatabaseVolume })
+    const choice = choosePostgresPassword(undefined, 'sim-abc', {
+      shell: noShell,
+      hasDatabaseVolume,
+    })
     expect(hasDatabaseVolume).toHaveBeenCalledWith('sim-abc')
     expect(choice?.source).toBe('generated')
     expect(choice?.value).toMatch(/^[0-9a-f]{64}$/)
   })
 
   it('keeps the legacy password for a volume created before it was required', () => {
+    expect(
+      choosePostgresPassword('', 'sim-abc', { shell: noShell, hasDatabaseVolume: () => true })
+    ).toEqual({ value: LEGACY_POSTGRES_PASSWORD, source: 'legacy' })
+  })
+
+  it('persists a shell-only password, which is what Compose is using', () => {
+    const hasDatabaseVolume = vi.fn(() => true)
     expect(
       choosePostgresPassword(undefined, 'sim-abc', {
-        shellValue: '',
-        hasDatabaseVolume: () => true,
+        shell: { POSTGRES_PASSWORD: 'in-shell' },
+        hasDatabaseVolume,
       })
-    ).toEqual({ value: LEGACY_POSTGRES_PASSWORD, source: 'legacy' })
+    ).toEqual({ value: 'in-shell', source: 'environment' })
+    expect(hasDatabaseVolume).not.toHaveBeenCalled()
+  })
+
+  it('accepts a shell password that matches .env', () => {
+    expect(
+      choosePostgresPassword('same', 'sim-abc', { shell: { POSTGRES_PASSWORD: 'same' } })
+    ).toBeNull()
   })
 
-  it('reads the shell environment by default', () => {
+  it('refuses a shell password that differs from .env', () => {
+    expect(() =>
+      choosePostgresPassword('in-env-file', 'sim-abc', { shell: { POSTGRES_PASSWORD: 'other' } })
+    ).toThrow(SetupError)
+  })
+
+  it('refuses an empty shell export, which Compose would use over .env', () => {
+    for (const envFileValue of [undefined, 'in-env-file']) {
+      expect(() =>
+        choosePostgresPassword(envFileValue, 'sim-abc', { shell: { POSTGRES_PASSWORD: '' } })
+      ).toThrow(/exported but empty/)
+    }
+  })
+
+  it.each(['pa ss', 'pass#word', 'pa"ss', "pa'ss", 'pa\\ss', 'pa$ss'])(
+    'refuses to persist %s, which .env cannot store verbatim',
+    (value) => {
+      expect(() =>
+        choosePostgresPassword(undefined, 'sim-abc', {
+          shell: { POSTGRES_PASSWORD: value },
+          hasDatabaseVolume: () => false,
+        })
+      ).toThrow(/cannot store verbatim/)
+    }
+  )
+
+  it('reads the process environment by default', () => {
     vi.stubEnv('POSTGRES_PASSWORD', 'from-process')
     expect(choosePostgresPassword(undefined, 'sim-abc', { hasDatabaseVolume: () => true })).toEqual(
       { value: 'from-process', source: 'environment' }

packages/sim-setup/src/compose-database.ts

@@ -32,37 +32,72 @@ export interface PostgresPasswordChoice {
   source: PostgresPasswordSource
 }
 
+/**
+ * Characters that `.env` would reinterpret — whitespace, comments, quotes,
+ * escapes, and Compose's `$` interpolation — so a value containing one cannot
+ * be written unquoted and read back unchanged.
+ */
+const DOTENV_UNSAFE = /[\s#'"\\$]/
+
 interface ChooseOptions {
-  /** `POSTGRES_PASSWORD` from the shell, which Compose interpolates over `.env`. */
-  shellValue?: string
+  /** The shell environment, whose `POSTGRES_PASSWORD` Compose interpolates over `.env`. */
+  shell?: NodeJS.ProcessEnv
   hasDatabaseVolume?: (project: string) => boolean
 }
 
 /**
  * Picks the `POSTGRES_PASSWORD` to write to a Compose install's `.env`, or null
- * when `.env` already has one. The production Compose file requires the
- * variable, and the value must match what the data volume was created with —
+ * when `.env` already has the right one. The production Compose file requires
+ * the variable, and the value must match what the data volume was created with —
  * Postgres ignores `POSTGRES_PASSWORD` on an existing data directory, so a
  * wrong value locks the app out of its own database:
  *
- * - A value exported in the shell is what Compose is using, so it is persisted;
- *   otherwise a later run without the export would fall back to a guess.
+ * - A value exported in the shell is what Compose is using. It is persisted when
+ *   `.env` has none, so a later run without the export does not fall back to a
+ *   guess. An empty export, one that differs from `.env`, or one `.env` cannot
+ *   hold verbatim is refused: which value the volume was created with cannot be
+ *   known, and either silent choice can lock the app out.
  * - With no value anywhere, an existing volume was created with the legacy
  *   password, and a project with no volume yet gets a generated one.
  */
 export function choosePostgresPassword(
   envFileValue: string | undefined,
   project: string,
-  {
-    shellValue = process.env.POSTGRES_PASSWORD,
-    hasDatabaseVolume = composeDatabaseVolumeExists,
-  }: ChooseOptions = {}
+  { shell = process.env, hasDatabaseVolume = composeDatabaseVolumeExists }: ChooseOptions = {}
 ): PostgresPasswordChoice | null {
-  if (envFileValue) return null
-  if (shellValue) return { value: shellValue, source: 'environment' }
-  return hasDatabaseVolume(project)
-    ? { value: LEGACY_POSTGRES_PASSWORD, source: 'legacy' }
-    : { value: generateSecret(), source: 'generated' }
+  const shellValue = shell.POSTGRES_PASSWORD
+  if (shellValue === undefined) {
+    if (envFileValue) return null
+    return hasDatabaseVolume(project)
+      ? { value: LEGACY_POSTGRES_PASSWORD, source: 'legacy' }
+      : { value: generateSecret(), source: 'generated' }
+  }
+  if (shellValue === '') {
+    throw new SetupError(
+      'POSTGRES_PASSWORD is exported but empty, and Compose uses it over .env.',
+      ['unset it (unset POSTGRES_PASSWORD) so the value in .env applies']
+    )
+  }
+  if (envFileValue) {
+    if (envFileValue === shellValue) return null
+    throw new SetupError(
+      'POSTGRES_PASSWORD in the shell differs from the one in .env, so it is unclear which one the database was created with.',
+      [
+        'unset the exported POSTGRES_PASSWORD if .env holds the database password',
+        'or set the exported value in .env if that is the database password',
+      ]
+    )
+  }
+  if (DOTENV_UNSAFE.test(shellValue)) {
+    throw new SetupError(
+      'POSTGRES_PASSWORD is exported only in the shell, and contains characters .env cannot store verbatim.',
+      [
+        'add it to .env yourself, quoted, so later runs without the export still use it',
+        'new installs: use a value from openssl rand -hex 24',
+      ]
+    )
+  }
+  return { value: shellValue, source: 'environment' }
 }
 
 /** Whether a Compose project already has a Postgres data volume, found by Compose's own labels. */