@zintrust/core 3.5.1 → 3.5.2

package/src/security/SignedRequest.d.ts

@@ -0,0 +1,53 @@
+export type SignedRequestHeaders = {
+    'x-zt-key-id': string;
+    'x-zt-timestamp': string;
+    'x-zt-nonce': string;
+    'x-zt-body-sha256': string;
+    'x-zt-signature': string;
+};
+export type SignedRequestCreateHeadersParams = {
+    method: string;
+    url: string | URL;
+    body?: string | Uint8Array | null;
+    keyId: string;
+    secret: string;
+    timestampMs?: number;
+    nonce?: string;
+};
+export type SignedRequestVerifyParams = {
+    method: string;
+    url: string | URL;
+    body?: string | Uint8Array | null;
+    headers: Headers | Record<string, string | undefined>;
+    getSecretForKeyId: (keyId: string) => string | undefined | Promise<string | undefined>;
+    nowMs?: number;
+    windowMs?: number;
+    /**
+     * Optional replay protection hook.
+     * Return true if the nonce is accepted and stored; false if replayed/invalid.
+     */
+    verifyNonce?: (keyId: string, nonce: string, ttlMs: number) => Promise<boolean>;
+};
+export type SignedRequestVerifyResult = {
+    ok: true;
+    keyId: string;
+    timestampMs: number;
+    nonce: string;
+} | {
+    ok: false;
+    code: 'MISSING_HEADER' | 'INVALID_TIMESTAMP' | 'EXPIRED' | 'INVALID_BODY_SHA' | 'INVALID_SIGNATURE' | 'UNKNOWN_KEY' | 'REPLAYED';
+    message: string;
+};
+export declare const SignedRequest: Readonly<{
+    sha256Hex: (data: string | Uint8Array) => Promise<string>;
+    canonicalString: (params: {
+        method: string;
+        url: string | URL;
+        timestampMs: number;
+        nonce: string;
+        bodySha256Hex: string;
+    }) => string;
+    createHeaders(params: SignedRequestCreateHeadersParams): Promise<SignedRequestHeaders>;
+    verify(params: SignedRequestVerifyParams): Promise<SignedRequestVerifyResult>;
+}>;
+//# sourceMappingURL=SignedRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SignedRequest.d.ts","sourceRoot":"","sources":["../../../src/security/SignedRequest.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACjF,CAAC;AAEF,MAAM,MAAM,yBAAyB,GACjC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EACA,gBAAgB,GAChB,mBAAmB,GACnB,SAAS,GACT,kBAAkB,GAClB,mBAAmB,GACnB,aAAa,GACb,UAAU,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AA0FN,eAAO,MAAM,aAAa;sBAzBK,MAAM,GAAG,UAAU,KAAG,OAAO,CAAC,MAAM,CAAC;8BAKnC;QAC/B,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;KACvB,KAAG,MAAM;0BAiBoB,gCAAgC,GAAG,OAAO,CAAC,oBAAoB,CAAC;mBAuCvE,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC;EAuCnF,CAAC"}

package/src/security/SignedRequest.js

@@ -0,0 +1,172 @@
+const getHeader = (headers, name) => {
+    if (typeof headers.get === 'function') {
+        const value = headers.get(name);
+        return value ?? undefined;
+    }
+    return headers[name];
+};
+const 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;
+};
+const getCrypto = () => {
+    if (typeof crypto === 'undefined' || crypto.subtle === undefined) {
+        // Some runtimes (or test environments) may not expose WebCrypto.
+        // Keep this as a typed ZinTrust error to satisfy lint rules.
+        // eslint-disable-next-line no-restricted-syntax
+        throw new Error('WebCrypto is not available in this runtime');
+    }
+    return crypto;
+};
+const getSubtle = () => getCrypto().subtle;
+const toBytes = (data) => {
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    return new Uint8Array(bytes);
+};
+const toHex = (bytes) => {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let out = '';
+    for (const element of view) {
+        out += element.toString(16).padStart(2, '0');
+    }
+    return out;
+};
+const sha256Hex = async (data) => {
+    const digest = await getSubtle().digest('SHA-256', toBytes(data));
+    return toHex(digest);
+};
+const canonicalString = (params) => {
+    const u = typeof params.url === 'string' ? new URL(params.url) : params.url;
+    const method = params.method.toUpperCase();
+    // Keep URL pieces aligned with plan: pathname + search (including leading '?' or '').
+    return [
+        method,
+        u.pathname,
+        u.search,
+        String(params.timestampMs),
+        params.nonce,
+        params.bodySha256Hex,
+    ].join('\n');
+};
+export const SignedRequest = Object.freeze({
+    sha256Hex,
+    canonicalString,
+    async createHeaders(params) {
+        const timestampMs = params.timestampMs ?? Date.now();
+        const webCrypto = getCrypto();
+        const nonce = params.nonce ??
+            (typeof webCrypto.randomUUID === 'function'
+                ? webCrypto.randomUUID()
+                : toHex(webCrypto.getRandomValues(new Uint8Array(16))));
+        const body = params.body ?? '';
+        const bodySha = await sha256Hex(body);
+        const canonical = canonicalString({
+            method: params.method,
+            url: params.url,
+            timestampMs,
+            nonce,
+            bodySha256Hex: bodySha,
+        });
+        const subtle = getSubtle();
+        const key = await subtle.importKey('raw', toBytes(params.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        const signatureBytes = await subtle.sign('HMAC', key, toBytes(canonical));
+        const signature = toHex(signatureBytes);
+        return {
+            'x-zt-key-id': params.keyId,
+            'x-zt-timestamp': String(timestampMs),
+            'x-zt-nonce': nonce,
+            'x-zt-body-sha256': bodySha,
+            'x-zt-signature': signature,
+        };
+    },
+    async verify(params) {
+        const parsed = parseAndValidateHeaders(params.headers);
+        if (parsed.ok === false)
+            return parsed;
+        const { keyId, timestampMs, nonce, bodySha, signature } = parsed;
+        const nowMs = params.nowMs ?? Date.now();
+        const windowMs = params.windowMs ?? 60_000;
+        const windowCheck = validateTimestampWindow({ nowMs, timestampMs, windowMs });
+        if (windowCheck.ok === false)
+            return windowCheck;
+        const bodyCheck = await validateBodyHash({ body: params.body ?? '', bodyShaHeader: bodySha });
+        if (bodyCheck.ok === false)
+            return bodyCheck;
+        const secret = await params.getSecretForKeyId(keyId);
+        if (secret === undefined || secret.trim() === '') {
+            return { ok: false, code: 'UNKNOWN_KEY', message: 'Unknown key id' };
+        }
+        const sigCheck = await validateSignature({
+            method: params.method,
+            url: params.url,
+            timestampMs,
+            nonce,
+            bodySha,
+            signature,
+            secret,
+        });
+        if (sigCheck.ok === false)
+            return sigCheck;
+        if (params.verifyNonce !== undefined) {
+            const ok = await params.verifyNonce(keyId, nonce, windowMs);
+            if (ok === false) {
+                return { ok: false, code: 'REPLAYED', message: 'Nonce replayed or rejected' };
+            }
+        }
+        return { ok: true, keyId, timestampMs, nonce };
+    },
+});
+const parseAndValidateHeaders = (headers) => {
+    const keyId = getHeader(headers, 'x-zt-key-id');
+    const ts = getHeader(headers, 'x-zt-timestamp');
+    const nonce = getHeader(headers, 'x-zt-nonce');
+    const bodySha = getHeader(headers, 'x-zt-body-sha256');
+    const signature = getHeader(headers, 'x-zt-signature');
+    if (keyId === undefined ||
+        ts === undefined ||
+        nonce === undefined ||
+        bodySha === undefined ||
+        signature === undefined) {
+        return { ok: false, code: 'MISSING_HEADER', message: 'Missing required signing headers' };
+    }
+    const timestampMs = Number.parseInt(ts, 10);
+    if (!Number.isFinite(timestampMs)) {
+        return { ok: false, code: 'INVALID_TIMESTAMP', message: 'Invalid x-zt-timestamp' };
+    }
+    return { ok: true, keyId, timestampMs, nonce, bodySha, signature };
+};
+const validateTimestampWindow = (params) => {
+    if (Math.abs(params.nowMs - params.timestampMs) > params.windowMs) {
+        return { ok: false, code: 'EXPIRED', message: 'Request timestamp outside allowed window' };
+    }
+    return { ok: true };
+};
+const validateBodyHash = async (params) => {
+    const computedBodySha = await sha256Hex(params.body);
+    if (!timingSafeEquals(computedBodySha, params.bodyShaHeader)) {
+        return { ok: false, code: 'INVALID_BODY_SHA', message: 'Body hash mismatch' };
+    }
+    return { ok: true };
+};
+const validateSignature = async (params) => {
+    const subtle = getSubtle();
+    const canonical = canonicalString({
+        method: params.method,
+        url: params.url,
+        timestampMs: params.timestampMs,
+        nonce: params.nonce,
+        bodySha256Hex: params.bodySha,
+    });
+    const key = await subtle.importKey('raw', toBytes(params.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const expectedBytes = await subtle.sign('HMAC', key, toBytes(canonical));
+    const expected = toHex(expectedBytes);
+    if (!timingSafeEquals(expected, params.signature)) {
+        return { ok: false, code: 'INVALID_SIGNATURE', message: 'Invalid signature' };
+    }
+    return { ok: true };
+};

package/src/security/StartupSecretValidation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Startup Secret Validation
+ *
+ * Validates critical secrets early at boot time so production misconfiguration
+ * fails fast and predictably.
+ */
+export type StartupSecretValidationError = {
+    key: string;
+    message: string;
+};
+export type StartupSecretValidationResult = {
+    valid: boolean;
+    errors: StartupSecretValidationError[];
+};
+export declare const StartupSecretValidation: Readonly<{
+    validate(): StartupSecretValidationResult;
+    assertValid(): void;
+}>;
+export default StartupSecretValidation;
+//# sourceMappingURL=StartupSecretValidation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StartupSecretValidation.d.ts","sourceRoot":"","sources":["../../../src/security/StartupSecretValidation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,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;AA4HF,eAAO,MAAM,uBAAuB;gBACtB,6BAA6B;mBAiB1B,IAAI;EAQnB,CAAC;AAEH,eAAe,uBAAuB,CAAC"}

package/src/security/StartupSecretValidation.js

@@ -0,0 +1,148 @@
+/**
+ * Startup Secret Validation
+ *
+ * Validates critical secrets early at boot time so production misconfiguration
+ * 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';
+import { isNonEmptyString } from '../helper/index.js';
+const validateApiKeySecret = () => {
+    if (!securityConfig.apiKey.enabled)
+        return null;
+    const secret = (securityConfig.apiKey.secret ?? '').trim();
+    if (secret.length > 0)
+        return null;
+    return {
+        key: 'API_KEY_SECRET',
+        message: 'API_KEY_SECRET must be set when API key auth is enabled',
+    };
+};
+const validateJwtSecret = () => {
+    if (!securityConfig.jwt.enabled)
+        return null;
+    try {
+        const secret = securityConfig.jwt.secret.trim();
+        const appKey = (Env.APP_KEY ?? '').trim();
+        if (secret.length === 0) {
+            if (appKey.length > 0)
+                return null;
+            return {
+                key: 'JWT_SECRET',
+                message: 'JWT_SECRET must be set when JWT is enabled (or provide APP_KEY)',
+            };
+        }
+        return null;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        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 shouldValidateEncryptionInterop = () => {
+    const cipherRaw = (Env.ENCRYPTION_CIPHER ?? '').trim();
+    const previousKeysRaw = (Env.APP_PREVIOUS_KEYS ?? '').trim();
+    return isNonEmptyString(cipherRaw) || isNonEmptyString(previousKeysRaw);
+};
+const validateEncryptionInterop = () => {
+    const errors = [];
+    if (!shouldValidateEncryptionInterop()) {
+        return errors;
+    }
+    const cipherRaw = (Env.ENCRYPTION_CIPHER ?? '').trim();
+    if (cipherRaw.length === 0) {
+        errors.push({
+            key: 'ENCRYPTION_CIPHER',
+            message: 'ENCRYPTION_CIPHER must be set when encrypted envelope interoperability is enabled (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)
+            return { valid: true, errors: [] };
+        if (!appConfig.isProduction())
+            return { valid: true, errors: [] };
+        const errors = [];
+        const jwtError = validateJwtSecret();
+        if (jwtError !== null)
+            errors.push(jwtError);
+        const apiKeyError = validateApiKeySecret();
+        if (apiKeyError !== null)
+            errors.push(apiKeyError);
+        errors.push(...validateEncryptionInterop());
+        return { valid: errors.length === 0, errors };
+    },
+    assertValid() {
+        const result = StartupSecretValidation.validate();
+        if (result.valid)
+            return;
+        throw ErrorFactory.createConfigError('Invalid startup secret configuration', {
+            errors: result.errors,
+        });
+    },
+});
+export default StartupSecretValidation;

package/src/security/TokenRevocation.d.ts

@@ -0,0 +1,24 @@
+type AuthorizationHeader = string | string[] | undefined;
+export type TokenRevocationDriverName = 'database' | 'memory' | 'redis' | 'kv' | 'kv-remote';
+export declare const TokenRevocation: Readonly<{
+    /**
+     * Mark a token as revoked.
+     *
+     * Storage is keyed by JWT `jti` when present; otherwise falls back to the raw token string.
+     */
+    revoke(header: AuthorizationHeader): Promise<string | null>;
+    /**
+     * Check if a token is revoked.
+     */
+    isRevoked(token: string): Promise<boolean>;
+    /**
+     * For observability.
+     */
+    getDriver(): TokenRevocationDriverName;
+    /**
+     * Test/boot helper: reset cached driver.
+     */
+    _resetForTests(): void;
+}>;
+export default TokenRevocation;
+//# sourceMappingURL=TokenRevocation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenRevocation.d.ts","sourceRoot":"","sources":["../../../src/security/TokenRevocation.ts"],"names":[],"mappings":"AAeA,KAAK,mBAAmB,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAEzD,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,WAAW,CAAC;AA4vB7F,eAAO,MAAM,eAAe;IAC1B;;;;OAIG;mBACkB,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUjE;;OAEG;qBACoB,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMhD;;OAEG;iBACU,yBAAyB;IAItC;;OAEG;sBACe,IAAI;EAItB,CAAC;AAEH,eAAe,eAAe,CAAC"}