@forklaunch/core 1.2.9 → 1.3.2

package/lib/{openTelemetryCollector-DXGXRvQP.d.mts → openTelemetryCollector-DorlR4pn.d.mts}

@@ -1,5 +1,6 @@
 import { Counter, Gauge, Histogram, UpDownCounter, ObservableCounter, ObservableGauge, ObservableUpDownCounter } from '@opentelemetry/api';
-import { LevelWithSilentOrString, LevelWithSilent } from 'pino';
+import pino, { LevelWithSilentOrString, LevelWithSilent } from 'pino';
+import { AnyValueMap } from '@opentelemetry/api-logs';
 
 type MetricType<T extends string> = T extends 'counter' ? Counter : T extends 'gauge' ? Gauge : T extends 'histogram' ? Histogram : T extends 'upDownCounter' ? UpDownCounter : T extends 'observableCounter' ? ObservableCounter : T extends 'observableGauge' ? ObservableGauge : T extends 'observableUpDownCounter' ? ObservableUpDownCounter : undefined;
 type MetricsDefinition = Record<string, 'counter' | 'gauge' | 'histogram' | 'upDownCounter' | 'observableCounter' | 'observableGauge' | 'observableUpDownCounter'>;
@@ -20,8 +21,26 @@ interface TelemetryOptions {
     level: LevelWithSilentOrString;
 }
 
+declare function meta(meta: Record<string, unknown>): LoggerMeta;
+declare class PinoLogger {
+    private pinoLogger;
+    private meta;
+    constructor(level: LevelWithSilentOrString, meta?: AnyValueMap);
+    log(level: LevelWithSilent, ...args: (string | unknown | LoggerMeta)[]): void;
+    error: LogFn;
+    info: LogFn;
+    debug: LogFn;
+    warn: LogFn;
+    trace: LogFn;
+    child(meta?: AnyValueMap): PinoLogger;
+    getBaseLogger(): pino.Logger;
+}
+declare function logger(level: LevelWithSilentOrString, meta?: AnyValueMap): PinoLogger;
+
 declare class OpenTelemetryCollector<AppliedMetricsDefinition extends MetricsDefinition> {
-    #private;
+    _logger: PinoLogger;
+    _serviceName: string;
+    _metrics: Record<keyof AppliedMetricsDefinition, Counter | Gauge | Histogram | UpDownCounter | ObservableCounter | ObservableGauge | ObservableUpDownCounter>;
     constructor(serviceName: string, level?: LevelWithSilentOrString, metricDefinitions?: AppliedMetricsDefinition);
     log(level: LevelWithSilent, ...args: (string | unknown | LoggerMeta)[]): void;
     info: LogFn;
@@ -48,4 +67,4 @@ declare const httpServerDurationHistogram: Histogram<{
     "http.response.status_code": number;
 }>;
 
-export { type LoggerMeta as L, type MetricsDefinition as M, OpenTelemetryCollector as O, type TelemetryOptions as T, type LogFn as a, type MetricType as b, httpServerDurationHistogram as c, httpRequestsTotalCounter as h };
+export { type LogFn as L, type MetricsDefinition as M, OpenTelemetryCollector as O, PinoLogger as P, type TelemetryOptions as T, type LoggerMeta as a, type MetricType as b, httpServerDurationHistogram as c, httpRequestsTotalCounter as h, logger as l, meta as m };

package/lib/{openTelemetryCollector-DXGXRvQP.d.ts → openTelemetryCollector-DorlR4pn.d.ts}

@@ -1,5 +1,6 @@
 import { Counter, Gauge, Histogram, UpDownCounter, ObservableCounter, ObservableGauge, ObservableUpDownCounter } from '@opentelemetry/api';
-import { LevelWithSilentOrString, LevelWithSilent } from 'pino';
+import pino, { LevelWithSilentOrString, LevelWithSilent } from 'pino';
+import { AnyValueMap } from '@opentelemetry/api-logs';
 
 type MetricType<T extends string> = T extends 'counter' ? Counter : T extends 'gauge' ? Gauge : T extends 'histogram' ? Histogram : T extends 'upDownCounter' ? UpDownCounter : T extends 'observableCounter' ? ObservableCounter : T extends 'observableGauge' ? ObservableGauge : T extends 'observableUpDownCounter' ? ObservableUpDownCounter : undefined;
 type MetricsDefinition = Record<string, 'counter' | 'gauge' | 'histogram' | 'upDownCounter' | 'observableCounter' | 'observableGauge' | 'observableUpDownCounter'>;
@@ -20,8 +21,26 @@ interface TelemetryOptions {
     level: LevelWithSilentOrString;
 }
 
+declare function meta(meta: Record<string, unknown>): LoggerMeta;
+declare class PinoLogger {
+    private pinoLogger;
+    private meta;
+    constructor(level: LevelWithSilentOrString, meta?: AnyValueMap);
+    log(level: LevelWithSilent, ...args: (string | unknown | LoggerMeta)[]): void;
+    error: LogFn;
+    info: LogFn;
+    debug: LogFn;
+    warn: LogFn;
+    trace: LogFn;
+    child(meta?: AnyValueMap): PinoLogger;
+    getBaseLogger(): pino.Logger;
+}
+declare function logger(level: LevelWithSilentOrString, meta?: AnyValueMap): PinoLogger;
+
 declare class OpenTelemetryCollector<AppliedMetricsDefinition extends MetricsDefinition> {
-    #private;
+    _logger: PinoLogger;
+    _serviceName: string;
+    _metrics: Record<keyof AppliedMetricsDefinition, Counter | Gauge | Histogram | UpDownCounter | ObservableCounter | ObservableGauge | ObservableUpDownCounter>;
     constructor(serviceName: string, level?: LevelWithSilentOrString, metricDefinitions?: AppliedMetricsDefinition);
     log(level: LevelWithSilent, ...args: (string | unknown | LoggerMeta)[]): void;
     info: LogFn;
@@ -48,4 +67,4 @@ declare const httpServerDurationHistogram: Histogram<{
     "http.response.status_code": number;
 }>;
 
-export { type LoggerMeta as L, type MetricsDefinition as M, OpenTelemetryCollector as O, type TelemetryOptions as T, type LogFn as a, type MetricType as b, httpServerDurationHistogram as c, httpRequestsTotalCounter as h };
+export { type LogFn as L, type MetricsDefinition as M, OpenTelemetryCollector as O, PinoLogger as P, type TelemetryOptions as T, type LoggerMeta as a, type MetricType as b, httpServerDurationHistogram as c, httpRequestsTotalCounter as h, logger as l, meta as m };

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 };