@rvoh/dream 2.35.0 → 2.36.1

package/dist/cjs/src/encrypt/InternalEncrypt.js

@@ -1,4 +1,7 @@
 import DreamApp from '../dream-app/index.js';
+import DecryptionError from '../errors/encrypt/DecryptionError.js';
+import DecryptionParseError from '../errors/encrypt/DecryptionParseError.js';
+import DecryptionRotationError from '../errors/encrypt/DecryptionRotationError.js';
 import MissingColumnEncryptionOpts from '../errors/encrypt/MissingColumnEncryptionOpts.js';
 import Encrypt from './index.js';
 export default class InternalEncrypt {
@@ -11,19 +14,89 @@ export default class InternalEncrypt {
             return null;
         return this.doEncryption(data, encryptOpts.current);
     }
-    static decryptColumn(data) {
+    /**
+     * Returns `existingCiphertext` when the current column key opens it to a
+     * value whose JSON serialization equals `data`'s, the plaintext
+     * `encryptColumn(data)` would encrypt, and otherwise `encryptColumn(data)`.
+     * A value only the legacy key opens, ciphertext no key opens, and a
+     * missing `existingCiphertext` all get fresh ciphertext. It never calls
+     * `onLegacyKeyUsed`.
+     */
+    static reuseOrEncryptColumn(data, existingCiphertext) {
+        if (data === null || data === undefined || typeof existingCiphertext !== 'string')
+            return this.encryptColumn(data);
+        const dreamApp = DreamApp.getOrFail();
+        const encryptOpts = dreamApp.encryption?.columns;
+        if (!encryptOpts)
+            throw new MissingColumnEncryptionOpts();
+        let existingPlaintext;
+        try {
+            existingPlaintext = Encrypt.decrypt(existingCiphertext, encryptOpts.current);
+        }
+        catch (err) {
+            if (err instanceof DecryptionError || err instanceof DecryptionParseError)
+                return this.encryptColumn(data);
+            throw err;
+        }
+        return JSON.stringify(existingPlaintext) === JSON.stringify(data)
+            ? existingCiphertext
+            : this.encryptColumn(data);
+    }
+    /**
+     * Decrypts `data` with the column keys, current then legacy.
+     * `onLegacyKeyUsed` is passed to `Encrypt.decrypt`, so it is called only
+     * when the legacy key opened the value.
+     */
+    static decryptColumn(data, callbacks = {}) {
         const dreamApp = DreamApp.getOrFail();
         const encryptOpts = dreamApp.encryption?.columns;
         if (!encryptOpts)
             throw new MissingColumnEncryptionOpts();
         if (data === null || data === undefined)
             return null;
-        return this.doDecryption(data, encryptOpts.current, encryptOpts.legacy);
+        return this.doDecryption(data, encryptOpts.current, encryptOpts.legacy, callbacks);
+    }
+    /**
+     * Encrypts `data`, a column's ciphertext, again with the current column key
+     * (see `Encrypt.reencrypt`), opening it with the current key or, failing
+     * that, the legacy one. It does not call `onLegacyKeyUsed`.
+     */
+    static reencryptColumn(data) {
+        const dreamApp = DreamApp.getOrFail();
+        const encryptOpts = dreamApp.encryption?.columns;
+        if (!encryptOpts)
+            throw new MissingColumnEncryptionOpts();
+        if (data === null || data === undefined)
+            return null;
+        return Encrypt.reencrypt(data, encryptOpts.current, encryptOpts.legacy);
+    }
+    /**
+     * Whether `data` is ciphertext that the column keys (current, then legacy)
+     * open to a value `decryptColumn` returns. A missing column encryption
+     * config or key still throws, since that is a configuration error rather
+     * than a property of `data`.
+     */
+    static isDecryptableColumnCiphertext(data) {
+        const dreamApp = DreamApp.getOrFail();
+        const encryptOpts = dreamApp.encryption?.columns;
+        if (!encryptOpts)
+            throw new MissingColumnEncryptionOpts();
+        try {
+            this.doDecryption(data, encryptOpts.current, encryptOpts.legacy);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof DecryptionError ||
+                err instanceof DecryptionParseError ||
+                err instanceof DecryptionRotationError)
+                return false;
+            throw err;
+        }
     }
     static doEncryption(data, encryptionOpts) {
         return Encrypt.encrypt(data, encryptionOpts);
     }
-    static doDecryption(data, encryptionOpts, legacyEncryptionOpts) {
-        return Encrypt.decrypt(data, encryptionOpts, legacyEncryptionOpts);
+    static doDecryption(data, encryptionOpts, legacyEncryptionOpts, callbacks = {}) {
+        return Encrypt.decrypt(data, encryptionOpts, legacyEncryptionOpts, callbacks);
     }
 }

package/dist/cjs/src/encrypt/defaultEncryptedColumnName.js

@@ -0,0 +1,10 @@
+import pascalize from '../helpers/pascalize.js';
+/**
+ * The column that holds an `@deco.Encrypted` property's ciphertext when the
+ * decorator is not given one: the property's name, pascalized and prefixed
+ * with `encrypted`. `secretPhone`, or `secret_phone`, gives
+ * `encryptedSecretPhone`, which is the `encrypted_secret_phone` column.
+ */
+export default function defaultEncryptedColumnName(propertyName) {
+    return `encrypted${pascalize(propertyName)}`;
+}

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

@@ -41,14 +41,30 @@ export default class Encrypt {
      *
      * `MissingEncryptionKey` propagates from either form when a key is missing.
      *
+     * **`onLegacyKeyUsed`** (optional fourth argument): during a key rotation,
+     * tells you which values still need the legacy key. It is called with no
+     * arguments, synchronously, before a three-arg call returns a value that
+     * the legacy key opened. It is not called when the current key opens the
+     * value, when decryption throws, or in the two-arg form. An error it
+     * throws propagates from `decrypt` as is.
+     *
+     * ```ts
+     * const value = Encrypt.decrypt<string>(
+     *   encrypted,
+     *   { algorithm: 'aes-256-gcm', key: newKey },
+     *   { algorithm: 'aes-256-gcm', key: oldKey },
+     *   { onLegacyKeyUsed: () => console.warn('this value is still encrypted with the old key') }
+     * )
+     * ```
+     *
      * @throws MissingEncryptionKey
      * @throws DecryptionError
      * @throws DecryptionParseError
      * @throws DecryptionRotationError
      */
-    static decrypt(encrypted, { algorithm, key }, legacyOpts) {
+    static decrypt(encrypted, { algorithm, key }, legacyOpts, { onLegacyKeyUsed } = {}) {
         if (legacyOpts)
-            return this.attemptDecryptionWithLegacyKeys(encrypted, { algorithm, key }, legacyOpts);
+            return this.attemptDecryptionWithLegacyKeys(encrypted, { algorithm, key }, legacyOpts, onLegacyKeyUsed);
         if (!key)
             throw new MissingEncryptionKey();
         if ([null, undefined].includes(encrypted))
@@ -65,7 +81,31 @@ export default class Encrypt {
             }
         }
     }
-    static attemptDecryptionWithLegacyKeys(encrypted, currentOpts, legacyOpts) {
+    /**
+     * Opens `encrypted` as {@link Encrypt.decrypt} does, with `currentOpts` and,
+     * when they do not open it, `legacyOpts`, and encrypts the value again with
+     * `currentOpts`, so that reading it no longer needs the legacy key. Use it
+     * during a key rotation for a value stored outside an `@deco.Encrypted`
+     * column, such as a cookie; `Model.reencryptEncryptedColumns()` does this
+     * for every value of a model's encrypted properties.
+     *
+     * ```ts
+     * const rewritten = Encrypt.reencrypt(
+     *   storedValue,
+     *   { algorithm: 'aes-256-gcm', key: newKey },
+     *   { algorithm: 'aes-256-gcm', key: oldKey }
+     * )
+     * ```
+     *
+     * @throws MissingEncryptionKey
+     * @throws DecryptionError
+     * @throws DecryptionParseError
+     * @throws DecryptionRotationError
+     */
+    static reencrypt(encrypted, currentOpts, legacyOpts) {
+        return this.encrypt(this.decrypt(encrypted, currentOpts, legacyOpts), currentOpts);
+    }
+    static attemptDecryptionWithLegacyKeys(encrypted, currentOpts, legacyOpts, onLegacyKeyUsed) {
         let currentKeyError;
         try {
             return this.decrypt(encrypted, currentOpts);
@@ -75,14 +115,19 @@ export default class Encrypt {
                 throw err;
             currentKeyError = err;
         }
+        let decrypted;
         try {
-            return this.decrypt(encrypted, legacyOpts);
+            decrypted = this.decrypt(encrypted, legacyOpts);
         }
         catch (err) {
             if (!(err instanceof DecryptionError))
                 throw err;
             throw new DecryptionRotationError(currentKeyError, err);
         }
+        // called outside the try above, so an error the callback throws is never
+        // mistaken for the legacy key failing
+        onLegacyKeyUsed?.();
+        return decrypted;
     }
     /**
      * Generates a base64-encoded random key suitable for the given algorithm.
@@ -100,11 +145,26 @@ export default class Encrypt {
      *    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`).
+     *    `@Encrypted` columns, re-encrypt every existing row under the new key
+     *    by calling `reencryptEncryptedColumns()` on each model that has
+     *    encrypted properties (`await User.reencryptEncryptedColumns()`), in
+     *    each environment, from a console or a script rather than a migration.
+     *    Run it only once every server in that environment runs with the new
+     *    `current`: a server still on the old `current` keeps writing old-key
+     *    values that its single pass over the table can miss. Writing old-key
+     *    ciphertext straight into a backing column (`setAttribute`,
+     *    `setAttributes` or `updateAttributes` given the backing column) after
+     *    it has run also puts an old-key value back. For any other value
+     *    encrypted with these keys, {@link Encrypt.reencrypt} rewrites it.
      * 5. Drop `legacy` from config and deploy again.
      *
+     * To see which values still need the old key while `legacy` is
+     * configured, register `dreamApp.on('encryption:legacy-key-used', ...)`,
+     * which fires each time reading an `@Encrypted` property needed `legacy`
+     * to open the value, or pass `onLegacyKeyUsed` to {@link Encrypt.decrypt}
+     * for values you decrypt yourself. A value nobody reads never fires
+     * either, so silence alone does not show that `legacy` is safe to drop.
+     *
      * ## When to rotate
      *
      * - On a scheduled cadence (90–180 days is a reasonable policy default).
@@ -116,8 +176,15 @@ export default class Encrypt {
      * - 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
-     *   `DecryptionRotationError` on any not-yet-rewritten row.
+     *   re-encrypted under the new key. Once `legacy` is dropped, reading the
+     *   `@Encrypted` property of a row that is still under the old key throws
+     *   `DecryptionError`, the same error a tampered or corrupted value
+     *   throws, so the error class alone cannot show that `legacy` was
+     *   dropped too early. `DecryptionRotationError` is thrown only while
+     *   `legacy` is configured and neither key opens the value. Neither class
+     *   extends the other, so code that catches `DecryptionRotationError`
+     *   during a rotation must also catch `DecryptionError` to handle such a
+     *   read once `legacy` is dropped.
      */
     static generateKey(algorithm) {
         switch (algorithm) {

package/dist/cjs/src/errors/DoNotSetEncryptedFieldsDirectly.js

@@ -13,6 +13,10 @@ export default class DoNotSetEncryptedFieldsDirectly extends Error {
 Do not set @Encrypted columns directly. Instead, set their accessors, so that
 those fields can be encrypted by Dream internally.
 
+Writes that bypass setters, such as setAttribute, setAttributes and
+updateAttributes, accept a value for an @Encrypted column only when it is
+ciphertext that decrypts with this app's encryption keys, or null.
+
 Dream class: ${this.dreamClass.sanitizedName}
 Problematic setter: ${this.encryptedColumnName}
 Setter to be used instead: ${this.encryptedProperty}`;

package/dist/cjs/src/errors/associations/UnrecognizedAssociationConditionKeys.js

@@ -0,0 +1,25 @@
+export default class UnrecognizedAssociationConditionKeys extends Error {
+    associationName;
+    unrecognizedKeys;
+    acceptedKeys;
+    methodName;
+    constructor(associationName, unrecognizedKeys, acceptedKeys, methodName) {
+        super();
+        this.associationName = associationName;
+        this.unrecognizedKeys = unrecognizedKeys;
+        this.acceptedKeys = acceptedKeys;
+        this.methodName = methodName;
+    }
+    get message() {
+        const source = this.methodName
+            ? `in the object passed to ${this.methodName}('${this.associationName}')`
+            : `in the condition on the "${this.associationName}" association`;
+        return `
+Unrecognized key${this.unrecognizedKeys.length === 1 ? '' : 's'} ${source}: ${this.unrecognizedKeys.join(', ')}
+Accepted keys: ${this.acceptedKeys.join(', ')}
+
+Where-clauses on an association go under \`and\`, \`andNot\` or \`andAny\`, e.g.:
+  { and: { email: 'how@yadoin' } }
+`;
+    }
+}

package/dist/cjs/src/helpers/Env.js

@@ -34,6 +34,22 @@ export default class Env {
         const parsedVal = parseInt(val, 10);
         return (parsedVal.toString() === val ? parsedVal : undefined);
     }
+    /**
+     * Reads a boolean environment variable. Only the exact string `"1"` is
+     * true. Every other value is false, including `"true"`, `"TRUE"`, `"yes"`
+     * and `""`, and so is an unset variable.
+     *
+     * ```ts
+     * // FEATURE_FLAG=1
+     * AppEnv.boolean('FEATURE_FLAG') // true
+     *
+     * // FEATURE_FLAG=true
+     * AppEnv.boolean('FEATURE_FLAG') // false
+     * ```
+     *
+     * @param env - the name of the environment variable
+     * @returns `true` when the variable is exactly `"1"`, otherwise `false`
+     */
     boolean(env) {
         return this.optional(env) === '1';
     }
@@ -51,9 +67,21 @@ export default class Env {
     unsetInteger(env) {
         delete process.env[env];
     }
+    /**
+     * Sets a boolean environment variable to `"1"`, the only value
+     * {@link Env.boolean} reads as true.
+     *
+     * @param env - the name of the environment variable
+     */
     setBoolean(env) {
         process.env[env] = '1';
     }
+    /**
+     * Deletes a boolean environment variable. {@link Env.boolean} reads an
+     * unset variable as false, since only the exact string `"1"` is true.
+     *
+     * @param env - the name of the environment variable
+     */
     unsetBoolean(env) {
         delete process.env[env];
     }

package/dist/cjs/src/helpers/cli/generateDreamContent.js

@@ -1,5 +1,6 @@
 import pluralize from 'pluralize-esm';
 import serializerGlobalNameFromFullyQualifiedModelName from '../../serializer/helpers/serializerGlobalNameFromFullyQualifiedModelName.js';
+import defaultEncryptedColumnName from '../../encrypt/defaultEncryptedColumnName.js';
 import camelize from '../camelize.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
 import pascalize from '../pascalize.js';
@@ -189,7 +190,7 @@ public ${associationForeignKey}: DreamColumn<${modelClassName}, '${associationNa
     };
 }
 export function createEncryptedAttribute(attributeName, attribute, modelClassName) {
-    const encryptedColumnName = camelize(`encrypted_${attributeName}`);
+    const encryptedColumnName = defaultEncryptedColumnName(attributeName);
     const content = `
 @deco.Encrypted()
 public ${camelize(attributeName)}: DreamColumn<${modelClassName}, '${encryptedColumnName}'>`;

package/dist/cjs/src/helpers/cli/generateFactoryContent.js

@@ -46,7 +46,7 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
         switch (safeAttributeType) {
             case 'belongsto': {
                 // When `Model@alias:belongs_to`, the factory property uses the alias;
-                // otherwise it uses the model's last namespace segment (legacy form).
+                // otherwise it uses the model's last namespace segment.
                 const attributeVariable = aliasName ? camelize(aliasName) : camelize(attributeName.split('/').pop());
                 const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(attributeName);
                 const associationModelName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedAssociatedModelName);

package/dist/cjs/src/helpers/cli/generateMigrationContent.js

@@ -4,6 +4,7 @@ import Query from '../../dream/Query.js';
 import InvalidDecimalFieldPassedToGenerator from '../../errors/InvalidDecimalFieldPassedToGenerator.js';
 import NoColumnsToAlterMigration from '../../errors/NoColumnsToAlterMigration.js';
 import UnparseableMigrationColumn from '../../errors/UnparseableMigrationColumn.js';
+import defaultEncryptedColumnName from '../../encrypt/defaultEncryptedColumnName.js';
 import camelize from '../camelize.js';
 import compact from '../compact.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
@@ -141,7 +142,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
                 columnDefs.push(generateBooleanStr(attributeName, { omitInlineNonNull }));
                 break;
             case 'encrypted':
-                attributeName = `encrypted_${attributeName}`;
+                attributeName = snakeify(defaultEncryptedColumnName(attributeName));
                 columnDefs.push(generateColumnStr(attributeName, 'text', descriptors, {
                     omitInlineNonNull,
                     skipUniqueHeuristic: true,
@@ -183,13 +184,12 @@ export default function generateMigrationContent({ connectionName = 'default', t
     // time rather than generation time. Fail loudly here instead.
     //
     // This guard is scoped to the standalone `g:migration` `-to-`/`-from-` flow
-    // only (`stiChildClassName` is unset there). `g:sti-child` legitimately
-    // calls this function in alter mode with zero `columnsWithTypes` — a
-    // zero-attribute STI child is a documented use case (see `g:sti-child`'s
-    // help example in src/cli/index.ts), and `generateStiMigrationContent`
-    // handles the type-column/check-constraint machinery separately from the
-    // `columnDefs` this check inspects, so an empty `columnDefs` there is
-    // expected, not a sign of a mistyped/unparseable column list.
+    // only (`stiChildClassName` is unset there); STI child migrations skip it.
+    // `g:sti-child` writes no migration for a child declared with no columns
+    // (see `generateDream`), so an STI child migration reaches this point with
+    // an empty `columnDefs` only when none of its declarations produced a
+    // column (e.g. only `has_one`/`has_many` ones), and it then emits the bare
+    // `.alterTable(...).execute()` described above.
     if (altering &&
         columnDefs.length === 0 &&
         table !== MIGRATION_TABLE_NAME_PLACEHOLDER &&
@@ -472,7 +472,7 @@ function generateBelongsToStr(connectionName, associationName, { primaryKeyType,
     const dataType = dbDriverClass.foreignKeyTypeFromPrimaryKey(primaryKeyType);
     const references = lookupReferencesTable(associationName, originalAssociationName);
     // When the user passed `Model@alias:belongs_to`, the column name comes from
-    // the alias; otherwise it's the model's last segment (existing behavior).
+    // the alias; otherwise it's the model's last segment.
     const columnNameSource = aliasName ? snakeify(aliasName) : associationName.split('/').pop();
     return `.addColumn('${associationNameToForeignKey(columnNameSource)}', '${dataType}', col => col.references('${references}.id').onDelete('restrict')${optional ? '' : '.notNull()'})`;
 }

package/dist/cjs/src/helpers/cli/generateSerializerContent.js

@@ -40,6 +40,16 @@ export default function generateSerializerContent({ fullyQualifiedModelName, col
         ? `import { ${uniq(dreamImports).join(', ')} } from '@rvoh/dream'\n`
         : '';
     const additionalImportsStr = uniq(additionalImports).join('');
+    // An STI base renders the `type` discriminator in its summary serializers,
+    // so each default serializer, and each STI child serializer, inherits it.
+    const rendersStiType = stiBaseSerializer &&
+        columnsWithTypes.some(attr => {
+            const [name, type] = attr.split(':');
+            return name === 'type' && !isAssociationType(type);
+        });
+    const stiTypeAttribute = rendersStiType
+        ? `\n    .attribute('type', { openapi: { type: 'string', enum: [(StiChildClass ?? ${modelClassName}).sanitizedName] } })`
+        : '';
     const buildSerializerPair = (variantSuffix) => {
         const summaryName = variantSerializerClassName(localSerializerBase, variantSuffix, 'summary');
         const defaultName = variantSerializerClassName(localSerializerBase, variantSuffix, 'default');
@@ -50,15 +60,17 @@ export default function generateSerializerContent({ fullyQualifiedModelName, col
             ? `${variantSerializerClassName(parentSerializerBase, variantSuffix, 'default')}(${modelClassName}, ${modelSerializerArgs})`
             : `${summaryName}(${stiBaseSerializer ? 'StiChildClass, ' : ''}${modelSerializerArgs})`;
         const summary = `export const ${summaryName} = ${modelSerializerSignature} =>
-  ${summaryExtends}${isSTI ? '' : `\n    .attribute('id')`}`;
+  ${summaryExtends}${isSTI ? '' : `\n    .attribute('id')`}${stiTypeAttribute}`;
         const defaultBody = columnsWithTypes
             .map(attr => {
             const [name, type] = attr.split(':');
             if (name === undefined)
                 return '';
-            if (['belongsto', 'hasone', 'hasmany'].includes(camelize(type)?.toLowerCase()))
+            if (isAssociationType(type))
                 return '';
-            return `\n    ${attribute(modelClassName, name, type, attr, stiBaseSerializer)}`;
+            if (rendersStiType && name === 'type')
+                return '';
+            return `\n    ${attribute(name, type, attr)}`;
         })
             .join('');
         const def = `export const ${defaultName} = ${modelSerializerSignature} =>
@@ -75,16 +87,17 @@ function variantSerializerClassName(serializerBase, variantSuffix, kind) {
         ? `${serializerBase}${variantSuffix}SummarySerializer`
         : `${serializerBase}${variantSuffix}Serializer`;
 }
-function attribute(modelClassName, name, type, attr, stiBaseSerializer) {
-    if (name === 'type' && stiBaseSerializer) {
-        return `.attribute('type', { openapi: { type: 'string', enum: [(StiChildClass ?? ${modelClassName}).sanitizedName] } })`;
-    }
+function isAssociationType(type) {
+    return ['belongsto', 'hasone', 'hasmany'].includes(camelize(type)?.toLowerCase());
+}
+function attribute(name, type, attr) {
     switch (type) {
         case 'json':
         case 'jsonb':
+            return `.attribute('${camelize(name)}', { openapi: { type: 'object', properties: { } } })`;
         case 'json[]':
         case 'jsonb[]':
-            return `.attribute('${camelize(name)}', { openapi: { type: 'object', properties: { } } })`;
+            return `.attribute('${camelize(name)}', { openapi: { type: 'array', items: { type: 'object', properties: { } } } })`;
         default:
             return `.attribute('${camelize(name)}'${attributeOptionsSpecifier(type, attr)})`;
     }

package/dist/cjs/src/serializer/SerializerRenderer.js

@@ -1,3 +1,4 @@
+import Dream from '../Dream.js';
 import RendersManyMustReceiveArray from '../errors/serializers/RendersManyMustReceiveArray.js';
 import compact from '../helpers/compact.js';
 import round from '../helpers/round.js';
@@ -8,7 +9,7 @@ import { DateTime } from '../utils/datetime/DateTime.js';
 import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
 import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
 import inferSerializerFromDreamOrViewModel from './helpers/inferSerializerFromDreamOrViewModel.js';
-import { serializerForAssociatedClass } from './helpers/serializerForAssociatedClass.js';
+import { serializersForAssociatedClass } from './helpers/serializersForAssociatedClass.js';
 export default class SerializerRenderer {
     serializerBuilder;
     passthroughData;
@@ -95,19 +96,16 @@ export default class SerializerRenderer {
                 case 'rendersOne': {
                     const outputAttributeName = this.setCase(attribute.options.as ?? attribute.name);
                     const associatedObject = data[attribute.name];
-                    let serializer = null;
-                    if (associatedObject) {
-                        serializer = serializerForAssociatedObject(associatedObject, attribute.options, renderTimeResolutionContext(attribute.options, 'rendersOne', attribute.name));
-                    }
-                    else if (attribute.options.flatten) {
-                        /**
-                         * Only used when flatten: true, and the associated model is null, in which case,
-                         * we need something to determine the keys that will be flattened into the
-                         * rendering serializer
-                         */
-                        serializer = serializerForAssociatedClass(data, attribute.name, attribute.options);
+                    if (!associatedObject && attribute.options.flatten) {
+                        return {
+                            ...accumulator,
+                            ...this.nullFlattenedAttributes(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), passthroughData),
+                        };
                     }
-                    const serializerBuilder = serializer?.(attribute.options.flatten ? (associatedObject ?? {}) : associatedObject, 
+                    const serializer = associatedObject
+                        ? serializerForAssociatedObject(associatedObject, attribute.options, renderTimeResolutionContext(attribute.options, 'rendersOne', attribute.name))
+                        : null;
+                    const serializerBuilder = serializer?.(associatedObject, 
                     // passthrough data going into the serializer is the argument that gets
                     // used in the custom attribute callback function
                     passthroughData);
@@ -178,6 +176,60 @@ export default class SerializerRenderer {
         }, renderedAttributes);
         return renderedAttributes;
     }
+    /**
+     * The keys a flattened `rendersOne` adds to the parent's payload when its associated object is
+     * null: each key any of `serializers` declares, set to `null`. There are several serializers when
+     * the association is a polymorphic BelongsTo, one for each target class, or when the associated
+     * class is an STI base, one for each child, and their keys are unioned.
+     *
+     * Each serializer is built with `undefined` data to read its declarations, as Psychic's OpenAPI
+     * generation and `preloadFor` build it, and nothing is rendered: no attribute callback runs and
+     * no association of the missing object is read. A flattened `rendersOne` it declares adds its
+     * own serializers' keys the same way. A flattened `customAttribute` adds none, since only its
+     * callback knows its keys.
+     */
+    nullFlattenedAttributes(serializers, passthroughData, serializersBeingFlattened = new Set()) {
+        return serializers.reduce((flattenedKeys, serializer) => {
+            // a serializer reached again, e.g. one that flattens itself directly or through others, or
+            // one that two polymorphic targets or two STI children both flatten, adds no keys the first
+            // walk through it did not
+            if (serializersBeingFlattened.has(serializer))
+                return flattenedKeys;
+            serializersBeingFlattened.add(serializer);
+            const serializerBuilder = serializer(undefined, passthroughData);
+            const dreamClass = serializerBuilder instanceof DreamSerializerBuilder
+                ? serializerBuilder['$typeForOpenapi']
+                : null;
+            return serializerBuilder['attributes'].reduce((keys, attribute) => {
+                const attributeType = attribute.type;
+                switch (attributeType) {
+                    case 'attribute':
+                    case 'delegatedAttribute':
+                    case 'rendersMany':
+                        keys[this.setCase(attribute.options?.as ?? attribute.name)] = null;
+                        return keys;
+                    case 'customAttribute':
+                        if (!attribute.options.flatten)
+                            keys[this.setCase(attribute.name)] = null;
+                        return keys;
+                    case 'rendersOne':
+                        if (!attribute.options.flatten) {
+                            keys[this.setCase(attribute.options.as ?? attribute.name)] = null;
+                            return keys;
+                        }
+                        return {
+                            ...keys,
+                            ...this.nullFlattenedAttributes(serializersForAssociatedClass(dreamClass, attribute.name, attribute.options), passthroughData, serializersBeingFlattened),
+                        };
+                    default: {
+                        // protection so that if a new ValidationType is ever added, this will throw a type error at build time
+                        const _never = attributeType;
+                        throw new Error(`Unhandled serializer attribute type: ${_never}`);
+                    }
+                }
+            }, flattenedKeys);
+        }, {});
+    }
     setCase(attr) {
         switch (this.renderOpts.casing) {
             case 'camel':