@zintrust/core 0.1.15 → 0.1.17

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/PasswordResetTokenBroker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Password Reset Token Broker
+ *
+ * Framework-agnostic, storage-pluggable password reset token flow.
+ *
+ * - Generates high-entropy tokens for a given identifier (usually an email).
+ * - Stores only a SHA-256 hash of the token (one active token per identifier).
+ * - Supports verification and one-time consumption.
+ */
+export interface PasswordResetTokenRecord {
+    identifier: string;
+    tokenHash: string;
+    createdAt: Date;
+    expiresAt: Date;
+}
+export interface IPasswordResetTokenStore {
+    set(record: PasswordResetTokenRecord): void | Promise<void>;
+    get(identifier: string): PasswordResetTokenRecord | null | Promise<PasswordResetTokenRecord | null>;
+    delete(identifier: string): void | Promise<void>;
+    cleanup?(now?: Date): number | Promise<number>;
+    clear?(): void | Promise<void>;
+}
+export interface IPasswordResetTokenBroker {
+    createToken(identifier: string): Promise<string>;
+    verifyToken(identifier: string, token: string): Promise<boolean>;
+    consumeToken(identifier: string, token: string): Promise<boolean>;
+}
+export interface PasswordResetTokenBrokerOptions {
+    store?: IPasswordResetTokenStore;
+    ttlMs?: number;
+    tokenBytes?: number;
+    now?: () => Date;
+}
+export interface PasswordResetTokenBrokerType {
+    create(options?: PasswordResetTokenBrokerOptions): IPasswordResetTokenBroker;
+    createInMemoryStore(): IPasswordResetTokenStore;
+}
+export declare const PasswordResetTokenBroker: PasswordResetTokenBrokerType;
+//# sourceMappingURL=PasswordResetTokenBroker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PasswordResetTokenBroker.d.ts","sourceRoot":"","sources":["../../../src/security/PasswordResetTokenBroker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,GAAG,CACD,UAAU,EAAE,MAAM,GACjB,wBAAwB,GAAG,IAAI,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,+BAA+B;IAC9C,KAAK,CAAC,EAAE,wBAAwB,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,CAAC,OAAO,CAAC,EAAE,+BAA+B,GAAG,yBAAyB,CAAC;IAC7E,mBAAmB,IAAI,wBAAwB,CAAC;CACjD;AAmFD,eAAO,MAAM,wBAAwB,EAAE,4BAGrC,CAAC"}

package/src/security/PasswordResetTokenBroker.js

@@ -0,0 +1,131 @@
+/**
+ * Password Reset Token Broker
+ *
+ * Framework-agnostic, storage-pluggable password reset token flow.
+ *
+ * - Generates high-entropy tokens for a given identifier (usually an email).
+ * - Stores only a SHA-256 hash of the token (one active token per identifier).
+ * - Supports verification and one-time consumption.
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { createHash, randomBytes } from '../node-singletons/crypto.js';
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_TOKEN_BYTES = 32; // 256 bits
+const createInMemoryStore = () => {
+    const map = new Map();
+    return {
+        set(record) {
+            map.set(record.identifier, record);
+        },
+        get(identifier) {
+            return map.get(identifier) ?? null;
+        },
+        delete(identifier) {
+            map.delete(identifier);
+        },
+        cleanup(now = new Date()) {
+            let removed = 0;
+            for (const [identifier, record] of map.entries()) {
+                if (now.getTime() > record.expiresAt.getTime()) {
+                    map.delete(identifier);
+                    removed++;
+                }
+            }
+            return removed;
+        },
+        clear() {
+            map.clear();
+        },
+    };
+};
+const create = (options = {}) => {
+    const store = options.store ?? createInMemoryStore();
+    const ttlMs = normalizeTtlMs(options.ttlMs ?? DEFAULT_TTL_MS);
+    const tokenBytes = normalizeTokenBytes(options.tokenBytes ?? DEFAULT_TOKEN_BYTES);
+    const now = options.now ?? (() => new Date());
+    return {
+        async createToken(identifier) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const token = randomBytes(tokenBytes).toString('hex');
+            const tokenHash = sha256Hex(token);
+            const createdAt = now();
+            const expiresAt = new Date(createdAt.getTime() + ttlMs);
+            await store.set({ identifier: normalizedIdentifier, tokenHash, createdAt, expiresAt });
+            return token;
+        },
+        async verifyToken(identifier, token) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const normalizedToken = normalizeToken(token);
+            const record = await store.get(normalizedIdentifier);
+            if (record === null)
+                return false;
+            if (isExpired(record, now())) {
+                await store.delete(normalizedIdentifier);
+                return false;
+            }
+            const computed = sha256Hex(normalizedToken);
+            return timingSafeEquals(record.tokenHash, computed);
+        },
+        async consumeToken(identifier, token) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const ok = await this.verifyToken(normalizedIdentifier, token);
+            if (!ok)
+                return false;
+            await store.delete(normalizedIdentifier);
+            return true;
+        },
+    };
+};
+export const PasswordResetTokenBroker = Object.freeze({
+    create,
+    createInMemoryStore,
+});
+function normalizeIdentifier(identifier) {
+    if (typeof identifier !== 'string') {
+        throw ErrorFactory.createValidationError('Invalid identifier');
+    }
+    const trimmed = identifier.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid identifier');
+    }
+    return trimmed;
+}
+function normalizeToken(token) {
+    if (typeof token !== 'string') {
+        throw ErrorFactory.createValidationError('Invalid token');
+    }
+    const trimmed = token.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid token');
+    }
+    return trimmed;
+}
+function normalizeTtlMs(ttlMs) {
+    const value = Number.isFinite(ttlMs) ? Math.trunc(ttlMs) : 0;
+    if (value <= 0) {
+        throw ErrorFactory.createConfigError('Invalid password reset TTL', { ttlMs });
+    }
+    return value;
+}
+function normalizeTokenBytes(tokenBytes) {
+    const value = Number.isFinite(tokenBytes) ? Math.trunc(tokenBytes) : 0;
+    if (value <= 0) {
+        throw ErrorFactory.createConfigError('Invalid password reset token bytes', { tokenBytes });
+    }
+    return value;
+}
+function isExpired(record, now) {
+    return now.getTime() > record.expiresAt.getTime();
+}
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function timingSafeEquals(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= (a.codePointAt(i) ?? 0) ^ (b.codePointAt(i) ?? 0);
+    }
+    return result === 0;
+}

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/session/SessionManager.d.ts

@@ -0,0 +1,39 @@
+export type SessionData = Record<string, unknown>;
+export interface ISession {
+    id: string;
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    forget(key: string): void;
+    all(): SessionData;
+    clear(): void;
+}
+export interface ISessionManager {
+    getIdFromCookieHeader(cookieHeader: string | undefined): string | undefined;
+    getIdFromRequest(req: {
+        getHeader: (name: string) => unknown;
+        sessionId?: unknown;
+        context?: Record<string, unknown>;
+    }): string | undefined;
+    ensureSessionId(req: {
+        getHeader: (name: string) => unknown;
+        sessionId?: unknown;
+        context: Record<string, unknown>;
+    }, res: {
+        getHeader: (name: string) => unknown;
+        setHeader: (name: string, value: string | string[]) => unknown;
+    }): Promise<string>;
+    get(sessionId: string): ISession;
+    destroy(sessionId: string): void;
+    cleanup(): number;
+}
+export interface SessionManagerOptions {
+    cookieName?: string;
+    headerName?: string;
+    ttlMs?: number;
+}
+export declare const SessionManager: Readonly<{
+    create(options?: SessionManagerOptions): ISessionManager;
+}>;
+export default SessionManager;
+//# sourceMappingURL=SessionManager.d.ts.map

package/src/session/SessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../../../src/session/SessionManager.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,IAAI,WAAW,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5E,gBAAgB,CAAC,GAAG,EAAE;QACpB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,MAAM,GAAG,SAAS,CAAC;IACvB,eAAe,CACb,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,EACD,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,CAAC;KAChE,GACA,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,IAAI,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyHD,eAAO,MAAM,cAAc;qBACT,qBAAqB,GAAQ,eAAe;EA2E5D,CAAC;AAEH,eAAe,cAAc,CAAC"}