@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/database/encryption/documentdb-encryption-service.md

@@ -225,7 +225,84 @@ Database (ENCRYPTED STORAGE) ✅ SECURE
 1. **Consistency**: Same encryption format and Cryptor as Prisma Extension
 2. **Reusability**: Single service used by all DocumentDB repositories
 3. **Schema-Driven**: Uses `encryption-schema-registry.js` (same as Prisma)
-4. **Environment-Aware**: Respects STAGE-based bypass (dev/test/local)
+4. **Fails Closed**: Same rule as the Prisma client; a deployed runtime with no key throws, only local runs skip encryption
+5. **Error-Tolerant**: Graceful handling of decryption failures
+6. **Testable**: Can be unit tested independently of repositories
+
+---
+
+## Technical Specification
+
+### Class Design
+
+```javascript
+/**
+ * Encryption service specifically for DocumentDB repositories
+ * that use $runCommandRaw and bypass Prisma Extensions.
+ *
+ * Provides document-level encryption/decryption,
+ * handling nested fields according to the encryption schema registry.
+ */
+class DocumentDBEncryptionService {
+    constructor()
+    _initializeCryptor()
+    async encryptFields(modelName, document)
+    async decryptFields(modelName, document)
+    async _encryptFieldPath(document, fieldPath, modelName)
+    async _decryptFieldPath(document, fieldPath, modelName)
+    _isEncryptedValue(value)
+}
+```
+
+### Method Specifications
+
+#### `constructor()`
+
+**Purpose**: Initialize the service and configure Cryptor
+
+**Behavior**:
+
+-   Calls `_initializeCryptor()` immediately
+-   Sets up `this.cryptor` and `this.enabled` properties
+
+**No parameters**
+
+---
+
+#### `_initializeCryptor()`
+
+**Purpose**: Initialize Cryptor with environment-based configuration
+
+**Logic**:
+
+```javascript
+1. loadCustomEncryptionSchema()
+2. config = getEncryptionConfig()   // encryption/encryption-config.js, shared with the Prisma client
+   - throws EncryptionConfigurationError in a deployed runtime with no key
+3. If !config.enabled (local dev/test/local stage, local run without keys,
+   or FRIGG_ENCRYPTION_DISABLED=true opt-out):
+   - Set this.cryptor = null
+   - Set this.enabled = false
+   - Return
+4. Create Cryptor({ shouldUseAws: config.method === 'kms' })
+5. Set this.enabled = true
+```
+
+**Environment Variables Used** (see "When Encryption Runs" in README.md):
+
+-   `AWS_LAMBDA_FUNCTION_NAME` / `LAMBDA_TASK_ROOT` / `AWS_EXECUTION_ENV=AWS_Lambda_*`, or a non-`aws` `FRIGG_PROVIDER`, minus `IS_OFFLINE` / `IS_LOCAL` / `NETLIFY_DEV` / `JEST_WORKER_ID`: deployed or local run
+-   `STAGE` or `NODE_ENV`: dev/test/local skip encryption on local runs only
+-   `KMS_KEY_ARN`: AWS KMS key ARN (enables KMS encryption)
+-   `AES_KEY_ID`: AES key identifier (enables AES encryption)
+-   `AES_KEY`: AES encryption key (required with AES_KEY_ID in a deployed runtime)
+-   `FRIGG_ENCRYPTION_DISABLED`: explicit plaintext opt-out for a deployed stage with no key
+
+### Design Principles
+
+1. **Consistency**: Same encryption format and Cryptor as Prisma Extension
+2. **Reusability**: Single service used by all DocumentDB repositories
+3. **Schema-Driven**: Uses `encryption-schema-registry.js` (same as Prisma)
+4. **Fails Closed**: Same rule as the Prisma client; a deployed runtime with no key throws, only local runs skip encryption
 5. **Error-Tolerant**: Graceful handling of decryption failures
 6. **Testable**: Can be unit tested independently of repositories
 

package/database/encryption/encryption-config.js

@@ -0,0 +1,219 @@
+/**
+ * Field-level encryption configuration: decides whether sensitive fields are
+ * encrypted, and with which key, from the process environment.
+ *
+ * The rule fails closed:
+ *
+ * - **Deployed** (running in AWS Lambda, and not under
+ *   serverless-offline, `serverless invoke local` or Jest): the stage name is
+ *   ignored. A configured key (KMS_KEY_ARN, or AES_KEY_ID with AES_KEY) turns
+ *   encryption on. With no key, the configuration is an error and the Prisma
+ *   client refuses to start, unless FRIGG_ENCRYPTION_DISABLED=true opts out
+ *   explicitly.
+ * - **Local** (`frigg start`, tests, scripts on a laptop): the stages dev,
+ *   test and local skip encryption. Any other stage encrypts when a key is
+ *   configured and stays plaintext, with a warning, when none is.
+ *
+ * Every module that encrypts or reports on encryption reads this one rule.
+ */
+
+const { logger } = require('./logger');
+const {
+    isDeployedRuntime: isDeployedProviderRuntime,
+} = require('../../providers/runtime-detection');
+
+const LOCAL_BYPASS_STAGES = ['dev', 'test', 'local'];
+const OPT_OUT_VAR = 'FRIGG_ENCRYPTION_DISABLED';
+
+class EncryptionConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EncryptionConfigurationError';
+    }
+}
+
+function isSet(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+
+function isTrue(value) {
+    if (typeof value !== 'string') return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === 'true' || normalized === '1';
+}
+
+/**
+ * True when the process runs as a deployed function, on AWS Lambda or on the
+ * active provider's platform (provider-netlify: FRIGG_PROVIDER=netlify, set by
+ * its generated entry points), and not under a local emulator or test runner.
+ * One rule for encryption and queue authentication: core/providers/
+ * runtime-detection asks the provider's detect(), and fails closed when a
+ * named non-AWS provider cannot be loaded.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function isDeployedRuntime(env = process.env) {
+    return isDeployedProviderRuntime(env);
+}
+
+function missingKeyMessage(stage) {
+    return (
+        `[Frigg] No field-level encryption key is configured for stage "${stage}". ` +
+        'A deployed Frigg app will not write credentials and other sensitive fields in plaintext. ' +
+        "Fix: set encryption: { fieldLevelEncryptionMethod: 'kms' } in the app definition and redeploy " +
+        '(Frigg creates or discovers a KMS key and sets KMS_KEY_ARN), ' +
+        'or provide AES_KEY_ID and AES_KEY (32 characters) in the Lambda environment. ' +
+        `To run this stage without encryption on purpose, set ${OPT_OUT_VAR}=true ` +
+        "(or encryption: { fieldLevelEncryptionMethod: 'none' } in the app definition)."
+    );
+}
+
+function incompleteAesMessage(stage) {
+    return (
+        `[Frigg] AES_KEY_ID is set but AES_KEY is not (stage "${stage}"). ` +
+        'Provide AES_KEY (32 characters) alongside AES_KEY_ID, ' +
+        "or use KMS with encryption: { fieldLevelEncryptionMethod: 'kms' }."
+    );
+}
+
+/**
+ * Resolves the encryption configuration without side effects.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {{
+ *   enabled: boolean,
+ *   method: 'kms'|'aes'|undefined,
+ *   mode: 'kms'|'aes'|'none',
+ *   runtime: 'deployed'|'local',
+ *   stage: string,
+ *   bypassed: boolean,
+ *   optedOut: boolean,
+ *   optOutIgnored: boolean,
+ *   hasKMS: boolean,
+ *   hasAES: boolean,
+ *   error: string|null,
+ * }} `error` is set when a deployed runtime has no usable key.
+ */
+function resolveEncryptionConfig(env = process.env) {
+    const stage = env.STAGE || env.NODE_ENV || 'development';
+    const runtime = isDeployedRuntime(env) ? 'deployed' : 'local';
+    const hasKMS = isSet(env.KMS_KEY_ARN);
+    const hasAES = isSet(env.AES_KEY_ID);
+    const optOutRequested = isTrue(env[OPT_OUT_VAR]);
+
+    const base = {
+        enabled: false,
+        method: undefined,
+        mode: 'none',
+        runtime,
+        stage,
+        bypassed: false,
+        optedOut: false,
+        optOutIgnored: false,
+        hasKMS,
+        hasAES,
+        error: null,
+    };
+
+    if (runtime === 'local') {
+        if (LOCAL_BYPASS_STAGES.includes(String(stage).toLowerCase())) {
+            return { ...base, bypassed: true };
+        }
+        if (hasKMS || hasAES) {
+            const method = hasKMS ? 'kms' : 'aes';
+            return { ...base, enabled: true, method, mode: method };
+        }
+        return base;
+    }
+
+    const hasCompleteAES = hasAES && isSet(env.AES_KEY);
+    if (hasKMS || hasCompleteAES) {
+        const method = hasKMS ? 'kms' : 'aes';
+        return {
+            ...base,
+            enabled: true,
+            method,
+            mode: method,
+            optOutIgnored: optOutRequested,
+        };
+    }
+
+    if (optOutRequested) {
+        return { ...base, optedOut: true };
+    }
+
+    return {
+        ...base,
+        error: hasAES ? incompleteAesMessage(stage) : missingKeyMessage(stage),
+    };
+}
+
+const warned = new Set();
+
+function warnOnce(key, message) {
+    if (warned.has(key)) return;
+    warned.add(key);
+    logger.warn(message);
+}
+
+/**
+ * Resolves the encryption configuration for use: throws when a deployed
+ * runtime has no usable key, and warns once per process (once per Lambda
+ * cold start) when encryption is explicitly disabled.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {ReturnType<typeof resolveEncryptionConfig>}
+ * @throws {EncryptionConfigurationError}
+ */
+function getEncryptionConfig(env = process.env) {
+    const config = resolveEncryptionConfig(env);
+
+    if (config.error) {
+        throw new EncryptionConfigurationError(config.error);
+    }
+
+    if (config.optedOut) {
+        warnOnce(
+            'opted-out',
+            `[Frigg] ${OPT_OUT_VAR}=true: field-level encryption is OFF for stage "${config.stage}". ` +
+                'Credentials and other sensitive fields are stored in PLAINTEXT. ' +
+                `Remove ${OPT_OUT_VAR} and configure a key (fieldLevelEncryptionMethod: 'kms') to encrypt them.`
+        );
+    }
+
+    if (config.optOutIgnored) {
+        warnOnce(
+            'opt-out-ignored',
+            `[Frigg] ${OPT_OUT_VAR}=true is ignored because an encryption key is configured; ` +
+                `fields are encrypted with ${config.method.toUpperCase()}. ` +
+                'Turning encryption off while a key is present would leave encrypted data unreadable.'
+        );
+    }
+
+    if (config.runtime === 'local' && !config.enabled && !config.bypassed) {
+        warnOnce(
+            'local-no-keys',
+            `No encryption keys configured (KMS_KEY_ARN or AES_KEY_ID) for local stage "${config.stage}". ` +
+                'Field-level encryption disabled for this local run. ' +
+                'A deployed stage without a key refuses to start.'
+        );
+    }
+
+    return config;
+}
+
+/** Test helper: let the once-per-process warnings fire again. */
+function resetEncryptionConfigWarnings() {
+    warned.clear();
+}
+
+module.exports = {
+    EncryptionConfigurationError,
+    LOCAL_BYPASS_STAGES,
+    OPT_OUT_VAR,
+    getEncryptionConfig,
+    isDeployedRuntime,
+    resetEncryptionConfigWarnings,
+    resolveEncryptionConfig,
+};

package/database/encryption/encryption-schema-registry.js

@@ -10,6 +10,11 @@
 
 const { logger } = require('./logger');
 const { registerDeniedKeys } = require('../../logs/denied-keys');
+const {
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+    EntityRegistryError,
+} = require('../../modules/entity-type-registry');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -39,6 +44,12 @@ const CORE_ENCRYPTION_SCHEMA = {
     Token: {
         fields: ['token'],
     },
+
+    // Multi-step authorization (Management API v2): earlier steps can collect
+    // emails, usernames or one-time codes.
+    AuthorizationSession: {
+        fields: ['stepData'],
+    },
 };
 
 let customSchema = {};
@@ -160,8 +171,9 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
  * Each module can declare credentialFields to encrypt in its encryption config.
  *
  * @param {Array} integrations - Array of integration classes with modules
+ * @param {object} [entities] - `appDefinition.entities` (ADR-059 registry)
  */
-function loadModuleEncryptionSchemas(integrations) {
+function loadModuleEncryptionSchemas(integrations, entities) {
     if (!integrations) {
         throw new Error('integrations parameter is required');
     }
@@ -170,27 +182,39 @@ function loadModuleEncryptionSchemas(integrations) {
         throw new Error('integrations must be an array');
     }
 
-    if (integrations.length === 0) {
+    // `entities` is the app definition's registry (ADR-059): a module an app
+    // registers without any integration still carries credentials to encrypt.
+    if (integrations.length === 0 && !entities) {
         return;
     }
 
-    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
-
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
+    const moduleDefinitions = getEntityTypeDefinitions(
+        getEntityTypeRegistry({ integrations, entities })
+    );
     const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
 
-    if (credentialFields.length === 0) {
+    // Core fields are encrypted already and a custom schema may not repeat
+    // them. Everything the app registered itself stays: module fields are added
+    // to the custom schema, never substituted for it (other models included).
+    const coreFields = new Set(CORE_ENCRYPTION_SCHEMA.Credential?.fields || []);
+    const fields = [
+        ...new Set([
+            ...(customSchema.Credential?.fields || []),
+            ...credentialFields.filter((field) => !coreFields.has(field)),
+        ]),
+    ];
+
+    if (fields.length === 0) {
         return;
     }
 
     const moduleSchema = {
-        Credential: {
-            fields: credentialFields
-        }
+        ...customSchema,
+        Credential: { ...customSchema.Credential, fields },
     };
 
     logger.info(
-        `Registering module-level encryption for ${credentialFields.length} credential fields`
+        `Registering module-level encryption for ${fields.length} credential fields`
     );
 
     registerCustomSchema(moduleSchema);
@@ -205,22 +229,80 @@ function loadModuleEncryptionSchemas(integrations) {
  *
  * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
  */
-function loadCustomEncryptionSchema() {
-    try {
-        // Lazy require to avoid circular dependency issues
-        const path = require('node:path');
-        const { findNearestBackendPackageJson } = require('../../utils');
+/**
+ * Registers encryption schemas declared by app-level extensions
+ * (`appDefinition.coreExtensions[].encryption`), e.g. the db-credentials
+ * extension's `OAuthAppCredential.clientSecret`.
+ *
+ * @param {Array<Object>} extensions - Normalized extensions (extension-loader)
+ */
+function loadExtensionEncryptionSchemas(extensions) {
+    if (!extensions || !Array.isArray(extensions) || extensions.length === 0) {
+        return;
+    }
+
+    for (const ext of extensions) {
+        if (!ext.encryption || typeof ext.encryption !== 'object') {
+            continue;
+        }
+
+        const schema = {};
+        for (const [modelName, config] of Object.entries(ext.encryption)) {
+            if (config && Array.isArray(config.fields) && config.fields.length > 0) {
+                schema[modelName] = { fields: config.fields };
+            }
+        }
 
-        const backendPackagePath = findNearestBackendPackageJson();
-        if (!backendPackagePath) {
-            return; // No backend found, skip custom schema
+        if (Object.keys(schema).length > 0) {
+            logger.info(
+                `Registering encryption schema from extension "${ext.name}" for models: ${Object.keys(schema).join(', ')}`
+            );
+            // registerCustomSchema replaces the registered schema, so merge:
+            // an extension adds its models to the app's encryption.schema
+            // rather than dropping it.
+            const merged = { ...customSchema };
+            for (const [modelName, config] of Object.entries(schema)) {
+                const existing = merged[modelName]?.fields || [];
+                merged[modelName] = {
+                    ...merged[modelName],
+                    fields: [...new Set([...existing, ...config.fields])],
+                };
+            }
+            registerCustomSchema(merged);
         }
+    }
+}
 
-        const backendDir = path.dirname(backendPackagePath);
-        const backendIndexPath = path.join(backendDir, 'index.js');
+function readAppDefinitionForEncryption() {
+    // Lazy require to avoid circular dependency issues
+    const {
+        getPresetAppDefinition,
+    } = require('../../handlers/app-definition-loader');
+    // A definition preset with setAppDefinition() (provider-netlify's
+    // preamble) wins: on Netlify process.cwd() cannot find the backend.
+    const preset = getPresetAppDefinition();
+    if (preset) {
+        return preset;
+    }
+
+    const path = require('node:path');
+    const { findNearestBackendPackageJson } = require('../../utils');
+
+    const backendPackagePath = findNearestBackendPackageJson();
+    if (!backendPackagePath) {
+        return null; // No backend found, skip custom schema
+    }
 
-        const backendModule = require(backendIndexPath);
-        const appDefinition = backendModule?.Definition;
+    const backendDir = path.dirname(backendPackagePath);
+    const backendIndexPath = path.join(backendDir, 'index.js');
+
+    const backendModule = require(backendIndexPath);
+    return backendModule?.Definition || null;
+}
+
+function loadCustomEncryptionSchema() {
+    try {
+        const appDefinition = readAppDefinitionForEncryption();
 
         if (!appDefinition) {
             return; // No app definition found
@@ -240,12 +322,26 @@ function loadCustomEncryptionSchema() {
             registerEncryptionOptOut(disable);
         }
 
+        // Load app-level extension encryption schemas. Before the module
+        // schemas: loadModuleEncryptionSchemas currently throws (see the
+        // NOTE inside it) and the throw would skip anything after it.
+        const { loadExtensions } = require('../../extensions/extension-loader');
+        const extensions = loadExtensions(appDefinition);
+        if (extensions.length > 0) {
+            loadExtensionEncryptionSchemas(extensions);
+        }
+
         // Load module-level encryption schemas from integrations
         const integrations = appDefinition.integrations;
-        if (integrations && Array.isArray(integrations)) {
-            loadModuleEncryptionSchemas(integrations);
+        if (Array.isArray(integrations) || appDefinition.entities) {
+            loadModuleEncryptionSchemas(
+                Array.isArray(integrations) ? integrations : [],
+                appDefinition.entities
+            );
         }
     } catch (error) {
+        // A bad entity registry is a configuration error, not "no custom schema".
+        if (error instanceof EntityRegistryError) throw error;
         // Silently ignore errors - custom schema is optional
         // This handles cases like:
         // - Backend package.json not found (tests, standalone usage)
@@ -396,6 +492,7 @@ module.exports = {
     registerEncryptionOptOut,
     loadCustomEncryptionSchema,
     loadModuleEncryptionSchemas,
+    loadExtensionEncryptionSchemas,
     extractCredentialFieldsFromModules,
     validateCustomSchema,
     validateOptOut,

package/database/encryption/field-encryption-service.js

@@ -4,8 +4,41 @@
  * Infrastructure layer service that orchestrates field-level encryption/decryption.
  * Handles nested JSON paths (e.g., 'data.access_token') and bulk operations.
  */
+const { logger } = require('./logger');
+const { isDeployedRuntime } = require('./encryption-config');
+
+/**
+ * Thrown when a value that looks like ciphertext cannot be decrypted in a
+ * deployed runtime (a wrong, rotated or missing key). Returning the stored
+ * ciphertext would hand it to API modules as if it were a token.
+ */
+class FieldDecryptionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FieldDecryptionError';
+    }
+}
+
+// Cryptor.encrypt() returns `${keyId}:${iv}:${ciphertext}:${encryptedKey}`:
+// keyId and encryptedKey are base64, iv is 16 bytes of hex, ciphertext is hex.
+// Plaintext with three colons (`https://user:pw@host:443`, `a:b:c:d`) must not
+// be mistaken for it.
+const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/;
+const IV_PART = /^[0-9a-f]{32}$/i;
+const CIPHERTEXT_PART = /^(?:[0-9a-f]{2})+$/i;
+
 class FieldEncryptionService {
-    constructor({ cryptor, schema }) {
+    /**
+     * @param {Object} params
+     * @param {Object} params.cryptor
+     * @param {Object} params.schema
+     * @param {() => boolean} [params.failClosedOnDecryptError] - whether a
+     *   ciphertext-shaped value that fails to decrypt throws. Defaults to
+     *   "running deployed" (encryption-config's isDeployedRuntime), read on
+     *   each failure. Locally such a value is returned as stored, with a
+     *   warning.
+     */
+    constructor({ cryptor, schema, failClosedOnDecryptError }) {
         if (!cryptor) {
             throw new Error('Cryptor instance required');
         }
@@ -15,6 +48,10 @@ class FieldEncryptionService {
 
         this.cryptor = cryptor;
         this.schema = schema;
+        this.failClosedOnDecryptError =
+            typeof failClosedOnDecryptError === 'function'
+                ? failClosedOnDecryptError
+                : () => isDeployedRuntime();
     }
 
     /**
@@ -97,12 +134,33 @@ class FieldEncryptionService {
         const decryptionPromises = fields.map(async (fieldPath) => {
             const value = this._getNestedValue(decrypted, fieldPath);
 
-            if (this._isEncrypted(value)) {
+            if (!this._isEncrypted(value)) {
+                return null;
+            }
+            try {
                 const decryptedValue = await this.cryptor.decrypt(value);
                 const deserializedValue = this._deserializeAfterDecryption(decryptedValue);
                 return { fieldPath, decryptedValue: deserializedValue };
+            } catch (error) {
+                // Deployed: a ciphertext-shaped value under a wrong, rotated or
+                // missing key fails the read rather than reaching an API
+                // module as a token. Legacy plaintext never gets here: it does
+                // not look like ciphertext (_isEncrypted).
+                if (this.failClosedOnDecryptError()) {
+                    throw new FieldDecryptionError(
+                        `Could not decrypt ${modelName}.${fieldPath}`,
+                        { cause: error }
+                    );
+                }
+                // Local: a value that looks like ciphertext but is not is read
+                // as it is stored. One such field must not fail the whole
+                // read, findMany included.
+                logger.warn(
+                    `Could not decrypt ${modelName}.${fieldPath}; returning the stored value`,
+                    { errorName: error?.name }
+                );
+                return null;
             }
-            return null;
         });
 
         const results = await Promise.all(decryptionPromises);
@@ -152,7 +210,13 @@ class FieldEncryptionService {
         }
 
         const parts = value.split(':');
-        return parts.length >= 4;
+        return (
+            parts.length === 4 &&
+            BASE64_PART.test(parts[0]) &&
+            IV_PART.test(parts[1]) &&
+            CIPHERTEXT_PART.test(parts[2]) &&
+            BASE64_PART.test(parts[3])
+        );
     }
 
     _getNestedValue(obj, path) {
@@ -251,4 +315,4 @@ class FieldEncryptionService {
     }
 }
 
-module.exports = { FieldEncryptionService };
+module.exports = { FieldEncryptionService, FieldDecryptionError };

package/database/encryption/integration-mapping-encryption.js

@@ -1,4 +1,4 @@
-const { getEncryptionConfig } = require('../prisma');
+const { getEncryptionConfig } = require('./encryption-config');
 const { Cryptor } = require('../../encrypt/Cryptor');
 const {
     getFieldsToDecryptOnRead,

package/database/encryption/test-support/fake-ciphertext.js

@@ -0,0 +1,15 @@
+/**
+ * Test double for Cryptor output. Same shape as the real thing
+ * (`keyId:iv:ciphertext:encryptedKey`: base64, 16-byte hex, hex, base64) so
+ * FieldEncryptionService._isEncrypted accepts it, with the plaintext
+ * recoverable for the fake decrypt.
+ */
+const fakeCiphertext = (plain) =>
+    `a2V5SWQ=:${'0'.repeat(32)}:${Buffer.from(String(plain)).toString(
+        'hex'
+    )}:ZW5jS2V5`;
+
+const fakePlaintext = (ciphertext) =>
+    Buffer.from(String(ciphertext).split(':')[2], 'hex').toString();
+
+module.exports = { fakeCiphertext, fakePlaintext };

package/database/organization-where.js

@@ -0,0 +1,18 @@
+/**
+ * The Prisma `where` fragment for an `organizationId` on MongoDB (ADR-056
+ * §3.6), shared by the entity and integration adapters.
+ *
+ * Prisma on MongoDB: `null` matches only an explicit null and `isSet: false`
+ * only a missing field. A row written before the column existed is the common
+ * "no organization" case, so `null` here means both.
+ */
+function organizationWhere(organizationId) {
+    if (organizationId === null) {
+        return {
+            OR: [{ organizationId: null }, { organizationId: { isSet: false } }],
+        };
+    }
+    return { organizationId };
+}
+
+module.exports = { organizationWhere };