create-mercato-app 0.8.1-develop.7296.1.2111d779db → 0.8.1-develop.7441.1.b42958b98c

package/agentic/shared/ai/skills/om-data-model-design/references/sensitive-data.md

@@ -6,5 +6,5 @@ Load this reference when records contain PII, credentials, addresses, contact in
 2. In module `encryption.ts`, import `ModuleEncryptionMap` from `@open-mercato/shared/modules/encryption`, declare `defaultEncryptionMaps: ModuleEncryptionMap[] = [{ entityId: '<module>:<entity>', fields: [{ field: '<database_field>' }] }]`, then `export default defaultEncryptionMaps` for generated registry compatibility. The entries are field-rule objects, not string names. Use a sibling `hashField` only for deterministic equality lookup. Let `TenantDataEncryptionService` populate it during encrypted writes, and query it with `lookupHashCandidates(value)` from `@open-mercato/shared/lib/encryption/aes`; use `hashForLookup(value)` from the same import only when the installed write contract explicitly requires a single keyed value. Never use raw SHA-256 for low-entropy PII such as email or phone values.
 3. Import `findWithDecryption`, `findOneWithDecryption`, or `findAndCountWithDecryption` from `@open-mercato/shared/lib/encryption/find` and make a concrete call in every implemented direct sensitive-record read path; an unused import or encryption map alone is not a decrypted read. For `makeCrudRoute`, its `entityId` + `fields` factory QueryEngine owns list decryption and `list` has no `findAndCount` override key—do not insert a decryption helper as an unsupported option. Put trusted tenant/organization constraints in each direct helper query `where` **and** pass `{ tenantId, organizationId }` as the fifth-argument decryption scope. The scope selects keys; it does not authorize or scope the ORM query. Use a null/global scope only when the installed contract explicitly permits it. Audit detail/export/search/worker/CLI and other direct ORM paths.
 4. Keep secrets out of responses, logs, errors, events, snapshots, cache keys, search documents, vector sources, and test artifacts. Exclude encrypted source values from `search.ts` field policies and indexes; index only an explicitly approved hash-only sibling for exact equality. Never sort or fuzzy-filter ciphertext.
-5. Seed/update encryption configuration through the supported command; never hand-roll KMS/AES. For every new or changed map, use an isolated initialized test tenant to reconcile the map, read back its registration, insert a fixture through the real write path, and assert the sensitive database columns are ciphertext before claiming runtime coverage.
+5. Seed/update encryption configuration through the supported command; never hand-roll KMS/AES. For every new or changed map, use an isolated initialized test tenant to reconcile the map, read back its registration, insert a fixture through the real write path, and assert the sensitive database columns are ciphertext before claiming runtime coverage. A fresh test tenant does not prove existing tenants are covered: maps are seeded only when a tenant is created, and nothing re-seeds tenants that already exist. When you add a map, or a field to an existing map, in a module that may already be deployed, ship a backfill migration in the same module: `this.addSql(buildEncryptionMapBackfillSql({ entityId, fields }))` from `@open-mercato/shared/lib/encryption/migration-backfill`. It inserts the map for every existing (tenant, organization) scope that already has active maps (`NOT EXISTS` guard) and appends missing fields to existing maps. Write the entity id and fields literally in the migration and leave `down()` empty. `yarn db:generate` warns when the local database shows an unbackfilled field. Plaintext rows written before the backfill are encrypted by `yarn mercato entities rotate-encryption-key --tenant <id>` without `--old-key`.
 6. Test authorized decryption, cross-scope denial, redaction, missing keys, export/search behavior, and cleanup/retention.