@forklaunch/core 1.2.9 → 1.3.0

package/lib/persistence/index.d.mts

@@ -1,4 +1,4 @@
-import { PropertyBuilders, EntityMetadataWithProperties, EntitySchemaWithMeta, InferEntityFromProperties, EventSubscriber, EventArgs, FilterDef, EntityManager, MikroORM } from '@mikro-orm/core';
+import { PropertyBuilders, EntityMetadataWithProperties, EntitySchemaWithMeta, InferEntityFromProperties, Type, Platform, TransformContext, FilterDef, EntityManager, EventSubscriber, MikroORM } from '@mikro-orm/core';
 
 declare const ComplianceLevel: {
     readonly pii: "pii";
@@ -101,6 +101,19 @@ declare function defineComplianceEntity<const TName extends string, const TTable
     userIdField?: string;
 }): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject>, TBase, TProperties>;
 
+/**
+ * Wraps an EntityManager to block `nativeInsert`, `nativeUpdate`, and
+ * `nativeDelete` on entities that have PII, PHI, or PCI compliance fields.
+ *
+ * This prevents bypassing the EncryptedType's encryption by using raw
+ * queries. Call this in the tenant context middleware when creating the
+ * request-scoped EM.
+ *
+ * @returns A Proxy-wrapped EntityManager that throws on native query
+ *          operations targeting compliance entities.
+ */
+declare function wrapEmWithNativeQueryBlocking<T extends object>(em: T): T;
+
 declare class MissingEncryptionKeyError extends Error {
     readonly name: "MissingEncryptionKeyError";
     constructor(message?: string);
@@ -122,60 +135,83 @@ declare class FieldEncryptor {
      */
     deriveKey(tenantId: string): Buffer;
     /**
-     * Encrypt a plaintext string for a specific tenant.
+     * Derive a deterministic IV from the key and plaintext using HMAC-SHA256,
+     * truncated to IV_BYTES. Same plaintext + same key → same IV → same
+     * ciphertext. This enables WHERE clause matching on encrypted columns
+     * while maintaining AES-256-GCM authenticated encryption.
+     *
+     * Meets SOC 2, HIPAA, PCI DSS, GDPR requirements for encryption at rest.
+     */
+    private deriveDeterministicIv;
+    /**
+     * Encrypt a plaintext string.
      *
-     * @returns Format: `v1:{base64(iv)}:{base64(authTag)}:{base64(ciphertext)}`
+     * Uses deterministic encryption (HMAC-derived IV) so the same plaintext
+     * always produces the same ciphertext. This enables database WHERE clause
+     * matching and UNIQUE constraints on encrypted columns.
+     *
+     * @returns Format: `v2:{base64(iv)}:{base64(authTag)}:{base64(ciphertext)}`
      */
     encrypt(plaintext: string | null): string | null;
     encrypt(plaintext: string | null, tenantId: string): string | null;
     /**
      * Decrypt a ciphertext string produced by {@link encrypt}.
+     * Supports both v1 (random IV) and v2 (deterministic IV) formats.
      */
     decrypt(ciphertext: string | null): string | null;
     decrypt(ciphertext: string | null, tenantId: string): string | null;
 }
 
 /**
- * MikroORM EventSubscriber that enforces field-level encryption for
- * compliance-classified fields (PHI and PCI).
+ * Register the FieldEncryptor instance for use by EncryptedType.
+ * Call this once at application bootstrap (e.g., in mikro-orm.config.ts).
+ */
+declare function registerEncryptor(encryptor: FieldEncryptor): void;
+/**
+ * Run a callback with the given tenant ID available to EncryptedType
+ * for per-tenant key derivation.
+ */
+declare function withEncryptionContext<T>(tenantId: string, fn: () => T): T;
+/**
+ * Set the encryption tenant ID for the current async context.
+ * Called automatically by the tenant context middleware — users
+ * don't need to call this directly.
+ */
+declare function setEncryptionTenantId(tenantId: string): void;
+/**
+ * Get the current tenant ID. Returns empty string when no context is set
+ * (startup, seeders, better-auth, background jobs).
+ */
+declare function getCurrentTenantId(): string;
+/**
+ * MikroORM custom Type that transparently encrypts/decrypts values.
+ *
+ * Works with any JS type (string, number, boolean, object/JSON).
+ * Non-string values are JSON-serialized before encryption and
+ * JSON-parsed after decryption.
  *
- * - **onBeforeCreate / onBeforeUpdate**: Encrypts PHI/PCI fields before
- *   database persistence. Throws `EncryptionRequiredError` if the encryption
- *   key is unavailable.
- * - **onLoad**: Decrypts PHI/PCI fields after loading from the database.
- *   Pre-migration plaintext (no `v1:` prefix) is returned as-is with a
- *   console warning to support rolling deployments.
+ * DB column is always `text` — the encrypted ciphertext is a string
+ * regardless of the original JS type.
  *
- * The tenant ID for key derivation is read from the EntityManager's filter
- * parameters (set by the tenant context middleware).
+ * Operates at the data conversion layer — before the identity map,
+ * during hydration, and during persistence. Entities always hold
+ * their original JS values (plaintext).
  */
-declare class ComplianceEventSubscriber implements EventSubscriber {
-    private readonly encryptor;
-    constructor(encryptor: FieldEncryptor);
-    beforeCreate(args: EventArgs<unknown>): Promise<void>;
-    beforeUpdate(args: EventArgs<unknown>): Promise<void>;
-    onLoad(args: EventArgs<unknown>): Promise<void>;
-    private encryptFields;
-    private decryptFields;
+declare class EncryptedType extends Type<unknown, string | null> {
+    private readonly originalType;
     /**
-     * Read the tenant ID from the EntityManager's filter parameters.
-     * Returns undefined when no tenant context is set (startup, seeders,
-     * better-auth). Callers skip encryption/decryption in that case.
+     * @param originalType - The original JS type hint ('string' | 'json' | 'number' | 'boolean').
+     *                       Used to determine serialization strategy.
      */
-    private getTenantId;
+    constructor(originalType?: string);
+    convertToDatabaseValue(value: unknown, _platform: Platform, _context?: TransformContext): string | null;
+    convertToJSValue(value: string | null, _platform: Platform): unknown;
+    getColumnType(): string;
+    get runtimeType(): string;
+    ensureComparable(): boolean;
+    private serializeValue;
+    private deserializeValue;
 }
-/**
- * Wraps an EntityManager to block `nativeInsert`, `nativeUpdate`, and
- * `nativeDelete` on entities that have PHI or PCI compliance fields.
- *
- * This prevents bypassing the ComplianceEventSubscriber's encryption
- * by using raw queries. Call this in the tenant context middleware when
- * creating the request-scoped EM.
- *
- * @returns A Proxy-wrapped EntityManager that throws on native query
- *          operations targeting compliance entities.
- */
-declare function wrapEmWithNativeQueryBlocking<T extends object>(em: T): T;
 
 /**
  * The name used to register the tenant isolation filter.
@@ -276,4 +312,4 @@ declare class RlsEventSubscriber implements EventSubscriber {
  */
 declare function setupRls(orm: MikroORM, config?: RlsConfig): void;
 
-export { ComplianceEventSubscriber, ComplianceLevel, ComplianceLevel as ComplianceLevelType, DecryptionError, EncryptionRequiredError, FieldEncryptor, MissingEncryptionKeyError, type ParsedDuration, RetentionAction, RetentionAction as RetentionActionType, RetentionDuration, type RetentionPolicy, type RlsConfig, RlsEventSubscriber, TENANT_FILTER_NAME, createTenantFilterDef, defineComplianceEntity, entityHasEncryptedFields, fp, getAllRetentionPolicies, getAllUserIdFields, getComplianceMetadata, getEntityComplianceFields, getEntityRetention, getEntityUserIdField, getSuperAdminContext, parseDuration, setupRls, setupTenantFilter, subtractDuration, wrapEmWithNativeQueryBlocking };
+export { ComplianceLevel, ComplianceLevel as ComplianceLevelType, DecryptionError, EncryptedType, EncryptionRequiredError, FieldEncryptor, MissingEncryptionKeyError, type ParsedDuration, RetentionAction, RetentionAction as RetentionActionType, RetentionDuration, type RetentionPolicy, type RlsConfig, RlsEventSubscriber, TENANT_FILTER_NAME, createTenantFilterDef, defineComplianceEntity, entityHasEncryptedFields, fp, getAllRetentionPolicies, getAllUserIdFields, getComplianceMetadata, getCurrentTenantId, getEntityComplianceFields, getEntityRetention, getEntityUserIdField, getSuperAdminContext, parseDuration, registerEncryptor, setEncryptionTenantId, setupRls, setupTenantFilter, subtractDuration, withEncryptionContext, wrapEmWithNativeQueryBlocking };

package/lib/persistence/index.d.ts

@@ -1,4 +1,4 @@
-import { PropertyBuilders, EntityMetadataWithProperties, EntitySchemaWithMeta, InferEntityFromProperties, EventSubscriber, EventArgs, FilterDef, EntityManager, MikroORM } from '@mikro-orm/core';
+import { PropertyBuilders, EntityMetadataWithProperties, EntitySchemaWithMeta, InferEntityFromProperties, Type, Platform, TransformContext, FilterDef, EntityManager, EventSubscriber, MikroORM } from '@mikro-orm/core';
 
 declare const ComplianceLevel: {
     readonly pii: "pii";
@@ -101,6 +101,19 @@ declare function defineComplianceEntity<const TName extends string, const TTable
     userIdField?: string;
 }): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject>, TBase, TProperties>;
 
+/**
+ * Wraps an EntityManager to block `nativeInsert`, `nativeUpdate`, and
+ * `nativeDelete` on entities that have PII, PHI, or PCI compliance fields.
+ *
+ * This prevents bypassing the EncryptedType's encryption by using raw
+ * queries. Call this in the tenant context middleware when creating the
+ * request-scoped EM.
+ *
+ * @returns A Proxy-wrapped EntityManager that throws on native query
+ *          operations targeting compliance entities.
+ */
+declare function wrapEmWithNativeQueryBlocking<T extends object>(em: T): T;
+
 declare class MissingEncryptionKeyError extends Error {
     readonly name: "MissingEncryptionKeyError";
     constructor(message?: string);
@@ -122,60 +135,83 @@ declare class FieldEncryptor {
      */
     deriveKey(tenantId: string): Buffer;
     /**
-     * Encrypt a plaintext string for a specific tenant.
+     * Derive a deterministic IV from the key and plaintext using HMAC-SHA256,
+     * truncated to IV_BYTES. Same plaintext + same key → same IV → same
+     * ciphertext. This enables WHERE clause matching on encrypted columns
+     * while maintaining AES-256-GCM authenticated encryption.
+     *
+     * Meets SOC 2, HIPAA, PCI DSS, GDPR requirements for encryption at rest.
+     */
+    private deriveDeterministicIv;
+    /**
+     * Encrypt a plaintext string.
      *
-     * @returns Format: `v1:{base64(iv)}:{base64(authTag)}:{base64(ciphertext)}`
+     * Uses deterministic encryption (HMAC-derived IV) so the same plaintext
+     * always produces the same ciphertext. This enables database WHERE clause
+     * matching and UNIQUE constraints on encrypted columns.
+     *
+     * @returns Format: `v2:{base64(iv)}:{base64(authTag)}:{base64(ciphertext)}`
      */
     encrypt(plaintext: string | null): string | null;
     encrypt(plaintext: string | null, tenantId: string): string | null;
     /**
      * Decrypt a ciphertext string produced by {@link encrypt}.
+     * Supports both v1 (random IV) and v2 (deterministic IV) formats.
      */
     decrypt(ciphertext: string | null): string | null;
     decrypt(ciphertext: string | null, tenantId: string): string | null;
 }
 
 /**
- * MikroORM EventSubscriber that enforces field-level encryption for
- * compliance-classified fields (PHI and PCI).
+ * Register the FieldEncryptor instance for use by EncryptedType.
+ * Call this once at application bootstrap (e.g., in mikro-orm.config.ts).
+ */
+declare function registerEncryptor(encryptor: FieldEncryptor): void;
+/**
+ * Run a callback with the given tenant ID available to EncryptedType
+ * for per-tenant key derivation.
+ */
+declare function withEncryptionContext<T>(tenantId: string, fn: () => T): T;
+/**
+ * Set the encryption tenant ID for the current async context.
+ * Called automatically by the tenant context middleware — users
+ * don't need to call this directly.
+ */
+declare function setEncryptionTenantId(tenantId: string): void;
+/**
+ * Get the current tenant ID. Returns empty string when no context is set
+ * (startup, seeders, better-auth, background jobs).
+ */
+declare function getCurrentTenantId(): string;
+/**
+ * MikroORM custom Type that transparently encrypts/decrypts values.
+ *
+ * Works with any JS type (string, number, boolean, object/JSON).
+ * Non-string values are JSON-serialized before encryption and
+ * JSON-parsed after decryption.
  *
- * - **onBeforeCreate / onBeforeUpdate**: Encrypts PHI/PCI fields before
- *   database persistence. Throws `EncryptionRequiredError` if the encryption
- *   key is unavailable.
- * - **onLoad**: Decrypts PHI/PCI fields after loading from the database.
- *   Pre-migration plaintext (no `v1:` prefix) is returned as-is with a
- *   console warning to support rolling deployments.
+ * DB column is always `text` — the encrypted ciphertext is a string
+ * regardless of the original JS type.
  *
- * The tenant ID for key derivation is read from the EntityManager's filter
- * parameters (set by the tenant context middleware).
+ * Operates at the data conversion layer — before the identity map,
+ * during hydration, and during persistence. Entities always hold
+ * their original JS values (plaintext).
  */
-declare class ComplianceEventSubscriber implements EventSubscriber {
-    private readonly encryptor;
-    constructor(encryptor: FieldEncryptor);
-    beforeCreate(args: EventArgs<unknown>): Promise<void>;
-    beforeUpdate(args: EventArgs<unknown>): Promise<void>;
-    onLoad(args: EventArgs<unknown>): Promise<void>;
-    private encryptFields;
-    private decryptFields;
+declare class EncryptedType extends Type<unknown, string | null> {
+    private readonly originalType;
     /**
-     * Read the tenant ID from the EntityManager's filter parameters.
-     * Returns undefined when no tenant context is set (startup, seeders,
-     * better-auth). Callers skip encryption/decryption in that case.
+     * @param originalType - The original JS type hint ('string' | 'json' | 'number' | 'boolean').
+     *                       Used to determine serialization strategy.
      */
-    private getTenantId;
+    constructor(originalType?: string);
+    convertToDatabaseValue(value: unknown, _platform: Platform, _context?: TransformContext): string | null;
+    convertToJSValue(value: string | null, _platform: Platform): unknown;
+    getColumnType(): string;
+    get runtimeType(): string;
+    ensureComparable(): boolean;
+    private serializeValue;
+    private deserializeValue;
 }
-/**
- * Wraps an EntityManager to block `nativeInsert`, `nativeUpdate`, and
- * `nativeDelete` on entities that have PHI or PCI compliance fields.
- *
- * This prevents bypassing the ComplianceEventSubscriber's encryption
- * by using raw queries. Call this in the tenant context middleware when
- * creating the request-scoped EM.
- *
- * @returns A Proxy-wrapped EntityManager that throws on native query
- *          operations targeting compliance entities.
- */
-declare function wrapEmWithNativeQueryBlocking<T extends object>(em: T): T;
 
 /**
  * The name used to register the tenant isolation filter.
@@ -276,4 +312,4 @@ declare class RlsEventSubscriber implements EventSubscriber {
  */
 declare function setupRls(orm: MikroORM, config?: RlsConfig): void;
 
-export { ComplianceEventSubscriber, ComplianceLevel, ComplianceLevel as ComplianceLevelType, DecryptionError, EncryptionRequiredError, FieldEncryptor, MissingEncryptionKeyError, type ParsedDuration, RetentionAction, RetentionAction as RetentionActionType, RetentionDuration, type RetentionPolicy, type RlsConfig, RlsEventSubscriber, TENANT_FILTER_NAME, createTenantFilterDef, defineComplianceEntity, entityHasEncryptedFields, fp, getAllRetentionPolicies, getAllUserIdFields, getComplianceMetadata, getEntityComplianceFields, getEntityRetention, getEntityUserIdField, getSuperAdminContext, parseDuration, setupRls, setupTenantFilter, subtractDuration, wrapEmWithNativeQueryBlocking };
+export { ComplianceLevel, ComplianceLevel as ComplianceLevelType, DecryptionError, EncryptedType, EncryptionRequiredError, FieldEncryptor, MissingEncryptionKeyError, type ParsedDuration, RetentionAction, RetentionAction as RetentionActionType, RetentionDuration, type RetentionPolicy, type RlsConfig, RlsEventSubscriber, TENANT_FILTER_NAME, createTenantFilterDef, defineComplianceEntity, entityHasEncryptedFields, fp, getAllRetentionPolicies, getAllUserIdFields, getComplianceMetadata, getCurrentTenantId, getEntityComplianceFields, getEntityRetention, getEntityUserIdField, getSuperAdminContext, parseDuration, registerEncryptor, setEncryptionTenantId, setupRls, setupTenantFilter, subtractDuration, withEncryptionContext, wrapEmWithNativeQueryBlocking };