@zintrust/core 0.1.16 → 0.1.18

package/README.md

@@ -16,7 +16,7 @@ cd my-app
 zin add db:sqlite
 
 # Start development
-npm run dev
+zin start
 ```
 
 Your API is now running at `http://localhost:7777`
@@ -169,7 +169,7 @@ export function registerRoutes(app: Application): void {
 ### 3. Run Your API
 
 ```bash
-npm run dev
+zin start
 ```
 
 Test it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/public/index.html

@@ -366,7 +366,7 @@
             >
             <a
               class="hover:text-slate-900 dark:hover:text-white"
-              href="https://linkedin.com/company/zintrust"
+              href="https://linkedin.com/company/zintrustjs"
               target="_blank"
               >LinkedIn</a
             >

package/src/cli/PromptHelper.js

@@ -63,7 +63,7 @@ export const PromptHelper = Object.freeze({
     /**
      * Ask for port number
      */
-    async port(defaultPort = 3000, interactive = true) {
+    async port(defaultPort = 7777, interactive = true) {
         if (!interactive) {
             return defaultPort;
         }

package/src/cli/commands/NewCommand.js

@@ -54,7 +54,7 @@ const getProjectDefaults = (name, options) => {
     const database = getStringOption(options, 'database', 'sqlite');
     const portRaw = getStringOption(options, 'port', '7777');
     const portParsed = Number.parseInt(portRaw, 10);
-    const port = Number.isFinite(portParsed) && portParsed > 0 ? portParsed : 3000;
+    const port = Number.isFinite(portParsed) && portParsed > 0 ? portParsed : 7777;
     const author = getStringOption(options, 'author', '');
     const description = getStringOption(options, 'description', `A new Zintrust project: ${name}`);
     const interactive = getBooleanOption(options, 'interactive', true);

package/src/cli/config/ConfigSchema.js

@@ -18,7 +18,7 @@ export const DEFAULT_CONFIG = Object.freeze({
         logging: false,
     },
     server: {
-        port: 3000,
+        port: 7777,
         host: '0.0.0.0',
         environment: 'development',
         debug: false,

package/src/cli/scaffolding/ProjectScaffolder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AAwaD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AA0ID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}
+{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AAsfD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AA0ID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}

package/src/cli/scaffolding/ProjectScaffolder.js

@@ -87,7 +87,7 @@ const createProjectConfigFile = (projectPath, variables) => {
                 connection: variables['database'] ?? 'sqlite',
             },
             server: {
-                port: variables['port'] ?? 3000,
+                port: variables['port'] ?? 7777,
             },
         };
         fs.writeFileSync(fullPath, JSON.stringify(config, null, 2));
@@ -97,18 +97,96 @@ const createProjectConfigFile = (projectPath, variables) => {
         return false;
     }
 };
+const stripEnvInlineComment = (value) => {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        if (!inSingle && !inDouble && ch === '#') {
+            const prev = value[i - 1];
+            if (prev === undefined || prev === ' ' || prev === '\t') {
+                return value.slice(0, i).trimEnd();
+            }
+        }
+    }
+    return value;
+};
+const backfillEnvDefaults = (envPath, defaults) => {
+    const raw = fs.readFileSync(envPath, 'utf8');
+    const lines = raw.split(/\r?\n/);
+    const seen = new Set();
+    const filled = new Set();
+    const out = lines.map((line) => {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            return line;
+        const withoutExport = trimmed.startsWith('export ') ? trimmed.slice('export '.length) : trimmed;
+        const eq = withoutExport.indexOf('=');
+        if (eq <= 0)
+            return line;
+        const key = withoutExport.slice(0, eq).trim();
+        if (key === '')
+            return line;
+        if (!Object.hasOwn(defaults, key))
+            return line;
+        if (seen.has(key))
+            return line;
+        seen.add(key);
+        const rhs = withoutExport.slice(eq + 1);
+        const withoutComment = stripEnvInlineComment(rhs);
+        const value = withoutComment.trim();
+        if (value !== '')
+            return line;
+        filled.add(key);
+        return `${key}=${defaults[key]}`;
+    });
+    const missingKeys = Object.keys(defaults).filter((k) => !seen.has(k));
+    if (missingKeys.length > 0) {
+        out.push(...missingKeys.map((k) => `${k}=${defaults[k]}`));
+    }
+    // Avoid rewriting if nothing changed.
+    if (filled.size === 0 && missingKeys.length === 0)
+        return;
+    fs.writeFileSync(envPath, out.join('\n') + (out.at(-1) === '' ? '' : '\n'));
+};
+const buildDatabaseEnvLines = (database) => {
+    if (database === 'postgresql' || database === 'postgres') {
+        return [
+            'DB_HOST=localhost',
+            'DB_PORT=5432',
+            'DB_DATABASE=zintrust',
+            'DB_USERNAME=postgres',
+            'DB_PASSWORD=',
+        ];
+    }
+    if (database === 'sqlite') {
+        // Provide both DB_DATABASE (used by the framework) and DB_PATH (common alias)
+        return ['DB_DATABASE=./database.sqlite', 'DB_PATH=./database.sqlite'];
+    }
+    return [];
+};
 const createEnvFile = (projectPath, variables) => {
     try {
         if (!fs.existsSync(projectPath)) {
             fs.mkdirSync(projectPath, { recursive: true });
         }
         const fullPath = path.join(projectPath, '.env');
-        // If the template already produced an .env, do not overwrite it here.
+        // If an .env already exists (e.g., from a template), do not overwrite user values.
+        // But we *do* backfill safe defaults for common bootstrap keys when missing/blank.
         if (fs.existsSync(fullPath)) {
+            backfillEnvDefaults(fullPath, {
+                HOST: 'localhost',
+                PORT: String(Number(variables['port'] ?? 7777)),
+                LOG_LEVEL: 'debug',
+            });
             return true;
         }
         const name = typeof variables['projectName'] === 'string' ? variables['projectName'] : 'zintrust-app';
-        const port = Number(variables['port'] ?? 3000);
+        const port = Number(variables['port'] ?? 7777);
         const database = typeof variables['database'] === 'string' ? variables['database'] : 'sqlite';
         // Generate a secure APP_KEY (32 bytes = 256-bit, base64 encoded)
         const appKeyBytes = randomBytes(32);
@@ -125,22 +203,7 @@ const createEnvFile = (projectPath, variables) => {
             `APP_KEY=${appKey}`,
             `DB_CONNECTION=${database}`,
         ];
-        const dbLines = (() => {
-            if (database === 'postgresql' || database === 'postgres') {
-                return [
-                    'DB_HOST=localhost',
-                    'DB_PORT=5432',
-                    'DB_DATABASE=zintrust',
-                    'DB_USERNAME=postgres',
-                    'DB_PASSWORD=',
-                ];
-            }
-            if (database === 'sqlite') {
-                // Provide both DB_DATABASE (used by the framework) and DB_PATH (common alias)
-                return ['DB_DATABASE=./database.sqlite', 'DB_PATH=./database.sqlite'];
-            }
-            return [];
-        })();
+        const dbLines = buildDatabaseEnvLines(database);
         const placeholderLines = [
             '',
             '# Logging',
@@ -152,7 +215,8 @@ const createEnvFile = (projectPath, variables) => {
             'JWT_SECRET=',
             'JWT_EXPIRES_IN=1h',
             'CSRF_SECRET=',
-            'ENCRYPTION_KEY=',
+            'ENCRYPTION_CIPHER=aes-256-cbc',
+            'APP_PREVIOUS_KEYS=',
             '',
             '# Cache / Queue',
             'CACHE_DRIVER=memory',
@@ -244,11 +308,15 @@ const loadTemplateFiles = (templateDir) => {
         if (relPath === 'template.json')
             return false;
         const normalized = normalizeRelPath(relPath);
+        // Project `.env` is generated by createEnvFile() so it can set defaults and create a secure APP_KEY.
+        // Some templates ship `.env.tpl` (which would become `.env`), but that file is intentionally ignored.
+        const outputRel = normalizeRelPath(getOutputRelPath(relPath));
+        if (outputRel === '.env')
+            return false;
         if (!normalized.startsWith('config/'))
             return true;
         // Starter apps should only ship app-level config modules.
         // Core/framework config internals (e.g. config/logging/*) remain core-owned.
-        const outputRel = normalizeRelPath(getOutputRelPath(relPath));
         return allowedConfigFiles.has(outputRel);
     };
     const readUtf8FileOrUndefined = (absPath) => {
@@ -423,7 +491,7 @@ const prepareContext = (state, options) => {
         projectSlug: options.name,
         author: options.author ?? 'Your Name',
         description: options.description ?? '',
-        port: options.port ?? 3000,
+        port: options.port ?? 7777,
         database: options.database ?? 'sqlite',
         template: state.templateName,
         migrationTimestamp,

package/src/config/env.d.ts

@@ -14,6 +14,7 @@ export declare const Env: Readonly<{
     HOST: string;
     APP_NAME: string;
     APP_KEY: string;
+    APP_PREVIOUS_KEYS: string;
     DB_CONNECTION: string;
     DB_HOST: string;
     DB_PORT: number;
@@ -55,6 +56,7 @@ export declare const Env: Readonly<{
     ENABLE_MICROSERVICES: boolean;
     TOKEN_TTL: number;
     TOKEN_LENGTH: number;
+    ENCRYPTION_CIPHER: string;
     ENVIRONMENT: string;
     REQUEST_TIMEOUT: number;
     MAX_BODY_SIZE: number;

package/src/config/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/config/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+CH,eAAO,MAAM,GAAG;eA/BE,MAAM,iBAAiB,MAAM,KAAG,MAAM;kBAMnC,MAAM,iBAAiB,MAAM,KAAG,MAAM;mBASrC,MAAM,iBAAiB,OAAO,KAAG,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAgGP,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO;;;;;;;;;EAkCxF,CAAC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/config/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+CH,eAAO,MAAM,GAAG;eA/BE,MAAM,iBAAiB,MAAM,KAAG,MAAM;kBAMnC,MAAM,iBAAiB,MAAM,KAAG,MAAM;mBASrC,MAAM,iBAAiB,OAAO,KAAG,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAqGP,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO;;;;;;;;;EAkCxF,CAAC"}

package/src/config/env.js

@@ -60,6 +60,8 @@ export const Env = Object.freeze({
     HOST: get('HOST', 'localhost'),
     APP_NAME: get('APP_NAME', 'ZinTrust'),
     APP_KEY: get('APP_KEY', ''),
+    // Optional key rotation support (comma-separated or JSON array of keys)
+    APP_PREVIOUS_KEYS: get('APP_PREVIOUS_KEYS', ''),
     // Database
     DB_CONNECTION: get('DB_CONNECTION', 'sqlite'),
     DB_HOST: get('DB_HOST', 'localhost'),
@@ -110,6 +112,8 @@ export const Env = Object.freeze({
     ENABLE_MICROSERVICES: getBool('ENABLE_MICROSERVICES', false),
     TOKEN_TTL: getInt('TOKEN_TTL', 3600000),
     TOKEN_LENGTH: getInt('TOKEN_LENGTH', 32),
+    // Encryption interop
+    ENCRYPTION_CIPHER: get('ENCRYPTION_CIPHER', ''),
     // Deployment
     ENVIRONMENT: get('ENVIRONMENT', 'development'),
     REQUEST_TIMEOUT: getInt('REQUEST_TIMEOUT', 30000),

package/src/config/index.d.ts

@@ -139,6 +139,9 @@ export declare const config: Readonly<{
             readonly cookieSameSite: "strict" | "lax" | "none";
         };
         readonly encryption: {
+            readonly cipher: string;
+            readonly appKey: string;
+            readonly appPreviousKeys: string;
             readonly algorithm: string;
             readonly key: string;
         };

package/src/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWR,CAAC;AAEZ,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWR,CAAC;AAEZ,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC"}

package/src/config/security.d.ts

@@ -9,7 +9,7 @@
  * Security keys can be configured per domain:
  * - APP_KEY: Default encryption key for all operations (auto-generated)
  * - API_KEY_SECRET: Optional API key authentication (if API_KEY_ENABLED=true)
- * - ENCRYPTION_KEY: Optional separate encryption key (overrides APP_KEY if set)
+ * - ENCRYPTION_CIPHER: Cipher for encrypted envelope interoperability
  * - JWT_SECRET: JWT token signing key
  *
  * Developers can use a single APP_KEY or configure separate keys for different
@@ -44,6 +44,9 @@ export declare const securityConfig: Readonly<{
      * Encryption
      */
     readonly encryption: {
+        readonly cipher: string;
+        readonly appKey: string;
+        readonly appPreviousKeys: string;
         readonly algorithm: string;
         readonly key: string;
     };

package/src/config/security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../src/config/security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA+IH,eAAO,MAAM,cAAc;IAtHzB;;OAEG;;;yBAGa,MAAM;4BAQ4B,OAAO,GAAG,OAAO,GAAG,OAAO;;;;;;IAO7E;;OAEG;;;;;;;;iCAQ6D,QAAQ,GAAG,KAAK,GAAG,MAAM;;IAGzF;;OAEG;;;;;IAMH;;OAEG;;;;;;IAOH;;OAEG;;;;;;;;;;IAWH;;OAEG;;;;;;;IAQH;;OAEG;;;;;IAMH;;OAEG;;;;;;;;;;IAWH;;OAEG;;;;;;;2BAOmD,QAAQ,GAAG,KAAK,GAAG,MAAM;;IAG/E;;OAEG;;;;;;;;EAUyD,CAAC"}
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../src/config/security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyJH,eAAO,MAAM,cAAc;IAhIzB;;OAEG;;;yBAGa,MAAM;4BAQ4B,OAAO,GAAG,OAAO,GAAG,OAAO;;;;;;IAO7E;;OAEG;;;;;;;;iCAQ6D,QAAQ,GAAG,KAAK,GAAG,MAAM;;IAGzF;;OAEG;;;;;;;;IAgBH;;OAEG;;;;;;IAOH;;OAEG;;;;;;;;;;IAWH;;OAEG;;;;;;;IAQH;;OAEG;;;;;IAMH;;OAEG;;;;;;;;;;IAWH;;OAEG;;;;;;;2BAOmD,QAAQ,GAAG,KAAK,GAAG,MAAM;;IAG/E;;OAEG;;;;;;;;EAUyD,CAAC"}

package/src/config/security.js

@@ -9,7 +9,7 @@
  * Security keys can be configured per domain:
  * - APP_KEY: Default encryption key for all operations (auto-generated)
  * - API_KEY_SECRET: Optional API key authentication (if API_KEY_ENABLED=true)
- * - ENCRYPTION_KEY: Optional separate encryption key (overrides APP_KEY if set)
+ * - ENCRYPTION_CIPHER: Cipher for encrypted envelope interoperability
  * - JWT_SECRET: JWT token signing key
  *
  * Developers can use a single APP_KEY or configure separate keys for different
@@ -70,6 +70,14 @@ const securityConfigObj = {
      * Encryption
      */
     encryption: {
+        // Required for framework-compatible encrypted payloads.
+        // Supported values: aes-256-cbc | aes-256-gcm (case-insensitive)
+        cipher: Env.get('ENCRYPTION_CIPHER', ''),
+        // Primary key used for encryption interoperability (framework-compatible envelopes).
+        // APP_KEY supports both `base64:...` and raw base64.
+        appKey: Env.get('APP_KEY', ''),
+        appPreviousKeys: Env.get('APP_PREVIOUS_KEYS', ''),
+        // Back-compat fields (not used by EncryptedEnvelope)
         algorithm: Env.get('ENCRYPTION_ALGORITHM', 'aes-256-cbc'),
         key: Env.get('ENCRYPTION_KEY', 'your-encryption-key'),
     },

package/src/features/Queue.d.ts

@@ -12,7 +12,7 @@ export declare const Queue: Readonly<{
     /**
      * Add a job to the queue
      */
-    add<T>(data: T): Promise<string>;
+    add<T>(data: T): string;
     /**
      * Process jobs (Placeholder)
      */

package/src/features/Queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Queue.d.ts","sourceRoot":"","sources":["../../../src/features/Queue.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK;UACJ,QAAQ,EAAE;IAEtB;;OAEG;QACO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IActC;;OAEG;qBACoB,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;EAMvE,CAAC"}
+{"version":3,"file":"Queue.d.ts","sourceRoot":"","sources":["../../../src/features/Queue.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK;UACJ,QAAQ,EAAE;IAEtB;;OAEG;QACC,CAAC,QAAQ,CAAC,GAAG,MAAM;IAcvB;;OAEG;qBACoB,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;EAMvE,CAAC"}

package/src/features/Queue.js

@@ -10,7 +10,7 @@ export const Queue = Object.freeze({
     /**
      * Add a job to the queue
      */
-    async add(data) {
+    add(data) {
         const id = generateSecureJobId();
         const job = {
             id,

package/src/index.d.ts

@@ -98,6 +98,7 @@ export { Schema, Validator } from './validation/Validator';
 export type { ISchema, SchemaType } from './validation/Validator';
 export { CsrfTokenManager } from './security/CsrfTokenManager';
 export type { CsrfTokenData, CsrfTokenManagerType, ICsrfTokenManager, } from './security/CsrfTokenManager';
+export { EncryptedEnvelope } from './security/EncryptedEnvelope';
 export { Encryptor } from './security/Encryptor';
 export { Hash } from './security/Hash';
 export { JwtManager } from './security/JwtManager';

package/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/src/index.js

@@ -50,6 +50,7 @@ export { ValidationError } from './validation/ValidationError.js';
 export { Schema, Validator } from './validation/Validator.js';
 // Security
 export { CsrfTokenManager } from './security/CsrfTokenManager.js';
+export { EncryptedEnvelope } from './security/EncryptedEnvelope.js';
 export { Encryptor } from './security/Encryptor.js';
 export { Hash } from './security/Hash.js';
 export { JwtManager } from './security/JwtManager.js';

package/src/middleware/RateLimiter.d.ts

@@ -12,8 +12,43 @@ export interface RateLimitOptions {
     statusCode?: number;
     headers?: boolean;
     keyGenerator?: (req: IRequest) => string;
+    /**
+     * Optional store selection for this middleware instance.
+     * - 'memory' uses an in-process Map (default)
+     * - 'redis' uses Cache.store('redis')
+     * - 'kv' uses Cache.store('kv')
+     * - 'db' uses Cache.store('mongodb')
+     */
+    store?: RateLimitStoreName;
 }
+export type RateLimitStoreName = 'memory' | 'redis' | 'kv' | 'db';
 export declare const RateLimiter: Readonly<{
+    /**
+     * Configure the store used by the programmatic API (attempt/tooManyAttempts/till/clear).
+     * Defaults to 'memory'.
+     */
+    configure(config?: {
+        store?: RateLimitStoreName;
+    }): void;
+    /**
+     * Attempt to perform an action.
+     *
+     * Returns true if allowed (and records the hit), false if rate limited.
+     */
+    attempt(key: string, maxAttempts: number, decaySeconds: number): Promise<boolean>;
+    /**
+     * Check if the key is currently rate limited.
+     */
+    tooManyAttempts(key: string, maxAttempts: number): Promise<boolean>;
+    /**
+     * Seconds until the key is available again.
+     * Returns 0 if not rate limited.
+     */
+    till(key: string): Promise<number>;
+    /**
+     * Clear rate limit state for a key.
+     */
+    clear(key: string): Promise<void>;
     /**
      * Create rate limiter middleware
      */

package/src/middleware/RateLimiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/middleware/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAC;CAC1C;AAoBD,eAAO,MAAM,WAAW;IACtB;;OAEG;qBACa,gBAAgB,GAAqB,UAAU;EA4D/D,CAAC"}
+{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/middleware/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAC;IAEzC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;AAyIlE,eAAO,MAAM,WAAW;IACtB;;;OAGG;uBACgB;QAAE,KAAK,CAAC,EAAE,kBAAkB,CAAA;KAAE,GAAG,IAAI;IAKxD;;;;OAIG;iBACgB,MAAM,eAAe,MAAM,gBAAgB,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYvF;;OAEG;yBACwB,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQzE;;;OAGG;cACa,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxC;;OAEG;eACc,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC;;OAEG;qBACa,gBAAgB,GAAqB,UAAU;EAgF/D,CAAC"}

package/src/middleware/RateLimiter.js

@@ -3,7 +3,104 @@
  * Token bucket implementation for request rate limiting
  * Zero-dependency implementation
  */
+import { Cache } from '../cache/Cache.js';
 import { Logger } from '../config/logger.js';
+const createMemoryStore = () => {
+    const entries = new Map();
+    let nextCleanupAt = Date.now() + 60_000;
+    const cleanupExpired = (now) => {
+        if (now < nextCleanupAt)
+            return;
+        for (const [k, state] of entries.entries()) {
+            if (now > state.resetTime)
+                entries.delete(k);
+        }
+        nextCleanupAt = now + 60_000;
+    };
+    return Object.freeze({
+        async get(key) {
+            await Promise.resolve();
+            const now = Date.now();
+            cleanupExpired(now);
+            const state = entries.get(key);
+            if (!state)
+                return null;
+            if (now > state.resetTime) {
+                entries.delete(key);
+                return null;
+            }
+            return { ...state };
+        },
+        async set(key, value) {
+            await Promise.resolve();
+            const now = Date.now();
+            cleanupExpired(now);
+            entries.set(key, { ...value });
+        },
+        async delete(key) {
+            await Promise.resolve();
+            entries.delete(key);
+        },
+    });
+};
+const createCacheStore = (storeName) => {
+    const store = Cache.store(storeName);
+    return Object.freeze({
+        async get(key) {
+            return store.get(key);
+        },
+        async set(key, value, ttlSeconds) {
+            await store.set(key, value, ttlSeconds);
+        },
+        async delete(key) {
+            await store.delete(key);
+        },
+    });
+};
+const normalizeStoreName = (name) => {
+    const raw = String(name ?? '')
+        .trim()
+        .toLowerCase();
+    if (raw === 'redis')
+        return 'redis';
+    if (raw === 'kv')
+        return 'kv';
+    if (raw === 'db' || raw === 'database' || raw === 'mongo' || raw === 'mongodb')
+        return 'db';
+    return 'memory';
+};
+const resolveStore = (name) => {
+    const selected = normalizeStoreName(name ?? process.env['RATE_LIMIT_STORE'] ?? process.env['RATE_LIMIT_DRIVER'] ?? 'memory');
+    if (selected === 'redis')
+        return { storeName: 'redis', store: createCacheStore('redis') };
+    if (selected === 'kv')
+        return { storeName: 'kv', store: createCacheStore('kv') };
+    if (selected === 'db')
+        return { storeName: 'db', store: createCacheStore('mongodb') };
+    return { storeName: 'memory', store: createMemoryStore() };
+};
+let serviceStoreSelection = normalizeStoreName(process.env['RATE_LIMIT_STORE'] ?? process.env['RATE_LIMIT_DRIVER'] ?? 'memory');
+let serviceStore = resolveStore(serviceStoreSelection).store;
+const prefixKey = (purpose, key) => {
+    const prefix = (process.env['RATE_LIMIT_KEY_PREFIX'] ?? 'zintrust:ratelimit:').toString().trim();
+    return `${prefix}${purpose}:${key}`;
+};
+const consume = async (params) => {
+    const now = Date.now();
+    const ttlSeconds = Math.max(1, Math.ceil(params.windowMs / 1000));
+    const existing = await params.store.get(params.key);
+    const state = existing === null || now > existing.resetTime
+        ? { count: 0, resetTime: now + params.windowMs }
+        : existing;
+    const nextCount = state.count + 1;
+    const nextState = { count: nextCount, resetTime: state.resetTime };
+    await params.store.set(params.key, nextState, ttlSeconds);
+    return {
+        count: nextCount,
+        resetTime: nextState.resetTime,
+        allowed: nextCount <= params.max,
+    };
+};
 const DEFAULT_OPTIONS = {
     windowMs: 60 * 1000, // 1 minute
     max: 100, // 100 requests per minute
@@ -15,11 +112,68 @@ const DEFAULT_OPTIONS = {
     },
 };
 export const RateLimiter = Object.freeze({
+    /**
+     * Configure the store used by the programmatic API (attempt/tooManyAttempts/till/clear).
+     * Defaults to 'memory'.
+     */
+    configure(config) {
+        serviceStoreSelection = normalizeStoreName(config?.store);
+        serviceStore = resolveStore(serviceStoreSelection).store;
+    },
+    /**
+     * Attempt to perform an action.
+     *
+     * Returns true if allowed (and records the hit), false if rate limited.
+     */
+    async attempt(key, maxAttempts, decaySeconds) {
+        const windowMs = Math.max(1, Math.floor(decaySeconds * 1000));
+        const namespacedKey = prefixKey('service', key);
+        const out = await consume({
+            store: serviceStore,
+            key: namespacedKey,
+            max: maxAttempts,
+            windowMs,
+        });
+        return out.allowed;
+    },
+    /**
+     * Check if the key is currently rate limited.
+     */
+    async tooManyAttempts(key, maxAttempts) {
+        const now = Date.now();
+        const namespacedKey = prefixKey('service', key);
+        const state = await serviceStore.get(namespacedKey);
+        if (!state || now > state.resetTime)
+            return false;
+        return state.count >= maxAttempts;
+    },
+    /**
+     * Seconds until the key is available again.
+     * Returns 0 if not rate limited.
+     */
+    async till(key) {
+        const now = Date.now();
+        const namespacedKey = prefixKey('service', key);
+        const state = await serviceStore.get(namespacedKey);
+        if (!state || now > state.resetTime)
+            return 0;
+        return Math.max(0, Math.ceil((state.resetTime - now) / 1000));
+    },
+    /**
+     * Clear rate limit state for a key.
+     */
+    async clear(key) {
+        const namespacedKey = prefixKey('service', key);
+        await serviceStore.delete(namespacedKey);
+    },
     /**
      * Create rate limiter middleware
      */
     create(options = DEFAULT_OPTIONS) {
         const config = { ...DEFAULT_OPTIONS, ...options };
+        const { storeName, store } = resolveStore(config.store);
+        const useMemoryInstanceStore = storeName === 'memory';
+        // Middleware store is per-instance (matches prior behavior).
         const clients = new Map();
         // Cleanup to prevent unbounded growth.
         // Done lazily (on requests) to avoid background timers in serverless/test environments.
@@ -27,29 +181,47 @@ export const RateLimiter = Object.freeze({
         const cleanupExpiredClients = (now) => {
             if (now < nextCleanupAt)
                 return;
-            for (const [key, state] of clients.entries()) {
+            for (const [k, state] of clients.entries()) {
                 if (now > state.resetTime) {
-                    clients.delete(key);
+                    clients.delete(k);
                 }
             }
             nextCleanupAt = now + config.windowMs;
         };
-        return async (req, res, next) => {
-            const key = config.keyGenerator ? config.keyGenerator(req) : 'unknown';
-            const now = Date.now();
-            cleanupExpiredClients(now);
+        const getOrInitClient = (key, now) => {
             let client = clients.get(key);
-            // Initialize or reset if window expired
             if (!client || now > client.resetTime) {
-                client = {
-                    count: 0,
-                    resetTime: now + config.windowMs,
-                };
+                client = { count: 0, resetTime: now + config.windowMs };
                 clients.set(key, client);
             }
-            client.count++;
-            const remaining = Math.max(0, config.max - client.count);
-            const resetTime = Math.ceil((client.resetTime - now) / 1000);
+            return client;
+        };
+        return async (req, res, next) => {
+            const key = config.keyGenerator ? config.keyGenerator(req) : 'unknown';
+            const now = Date.now();
+            let count;
+            let resetAt;
+            if (useMemoryInstanceStore) {
+                cleanupExpiredClients(now);
+                const client = getOrInitClient(key, now);
+                client.count++;
+                count = client.count;
+                resetAt = client.resetTime;
+            }
+            else {
+                // Include limiter config to avoid collisions between different middleware instances.
+                const middlewareKey = prefixKey('middleware', `${config.max}:${config.windowMs}:${key}`);
+                const out = await consume({
+                    store,
+                    key: middlewareKey,
+                    max: config.max,
+                    windowMs: config.windowMs,
+                });
+                count = out.count;
+                resetAt = out.resetTime;
+            }
+            const remaining = Math.max(0, config.max - count);
+            const resetTime = Math.ceil((resetAt - now) / 1000);
             // Set headers
             if (config.headers ?? false) {
                 res.setHeader('X-RateLimit-Limit', config.max.toString());
@@ -57,7 +229,7 @@ export const RateLimiter = Object.freeze({
                 res.setHeader('X-RateLimit-Reset', resetTime.toString());
             }
             // Check limit
-            if (client.count > config.max) {
+            if (count > config.max) {
                 Logger.warn(`Rate limit exceeded for IP: ${key}`);
                 res.setStatus(config.statusCode ?? 429);
                 res.json({

package/src/node-singletons/crypto.d.ts

@@ -3,5 +3,5 @@
  * Safe to import in both API and CLI code
  * Exported from node:crypto built-in
  */
-export { createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, } from 'node:crypto';
+export { createCipheriv, createDecipheriv, createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, timingSafeEqual, } from 'node:crypto';
 //# sourceMappingURL=crypto.d.ts.map

package/src/node-singletons/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/node-singletons/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,SAAS,GACV,MAAM,aAAa,CAAC"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/node-singletons/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,SAAS,EACT,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/src/node-singletons/crypto.js

@@ -3,4 +3,4 @@
  * Safe to import in both API and CLI code
  * Exported from node:crypto built-in
  */
-export { createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, } from 'node:crypto';
+export { createCipheriv, createDecipheriv, createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, timingSafeEqual, } from 'node:crypto';

package/src/security/EncryptedEnvelope.d.ts

@@ -0,0 +1,77 @@
+/**
+ * EncryptedEnvelope
+ *
+ * Framework-compatible encrypted payload envelope (PHP-style envelope).
+ *
+ * Format: base64(JSON({ iv, value, mac, tag }))
+ * - iv: base64
+ * - value: base64 ciphertext
+ * - mac: hex string (AES-CBC envelopes)
+ * - tag: base64 auth tag (AES-GCM envelopes)
+ */
+export type EncryptedEnvelopeCipher = 'aes-256-cbc' | 'aes-256-gcm';
+export type EncryptedEnvelopeCipherInput = EncryptedEnvelopeCipher | 'AES-256-CBC' | 'AES-256-GCM';
+export type EncryptedEnvelopePayload = {
+    iv: string;
+    value: string;
+    mac?: string;
+    tag?: string;
+};
+export type EncryptedEnvelopeSerializer<T> = {
+    serialize: (value: T) => string;
+    deserialize: (value: string) => T;
+};
+export type EncryptedEnvelopeKeyring = {
+    primaryKey: Uint8Array;
+    previousKeys: Uint8Array[];
+};
+export type EncryptedEnvelopeEnv = {
+    APP_KEY?: string;
+    APP_PREVIOUS_KEYS?: string;
+    ENCRYPTION_CIPHER?: string;
+};
+export declare const EncryptedEnvelope: Readonly<{
+    normalizeCipher: (cipher: EncryptedEnvelopeCipherInput) => EncryptedEnvelopeCipher;
+    /**
+     * Build a keyring from environment variables.
+     * - Uses APP_KEY
+     * - Supports APP_PREVIOUS_KEYS (comma-separated or JSON array)
+     */
+    keyringFromEnv(env?: EncryptedEnvelopeEnv): EncryptedEnvelopeKeyring;
+    /**
+     * Encrypt a UTF-8 string and return a framework-compatible base64(JSON) envelope.
+     */
+    encryptString(plaintext: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+    }): string;
+    /**
+     * Decrypt a framework-compatible base64(JSON) envelope to a UTF-8 string.
+     * Tries the primary key first, then previous keys.
+     */
+    decryptString(encrypted: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        previousKeys?: string[];
+    }): string;
+    /**
+     * Encrypt arbitrary values using a caller-provided serializer.
+     * This supports encrypted payloads for frameworks that store serialized values.
+     */
+    encrypt<T>(value: T, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        serializer: EncryptedEnvelopeSerializer<T>;
+    }): string;
+    /**
+     * Decrypt into an arbitrary value using a caller-provided serializer.
+     */
+    decrypt<T>(encrypted: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        previousKeys?: string[];
+        serializer: EncryptedEnvelopeSerializer<T>;
+    }): T;
+}>;
+export default EncryptedEnvelope;
+//# sourceMappingURL=EncryptedEnvelope.d.ts.map

package/src/security/EncryptedEnvelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptedEnvelope.d.ts","sourceRoot":"","sources":["../../../src/security/EncryptedEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,MAAM,MAAM,uBAAuB,GAAG,aAAa,GAAG,aAAa,CAAC;AACpE,MAAM,MAAM,4BAA4B,GAAG,uBAAuB,GAAG,aAAa,GAAG,aAAa,CAAC;AAEnG,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAChC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,UAAU,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AA6LF,eAAO,MAAM,iBAAiB;8BA3LG,4BAA4B,KAAG,uBAAuB;IA8LrF;;;;OAIG;yBAEI,oBAAoB,GACxB,wBAAwB;IAe3B;;OAEG;6BAEU,MAAM,WACR;QAAE,MAAM,EAAE,4BAA4B,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAC7D,MAAM;IAgCT;;;OAGG;6BAEU,MAAM,WACR;QAAE,MAAM,EAAE,4BAA4B,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GACtF,MAAM;IA0BT;;;OAGG;YACK,CAAC,SACA,CAAC,WACC;QACP,MAAM,EAAE,4BAA4B,CAAC;QACrC,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC;KAC5C,GACA,MAAM;IAQT;;OAEG;YACK,CAAC,aACI,MAAM,WACR;QACP,MAAM,EAAE,4BAA4B,CAAC;QACrC,GAAG,EAAE,MAAM,CAAC;QACZ,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,UAAU,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC;KAC5C,GACA,CAAC;EASJ,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/security/EncryptedEnvelope.js

@@ -0,0 +1,256 @@
+/**
+ * EncryptedEnvelope
+ *
+ * Framework-compatible encrypted payload envelope (PHP-style envelope).
+ *
+ * Format: base64(JSON({ iv, value, mac, tag }))
+ * - iv: base64
+ * - value: base64 ciphertext
+ * - mac: hex string (AES-CBC envelopes)
+ * - tag: base64 auth tag (AES-GCM envelopes)
+ */
+import { Env } from '../config/env.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual, } from '../node-singletons/crypto.js';
+const normalizeCipher = (cipher) => {
+    const normalized = cipher.toLowerCase();
+    if (normalized === 'aes-256-cbc')
+        return 'aes-256-cbc';
+    if (normalized === 'aes-256-gcm')
+        return 'aes-256-gcm';
+    throw ErrorFactory.createValidationError('Unsupported ENCRYPTION_CIPHER', {
+        cipher,
+        supported: ['aes-256-cbc', 'aes-256-gcm'],
+    });
+};
+const normalizeBase64ForCompare = (value) => {
+    const trimmed = value.trim();
+    // Remove base64 padding without regex (avoids any regex backtracking concerns).
+    let end = trimmed.length;
+    while (end > 0 && trimmed.codePointAt(end - 1) === 61) {
+        end -= 1;
+    }
+    return trimmed.slice(0, end);
+};
+const decodeBase64 = (input, label) => {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+    }
+    // Note: Buffer.from(..., 'base64') does not reliably throw on invalid input.
+    // Validate by re-encoding and comparing (ignoring padding).
+    const decoded = Buffer.from(trimmed, 'base64');
+    if (decoded.length === 0) {
+        throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+    }
+    const roundTrip = decoded.toString('base64');
+    if (normalizeBase64ForCompare(roundTrip) !== normalizeBase64ForCompare(trimmed)) {
+        throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+    }
+    return decoded;
+};
+const CIPHER_KEY_BYTES = Object.freeze({
+    'aes-256-cbc': 32,
+    'aes-256-gcm': 32,
+});
+const expectedKeyBytesForCipher = (cipher) => CIPHER_KEY_BYTES[cipher];
+const parseKey = (key, cipher) => {
+    const trimmed = key.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Missing APP_KEY');
+    }
+    const raw = trimmed.startsWith('base64:') ? trimmed.slice('base64:'.length) : trimmed;
+    const bytes = decodeBase64(raw, 'APP_KEY');
+    const expectedBytes = expectedKeyBytesForCipher(cipher);
+    if (bytes.length !== expectedBytes) {
+        throw ErrorFactory.createValidationError('Invalid APP_KEY length for cipher', {
+            cipher,
+            expectedBytes,
+            actualBytes: bytes.length,
+        });
+    }
+    return new Uint8Array(bytes);
+};
+const parsePreviousKeys = (raw, cipher) => {
+    const value = (raw ?? '').trim();
+    if (value.length === 0)
+        return [];
+    const items = (() => {
+        if (value.startsWith('[')) {
+            try {
+                const parsed = JSON.parse(value);
+                if (!Array.isArray(parsed))
+                    return [];
+                return parsed.filter((v) => typeof v === 'string');
+            }
+            catch {
+                return [];
+            }
+        }
+        return value
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    })();
+    return items.map((k) => parseKey(k, cipher));
+};
+const parsePayload = (payload) => {
+    const decoded = Buffer.from(payload, 'base64').toString('utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (not JSON)');
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (not an object)');
+    }
+    const record = parsed;
+    const iv = typeof record['iv'] === 'string' ? record['iv'] : '';
+    const value = typeof record['value'] === 'string' ? record['value'] : '';
+    const mac = typeof record['mac'] === 'string' ? record['mac'] : undefined;
+    const tag = typeof record['tag'] === 'string' ? record['tag'] : undefined;
+    if (iv.length === 0 || value.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (missing iv/value)');
+    }
+    return { iv, value, mac, tag };
+};
+const computeMacHex = (key, ivBase64, valueBase64) => {
+    // Envelope MAC: mac = HMAC-SHA256(iv + value, key), where iv/value are base64 strings.
+    return createHmac('sha256', Buffer.from(key))
+        .update(ivBase64 + valueBase64, 'utf8')
+        .digest('hex');
+};
+const timingSafeEqualsHex = (a, b) => {
+    const aBuf = Buffer.from(a, 'utf8');
+    const bBuf = Buffer.from(b, 'utf8');
+    if (aBuf.length !== bBuf.length)
+        return false;
+    return timingSafeEqual(aBuf, bBuf);
+};
+const ivLengthFor = (cipher) => {
+    // OpenSSL defaults for these ciphers.
+    if (cipher === 'aes-256-gcm')
+        return 12;
+    return 16;
+};
+const decryptWithKey = (payload, cipher, key) => {
+    const iv = decodeBase64(payload.iv, 'iv');
+    const ciphertext = decodeBase64(payload.value, 'value');
+    if (cipher === 'aes-256-cbc') {
+        const expected = payload.mac ?? '';
+        if (expected.length === 0) {
+            throw ErrorFactory.createValidationError('Missing mac for aes-256-cbc envelope');
+        }
+        const actual = computeMacHex(key, payload.iv, payload.value);
+        if (!timingSafeEqualsHex(actual, expected)) {
+            throw ErrorFactory.createSecurityError('Invalid MAC');
+        }
+        const decipher = createDecipheriv('aes-256-cbc', Buffer.from(key), iv);
+        const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return plain.toString('utf8');
+    }
+    const tagB64 = (payload.tag ?? '').trim();
+    if (tagB64.length === 0) {
+        throw ErrorFactory.createValidationError('Missing tag for aes-256-gcm envelope');
+    }
+    const tag = decodeBase64(tagB64, 'tag');
+    const decipher = createDecipheriv('aes-256-gcm', Buffer.from(key), iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return plain.toString('utf8');
+};
+export const EncryptedEnvelope = Object.freeze({
+    normalizeCipher,
+    /**
+     * Build a keyring from environment variables.
+     * - Uses APP_KEY
+     * - Supports APP_PREVIOUS_KEYS (comma-separated or JSON array)
+     */
+    keyringFromEnv(env = Env) {
+        const cipherRaw = (env.ENCRYPTION_CIPHER ?? '').trim();
+        if (cipherRaw.length === 0) {
+            throw ErrorFactory.createConfigError('ENCRYPTION_CIPHER must be set', {
+                key: 'ENCRYPTION_CIPHER',
+            });
+        }
+        const cipher = normalizeCipher(cipherRaw);
+        const primaryKey = parseKey(env.APP_KEY ?? '', cipher);
+        const previousKeys = parsePreviousKeys(env.APP_PREVIOUS_KEYS, cipher);
+        return { primaryKey, previousKeys };
+    },
+    /**
+     * Encrypt a UTF-8 string and return a framework-compatible base64(JSON) envelope.
+     */
+    encryptString(plaintext, options) {
+        const cipher = normalizeCipher(options.cipher);
+        const key = parseKey(options.key, cipher);
+        const iv = randomBytes(ivLengthFor(cipher));
+        if (cipher === 'aes-256-cbc') {
+            const c = createCipheriv('aes-256-cbc', Buffer.from(key), iv);
+            const ciphertext = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+            const ivB64 = iv.toString('base64');
+            const valueB64 = ciphertext.toString('base64');
+            const mac = computeMacHex(key, ivB64, valueB64);
+            const envelope = { iv: ivB64, value: valueB64, mac, tag: '' };
+            return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+        }
+        const c = createCipheriv('aes-256-gcm', Buffer.from(key), iv);
+        const ciphertext = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+        const tag = c.getAuthTag();
+        const envelope = {
+            iv: iv.toString('base64'),
+            value: ciphertext.toString('base64'),
+            mac: '',
+            tag: tag.toString('base64'),
+        };
+        return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+    },
+    /**
+     * Decrypt a framework-compatible base64(JSON) envelope to a UTF-8 string.
+     * Tries the primary key first, then previous keys.
+     */
+    decryptString(encrypted, options) {
+        const cipher = normalizeCipher(options.cipher);
+        const primaryKey = parseKey(options.key, cipher);
+        const previous = (options.previousKeys ?? []).map((k) => parseKey(k, cipher));
+        const payload = parsePayload(encrypted);
+        const keys = [primaryKey, ...previous];
+        let lastError;
+        for (const key of keys) {
+            try {
+                return decryptWithKey(payload, cipher, key);
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw ErrorFactory.createSecurityError('Unable to decrypt encrypted envelope with provided keyring', {
+            cause: lastError instanceof Error ? lastError.message : String(lastError),
+        });
+    },
+    /**
+     * Encrypt arbitrary values using a caller-provided serializer.
+     * This supports encrypted payloads for frameworks that store serialized values.
+     */
+    encrypt(value, options) {
+        const serialized = options.serializer.serialize(value);
+        return EncryptedEnvelope.encryptString(serialized, {
+            cipher: options.cipher,
+            key: options.key,
+        });
+    },
+    /**
+     * Decrypt into an arbitrary value using a caller-provided serializer.
+     */
+    decrypt(encrypted, options) {
+        const serialized = EncryptedEnvelope.decryptString(encrypted, {
+            cipher: options.cipher,
+            key: options.key,
+            previousKeys: options.previousKeys,
+        });
+        return options.serializer.deserialize(serialized);
+    },
+});
+export default EncryptedEnvelope;

package/src/security/StartupSecretValidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StartupSecretValidation.d.ts","sourceRoot":"","sources":["../../../src/security/StartupSecretValidation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,MAAM,4BAA4B,GAAG;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,4BAA4B,EAAE,CAAC;CACxC,CAAC;AA6BF,eAAO,MAAM,uBAAuB;gBACtB,6BAA6B;mBAe1B,IAAI;EAQnB,CAAC;AAEH,eAAe,uBAAuB,CAAC"}
+{"version":3,"file":"StartupSecretValidation.d.ts","sourceRoot":"","sources":["../../../src/security/StartupSecretValidation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,MAAM,4BAA4B,GAAG;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,4BAA4B,EAAE,CAAC;CACxC,CAAC;AA2GF,eAAO,MAAM,uBAAuB;gBACtB,6BAA6B;mBAiB1B,IAAI;EAQnB,CAAC;AAEH,eAAe,uBAAuB,CAAC"}

package/src/security/StartupSecretValidation.js

@@ -5,6 +5,7 @@
  * fails fast and predictably.
  */
 import { appConfig } from '../config/app.js';
+import { Env } from '../config/env.js';
 import { securityConfig } from '../config/security.js';
 import { startupConfig } from '../config/startup.js';
 import { ErrorFactory } from '../exceptions/ZintrustError.js';
@@ -34,6 +35,76 @@ const validateJwtSecret = () => {
         return { key: 'JWT_SECRET', message };
     }
 };
+const normalizeCipher = (raw) => {
+    const value = raw.trim().toLowerCase();
+    if (value === 'aes-256-cbc')
+        return 'aes-256-cbc';
+    if (value === 'aes-256-gcm')
+        return 'aes-256-gcm';
+    return null;
+};
+const parseBase64KeyBytes = (rawKey) => {
+    const base64 = rawKey.startsWith('base64:') ? rawKey.slice('base64:'.length) : rawKey;
+    const decoded = Buffer.from(base64, 'base64');
+    if (decoded.length === 0) {
+        return null;
+    }
+    return decoded.length;
+};
+const validateEncryptionInterop = () => {
+    const errors = [];
+    const cipherRaw = (Env.ENCRYPTION_CIPHER ?? '').trim();
+    if (cipherRaw.length === 0) {
+        errors.push({
+            key: 'ENCRYPTION_CIPHER',
+            message: 'ENCRYPTION_CIPHER must be set (supported: aes-256-cbc, aes-256-gcm)',
+        });
+        return errors;
+    }
+    const cipher = normalizeCipher(cipherRaw);
+    if (cipher === null) {
+        errors.push({
+            key: 'ENCRYPTION_CIPHER',
+            message: 'Unsupported ENCRYPTION_CIPHER (supported: aes-256-cbc, aes-256-gcm)',
+        });
+    }
+    const appKey = (Env.APP_KEY ?? '').trim();
+    if (appKey.length === 0) {
+        errors.push({ key: 'APP_KEY', message: 'APP_KEY must be set for encryption interoperability' });
+        return errors;
+    }
+    const bytes = parseBase64KeyBytes(appKey);
+    if (bytes === null) {
+        errors.push({
+            key: 'APP_KEY',
+            message: 'APP_KEY must be valid base64 (supports base64:... prefix)',
+        });
+        return errors;
+    }
+    // Current supported ciphers are aes-256-*, so require 32-byte keys.
+    if (bytes !== 32) {
+        errors.push({
+            key: 'APP_KEY',
+            message: `APP_KEY must decode to 32 bytes for ${cipherRaw}`,
+        });
+    }
+    const prev = (Env.APP_PREVIOUS_KEYS ?? '').trim();
+    if (prev.length > 0 && prev.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(prev);
+            if (!Array.isArray(parsed) || !parsed.every((v) => typeof v === 'string')) {
+                errors.push({
+                    key: 'APP_PREVIOUS_KEYS',
+                    message: 'APP_PREVIOUS_KEYS JSON must be an array of strings',
+                });
+            }
+        }
+        catch {
+            errors.push({ key: 'APP_PREVIOUS_KEYS', message: 'APP_PREVIOUS_KEYS must be valid JSON' });
+        }
+    }
+    return errors;
+};
 export const StartupSecretValidation = Object.freeze({
     validate() {
         if (!startupConfig.validateSecrets)
@@ -47,6 +118,7 @@ export const StartupSecretValidation = Object.freeze({
         const apiKeyError = validateApiKeySecret();
         if (apiKeyError !== null)
             errors.push(apiKeyError);
+        errors.push(...validateEncryptionInterop());
         return { valid: errors.length === 0, errors };
     },
     assertValid() {

package/src/templates/features/Queue.ts.tpl

@@ -19,7 +19,7 @@ export const Queue = Object.freeze({
   /**
    * Add a job to the queue
    */
-  async add<T>(data: T): Promise<string> {
+  add<T>(data: T): string {
     const id = generateSecureJobId();
     const job: QueueJob = {
       id,

package/src/templates/project/basic/config/env.ts.tpl

@@ -64,6 +64,8 @@ export const Env = Object.freeze({
   HOST: get('HOST', 'localhost'),
   APP_NAME: get('APP_NAME', 'ZinTrust'),
   APP_KEY: get('APP_KEY', ''),
+  // Optional key rotation support (comma-separated or JSON array of keys)
+  APP_PREVIOUS_KEYS: get('APP_PREVIOUS_KEYS', ''),
 
   // Database
   DB_CONNECTION: get('DB_CONNECTION', 'sqlite'),
@@ -124,6 +126,9 @@ export const Env = Object.freeze({
   TOKEN_TTL: getInt('TOKEN_TTL', 3600000),
   TOKEN_LENGTH: getInt('TOKEN_LENGTH', 32),
 
+  // Encryption interop
+  ENCRYPTION_CIPHER: get('ENCRYPTION_CIPHER', ''),
+
   // Deployment
   ENVIRONMENT: get('ENVIRONMENT', 'development'),
   REQUEST_TIMEOUT: getInt('REQUEST_TIMEOUT', 30000),

package/src/templates/project/basic/config/security.ts.tpl

@@ -9,7 +9,7 @@
  * Security keys can be configured per domain:
  * - APP_KEY: Default encryption key for all operations (auto-generated)
  * - API_KEY_SECRET: Optional API key authentication (if API_KEY_ENABLED=true)
- * - ENCRYPTION_KEY: Optional separate encryption key (overrides APP_KEY if set)
+ * - ENCRYPTION_CIPHER: Cipher for encrypted envelope interoperability
  * - JWT_SECRET: JWT token signing key
  *
  * Developers can use a single APP_KEY or configure separate keys for different
@@ -76,6 +76,16 @@ const securityConfigObj = {
    * Encryption
    */
   encryption: {
+    // Required for framework-compatible encrypted payloads.
+    // Supported values: aes-256-cbc | aes-256-gcm (case-insensitive)
+    cipher: Env.get('ENCRYPTION_CIPHER', ''),
+
+    // Primary key used for encryption interoperability (framework-compatible envelopes).
+    // APP_KEY supports both `base64:...` and raw base64.
+    appKey: Env.get('APP_KEY', ''),
+    appPreviousKeys: Env.get('APP_PREVIOUS_KEYS', ''),
+
+    // Back-compat fields (not used by EncryptedEnvelope)
     algorithm: Env.get('ENCRYPTION_ALGORITHM', 'aes-256-cbc'),
     key: Env.get('ENCRYPTION_KEY', 'your-encryption-key'),
   },