@digilogiclabs/platform-core 1.3.0 → 1.4.0

package/README.md

@@ -2,9 +2,9 @@
 
 > Vendor-agnostic infrastructure abstraction layer for building portable, enterprise-grade applications.
 
-[![Tests](https://img.shields.io/badge/tests-343%20passing-brightgreen)](./tests)
-[![Adapters](https://img.shields.io/badge/adapters-14-blue)](./src/adapters)
-[![Interfaces](https://img.shields.io/badge/interfaces-12-blue)](./src/interfaces)
+[![Tests](https://img.shields.io/badge/tests-1270%2B%20passing-brightgreen)](./tests)
+[![Adapters](https://img.shields.io/badge/adapters-50%2B-blue)](./src/adapters)
+[![Interfaces](https://img.shields.io/badge/interfaces-34-blue)](./src/interfaces)
 
 ## Overview
 
@@ -28,6 +28,8 @@ Platform Core provides a unified API for common infrastructure services, allowin
 - **Hooks** - Lifecycle events for database, cache, email, queue operations
 - **Resilience** - Retry, circuit breaker, timeout, bulkhead, fallback patterns
 - **Metrics** - Counters, gauges, histograms, timings with tag support
+- **Security** - HTML escaping, URL detection, content sanitization for emails
+- **API Utilities** - Structured errors, error classification, pagination helpers
 
 ## Installation
 
@@ -547,6 +549,80 @@ const summary = metrics.getSummary();
 console.log(summary.counters, summary.timings);
 ```
 
+## Security Utilities
+
+Helpers for safe rendering of user content in emails and HTML output:
+
+```typescript
+import {
+  escapeHtml,
+  containsUrls,
+  containsHtml,
+  stripHtml,
+  defangUrl,
+  sanitizeForEmail,
+} from "@digilogiclabs/platform-core";
+
+// Escape HTML special characters
+escapeHtml('<script>alert("xss")</script>');
+// → '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+
+// Detect URLs or HTML in user input
+containsUrls("visit https://evil.com"); // true
+containsUrls("visit evil.com"); // true (bare domain detection)
+containsHtml("<b>bold</b>"); // true
+
+// Strip HTML tags
+stripHtml("<p>Hello <b>world</b></p>"); // "Hello world"
+
+// Defang URLs to prevent auto-linking in email clients
+defangUrl("https://evil.com/path"); // "hxxps://evil[com]/path"
+
+// Sanitize user content for HTML email templates
+sanitizeForEmail(userInput); // Escapes all HTML entities
+```
+
+## API Utilities
+
+Framework-agnostic error handling and response helpers:
+
+```typescript
+import {
+  ApiError,
+  ApiErrorCode,
+  CommonApiErrors,
+  classifyError,
+  buildPagination,
+  isApiError,
+} from "@digilogiclabs/platform-core";
+import type {
+  ApiSuccessResponse,
+  ApiPaginatedResponse,
+} from "@digilogiclabs/platform-core";
+
+// Pre-built error factories
+throw CommonApiErrors.notFound("User"); // 404
+throw CommonApiErrors.unauthorized(); // 401
+throw CommonApiErrors.forbidden(); // 403
+throw CommonApiErrors.validationError(details); // 400
+throw CommonApiErrors.rateLimitExceeded(); // 429
+
+// Custom API errors
+throw new ApiError(422, "Invalid input", ApiErrorCode.VALIDATION_ERROR, {
+  field: "email",
+  message: "Invalid format",
+});
+
+// Classify any error into { status, body }
+// Handles: ApiError, Zod validation errors, PostgreSQL errors, generic errors
+const { status, body } = classifyError(error, isDev);
+// → { status: 409, body: { error: "Resource already exists", code: "CONFLICT" } }
+
+// Pagination helper
+const pagination = buildPagination(1, 20, 100);
+// → { page: 1, limit: 20, total: 100, totalPages: 5, hasMore: true }
+```
+
 ## Local Development
 
 Start the development infrastructure:

package/dist/{ConsoleEmail-hUDFsKoA.d.mts → ConsoleEmail-ubSVWgTa.d.mts}

@@ -1736,6 +1736,108 @@ declare class MemoryRAG implements IRAG {
     private deduplicateResults;
 }
 
+/**
+ * ICrypto - Field-Level Encryption Interface
+ * Provides AES-256-GCM encryption with key rotation for PII in databases.
+ */
+type CryptoAlgorithm = "aes-256-gcm";
+type CryptoKeyStatus = "active" | "decrypt-only" | "retired";
+/** Encrypted field stored in database columns */
+interface EncryptedField {
+    /** Base64-encoded ciphertext */
+    ciphertext: string;
+    /** Base64-encoded initialization vector (96-bit for GCM) */
+    iv: string;
+    /** Base64-encoded GCM authentication tag */
+    tag: string;
+    /** ID of the key used for encryption */
+    keyId: string;
+    /** Algorithm used */
+    algorithm: CryptoAlgorithm;
+    /** Schema version for forward compatibility */
+    version: 1;
+}
+/** Deterministic encrypted field — enables WHERE clause lookups */
+interface DeterministicEncryptedField {
+    /** HMAC-SHA256 hash for equality searches */
+    hash: string;
+    /** Full encrypted field for decryption */
+    encrypted: EncryptedField;
+}
+/** Key metadata (never exposes raw key material) */
+interface CryptoKeyMetadata {
+    keyId: string;
+    createdAt: Date;
+    status: CryptoKeyStatus;
+}
+/** Options for encrypt/decrypt operations */
+interface EncryptOptions {
+    /** Specific key ID to use (defaults to active key) */
+    keyId?: string;
+    /** Additional Authenticated Data for GCM (e.g., table name + row ID) */
+    aad?: string;
+}
+/** Result of a key rotation */
+interface KeyRotationResult {
+    /** ID of the new active key */
+    newKeyId: string;
+    /** ID of the previous active key (now decrypt-only) */
+    previousKeyId: string;
+}
+interface ICrypto {
+    /**
+     * Encrypt plaintext using AES-256-GCM with a random IV.
+     * Each call produces unique ciphertext (non-deterministic).
+     */
+    encrypt(plaintext: string, options?: EncryptOptions): Promise<EncryptedField>;
+    /**
+     * Decrypt an encrypted field back to plaintext.
+     * Automatically selects the correct key by keyId.
+     */
+    decrypt(field: EncryptedField, options?: EncryptOptions): Promise<string>;
+    /**
+     * Encrypt with a deterministic hash for searchable encryption.
+     * The hash is stable for the same plaintext (HMAC-SHA256),
+     * while the encrypted value still uses a random IV.
+     */
+    encryptDeterministic(plaintext: string, options?: EncryptOptions): Promise<DeterministicEncryptedField>;
+    /**
+     * Compute a deterministic hash (HMAC-SHA256) for WHERE clause lookups.
+     * Use this to search for records without decrypting.
+     */
+    computeHash(plaintext: string): Promise<string>;
+    /**
+     * Encrypt multiple fields in a single call.
+     */
+    encryptBatch(fields: Record<string, string>, options?: EncryptOptions): Promise<Record<string, EncryptedField>>;
+    /**
+     * Decrypt multiple fields in a single call.
+     */
+    decryptBatch(fields: Record<string, EncryptedField>, options?: EncryptOptions): Promise<Record<string, string>>;
+    /**
+     * Rotate to a new encryption key.
+     * The old key is marked as decrypt-only (can still decrypt, cannot encrypt new data).
+     */
+    rotateKey(): Promise<KeyRotationResult>;
+    /**
+     * Re-encrypt a field with the current active key.
+     * Used after key rotation to migrate old ciphertext.
+     */
+    reEncrypt(field: EncryptedField, options?: EncryptOptions): Promise<EncryptedField>;
+    /**
+     * List all keys and their statuses.
+     */
+    listKeys(): Promise<CryptoKeyMetadata[]>;
+    /**
+     * Get the ID of the current active encryption key.
+     */
+    getActiveKeyId(): Promise<string>;
+    /**
+     * Health check — verifies encrypt/decrypt round-trip works.
+     */
+    healthCheck(): Promise<boolean>;
+}
+
 /**
  * Main Platform interface
  * Combines all infrastructure services into a single entry point
@@ -1774,6 +1876,8 @@ interface IPlatform {
     readonly ai?: IAI;
     /** RAG service (optional, enabled via RAG_ENABLED=true) */
     readonly rag?: IRAG;
+    /** Crypto service for field-level encryption (optional) */
+    readonly crypto?: ICrypto;
     /**
      * Check health of all services
      */
@@ -2339,6 +2443,37 @@ declare const RAGConfigSchema: z.ZodEffects<z.ZodObject<{
     embeddingApiKey?: string | undefined;
     embeddingModel?: string | undefined;
 }>;
+declare const CryptoConfigSchema: z.ZodEffects<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    masterKey: z.ZodOptional<z.ZodString>;
+    hmacKey: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}, {
+    enabled?: boolean | undefined;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}>, {
+    enabled: boolean;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}, {
+    enabled?: boolean | undefined;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}>;
+declare const SecurityConfigSchema: z.ZodObject<{
+    enforceTls: z.ZodDefault<z.ZodBoolean>;
+    tlsWarnOnly: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    enforceTls: boolean;
+    tlsWarnOnly: boolean;
+}, {
+    enforceTls?: boolean | undefined;
+    tlsWarnOnly?: boolean | undefined;
+}>;
 declare const RetryConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     maxAttempts: z.ZodDefault<z.ZodNumber>;
@@ -3170,6 +3305,37 @@ declare const PlatformConfigSchema: z.ZodObject<{
         embeddingApiKey?: string | undefined;
         embeddingModel?: string | undefined;
     }>>;
+    crypto: z.ZodDefault<z.ZodEffects<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        masterKey: z.ZodOptional<z.ZodString>;
+        hmacKey: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }>, {
+        enabled: boolean;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }>>;
+    security: z.ZodDefault<z.ZodObject<{
+        enforceTls: z.ZodDefault<z.ZodBoolean>;
+        tlsWarnOnly: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enforceTls: boolean;
+        tlsWarnOnly: boolean;
+    }, {
+        enforceTls?: boolean | undefined;
+        tlsWarnOnly?: boolean | undefined;
+    }>>;
     resilience: z.ZodDefault<z.ZodObject<{
         retry: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -3489,6 +3655,10 @@ declare const PlatformConfigSchema: z.ZodObject<{
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    security: {
+        enforceTls: boolean;
+        tlsWarnOnly: boolean;
+    };
     email: {
         provider: "console" | "smtp" | "memory" | "resend";
         secure: boolean;
@@ -3501,6 +3671,11 @@ declare const PlatformConfigSchema: z.ZodObject<{
         from?: string | undefined;
         replyTo?: string | undefined;
     };
+    crypto: {
+        enabled: boolean;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    };
     database: {
         provider: "memory" | "postgres" | "supabase";
         poolSize: number;
@@ -3639,6 +3814,10 @@ declare const PlatformConfigSchema: z.ZodObject<{
         };
     };
 }, {
+    security?: {
+        enforceTls?: boolean | undefined;
+        tlsWarnOnly?: boolean | undefined;
+    } | undefined;
     email?: {
         provider?: "console" | "smtp" | "memory" | "resend" | undefined;
         password?: string | undefined;
@@ -3651,6 +3830,11 @@ declare const PlatformConfigSchema: z.ZodObject<{
         replyTo?: string | undefined;
         rateLimitPerSecond?: number | undefined;
     } | undefined;
+    crypto?: {
+        enabled?: boolean | undefined;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    } | undefined;
     database?: {
         provider?: "memory" | "postgres" | "supabase" | undefined;
         url?: string | undefined;
@@ -3798,6 +3982,8 @@ type QueueConfig = z.infer<typeof QueueConfigSchema>;
 type ResilienceConfig = z.infer<typeof ResilienceConfigSchema>;
 type ObservabilityConfig = z.infer<typeof ObservabilityConfigSchema>;
 type MiddlewareConfig = z.infer<typeof MiddlewareConfigSchema>;
+type CryptoConfig = z.infer<typeof CryptoConfigSchema>;
+type SecurityConfig = z.infer<typeof SecurityConfigSchema>;
 /**
  * Load configuration from environment variables
  */
@@ -4034,4 +4220,4 @@ declare class ConsoleEmail implements IEmail {
     private formatAddresses;
 }
 
-export { type RAGDocument as $, type AIConfig as A, type AIChatRequest as B, ConsoleEmail as C, type AIChatResponse as D, EnvSecrets as E, type AIStreamChunk as F, type AIStreamCallback as G, type AICompletionRequest as H, type IPlatform as I, type Job as J, type AICompletionResponse as K, type AIEmbeddingRequest as L, MemoryDatabase as M, NoopLogger as N, type AIEmbeddingResponse as O, type PlatformHealthStatus as P, type QueryResult as Q, type RepeatOptions as R, type StorageFile as S, type AIModelConfig as T, type UploadOptions as U, type AIModelType as V, type AIProvider as W, type IRAG as X, type RAGConfig as Y, type CreateCollectionOptions as Z, type RAGCollection as _, MemoryCache as a, type EmailAddress as a$, type IngestionOptions as a0, type BulkIngestionResult as a1, type IngestionResult as a2, type DocumentStatus as a3, type RAGChunk as a4, type RAGSearchQuery as a5, type RAGSearchResponse as a6, type RAGSearchResult as a7, type ContextAssemblyConfig as a8, type AssembledContext as a9, type AIToolCall as aA, type AITool as aB, type AIChatChoice as aC, type AIFinishReason as aD, type AIUsageInfo as aE, type RoutingStrategy as aF, type AIRouterConfig as aG, type AIErrorCode as aH, type AIError as aI, MemoryRAG as aJ, ChunkingPresets as aK, type ChunkingStrategy as aL, type ChunkingConfig as aM, type SearchMode as aN, type RAGFilter as aO, type RAGPipelineStep as aP, createPlatformAsync as aQ, createScopedMetrics as aR, MemoryTracing as aS, NoopTracing as aT, type ITracing as aU, type ISpan as aV, type SpanContext as aW, type SpanOptions as aX, type SpanStatus as aY, type SpanKind as aZ, type TracingConfig as a_, type RAGPipeline as aa, type ICacheOptions as ab, type JobResult as ac, type JobContext as ad, type JobEvent as ae, type QueueStats as af, type BackoffOptions as ag, type LogLevel as ah, type LogMeta as ai, type LogEntry as aj, type LoggerConfig as ak, type MetricTags as al, type HistogramStats as am, type TimingStats as an, type Secret as ao, type SecretMetadata as ap, type GetSecretOptions as aq, type SetSecretOptions as ar, type RotateSecretOptions as as, type RotationResult as at, createAIError as au, isAIError as av, AIErrorMessages as aw, MemoryAI as ax, type AIRole as ay, type AIMessage as az, MemoryStorage as b, type EmailAttachment as b0, calculateBackoff as b1, generateJobId as b2, type SpanStatusCode as b3, type SpanEvent as b4, DatabaseProviderSchema as b5, CacheProviderSchema as b6, StorageProviderSchema as b7, EmailProviderSchema as b8, QueueProviderSchema as b9, type EmailConfig as bA, type QueueConfig as bB, type ResilienceConfig as bC, type ObservabilityConfig as bD, type MiddlewareConfig as bE, loadConfig as bF, validateConfig as bG, safeValidateConfig as bH, getDefaultConfig as bI, TracingProviderSchema as ba, LogLevelSchema as bb, AIProviderSchema as bc, RAGProviderSchema as bd, DatabaseConfigSchema as be, CacheConfigSchema as bf, StorageConfigSchema as bg, EmailConfigSchema as bh, QueueConfigSchema as bi, AIConfigSchema as bj, RAGConfigSchema as bk, RetryConfigSchema as bl, CircuitBreakerConfigSchema as bm, TimeoutConfigSchema as bn, BulkheadConfigSchema as bo, ResilienceConfigSchema as bp, LoggingConfigSchema as bq, MetricsConfigSchema as br, TracingConfigSchema as bs, ObservabilityConfigSchema as bt, MiddlewareConfigSchema as bu, PlatformConfigSchema as bv, type PlatformConfig as bw, type DatabaseConfig as bx, type CacheConfig as by, type StorageConfig as bz, MemoryEmail as c, MemoryQueue as d, type IDatabase as e, MemorySecrets as f, createPlatform as g, ConsoleLogger as h, MemoryMetrics as i, NoopMetrics as j, type IQueryBuilder as k, type ICache as l, type IStorage as m, type IEmail as n, type IQueue as o, type ILogger as p, type IMetrics as q, type ISecrets as r, type JobOptions as s, type EmailMessage as t, type MetricsSummary as u, type EmailResult as v, type JobState as w, type JobEventType as x, type JobEventHandler as y, type IAI as z };
+export { type AIModelType as $, type JobState as A, type JobEventType as B, ConsoleEmail as C, type DeterministicEncryptedField as D, EnvSecrets as E, type JobEventHandler as F, type IAI as G, type AIConfig as H, type IPlatform as I, type Job as J, type KeyRotationResult as K, type AIChatRequest as L, MemoryDatabase as M, NoopLogger as N, type AIChatResponse as O, type PlatformHealthStatus as P, type QueryResult as Q, type RepeatOptions as R, type StorageFile as S, type AIStreamChunk as T, type UploadOptions as U, type AIStreamCallback as V, type AICompletionRequest as W, type AICompletionResponse as X, type AIEmbeddingRequest as Y, type AIEmbeddingResponse as Z, type AIModelConfig as _, MemoryCache as a, NoopTracing as a$, type AIProvider as a0, type IRAG as a1, type RAGConfig as a2, type CreateCollectionOptions as a3, type RAGCollection as a4, type RAGDocument as a5, type IngestionOptions as a6, type BulkIngestionResult as a7, type IngestionResult as a8, type DocumentStatus as a9, createAIError as aA, isAIError as aB, AIErrorMessages as aC, MemoryAI as aD, type AIRole as aE, type AIMessage as aF, type AIToolCall as aG, type AITool as aH, type AIChatChoice as aI, type AIFinishReason as aJ, type AIUsageInfo as aK, type RoutingStrategy as aL, type AIRouterConfig as aM, type AIErrorCode as aN, type AIError as aO, MemoryRAG as aP, ChunkingPresets as aQ, type ChunkingStrategy as aR, type ChunkingConfig as aS, type SearchMode as aT, type RAGFilter as aU, type RAGPipelineStep as aV, type CryptoKeyStatus as aW, type CryptoAlgorithm as aX, createPlatformAsync as aY, createScopedMetrics as aZ, MemoryTracing as a_, type RAGChunk as aa, type RAGSearchQuery as ab, type RAGSearchResponse as ac, type RAGSearchResult as ad, type ContextAssemblyConfig as ae, type AssembledContext as af, type RAGPipeline as ag, type ICacheOptions as ah, type JobResult as ai, type JobContext as aj, type JobEvent as ak, type QueueStats as al, type BackoffOptions as am, type LogLevel as an, type LogMeta as ao, type LogEntry as ap, type LoggerConfig as aq, type MetricTags as ar, type HistogramStats as as, type TimingStats as at, type Secret as au, type SecretMetadata as av, type GetSecretOptions as aw, type SetSecretOptions as ax, type RotateSecretOptions as ay, type RotationResult as az, MemoryStorage as b, type ITracing as b0, type ISpan as b1, type SpanContext as b2, type SpanOptions as b3, type SpanStatus as b4, type SpanKind as b5, type TracingConfig as b6, type EmailAddress as b7, type EmailAttachment as b8, calculateBackoff as b9, LoggingConfigSchema as bA, MetricsConfigSchema as bB, TracingConfigSchema as bC, ObservabilityConfigSchema as bD, MiddlewareConfigSchema as bE, PlatformConfigSchema as bF, type PlatformConfig as bG, type DatabaseConfig as bH, type CacheConfig as bI, type StorageConfig as bJ, type EmailConfig as bK, type QueueConfig as bL, type ResilienceConfig as bM, type ObservabilityConfig as bN, type MiddlewareConfig as bO, type CryptoConfig as bP, type SecurityConfig as bQ, loadConfig as bR, validateConfig as bS, safeValidateConfig as bT, getDefaultConfig as bU, generateJobId as ba, type SpanStatusCode as bb, type SpanEvent as bc, DatabaseProviderSchema as bd, CacheProviderSchema as be, StorageProviderSchema as bf, EmailProviderSchema as bg, QueueProviderSchema as bh, TracingProviderSchema as bi, LogLevelSchema as bj, AIProviderSchema as bk, RAGProviderSchema as bl, DatabaseConfigSchema as bm, CacheConfigSchema as bn, StorageConfigSchema as bo, EmailConfigSchema as bp, QueueConfigSchema as bq, AIConfigSchema as br, RAGConfigSchema as bs, CryptoConfigSchema as bt, SecurityConfigSchema as bu, RetryConfigSchema as bv, CircuitBreakerConfigSchema as bw, TimeoutConfigSchema as bx, BulkheadConfigSchema as by, ResilienceConfigSchema as bz, MemoryEmail as c, MemoryQueue as d, type IDatabase as e, MemorySecrets as f, createPlatform as g, ConsoleLogger as h, MemoryMetrics as i, NoopMetrics as j, type IQueryBuilder as k, type ICache as l, type IStorage as m, type IEmail as n, type IQueue as o, type ILogger as p, type IMetrics as q, type ISecrets as r, type JobOptions as s, type EmailMessage as t, type MetricsSummary as u, type ICrypto as v, type EncryptOptions as w, type EncryptedField as x, type CryptoKeyMetadata as y, type EmailResult as z };

package/dist/{ConsoleEmail-hUDFsKoA.d.ts → ConsoleEmail-ubSVWgTa.d.ts}

@@ -1736,6 +1736,108 @@ declare class MemoryRAG implements IRAG {
     private deduplicateResults;
 }
 
+/**
+ * ICrypto - Field-Level Encryption Interface
+ * Provides AES-256-GCM encryption with key rotation for PII in databases.
+ */
+type CryptoAlgorithm = "aes-256-gcm";
+type CryptoKeyStatus = "active" | "decrypt-only" | "retired";
+/** Encrypted field stored in database columns */
+interface EncryptedField {
+    /** Base64-encoded ciphertext */
+    ciphertext: string;
+    /** Base64-encoded initialization vector (96-bit for GCM) */
+    iv: string;
+    /** Base64-encoded GCM authentication tag */
+    tag: string;
+    /** ID of the key used for encryption */
+    keyId: string;
+    /** Algorithm used */
+    algorithm: CryptoAlgorithm;
+    /** Schema version for forward compatibility */
+    version: 1;
+}
+/** Deterministic encrypted field — enables WHERE clause lookups */
+interface DeterministicEncryptedField {
+    /** HMAC-SHA256 hash for equality searches */
+    hash: string;
+    /** Full encrypted field for decryption */
+    encrypted: EncryptedField;
+}
+/** Key metadata (never exposes raw key material) */
+interface CryptoKeyMetadata {
+    keyId: string;
+    createdAt: Date;
+    status: CryptoKeyStatus;
+}
+/** Options for encrypt/decrypt operations */
+interface EncryptOptions {
+    /** Specific key ID to use (defaults to active key) */
+    keyId?: string;
+    /** Additional Authenticated Data for GCM (e.g., table name + row ID) */
+    aad?: string;
+}
+/** Result of a key rotation */
+interface KeyRotationResult {
+    /** ID of the new active key */
+    newKeyId: string;
+    /** ID of the previous active key (now decrypt-only) */
+    previousKeyId: string;
+}
+interface ICrypto {
+    /**
+     * Encrypt plaintext using AES-256-GCM with a random IV.
+     * Each call produces unique ciphertext (non-deterministic).
+     */
+    encrypt(plaintext: string, options?: EncryptOptions): Promise<EncryptedField>;
+    /**
+     * Decrypt an encrypted field back to plaintext.
+     * Automatically selects the correct key by keyId.
+     */
+    decrypt(field: EncryptedField, options?: EncryptOptions): Promise<string>;
+    /**
+     * Encrypt with a deterministic hash for searchable encryption.
+     * The hash is stable for the same plaintext (HMAC-SHA256),
+     * while the encrypted value still uses a random IV.
+     */
+    encryptDeterministic(plaintext: string, options?: EncryptOptions): Promise<DeterministicEncryptedField>;
+    /**
+     * Compute a deterministic hash (HMAC-SHA256) for WHERE clause lookups.
+     * Use this to search for records without decrypting.
+     */
+    computeHash(plaintext: string): Promise<string>;
+    /**
+     * Encrypt multiple fields in a single call.
+     */
+    encryptBatch(fields: Record<string, string>, options?: EncryptOptions): Promise<Record<string, EncryptedField>>;
+    /**
+     * Decrypt multiple fields in a single call.
+     */
+    decryptBatch(fields: Record<string, EncryptedField>, options?: EncryptOptions): Promise<Record<string, string>>;
+    /**
+     * Rotate to a new encryption key.
+     * The old key is marked as decrypt-only (can still decrypt, cannot encrypt new data).
+     */
+    rotateKey(): Promise<KeyRotationResult>;
+    /**
+     * Re-encrypt a field with the current active key.
+     * Used after key rotation to migrate old ciphertext.
+     */
+    reEncrypt(field: EncryptedField, options?: EncryptOptions): Promise<EncryptedField>;
+    /**
+     * List all keys and their statuses.
+     */
+    listKeys(): Promise<CryptoKeyMetadata[]>;
+    /**
+     * Get the ID of the current active encryption key.
+     */
+    getActiveKeyId(): Promise<string>;
+    /**
+     * Health check — verifies encrypt/decrypt round-trip works.
+     */
+    healthCheck(): Promise<boolean>;
+}
+
 /**
  * Main Platform interface
  * Combines all infrastructure services into a single entry point
@@ -1774,6 +1876,8 @@ interface IPlatform {
     readonly ai?: IAI;
     /** RAG service (optional, enabled via RAG_ENABLED=true) */
     readonly rag?: IRAG;
+    /** Crypto service for field-level encryption (optional) */
+    readonly crypto?: ICrypto;
     /**
      * Check health of all services
      */
@@ -2339,6 +2443,37 @@ declare const RAGConfigSchema: z.ZodEffects<z.ZodObject<{
     embeddingApiKey?: string | undefined;
     embeddingModel?: string | undefined;
 }>;
+declare const CryptoConfigSchema: z.ZodEffects<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    masterKey: z.ZodOptional<z.ZodString>;
+    hmacKey: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}, {
+    enabled?: boolean | undefined;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}>, {
+    enabled: boolean;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}, {
+    enabled?: boolean | undefined;
+    masterKey?: string | undefined;
+    hmacKey?: string | undefined;
+}>;
+declare const SecurityConfigSchema: z.ZodObject<{
+    enforceTls: z.ZodDefault<z.ZodBoolean>;
+    tlsWarnOnly: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    enforceTls: boolean;
+    tlsWarnOnly: boolean;
+}, {
+    enforceTls?: boolean | undefined;
+    tlsWarnOnly?: boolean | undefined;
+}>;
 declare const RetryConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     maxAttempts: z.ZodDefault<z.ZodNumber>;
@@ -3170,6 +3305,37 @@ declare const PlatformConfigSchema: z.ZodObject<{
         embeddingApiKey?: string | undefined;
         embeddingModel?: string | undefined;
     }>>;
+    crypto: z.ZodDefault<z.ZodEffects<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        masterKey: z.ZodOptional<z.ZodString>;
+        hmacKey: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }>, {
+        enabled: boolean;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    }>>;
+    security: z.ZodDefault<z.ZodObject<{
+        enforceTls: z.ZodDefault<z.ZodBoolean>;
+        tlsWarnOnly: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enforceTls: boolean;
+        tlsWarnOnly: boolean;
+    }, {
+        enforceTls?: boolean | undefined;
+        tlsWarnOnly?: boolean | undefined;
+    }>>;
     resilience: z.ZodDefault<z.ZodObject<{
         retry: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -3489,6 +3655,10 @@ declare const PlatformConfigSchema: z.ZodObject<{
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
+    security: {
+        enforceTls: boolean;
+        tlsWarnOnly: boolean;
+    };
     email: {
         provider: "console" | "smtp" | "memory" | "resend";
         secure: boolean;
@@ -3501,6 +3671,11 @@ declare const PlatformConfigSchema: z.ZodObject<{
         from?: string | undefined;
         replyTo?: string | undefined;
     };
+    crypto: {
+        enabled: boolean;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    };
     database: {
         provider: "memory" | "postgres" | "supabase";
         poolSize: number;
@@ -3639,6 +3814,10 @@ declare const PlatformConfigSchema: z.ZodObject<{
         };
     };
 }, {
+    security?: {
+        enforceTls?: boolean | undefined;
+        tlsWarnOnly?: boolean | undefined;
+    } | undefined;
     email?: {
         provider?: "console" | "smtp" | "memory" | "resend" | undefined;
         password?: string | undefined;
@@ -3651,6 +3830,11 @@ declare const PlatformConfigSchema: z.ZodObject<{
         replyTo?: string | undefined;
         rateLimitPerSecond?: number | undefined;
     } | undefined;
+    crypto?: {
+        enabled?: boolean | undefined;
+        masterKey?: string | undefined;
+        hmacKey?: string | undefined;
+    } | undefined;
     database?: {
         provider?: "memory" | "postgres" | "supabase" | undefined;
         url?: string | undefined;
@@ -3798,6 +3982,8 @@ type QueueConfig = z.infer<typeof QueueConfigSchema>;
 type ResilienceConfig = z.infer<typeof ResilienceConfigSchema>;
 type ObservabilityConfig = z.infer<typeof ObservabilityConfigSchema>;
 type MiddlewareConfig = z.infer<typeof MiddlewareConfigSchema>;
+type CryptoConfig = z.infer<typeof CryptoConfigSchema>;
+type SecurityConfig = z.infer<typeof SecurityConfigSchema>;
 /**
  * Load configuration from environment variables
  */
@@ -4034,4 +4220,4 @@ declare class ConsoleEmail implements IEmail {
     private formatAddresses;
 }
 
-export { type RAGDocument as $, type AIConfig as A, type AIChatRequest as B, ConsoleEmail as C, type AIChatResponse as D, EnvSecrets as E, type AIStreamChunk as F, type AIStreamCallback as G, type AICompletionRequest as H, type IPlatform as I, type Job as J, type AICompletionResponse as K, type AIEmbeddingRequest as L, MemoryDatabase as M, NoopLogger as N, type AIEmbeddingResponse as O, type PlatformHealthStatus as P, type QueryResult as Q, type RepeatOptions as R, type StorageFile as S, type AIModelConfig as T, type UploadOptions as U, type AIModelType as V, type AIProvider as W, type IRAG as X, type RAGConfig as Y, type CreateCollectionOptions as Z, type RAGCollection as _, MemoryCache as a, type EmailAddress as a$, type IngestionOptions as a0, type BulkIngestionResult as a1, type IngestionResult as a2, type DocumentStatus as a3, type RAGChunk as a4, type RAGSearchQuery as a5, type RAGSearchResponse as a6, type RAGSearchResult as a7, type ContextAssemblyConfig as a8, type AssembledContext as a9, type AIToolCall as aA, type AITool as aB, type AIChatChoice as aC, type AIFinishReason as aD, type AIUsageInfo as aE, type RoutingStrategy as aF, type AIRouterConfig as aG, type AIErrorCode as aH, type AIError as aI, MemoryRAG as aJ, ChunkingPresets as aK, type ChunkingStrategy as aL, type ChunkingConfig as aM, type SearchMode as aN, type RAGFilter as aO, type RAGPipelineStep as aP, createPlatformAsync as aQ, createScopedMetrics as aR, MemoryTracing as aS, NoopTracing as aT, type ITracing as aU, type ISpan as aV, type SpanContext as aW, type SpanOptions as aX, type SpanStatus as aY, type SpanKind as aZ, type TracingConfig as a_, type RAGPipeline as aa, type ICacheOptions as ab, type JobResult as ac, type JobContext as ad, type JobEvent as ae, type QueueStats as af, type BackoffOptions as ag, type LogLevel as ah, type LogMeta as ai, type LogEntry as aj, type LoggerConfig as ak, type MetricTags as al, type HistogramStats as am, type TimingStats as an, type Secret as ao, type SecretMetadata as ap, type GetSecretOptions as aq, type SetSecretOptions as ar, type RotateSecretOptions as as, type RotationResult as at, createAIError as au, isAIError as av, AIErrorMessages as aw, MemoryAI as ax, type AIRole as ay, type AIMessage as az, MemoryStorage as b, type EmailAttachment as b0, calculateBackoff as b1, generateJobId as b2, type SpanStatusCode as b3, type SpanEvent as b4, DatabaseProviderSchema as b5, CacheProviderSchema as b6, StorageProviderSchema as b7, EmailProviderSchema as b8, QueueProviderSchema as b9, type EmailConfig as bA, type QueueConfig as bB, type ResilienceConfig as bC, type ObservabilityConfig as bD, type MiddlewareConfig as bE, loadConfig as bF, validateConfig as bG, safeValidateConfig as bH, getDefaultConfig as bI, TracingProviderSchema as ba, LogLevelSchema as bb, AIProviderSchema as bc, RAGProviderSchema as bd, DatabaseConfigSchema as be, CacheConfigSchema as bf, StorageConfigSchema as bg, EmailConfigSchema as bh, QueueConfigSchema as bi, AIConfigSchema as bj, RAGConfigSchema as bk, RetryConfigSchema as bl, CircuitBreakerConfigSchema as bm, TimeoutConfigSchema as bn, BulkheadConfigSchema as bo, ResilienceConfigSchema as bp, LoggingConfigSchema as bq, MetricsConfigSchema as br, TracingConfigSchema as bs, ObservabilityConfigSchema as bt, MiddlewareConfigSchema as bu, PlatformConfigSchema as bv, type PlatformConfig as bw, type DatabaseConfig as bx, type CacheConfig as by, type StorageConfig as bz, MemoryEmail as c, MemoryQueue as d, type IDatabase as e, MemorySecrets as f, createPlatform as g, ConsoleLogger as h, MemoryMetrics as i, NoopMetrics as j, type IQueryBuilder as k, type ICache as l, type IStorage as m, type IEmail as n, type IQueue as o, type ILogger as p, type IMetrics as q, type ISecrets as r, type JobOptions as s, type EmailMessage as t, type MetricsSummary as u, type EmailResult as v, type JobState as w, type JobEventType as x, type JobEventHandler as y, type IAI as z };
+export { type AIModelType as $, type JobState as A, type JobEventType as B, ConsoleEmail as C, type DeterministicEncryptedField as D, EnvSecrets as E, type JobEventHandler as F, type IAI as G, type AIConfig as H, type IPlatform as I, type Job as J, type KeyRotationResult as K, type AIChatRequest as L, MemoryDatabase as M, NoopLogger as N, type AIChatResponse as O, type PlatformHealthStatus as P, type QueryResult as Q, type RepeatOptions as R, type StorageFile as S, type AIStreamChunk as T, type UploadOptions as U, type AIStreamCallback as V, type AICompletionRequest as W, type AICompletionResponse as X, type AIEmbeddingRequest as Y, type AIEmbeddingResponse as Z, type AIModelConfig as _, MemoryCache as a, NoopTracing as a$, type AIProvider as a0, type IRAG as a1, type RAGConfig as a2, type CreateCollectionOptions as a3, type RAGCollection as a4, type RAGDocument as a5, type IngestionOptions as a6, type BulkIngestionResult as a7, type IngestionResult as a8, type DocumentStatus as a9, createAIError as aA, isAIError as aB, AIErrorMessages as aC, MemoryAI as aD, type AIRole as aE, type AIMessage as aF, type AIToolCall as aG, type AITool as aH, type AIChatChoice as aI, type AIFinishReason as aJ, type AIUsageInfo as aK, type RoutingStrategy as aL, type AIRouterConfig as aM, type AIErrorCode as aN, type AIError as aO, MemoryRAG as aP, ChunkingPresets as aQ, type ChunkingStrategy as aR, type ChunkingConfig as aS, type SearchMode as aT, type RAGFilter as aU, type RAGPipelineStep as aV, type CryptoKeyStatus as aW, type CryptoAlgorithm as aX, createPlatformAsync as aY, createScopedMetrics as aZ, MemoryTracing as a_, type RAGChunk as aa, type RAGSearchQuery as ab, type RAGSearchResponse as ac, type RAGSearchResult as ad, type ContextAssemblyConfig as ae, type AssembledContext as af, type RAGPipeline as ag, type ICacheOptions as ah, type JobResult as ai, type JobContext as aj, type JobEvent as ak, type QueueStats as al, type BackoffOptions as am, type LogLevel as an, type LogMeta as ao, type LogEntry as ap, type LoggerConfig as aq, type MetricTags as ar, type HistogramStats as as, type TimingStats as at, type Secret as au, type SecretMetadata as av, type GetSecretOptions as aw, type SetSecretOptions as ax, type RotateSecretOptions as ay, type RotationResult as az, MemoryStorage as b, type ITracing as b0, type ISpan as b1, type SpanContext as b2, type SpanOptions as b3, type SpanStatus as b4, type SpanKind as b5, type TracingConfig as b6, type EmailAddress as b7, type EmailAttachment as b8, calculateBackoff as b9, LoggingConfigSchema as bA, MetricsConfigSchema as bB, TracingConfigSchema as bC, ObservabilityConfigSchema as bD, MiddlewareConfigSchema as bE, PlatformConfigSchema as bF, type PlatformConfig as bG, type DatabaseConfig as bH, type CacheConfig as bI, type StorageConfig as bJ, type EmailConfig as bK, type QueueConfig as bL, type ResilienceConfig as bM, type ObservabilityConfig as bN, type MiddlewareConfig as bO, type CryptoConfig as bP, type SecurityConfig as bQ, loadConfig as bR, validateConfig as bS, safeValidateConfig as bT, getDefaultConfig as bU, generateJobId as ba, type SpanStatusCode as bb, type SpanEvent as bc, DatabaseProviderSchema as bd, CacheProviderSchema as be, StorageProviderSchema as bf, EmailProviderSchema as bg, QueueProviderSchema as bh, TracingProviderSchema as bi, LogLevelSchema as bj, AIProviderSchema as bk, RAGProviderSchema as bl, DatabaseConfigSchema as bm, CacheConfigSchema as bn, StorageConfigSchema as bo, EmailConfigSchema as bp, QueueConfigSchema as bq, AIConfigSchema as br, RAGConfigSchema as bs, CryptoConfigSchema as bt, SecurityConfigSchema as bu, RetryConfigSchema as bv, CircuitBreakerConfigSchema as bw, TimeoutConfigSchema as bx, BulkheadConfigSchema as by, ResilienceConfigSchema as bz, MemoryEmail as c, MemoryQueue as d, type IDatabase as e, MemorySecrets as f, createPlatform as g, ConsoleLogger as h, MemoryMetrics as i, NoopMetrics as j, type IQueryBuilder as k, type ICache as l, type IStorage as m, type IEmail as n, type IQueue as o, type ILogger as p, type IMetrics as q, type ISecrets as r, type JobOptions as s, type EmailMessage as t, type MetricsSummary as u, type ICrypto as v, type EncryptOptions as w, type EncryptedField as x, type CryptoKeyMetadata as y, type EmailResult as z };