@rvoh/dream 2.8.0 → 2.9.0

package/dist/cjs/src/serializer/builders/DreamSerializerBuilder.js

@@ -20,14 +20,27 @@ export default class DreamSerializerBuilder {
     /**
      * Includes an attribute from a nested object in the serialized output.
      *
-     * Accesses `targetName.name` on the data object. If the target object
-     * or the delegated attribute is null/undefined, the `default` option value
-     * will be used if provided.
+     * Accesses `targetName.name` on the data object. When the target object or the
+     * delegated attribute is null/undefined, the resolution order is:
+     *   1. `default` if provided → renders the default value
+     *   2. `required: false` → omits the key entirely from the rendered output
+     *   3. otherwise → renders `null`
      *
      * When the target is a Dream model, OpenAPI types may be automatically inferred
      * for standard database columns. For json/jsonb columns or non-Dream targets,
      * the `openapi` option is required.
      *
+     * `optional` and `required` are not aliases — they encode different things and can
+     * be used together:
+     *   - `optional: true` is an OpenAPI-only marker (no runtime effect). It declares
+     *     that the rendered value may be `null` (e.g. when delegating through a HasOne
+     *     that may be missing). Use this when you want the key to always be present
+     *     but the value to be nullable in the schema.
+     *   - `required: false` affects both runtime and OpenAPI. At runtime, when the
+     *     resolved value is `undefined` (which includes the case of a missing delegated
+     *     association with no `default`), the key is omitted from the rendered output.
+     *     In OpenAPI, the field is marked as not required.
+     *
      * @param targetName - The property name containing the target object (e.g., an association name)
      * @param name - The attribute name within the target object
      * @param options - Configuration options:
@@ -35,16 +48,22 @@ export default class DreamSerializerBuilder {
      *     (e.g., delegating `'user', 'email'` with `as: 'userEmail'` outputs the value
      *     under `userEmail`)
      *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *     (not available when delegating to a `'type'` STI discriminator column: substituting
+     *     a discriminator string when the association is actually missing produces a response
+     *     indistinguishable from "association present with that type," which is misleading)
      *   - `openapi` - OpenAPI schema definition; required for non-Dream targets and json/jsonb
      *     columns, optional for standard Dream columns (where types are inferred)
-     *   - `optional` - Set to `true` to indicate the value can be null in the OpenAPI schema
-     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). For Dream models, this is
-     *     auto-inferred from optional BelongsTo associations. Use this when delegating through
-     *     a HasOne or other nullable association.
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
+     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
+     *     key is still rendered (as `null`). For Dream models, this is auto-inferred
+     *     from optional BelongsTo associations. Use this when delegating through a
+     *     HasOne or other nullable association.
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
-     *     during rendering; does not affect the OpenAPI shape
-     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
-     *     when omitted, attributes are required by default
+     *     during rendering; does not affect the OpenAPI shape (not available when delegating
+     *     to a `'type'` STI discriminator column, which is always a string enum)
+     *   - `required` - Set to `false` to omit the key from the rendered output when the
+     *     resolved value is `undefined` (including a missing delegated association with
+     *     no `default`), and to mark the field as not required in the OpenAPI schema
      * @returns The serializer builder for method chaining
      *
      * @example

package/dist/cjs/src/serializer/builders/ObjectSerializerBuilder.js

@@ -69,8 +69,20 @@ export default class ObjectSerializerBuilder {
      * Includes an attribute from a nested object in the serialized output.
      *
      * Accesses `targetName.name` on the data object. The `openapi` option is always
-     * required. If the target object or the delegated attribute is null/undefined,
-     * the `default` option value will be used if provided.
+     * required. When the target object or the delegated attribute is null/undefined,
+     * the resolution order is:
+     *   1. `default` if provided → renders the default value
+     *   2. `required: false` → omits the key entirely from the rendered output
+     *   3. otherwise → renders `null`
+     *
+     * `optional` and `required` are not aliases — they encode different things and can
+     * be used together:
+     *   - `optional: true` is an OpenAPI-only marker (no runtime effect). It declares
+     *     that the rendered value may be `null`. Use this when you want the key to always
+     *     be present but the value to be nullable in the schema.
+     *   - `required: false` affects both runtime and OpenAPI. At runtime, when the
+     *     resolved value is `undefined`, the key is omitted from the rendered output.
+     *     In OpenAPI, the field is marked as not required.
      *
      * @param targetName - The property name containing the target object
      * @param name - The attribute name within the target object
@@ -80,10 +92,14 @@ export default class ObjectSerializerBuilder {
      *     (e.g., delegating `'profile', 'avatarUrl'` with `as: 'avatar'` outputs the value
      *     under `avatar`)
      *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
+     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
+     *     key is still rendered (as `null`)
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
      *     during rendering; does not affect the OpenAPI shape
-     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
-     *     when omitted, attributes are required by default
+     *   - `required` - Set to `false` to omit the key from the rendered output when the
+     *     resolved value is `undefined`, and to mark the field as not required in the
+     *     OpenAPI schema
      * @returns The serializer builder for method chaining
      *
      * @example

package/dist/esm/src/bin/index.js

@@ -3,9 +3,13 @@ import DreamApp from '../dream-app/index.js';
 import Query from '../dream/Query.js';
 import DBClassDeprecation from '../helpers/cli/DBClassDeprecation.js';
 import generateDream from '../helpers/cli/generateDream.js';
-import sspawn from '../helpers/sspawn.js';
+import EnvInternal from '../helpers/EnvInternal.js';
 export default class DreamBin {
     static async sync(onSync, options) {
+        if (!EnvInternal.isTest) {
+            DreamCLI.logger.log(`skipping sync: auto-generated type/schema files are only built when NODE_ENV=test (current NODE_ENV: ${process.env.NODE_ENV ?? 'unset'}). Run with NODE_ENV=test to regenerate.`);
+            return;
+        }
         const dreamApp = DreamApp.getOrFail();
         for (const connectionName of Object.keys(dreamApp.dbCredentials)) {
             await Query.dbDriverClass(connectionName).sync(connectionName, onSync, options);
@@ -76,7 +80,18 @@ export default class DreamBin {
     // to use it to generate docs for their apps.
     static async buildDocs() {
         DreamCLI.logger.logStartProgress('generating docs...');
-        await sspawn('pnpm typedoc src/package-exports/*.ts --tsconfig ./tsconfig.esm.build.json --out docs');
+        // safe (R-015): all argv elements are constant literals; typedoc itself
+        // expands the glob so we don't need shell-form invocation.
+        await DreamCLI.spawn('pnpm', {
+            args: [
+                'typedoc',
+                'src/package-exports/*.ts',
+                '--tsconfig',
+                './tsconfig.esm.build.json',
+                '--out',
+                'docs',
+            ],
+        });
         DreamCLI.logger.logEndProgress();
     }
 }

package/dist/esm/src/cli/index.js

@@ -1,11 +1,12 @@
+import { spawn } from 'child_process';
 import { InvalidArgumentError, Option } from 'commander';
 import DreamBin from '../bin/index.js';
 import DreamApp from '../dream-app/index.js';
 import Encrypt from '../encrypt/index.js';
+import SspawnRequiresDevelopmentOrTest from '../errors/SspawnRequiresDevelopmentOrTest.js';
 import generateDream from '../helpers/cli/generateDream.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import loadRepl from '../helpers/loadRepl.js';
-import sspawn from '../helpers/sspawn.js';
 import DreamCliLogger from './logger/DreamCliLogger.js';
 import colorize from './logger/loggable/colorize.js';
 export const CLI_INDENT = '                  ';
@@ -208,6 +209,8 @@ ${INDENT}  Settings/CommunicationPreferences   # src/app/models/Settings/Communi
             .alias('g:sti-child')
             .description(`Generates an STI (Single Table Inheritance) child model that extends an existing parent model. The child shares the parent's database table (discriminated by the \`type\` column) and can add child-specific columns. Generates a child model decorated with @STI(Parent), child serializers extending the parent's base serializers, a migration that ALTERs the parent table (not a new table), check constraints, a factory, and spec skeleton.
 ${INDENT}
+${INDENT}If the child declares no additional columns, only the model file is generated — no migration is created. STI children share the parent's table, so a no-columns child requires no schema change. Add a migration only by passing positional field:type args, in which case the generator emits one with the appropriate check constraint. STI children never receive @SoftDelete() — soft delete is enforced at the parent level only — and the generator does not accept --no-soft-delete.
+${INDENT}
 ${INDENT}The parent must already exist (typically generated with g:model --sti-base-serializer or g:resource --sti-base-serializer).
 ${INDENT}
 ${INDENT}Examples:
@@ -288,7 +291,7 @@ ${INDENT}  pnpm psy g:encryption-key --algorithm=aes-128-gcm`)
         });
         program
             .command('db:migrate')
-            .description(`Runs all pending database migrations in order, then automatically syncs types (in development/test). This is the primary command for applying schema changes after generating or editing a migration.
+            .description(`Runs all pending database migrations in order, then automatically syncs types (only when NODE_ENV=test, to avoid clobbering generated types from a stale dev database). This is the primary command for applying schema changes after generating or editing a migration.
 ${INDENT}
 ${INDENT}Example workflow:
 ${INDENT}  pnpm psy g:migration add-phone-to-users phone:string:optional
@@ -298,14 +301,14 @@ ${INDENT}  pnpm psy db:migrate`)
             .action(async ({ skipSync }) => {
             await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbMigrate();
-            if (EnvInternal.isDevelopmentOrTest && !skipSync) {
+            if (EnvInternal.isTest && !skipSync) {
                 await DreamBin.sync(onSync);
             }
             process.exit();
         });
         program
             .command('db:rollback')
-            .description(`Rolls back the most recent migration(s), then automatically syncs types (in development/test). Use this to undo a migration so you can edit and re-run it.
+            .description(`Rolls back the most recent migration(s), then automatically syncs types (only when NODE_ENV=test, to avoid clobbering generated types from a stale dev database). Use this to undo a migration so you can edit and re-run it.
 ${INDENT}
 ${INDENT}Examples:
 ${INDENT}  pnpm psy db:rollback              # rolls back the last migration
@@ -315,7 +318,7 @@ ${INDENT}  pnpm psy db:rollback --steps=3    # rolls back the last 3 migrations`
             .action(async ({ steps, skipSync }) => {
             await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbRollback({ steps });
-            if (EnvInternal.isDevelopmentOrTest && !skipSync) {
+            if (EnvInternal.isTest && !skipSync) {
                 await DreamBin.sync(onSync);
             }
             process.exit();
@@ -409,15 +412,84 @@ ${INDENT}Examples: User, Place, Room/Bedroom, Settings/CommunicationPreferences`
             process.exit();
         });
     }
-    /*
-     * the default spawn provided by node:child_process is incompatible
-     * with promises. this will automatically wrap the spawn method,
-     * and will by default connect STDOUT to the current STDOUT,
-     * so that whatever the command is outputting is output to the
-     * primary STDOUT context.
+    /**
+     * Run a developer-authored CLI command. Always runs in argv form (the
+     * underlying child_process `spawn` is called with `shell: false`):
+     * `command` is exec'd literally and `opts.args` are passed as separate
+     * argv elements. Shell-form invocation is intentionally not supported —
+     * there is no caller that needs `&&`-chaining, globs, or other shell
+     * features that can't be expressed as argv.
+     *
+     * For backward compatibility, `command` may contain implicit args
+     * separated by whitespace (e.g. `'pnpm psy sync'`); the leading token
+     * becomes the program and the rest are split out and prepended to any
+     * `opts.args` so the original argument order is preserved:
+     *
+     *     DreamCLI.spawn('pnpm psy sync')
+     *       → spawn('pnpm', ['psy', 'sync'])
+     *
+     *     DreamCLI.spawn('pnpm psy', { args: ['sync', '--flag'] })
+     *       → spawn('pnpm', ['psy', 'sync', '--flag'])
+     *
+     * ## Threat model (R-015)
+     *
+     * For dev-time CLI glue only (scaffolding, doc generation, type sync).
+     * **No runtime HTTP request input ever reaches this function.** Inputs
+     * are constant literals or composed from developer-supplied config
+     * (package.json scripts, CLI argv, scaffold templates) — never from
+     * runtime request input or any other untrusted external source.
+     *
+     * Argv-form is the safe choice for any caller that interpolates a
+     * config value, path, or credential: a database password containing
+     * `$` or backticks is passed literally to the child rather than
+     * interpreted by a shell.
+     *
+     * ## Layered defense
+     *
+     * Primary gate: every caller restricts spawn use to dev/test code paths
+     * (CLI commands, the dev watcher, scaffold-time code generators,
+     * generated `cli:sync` initializers wrapped in
+     * `if (AppEnv.isDevelopmentOrTest)`).
+     *
+     * Backstop: throws `SspawnRequiresDevelopmentOrTest` when `NODE_ENV` is
+     * anything other than `development` or `test`. Checking
+     * `!isDevelopmentOrTest` (rather than `isProduction`) means staging-style
+     * envs and any unforeseen NODE_ENV value also fail closed.
      */
     static async spawn(command, opts) {
-        return await sspawn(command, opts);
+        const tokens = command.trim().split(/\s+/).filter(Boolean);
+        const [program = '', ...implicitArgs] = tokens;
+        const { args: callerArgs = [], onStdout, ...spawnOpts } = opts ?? {};
+        const args = [...implicitArgs, ...callerArgs];
+        if (!EnvInternal.isDevelopmentOrTest) {
+            throw new SspawnRequiresDevelopmentOrTest([program, ...args].join(' '));
+        }
+        return new Promise((accept, reject) => {
+            const proc = spawn(program, args, { shell: false, ...spawnOpts });
+            // NOTE: stdout spy so this CLI utility can hijack the stdout from the
+            // child command and route it through a caller-provided sink.
+            proc.stdout?.on('data', chunk => {
+                const txt = chunk?.toString()?.trim();
+                if (typeof txt !== 'string' || !txt)
+                    return;
+                if (onStdout) {
+                    onStdout(txt);
+                }
+                else {
+                    // eslint-disable-next-line no-console
+                    console.log(txt);
+                }
+            });
+            proc.stdout?.on('error', handleSpawnError);
+            proc.stderr?.on('error', handleSpawnError);
+            proc.stderr?.on('data', handleSpawnError);
+            proc.on('error', handleSpawnError);
+            proc.on('close', code => {
+                if (code !== 0)
+                    reject(code);
+                accept();
+            });
+        });
     }
     static get logger() {
         this._logger ||= new DreamCliLogger();
@@ -432,3 +504,7 @@ function myParseInt(value) {
     }
     return parsedValue;
 }
+function handleSpawnError(err) {
+    // eslint-disable-next-line no-console
+    console.error(err?.toString());
+}

package/dist/esm/src/db/helpers/syncDbTypesFiles.js

@@ -5,7 +5,6 @@ import colorize from '../../cli/logger/loggable/colorize.js';
 import DreamApp from '../../dream-app/index.js';
 import ASTKyselyCodegenEnhancer from '../../helpers/cli/ASTKyselyCodegenEnhancer.js';
 import dreamPath from '../../helpers/path/dreamPath.js';
-import sspawn from '../../helpers/sspawn.js';
 import dbTypesFilenameForConnection from './dbTypesFilenameForConnection.js';
 export default async function syncDbTypesFiles(connectionName) {
     const dreamApp = DreamApp.getOrFail();
@@ -16,17 +15,23 @@ export default async function syncDbTypesFiles(connectionName) {
     const absoluteDbSyncPath = path.join(dreamApp.projectRoot, dbSyncFilePath);
     await CliFileWriter.cache(absoluteDbSyncPath);
     const lowLevelDbOpts = dreamApp.dbCredentialsFor(connectionName);
-    const dialect = `--dialect=${driverClass.syncDialect}`;
-    const url = `--url=${driverClass.syncDialect}://${dbConf.user}${dbConf.password ? `:${dbConf.password}` : ''}@${dbConf.host}:${dbConf.port}/${dbConf.name}`;
-    const outfile = `--out-file=${absoluteDbSyncPath}`;
-    const includePattern = lowLevelDbOpts?.tableIncludePattern
-        ? `--include-pattern="${lowLevelDbOpts.tableIncludePattern}"`
-        : '';
-    const excludePattern = lowLevelDbOpts?.tableExcludePattern
-        ? `--exclude-pattern="${lowLevelDbOpts.tableExcludePattern}"`
-        : '';
-    const kyselyCodegenCmd = `kysely-codegen ${dialect} ${url} ${includePattern} ${excludePattern} ${outfile}`;
-    await sspawn(kyselyCodegenCmd, {
+    // Argv form (R-015): the connection URL embeds the DB password, and passwords
+    // may legitimately contain shell meta-characters (`$`, backticks, spaces, etc.).
+    // DreamCLI.spawn always uses shell:false, so each arg is passed literally to
+    // the child rather than parsed by a shell — credentials are preserved and any
+    // future mutable source can't open a command-injection surface.
+    const userinfo = `${dbConf.user}${dbConf.password ? `:${dbConf.password}` : ''}`;
+    const url = `${driverClass.syncDialect}://${userinfo}@${dbConf.host}:${dbConf.port}/${dbConf.name}`;
+    const args = [`--dialect=${driverClass.syncDialect}`, `--url=${url}`];
+    if (lowLevelDbOpts?.tableIncludePattern) {
+        args.push(`--include-pattern=${lowLevelDbOpts.tableIncludePattern}`);
+    }
+    if (lowLevelDbOpts?.tableExcludePattern) {
+        args.push(`--exclude-pattern=${lowLevelDbOpts.tableExcludePattern}`);
+    }
+    args.push(`--out-file=${absoluteDbSyncPath}`);
+    await DreamCLI.spawn('kysely-codegen', {
+        args,
         onStdout: message => {
             DreamCLI.logger.logContinueProgress(colorize(`[db]`, { color: 'greenBright' }) + ' ' + message, {
                 logPrefixColor: 'greenBright',

package/dist/esm/src/decorators/class/ReplicaSafe.js

@@ -1,9 +1,8 @@
 import StiChildIncompatibleWithReplicaSafeDecorator from '../../errors/sti/StiChildIncompatibleWithReplicaSafeDecorator.js';
 export default function ReplicaSafe() {
     return function (target) {
-        const dreamClass = target;
-        if (dreamClass['isSTIChild'])
-            throw new StiChildIncompatibleWithReplicaSafeDecorator(dreamClass);
-        dreamClass['replicaSafe'] = true;
+        if (target['isSTIChild'])
+            throw new StiChildIncompatibleWithReplicaSafeDecorator(target);
+        target['replicaSafe'] = true;
     };
 }

package/dist/esm/src/decorators/class/STI.js

@@ -4,8 +4,7 @@ import StiChildIncompatibleWithSoftDeleteDecorator from '../../errors/sti/StiChi
 import { scopeImplementation } from '../static-method/Scope.js';
 export const STI_SCOPE_NAME = 'dream:STI';
 export default function STI(dreamClass) {
-    return function (target) {
-        const stiChildClass = target;
+    return function (stiChildClass) {
         const baseClass = dreamClass['sti'].baseClass || dreamClass;
         if (Object.getOwnPropertyDescriptor(stiChildClass, 'associationMetadataByType'))
             throw new StiChildCannotDefineNewAssociations(baseClass, stiChildClass);

package/dist/esm/src/decorators/class/SoftDelete.js

@@ -38,12 +38,11 @@ export const SOFT_DELETE_SCOPE_NAME = 'dream:SoftDelete';
  */
 export default function SoftDelete() {
     return function (target) {
-        const dreamClass = target;
-        if (dreamClass['isSTIChild'])
-            throw new StiChildIncompatibleWithSoftDeleteDecorator(dreamClass);
-        dreamClass['softDelete'] = true;
+        if (target['isSTIChild'])
+            throw new StiChildIncompatibleWithSoftDeleteDecorator(target);
+        target['softDelete'] = true;
         target[SOFT_DELETE_SCOPE_NAME] = function (query) {
-            return query.where({ [dreamClass.prototype['_deletedAtField']]: null });
+            return query.where({ [target.prototype['_deletedAtField']]: null });
         };
         scopeImplementation(target, SOFT_DELETE_SCOPE_NAME, { default: true });
     };

package/dist/esm/src/dream/QueryDriver/Kysely.js

@@ -99,7 +99,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 database: DreamApp.getOrFail().dbName(connectionName, dbConnectionType),
                 host: connectionConf.host || 'localhost',
                 port: connectionConf.port || 5432,
-                ssl: connectionConf.useSsl ? defaultPostgresSslConfig(connectionConf) : false,
+                ssl: resolvePostgresSsl(connectionConf),
             }),
         });
     }
@@ -2043,15 +2043,26 @@ const associationStringToAssociationAndMaybeAlias = function ({ dreamClass, asso
         alias,
     };
 };
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function defaultPostgresSslConfig(connectionConf) {
-    // TODO: properly configure (https://rvohealth.atlassian.net/browse/PDTC-2914)
-    return {
-        rejectUnauthorized: false,
-        // ca: fs.readFileSync('/path/to/server-certificates/root.crt').toString(),
-        // key: fs.readFileSync('/path/to/client-key/postgresql.key').toString(),
-        // cert: fs.readFileSync('/path/to/client-certificates/postgresql.crt').toString(),
-    };
+/**
+ * Resolve the value passed to `pg.Pool`'s `ssl` field for a given credential.
+ *
+ * Precedence:
+ *   1. If `connectionConf.ssl` is set (boolean or `tls.ConnectionOptions`),
+ *      pass it straight through to `pg`. This is the verified-TLS path —
+ *      apps configure `{ rejectUnauthorized: true, ca: <bundle> }` for
+ *      authenticated TLS against a private PKI, or `true` to use Node's
+ *      default verification against the system CA store.
+ *   2. Else if `connectionConf.useSsl` is `true`, fall back to
+ *      `{ rejectUnauthorized: false }` — encrypted but **not** authenticated.
+ *      Preserved for back-compat; new code should set `ssl` explicitly.
+ *   3. Else disable TLS.
+ */
+export function resolvePostgresSsl(connectionConf) {
+    if (connectionConf.ssl !== undefined)
+        return connectionConf.ssl;
+    if (connectionConf.useSsl)
+        return { rejectUnauthorized: false };
+    return false;
 }
 function shouldSoftDelete(dream, reallyDestroy) {
     const dreamClass = dream.constructor;

package/dist/esm/src/encrypt/algorithms/aes-gcm/decryptAESGCM.js

@@ -1,11 +1,24 @@
 import * as crypto from 'crypto';
+import DecryptionError from '../../../errors/encrypt/DecryptionError.js';
+import DecryptionParseError from '../../../errors/encrypt/DecryptionParseError.js';
 export default function decryptAESGCM(algorithm, encrypted, key) {
-    const { ciphertext, tag, iv } = unpackPayloadOrFail(encrypted);
-    const decipher = crypto.createDecipheriv(algorithm, Buffer.from(key, 'base64'), Buffer.from(iv, 'base64'));
-    decipher.setAuthTag(Buffer.from(tag, 'base64'));
-    let plaintext = decipher.update(ciphertext, 'base64', 'utf8');
-    plaintext += decipher.final('utf8');
-    return JSON.parse(plaintext);
+    let plaintext;
+    try {
+        const { ciphertext, tag, iv } = unpackPayloadOrFail(encrypted);
+        const decipher = crypto.createDecipheriv(algorithm, Buffer.from(key, 'base64'), Buffer.from(iv, 'base64'));
+        decipher.setAuthTag(Buffer.from(tag, 'base64'));
+        plaintext = decipher.update(ciphertext, 'base64', 'utf8');
+        plaintext += decipher.final('utf8');
+    }
+    catch (cause) {
+        throw Object.assign(new DecryptionError(), { cause });
+    }
+    try {
+        return JSON.parse(plaintext);
+    }
+    catch (cause) {
+        throw Object.assign(new DecryptionParseError(), { cause });
+    }
 }
 function unpackPayloadOrFail(payload) {
     const unpackedPayload = (typeof payload === 'string' ? JSON.parse(Buffer.from(payload, 'base64').toString()) : payload);

package/dist/esm/src/encrypt/index.js

@@ -1,3 +1,5 @@
+import DecryptionError from '../errors/encrypt/DecryptionError.js';
+import DecryptionWithRotationError from '../errors/encrypt/DecryptionWithRotationError.js';
 import MissingEncryptionKey from '../errors/encrypt/MissingEncryptionKey.js';
 import decryptAESGCM from './algorithms/aes-gcm/decryptAESGCM.js';
 import encryptAESGCM from './algorithms/aes-gcm/encryptAESGCM.js';
@@ -20,6 +22,30 @@ export default class Encrypt {
             }
         }
     }
+    /**
+     * Decrypts a value previously produced by {@link Encrypt.encrypt}.
+     *
+     * Behavior depends on whether `legacyOpts` is provided:
+     *
+     * **Two-arg form** (no rotation):
+     * - `null`/`undefined` input returns `null`.
+     * - Cipher op / auth tag / payload-shape failure throws `DecryptionError`.
+     * - Successful decrypt with non-JSON plaintext throws `DecryptionParseError`.
+     *
+     * **Three-arg form** (rotation): tries the current key first; on
+     * `DecryptionError` falls back to the legacy key. If both fail, throws
+     * `DecryptionWithRotationError` carrying both per-key errors. A
+     * `DecryptionParseError` from the current key is **not** retried — the
+     * cipher already matched, so a parse failure means the encrypted format
+     * is wrong (an app bug), not a wrong key.
+     *
+     * `MissingEncryptionKey` propagates from either form when a key is missing.
+     *
+     * @throws MissingEncryptionKey
+     * @throws DecryptionError
+     * @throws DecryptionParseError
+     * @throws DecryptionWithRotationError
+     */
     static decrypt(encrypted, { algorithm, key }, legacyOpts) {
         if (legacyOpts)
             return this.attemptDecryptionWithLegacyKeys(encrypted, { algorithm, key }, legacyOpts);
@@ -31,12 +57,7 @@ export default class Encrypt {
             case 'aes-256-gcm':
             case 'aes-192-gcm':
             case 'aes-128-gcm':
-                try {
-                    return decryptAESGCM(algorithm, encrypted, key);
-                }
-                catch {
-                    return null;
-                }
+                return decryptAESGCM(algorithm, encrypted, key);
             default: {
                 // protection so that if a new EncryptAlgorithm is ever added, this will throw a type error at build time
                 const _never = algorithm;
@@ -44,12 +65,60 @@ export default class Encrypt {
             }
         }
     }
-    static attemptDecryptionWithLegacyKeys(encrypted, { algorithm, key }, legacyOpts) {
-        const decrypted = this.decrypt(encrypted, { algorithm, key });
-        if (decrypted !== null)
-            return decrypted;
-        return this.decrypt(encrypted, legacyOpts);
+    static attemptDecryptionWithLegacyKeys(encrypted, currentOpts, legacyOpts) {
+        let currentKeyError;
+        try {
+            return this.decrypt(encrypted, currentOpts);
+        }
+        catch (err) {
+            if (!(err instanceof DecryptionError))
+                throw err;
+            currentKeyError = err;
+        }
+        try {
+            return this.decrypt(encrypted, legacyOpts);
+        }
+        catch (err) {
+            if (!(err instanceof DecryptionError))
+                throw err;
+            throw new DecryptionWithRotationError(currentKeyError, err);
+        }
     }
+    /**
+     * Generates a base64-encoded random key suitable for the given algorithm.
+     *
+     * ## Rotation workflow
+     *
+     * 1. Generate a new key: `const newKey = Encrypt.generateKey('aes-256-gcm')`.
+     * 2. Configure rotation by setting both `current` and `legacy`. For
+     *    encrypted columns: `dreamApp.set('encryption', { columns: { current:
+     *    { algorithm: 'aes-256-gcm', key: newKey }, legacy: { algorithm:
+     *    'aes-256-gcm', key: oldKey } } })`. For cookies, use the equivalent
+     *    shape under `psychicApp.set('encryption', { cookies: { current,
+     *    legacy } })`.
+     * 3. Deploy. New encryptions use `current`; existing ciphertext continues
+     *    to decrypt via `legacy` fallback.
+     * 4. For cookies, wait at least the cookie `maxAge` so all in-flight
+     *    cookies have either expired or been re-issued under the new key. For
+     *    `@Encrypted` columns, re-encrypt every existing row under the new
+     *    key (read each row and write it back; the setter re-encrypts with
+     *    `current`).
+     * 5. Drop `legacy` from config and deploy again.
+     *
+     * ## When to rotate
+     *
+     * - On a scheduled cadence (90–180 days is a reasonable policy default).
+     * - Incident response: leaked env file, departing employee with key
+     *   access, or any suspected key compromise.
+     *
+     * ## How long to keep `legacy`
+     *
+     * - For cookies: at least the cookie `maxAge`, so in-flight sessions are
+     *   not forced to re-authenticate.
+     * - For `@Encrypted` columns: until every existing row has been
+     *   re-encrypted under the new key. Dropping `legacy` early will cause
+     *   `DecryptionWithRotationError` on any not-yet-rewritten row.
+     */
     static generateKey(algorithm) {
         switch (algorithm) {
             case 'aes-256-gcm':

package/dist/esm/src/errors/SspawnRequiresDevelopmentOrTest.js

@@ -0,0 +1,26 @@
+export default class SspawnRequiresDevelopmentOrTest extends Error {
+    command;
+    constructor(command) {
+        super();
+        this.command = command;
+    }
+    get message() {
+        return `
+DreamCLI.spawn refused to run outside development or test
+(NODE_ENV must be 'development' or 'test').
+
+DreamCLI.spawn is dev-time CLI glue (scaffolding, docs generation,
+type sync). It must never run in a deployed process — production has
+no business shelling out arbitrary commands, and refusing here turns
+the dev-only contract into a runtime invariant. Checking
+\`!isDevelopmentOrTest\` (rather than \`isProduction\`) means
+staging-style envs and any unforeseen NODE_ENV value also fail closed.
+
+If you reached this from a deploy step, route the work through direct
+child_process APIs at the call site with explicit argv and a documented
+threat model rather than through this helper.
+
+  command: ${this.command}
+    `;
+    }
+}

package/dist/esm/src/errors/encrypt/DecryptionError.js

@@ -0,0 +1,5 @@
+export default class DecryptionError extends Error {
+    get message() {
+        return 'Failed to decrypt: cipher operation, authentication tag, or payload shape was invalid. The ciphertext may have been tampered with, corrupted, or encrypted with a different key.';
+    }
+}

package/dist/esm/src/errors/encrypt/DecryptionParseError.js

@@ -0,0 +1,5 @@
+export default class DecryptionParseError extends Error {
+    get message() {
+        return 'Decryption succeeded but the plaintext was not valid JSON. This indicates an encrypted-format mismatch (e.g. a non-JSON value was passed into Encrypt.encrypt), not tampering.';
+    }
+}

package/dist/esm/src/errors/encrypt/DecryptionWithRotationError.js

@@ -0,0 +1,12 @@
+export default class DecryptionWithRotationError extends Error {
+    currentKeyError;
+    legacyKeyError;
+    constructor(currentKeyError, legacyKeyError) {
+        super(undefined, { cause: { current: currentKeyError, legacy: legacyKeyError } });
+        this.currentKeyError = currentKeyError;
+        this.legacyKeyError = legacyKeyError;
+    }
+    get message() {
+        return 'Failed to decrypt with both the current and legacy keys. The ciphertext may have been tampered with, corrupted, or encrypted with a key that is no longer in rotation.';
+    }
+}