@friggframework/core 2.0.0--canary.702.d5e6de1.0 → 2.0.0--canary.666.89f6545.0

package/CLAUDE.md

@@ -206,11 +206,51 @@ packages/core/
 - `delete-integration-for-user.js` - Remove integration
 - `get-integration-instance.js` - Load integration with modules
 - `load-integration-context.js` - Full integration context loading
+- `add-entities-to-integration.js` / `remove-entities-from-integration.js` - Attach or detach entities on an existing integration
 
 **Repositories**:
 - `integration-repository-factory.js` - Creates database-specific repositories
 - `integration-repository-mongo.js` - MongoDB implementation
 - `integration-repository-postgres.js` - PostgreSQL implementation
+- `addEntitiesToIntegration(integrationId, entityIds)` /
+  `removeEntitiesFromIntegration(integrationId, entityIds)` change the entity
+  set of an existing integration (all three adapters; `null` for an unknown
+  integration). Reach them through the `addEntitiesToIntegration` /
+  `removeEntitiesFromIntegration` commands. The add use case
+  (`add-entities-to-integration.js`) rejects unknown entities
+  (`ENTITIES_NOT_FOUND`, 404), entities of another user
+  (`ENTITY_USER_MISMATCH`, 403) and entities of a module the integration does
+  not already hold (`ENTITY_MODULE_MISMATCH`, 400). The remove use case
+  (`remove-entities-from-integration.js`) refuses to leave a module with no
+  entity (`LAST_ENTITY_OF_MODULE`, 409). Re-adding an attached entity or
+  removing a detached one changes nothing; a detached entity is not deleted.
+  `integration-repository-entities-parity.db.test.js` runs every adapter against
+  real databases when `INTEGRATION_ENTITIES_PARITY_MONGO_URL` /
+  `INTEGRATION_ENTITIES_PARITY_POSTGRES_URL` are set. The DocumentDB adapter
+  writes only `Integration.entityIds` (as its `createIntegration` does), not
+  `Entity.integrationIds`.
+  **One credential, many accounts**: when one credential covers several
+  provider accounts, give each account its own entity (externalId = account
+  id) and attach them all to one integration; webhooks then route with
+  `findIntegrationByEntityExternalId`. Traps:
+  (1) `IntegrationBase` keys modules by module name, so `this.<moduleKey>`
+  holds only one entity's module, and on the queue/webhook path
+  (`get-integration-instance.js`) `this.entities` holds entity **ids**, not
+  records. For per-account work (a webhook for one account, teardown of every
+  account in `onDelete`), load
+  `this.commands.loadIntegrationContextById(this.id)` and use
+  `context.modules`: one module per entity, each with its record on
+  `module.entity` (pick by `module.entity.externalId`).
+  (2) `findIntegrationByEntityExternalId` counts every entity with that
+  externalId, attached or not, across users: reuse an existing entity
+  (`findEntity`) when an account comes back, or delete it when it is revoked,
+  never create a second one.
+  (3) `createIntegration` reuses an existing integration of the same user
+  and type whose entities include all requested ones (an exact match wins),
+  so a reconnect that sends the original entities finds the integration that
+  now holds more.
+  (4) Every module's delegate is the integration: an auth failure on any
+  account marks the shared credential invalid and the integration ERROR.
 - `integration-mapping-repository-*.js` - Mapping data persistence.
   `queryMappings(integrationId, { where, orderBy, skip, take, omit })`
   returns `{ mappings, total }`: one filtered, ordered page of an
@@ -226,7 +266,7 @@ packages/core/
   mapping keys to leave out of the rows; never write such rows back. Path
   segments must match `^[A-Za-z_][A-Za-z0-9_]*$`. The PostgreSQL, MongoDB and
   DocumentDB adapters give the same pages and totals;
-  `integration-mapping-repository-query-parity.test.js` checks that against
+  `integration-mapping-repository-query-parity.db.test.js` checks that against
   real databases when `QUERY_MAPPINGS_PARITY_MONGO_URL` /
   `QUERY_MAPPINGS_PARITY_POSTGRES_URL` are set. Two orderings still differ:
   strings compare by the database collation on PostgreSQL and by code point

package/application/commands/README.md

@@ -67,9 +67,10 @@ class MyIntegration extends IntegrationBase {
     async hydrateFromExternalUser(externalUserId) {
         // Find integration context by external entity ID
         const result =
-            await this.commands.findIntegrationContextByExternalEntityId(
-                externalUserId
-            );
+            await this.commands.findIntegrationContextByExternalEntityId({
+                externalId: externalUserId,
+                type: 'my-integration', // integration config.type to match
+            });
 
         if (result.error) {
             return { error: result.error };
@@ -231,9 +232,10 @@ Manage integration records and load full integration contexts.
 ```javascript
 // Find integration context by external entity ID
 // Returns { context, error } where context includes record + hydrated modules
-const result = await commands.findIntegrationContextByExternalEntityId(
-    'external-user-or-workspace-id'
-);
+const result = await commands.findIntegrationContextByExternalEntityId({
+    externalId: 'external-user-or-workspace-id',
+    type: 'my-integration', // integration config.type to match
+});
 
 if (!result.error) {
     integration.setIntegrationRecord(result.context);
@@ -299,7 +301,10 @@ try {
 For integration context operations, errors are returned in the result:
 
 ```javascript
-const result = await commands.findIntegrationContextByExternalEntityId(userId);
+const result = await commands.findIntegrationContextByExternalEntityId({
+    externalId: userId,
+    type: 'my-integration',
+});
 
 if (result.error) {
     return { error: result.error };
@@ -349,9 +354,10 @@ const result =
 const { createFriggCommands } = require('@friggframework/core');
 
 this.commands = createFriggCommands({ integrationClass: MyIntegration });
-const result = await this.commands.findIntegrationContextByExternalEntityId(
-    userId
-);
+const result = await this.commands.findIntegrationContextByExternalEntityId({
+    externalId: userId,
+    type: 'my-integration',
+});
 ```
 
 ## Best Practices
@@ -433,7 +439,7 @@ if (!user) {
 |                 | `findEntitiesByIds(ids)`                                | Find multiple by IDs                      |
 |                 | `updateEntity(id, updates)`                             | Update entity properties                  |
 |                 | `deleteEntity(id)`                                      | Delete entity                             |
-| **Integration** | `findIntegrationContextByExternalEntityId(externalId)`  | Load integration + modules by external ID |
+| **Integration** | `findIntegrationContextByExternalEntityId({ externalId, type })` | Load integration + modules by external ID |
 |                 | `loadIntegrationContextById(integrationId)`             | Load integration + modules by ID          |
 
 ## Support

package/application/commands/entity-commands.js

@@ -1,12 +1,24 @@
 const {
     createModuleRepository,
 } = require('../../modules/repositories/module-repository-factory');
+const { toCredentialId } = require('../../modules/utils/to-credential-id');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 404,
     INVALID_ENTITY_DATA: 400,
 };
 
+function toEntityDto(entity) {
+    return {
+        id: entity.id,
+        userId: entity.userId,
+        externalId: entity.externalId,
+        name: entity.name,
+        moduleName: entity.moduleName,
+        credentialId: toCredentialId(entity.credential),
+    };
+}
+
 function mapErrorToResponse(error) {
     const status = ERROR_CODE_MAP[error?.code] || 500;
     return {
@@ -66,16 +78,7 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.createEntity(entityData);
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -109,16 +112,7 @@ function createEntityCommands() {
                     return null;
                 }
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -139,16 +133,7 @@ function createEntityCommands() {
 
                 const entities = await moduleRepo.findEntitiesByUserId(userId);
 
-                return entities.map((entity) => ({
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                }));
+                return entities.map((entity) => toEntityDto(entity));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -180,16 +165,7 @@ function createEntityCommands() {
                         moduleName
                     );
 
-                return entities.map((entity) => ({
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                }));
+                return entities.map((entity) => toEntityDto(entity));
             } catch (error) {
                 if (error.code) {
                     return mapErrorToResponse(error);
@@ -213,16 +189,7 @@ function createEntityCommands() {
 
                 const entity = await moduleRepo.findEntityById(entityId);
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }
@@ -250,16 +217,7 @@ function createEntityCommands() {
                     throw error;
                 }
 
-                return {
-                    id: entity.id,
-                    userId: entity.userId,
-                    externalId: entity.externalId,
-                    name: entity.name,
-                    moduleName: entity.moduleName,
-                    credentialId: entity.credential?._id
-                        ? entity.credential._id.toString()
-                        : entity.credential,
-                };
+                return toEntityDto(entity);
             } catch (error) {
                 return mapErrorToResponse(error);
             }

package/application/commands/integration-commands.js

@@ -29,6 +29,12 @@ const {
 const {
     PatchIntegrationConfig,
 } = require('../../integrations/use-cases/patch-integration-config');
+const {
+    AddEntitiesToIntegration,
+} = require('../../integrations/use-cases/add-entities-to-integration');
+const {
+    RemoveEntitiesFromIntegration,
+} = require('../../integrations/use-cases/remove-entities-from-integration');
 const {
     getModulesDefinitionFromIntegrationClasses,
 } = require('../../integrations/utils/map-integration-dto');
@@ -40,6 +46,11 @@ const ERROR_CODE_MAP = {
     EXTERNAL_ID_REQUIRED: 400,
     TYPE_REQUIRED: 400,
     INTEGRATION_RECORD_NOT_FOUND: 404,
+    INVALID_INTEGRATION_DATA: 400,
+    ENTITIES_NOT_FOUND: 404,
+    ENTITY_USER_MISMATCH: 403,
+    ENTITY_MODULE_MISMATCH: 400,
+    LAST_ENTITY_OF_MODULE: 409,
 };
 
 function mapErrorToResponse(error) {
@@ -163,6 +174,17 @@ function createIntegrationCommands({ integrationClass } = {}) {
         integrationRepository,
     });
 
+    const addEntitiesToIntegrationUseCase = new AddEntitiesToIntegration({
+        integrationRepository,
+        moduleRepository,
+    });
+
+    const removeEntitiesFromIntegrationUseCase =
+        new RemoveEntitiesFromIntegration({
+            integrationRepository,
+            moduleRepository,
+        });
+
     return {
         findIntegrationById,
         listIntegrations,
@@ -307,6 +329,47 @@ function createIntegrationCommands({ integrationClass } = {}) {
             }
         },
 
+        /**
+         * Attach entities to an existing integration. Every entity must
+         * exist, belong to the integration's user, and be of a module the
+         * integration already holds; entities that are already attached are
+         * left as they are.
+         * @param {Object} params
+         * @param {string} params.integrationId - Integration ID
+         * @param {Array<string>} params.entityIds - Entity IDs to attach
+         * @returns {Promise<Object>} Updated integration
+         */
+        async addEntitiesToIntegration({ integrationId, entityIds }) {
+            try {
+                return await addEntitiesToIntegrationUseCase.execute(
+                    integrationId,
+                    entityIds
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Detach entities from an integration. Entities that are not
+         * attached are ignored; detached entities are not deleted. Each
+         * module must keep at least one entity.
+         * @param {Object} params
+         * @param {string} params.integrationId - Integration ID
+         * @param {Array<string>} params.entityIds - Entity IDs to detach
+         * @returns {Promise<Object>} Updated integration
+         */
+        async removeEntitiesFromIntegration({ integrationId, entityIds }) {
+            try {
+                return await removeEntitiesFromIntegrationUseCase.execute(
+                    integrationId,
+                    entityIds
+                );
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
         /**
          * Delete an integration by ID
          * @param {string} integrationId - Integration ID to delete

package/database/documentdb-encryption-service.js

@@ -1,4 +1,5 @@
 const { Cryptor } = require('../encrypt/Cryptor');
+const { isEncryptedEnvelope } = require('./encryption/ciphertext-format');
 const {
     getEncryptedFields,
     getFieldsToEncryptOnWrite,
@@ -295,39 +296,7 @@ class DocumentDBEncryptionService {
      * _isEncryptedValue({})  // false
      */
     _isEncryptedValue(value) {
-        // Must be string
-        if (typeof value !== 'string') {
-            return false;
-        }
-
-        // Must have exactly 4 colon-separated parts
-        const parts = value.split(':');
-        if (parts.length !== 4) {
-            return false;
-        }
-
-        // Enhanced validation: check for base64 pattern
-        // This prevents false positives on URLs, connection strings, etc.
-        const base64Pattern = /^[A-Za-z0-9+/=]+$/;
-
-        // All parts should be base64-encoded
-        if (!parts.every(part => base64Pattern.test(part))) {
-            return false;
-        }
-
-        // Encrypted values should be sufficiently long to be valid
-        // Real encrypted values from Cryptor are always >50 chars due to envelope encryption format:
-        // - keyId (base64): ~12 chars minimum
-        // - iv (base64): ~24 chars for 16-byte IV
-        // - ciphertext (base64): varies, minimum ~16 chars for small values
-        // - encryptedKey (base64): ~44 chars for 32-byte data key
-        // Total minimum: ~96 chars, so 50 is a safe lower bound
-        // This prevents false positives on non-encrypted strings that happen to have 4 colons
-        if (value.length < 50) {
-            return false;
-        }
-
-        return true;
+        return isEncryptedEnvelope(value);
     }
 }
 

package/database/encryption/README.md

@@ -508,9 +508,9 @@ return entities.map((e) => ({
 
 **Verified:**
 
--   ✅ `postgres-relation-decryption.test.js` - Proves the bug exists
--   ✅ `postgres-decryption-fix-verification.test.js` - Verifies separate queries work
--   ✅ `mongo-decryption-fix-verification.test.js` - Verifies fix for MongoDB
+-   ✅ `postgres-relation-decryption.db.test.js` - Proves the bug exists
+-   ✅ `postgres-decryption-fix-verification.db.test.js` - Verifies separate queries work
+-   ✅ `mongo-decryption-fix-verification.db.test.js` - Verifies fix for MongoDB
 
 **Implementation Examples:**
 

package/database/encryption/ciphertext-format.js

@@ -0,0 +1,24 @@
+/**
+ * Recognises values produced by Cryptor.encrypt():
+ *   keyId:iv:ciphertext:encryptedKey
+ * keyId and encryptedKey are base64, iv and ciphertext are hex, so all four
+ * parts match the base64 alphabet. Real envelopes are well over 50
+ * characters (the encrypted data key alone is longer).
+ *
+ * Shared by the Prisma (FieldEncryptionService) and DocumentDB paths so a
+ * plaintext value that happens to contain colons (`a:b:c:d`, a URL with
+ * userinfo and a port) is never mistaken for ciphertext: on write it gets
+ * encrypted, on read it is returned as plaintext.
+ */
+const BASE64_PART = /^[A-Za-z0-9+/=]+$/;
+const MIN_ENVELOPE_LENGTH = 50;
+
+function isEncryptedEnvelope(value) {
+    if (typeof value !== 'string' || value.length < MIN_ENVELOPE_LENGTH) {
+        return false;
+    }
+    const parts = value.split(':');
+    return parts.length === 4 && parts.every((part) => BASE64_PART.test(part));
+}
+
+module.exports = { isEncryptedEnvelope };

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

@@ -146,6 +146,16 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
         }
 
         for (const field of credentialFields) {
+            // Validate entry by entry: one bad entry must not drop the
+            // module's (or any other module's) valid fields.
+            if (typeof field !== 'string' || field.trim() === '') {
+                logger.warn(
+                    `Ignoring invalid encryption.credentialFields entry ${JSON.stringify(field)} ` +
+                        `in module "${moduleDef.moduleName || moduleDef.name || 'unknown'}" ` +
+                        '(expected a non-empty string)'
+                );
+                continue;
+            }
             const prefixedField = field.startsWith('data.') ? field : `data.${field}`;
             fields.push(prefixedField);
         }
@@ -174,26 +184,46 @@ function loadModuleEncryptionSchemas(integrations) {
         return;
     }
 
-    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
+    const { getModulesDefinitionFromIntegrationClasses } = require('../../integrations/utils/map-integration-dto');
+
+    // Integrations without modules contribute no credential fields.
+    const integrationsWithModules = integrations.filter(
+        (integration) => integration?.Definition?.modules
+    );
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(
+        integrationsWithModules
+    );
 
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
-    const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
+    // Fields the core schema already encrypts (e.g. data.api_key) are
+    // covered; registering them again would fail validation and drop every
+    // other module field with them.
+    const coreCredentialFields = CORE_ENCRYPTION_SCHEMA.Credential.fields;
+    const credentialFields = extractCredentialFieldsFromModules(
+        moduleDefinitions
+    ).filter((field) => !coreCredentialFields.includes(field));
 
     if (credentialFields.length === 0) {
         return;
     }
 
-    const moduleSchema = {
+    // Merge with whatever custom schema the app already registered rather
+    // than replacing it (registerCustomSchema overwrites).
+    const existingCredentialFields = customSchema.Credential?.fields || [];
+    const mergedSchema = {
+        ...customSchema,
         Credential: {
-            fields: credentialFields
-        }
+            ...customSchema.Credential,
+            fields: [
+                ...new Set([...existingCredentialFields, ...credentialFields]),
+            ],
+        },
     };
 
     logger.info(
         `Registering module-level encryption for ${credentialFields.length} credential fields`
     );
 
-    registerCustomSchema(moduleSchema);
+    registerCustomSchema(mergedSchema);
 }
 
 /**
@@ -205,7 +235,40 @@ function loadModuleEncryptionSchemas(integrations) {
  *
  * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
  */
+/**
+ * Raised when an app's encryption configuration is invalid. In deployed
+ * stages this fails startup instead of silently writing plaintext.
+ */
+class EncryptionSchemaError extends Error {
+    constructor(message, { cause } = {}) {
+        super(message, { cause });
+        this.name = 'EncryptionSchemaError';
+    }
+}
+
+/** Stages where field-level encryption is bypassed (see prisma.js). */
+function isLocalStage() {
+    const stage = process.env.STAGE || process.env.NODE_ENV || 'development';
+    return ['dev', 'test', 'local'].includes(stage.toLowerCase());
+}
+
+/**
+ * An app definition was found but part of its encryption configuration
+ * could not be applied. Deployed stages fail closed; local stages warn and
+ * carry on so development isn't blocked.
+ */
+function reportInvalidEncryptionConfig(what, error) {
+    const message = `Invalid ${what}: ${error.message}`;
+    if (isLocalStage()) {
+        logger.warn(`${message} (ignored in local stage)`);
+        return;
+    }
+    logger.error(message);
+    throw new EncryptionSchemaError(message, { cause: error });
+}
+
 function loadCustomEncryptionSchema() {
+    let appDefinition;
     try {
         // Lazy require to avoid circular dependency issues
         const path = require('node:path');
@@ -220,38 +283,54 @@ function loadCustomEncryptionSchema() {
         const backendIndexPath = path.join(backendDir, 'index.js');
 
         const backendModule = require(backendIndexPath);
-        const appDefinition = backendModule?.Definition;
+        appDefinition = backendModule?.Definition;
+    } catch (error) {
+        // No loadable backend (tests, standalone usage): custom schema is
+        // optional, so this stays at debug level.
+        logger.debug('Could not load custom encryption schema:', error.message);
+        return;
+    }
 
-        if (!appDefinition) {
-            return; // No app definition found
-        }
+    if (!appDefinition) {
+        return; // No app definition found
+    }
+
+    // From here an app definition exists, so failures are configuration
+    // errors and must be visible.
 
-        // Load app-level custom schema
-        const customSchema = appDefinition.encryption?.schema;
-        if (customSchema && Object.keys(customSchema).length > 0) {
+    // Load app-level custom schema
+    const customSchema = appDefinition.encryption?.schema;
+    if (customSchema && Object.keys(customSchema).length > 0) {
+        try {
             registerCustomSchema(customSchema);
+        } catch (error) {
+            reportInvalidEncryptionConfig('app encryption.schema', error);
         }
+    }
 
-        // Load app-level encryption opt-out — apps can declare fields they
-        // don't want encrypted on write (decryption on read still works,
-        // so legacy data remains readable).
-        const disable = appDefinition.encryption?.disable;
-        if (disable && Object.keys(disable).length > 0) {
+    // Load app-level encryption opt-out — apps can declare fields they
+    // don't want encrypted on write (decryption on read still works,
+    // so legacy data remains readable).
+    const disable = appDefinition.encryption?.disable;
+    if (disable && Object.keys(disable).length > 0) {
+        try {
             registerEncryptionOptOut(disable);
+        } catch (error) {
+            reportInvalidEncryptionConfig('app encryption.disable', error);
         }
+    }
 
-        // Load module-level encryption schemas from integrations
-        const integrations = appDefinition.integrations;
-        if (integrations && Array.isArray(integrations)) {
+    // Load module-level encryption schemas from integrations
+    const integrations = appDefinition.integrations;
+    if (integrations && Array.isArray(integrations)) {
+        try {
             loadModuleEncryptionSchemas(integrations);
+        } catch (error) {
+            reportInvalidEncryptionConfig(
+                'module encryption.credentialFields',
+                error
+            );
         }
-    } catch (error) {
-        // Silently ignore errors - custom schema is optional
-        // This handles cases like:
-        // - Backend package.json not found (tests, standalone usage)
-        // - No appDefinition defined
-        // - No custom encryption schema specified
-        logger.debug('Could not load custom encryption schema:', error.message);
     }
 }
 
@@ -386,6 +465,7 @@ function resetCustomSchema() {
 }
 
 module.exports = {
+    EncryptionSchemaError,
     CORE_ENCRYPTION_SCHEMA,
     getEncryptedFields,
     getFieldsToEncryptOnWrite,

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

@@ -1,3 +1,5 @@
+const { isEncryptedEnvelope } = require('./ciphertext-format');
+
 /**
  * Field Encryption Service
  *
@@ -147,12 +149,7 @@ class FieldEncryptionService {
     }
 
     _isEncrypted(value) {
-        if (typeof value !== 'string') {
-            return false;
-        }
-
-        const parts = value.split(':');
-        return parts.length >= 4;
+        return isEncryptedEnvelope(value);
     }
 
     _getNestedValue(obj, path) {
@@ -218,22 +215,22 @@ class FieldEncryptionService {
     }
 
     /**
-     * Serialize a value for encryption
-     * Objects/arrays are JSON stringified, primitives are converted to strings
+     * Serialize a value for encryption.
+     * Every value is JSON-encoded, strings included, so the type survives
+     * the round trip: '123456' is stored as "\"123456\"" and reads back as a
+     * string, 1234 reads back as a number.
      * @private
      */
     _serializeForEncryption(value) {
-        if (typeof value === 'object' && value !== null) {
-            // JSON.stringify for objects and arrays
-            return JSON.stringify(value);
-        }
-        // For primitives (string, number, boolean), convert to string
-        return String(value);
+        return JSON.stringify(value);
     }
 
     /**
-     * Deserialize a value after decryption
-     * Attempts to parse as JSON, returns string if parsing fails
+     * Deserialize a value after decryption.
+     * Parses the JSON written by _serializeForEncryption. Values encrypted by
+     * earlier versions stored strings raw: those that aren't valid JSON come
+     * back unchanged; a raw legacy string that is also valid JSON (e.g.
+     * '123456') still parses as it always did.
      * @private
      */
     _deserializeAfterDecryption(value) {