@zintrust/core 0.7.8 → 0.9.0

package/src/security/JwtVerifier.js

@@ -0,0 +1,336 @@
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { isArray, isNonEmptyString, isObject } from '../helper/index.js';
+import { detectRuntimePlatform, RuntimeServices } from '../runtime/RuntimeServices.js';
+const jwksCache = new Map();
+const getRuntime = () => RuntimeServices.create(detectRuntimePlatform());
+const isFailure = (value) => {
+    return isObject(value) && value['ok'] === false && typeof value['reason'] === 'string';
+};
+const toFailure = (reason, message, details) => ({
+    ok: false,
+    reason,
+    message,
+    ...(details === undefined ? {} : { details }),
+});
+const toThrownError = (failure) => {
+    return ErrorFactory.createSecurityError(failure.message, {
+        reason: failure.reason,
+        ...(failure.details === undefined ? {} : { details: failure.details }),
+    });
+};
+const normalizeBase64Url = (value) => {
+    const normalized = value.replaceAll('-', '+').replaceAll('_', '/');
+    const padding = normalized.length % 4;
+    return padding === 0 ? normalized : normalized.padEnd(normalized.length + (4 - padding), '=');
+};
+const base64UrlToBytes = (value) => {
+    const binary = globalThis.atob(normalizeBase64Url(value));
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++) {
+        bytes[index] = binary.codePointAt(index) ?? 0;
+    }
+    return bytes;
+};
+const decodeJwtSegment = (value) => {
+    const json = new TextDecoder().decode(base64UrlToBytes(value));
+    return JSON.parse(json);
+};
+const parseTokenParts = (token) => {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        return toFailure('invalid_token_format', 'JWT must contain header, payload, and signature');
+    }
+    const [encodedHeader, encodedPayload, encodedSignature] = parts;
+    if (!isNonEmptyString(encodedHeader) ||
+        !isNonEmptyString(encodedPayload) ||
+        !isNonEmptyString(encodedSignature)) {
+        return toFailure('invalid_token_format', 'JWT parts must not be empty');
+    }
+    return { encodedHeader, encodedPayload, encodedSignature };
+};
+const parseHeader = (encodedHeader) => {
+    try {
+        const header = decodeJwtSegment(encodedHeader);
+        if (!isObject(header)) {
+            return toFailure('invalid_header', 'JWT header must be an object');
+        }
+        return header;
+    }
+    catch (error) {
+        return toFailure('invalid_header', 'JWT header is not valid JSON', {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+};
+const parsePayload = (encodedPayload) => {
+    try {
+        const payload = decodeJwtSegment(encodedPayload);
+        if (!isObject(payload)) {
+            return toFailure('invalid_payload', 'JWT payload must be an object');
+        }
+        return payload;
+    }
+    catch (error) {
+        return toFailure('invalid_payload', 'JWT payload is not valid JSON', {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+};
+const getAlgorithm = (inputAlgorithm) => {
+    return inputAlgorithm ?? 'RS256';
+};
+const validateHeaderAlgorithm = (header, algorithm) => {
+    if (header['alg'] !== algorithm) {
+        return toFailure('unsupported_algorithm', `JWT algorithm must be ${algorithm}`);
+    }
+    return undefined;
+};
+const normalizeExpectedValues = (value) => {
+    if (value === undefined)
+        return [];
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed === '' ? [] : [trimmed];
+    }
+    return value
+        .map((item) => (typeof item === 'string' ? item.trim() : ''))
+        .filter((item) => item !== '');
+};
+const normalizeAudienceClaim = (audience) => {
+    if (typeof audience === 'string') {
+        const trimmed = audience.trim();
+        return trimmed === '' ? [] : [trimmed];
+    }
+    if (isArray(audience)) {
+        return audience
+            .map((item) => (typeof item === 'string' ? item.trim() : ''))
+            .filter((item) => item !== '');
+    }
+    return [];
+};
+const validateClaims = (payload, input) => {
+    const nowMs = input.nowMs ?? Date.now();
+    if (typeof payload.exp === 'number' &&
+        Number.isFinite(payload.exp) &&
+        nowMs >= payload.exp * 1000) {
+        return toFailure('token_expired', 'JWT has expired');
+    }
+    if (typeof payload.nbf === 'number' &&
+        Number.isFinite(payload.nbf) &&
+        nowMs < payload.nbf * 1000) {
+        return toFailure('token_not_yet_valid', 'JWT is not valid yet');
+    }
+    const expectedIssuers = normalizeExpectedValues(input.issuer);
+    if (expectedIssuers.length > 0) {
+        const issuer = typeof payload.iss === 'string' ? payload.iss.trim() : '';
+        if (!expectedIssuers.includes(issuer)) {
+            return toFailure('issuer_mismatch', 'JWT issuer did not match the expected issuer', {
+                expected: expectedIssuers,
+                received: issuer,
+            });
+        }
+    }
+    const expectedAudiences = normalizeExpectedValues(input.audience);
+    if (expectedAudiences.length > 0) {
+        const audiences = normalizeAudienceClaim(payload.aud);
+        const matched = audiences.some((audience) => expectedAudiences.includes(audience));
+        if (!matched) {
+            return toFailure('audience_mismatch', 'JWT audience did not match the expected audience', {
+                expected: expectedAudiences,
+                received: audiences,
+            });
+        }
+    }
+    return undefined;
+};
+const validateJwkForAlgorithm = (jwk, algorithm) => {
+    if (jwk.kty !== 'RSA') {
+        return toFailure('invalid_jwk', 'JWK must use RSA for RS256 verification', {
+            kty: jwk.kty,
+        });
+    }
+    if (!isNonEmptyString(jwk.n) || !isNonEmptyString(jwk.e)) {
+        return toFailure('invalid_jwk', 'JWK must include RSA modulus and exponent');
+    }
+    if (isNonEmptyString(jwk.alg) && jwk.alg !== algorithm) {
+        return toFailure('invalid_jwk', 'JWK algorithm does not match the requested JWT algorithm', {
+            expected: algorithm,
+            received: jwk.alg,
+        });
+    }
+    if (isNonEmptyString(jwk.use) && jwk.use !== 'sig') {
+        return toFailure('invalid_jwk', 'JWK use must allow signature verification', {
+            use: jwk.use,
+        });
+    }
+    return undefined;
+};
+const verifyRs256Signature = async (params) => {
+    const subtle = getRuntime().crypto.subtle;
+    try {
+        const key = await subtle.importKey('jwk', params.jwk, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']);
+        const signature = base64UrlToBytes(params.encodedSignature);
+        const signingInput = new TextEncoder().encode(params.signingInput);
+        return await subtle.verify('RSASSA-PKCS1-v1_5', key, signature, signingInput);
+    }
+    catch (error) {
+        return toFailure('invalid_jwk', 'JWK could not be imported for signature verification', {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+};
+const fetchJwks = async (input) => {
+    const cacheKey = (input.cacheKey ?? input.jwksUrl).trim();
+    const nowMs = input.nowMs ?? Date.now();
+    const cached = jwksCache.get(cacheKey);
+    if (cached !== undefined && cached.expiresAtMs > nowMs) {
+        return { jwks: cached.jwks, cacheHit: true };
+    }
+    const fetcher = input.fetcher ?? getRuntime().fetch;
+    let response;
+    try {
+        response = await fetcher(input.jwksUrl, {
+            headers: { accept: 'application/json' },
+        });
+    }
+    catch (error) {
+        return toFailure('jwks_fetch_failed', 'Failed to fetch JWKS document', {
+            jwksUrl: input.jwksUrl,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!response.ok) {
+        return toFailure('jwks_fetch_failed', 'JWKS endpoint returned a non-success response', {
+            jwksUrl: input.jwksUrl,
+            status: response.status,
+        });
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch (error) {
+        return toFailure('invalid_jwks', 'JWKS response was not valid JSON', {
+            jwksUrl: input.jwksUrl,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!isObject(body) || !isArray(body['keys'])) {
+        return toFailure('invalid_jwks', 'JWKS response must contain a keys array', {
+            jwksUrl: input.jwksUrl,
+        });
+    }
+    const jwks = {
+        keys: body['keys'].filter((item) => isObject(item)),
+    };
+    const cacheTtlSeconds = typeof input.cacheTtlSeconds === 'number' && Number.isFinite(input.cacheTtlSeconds)
+        ? input.cacheTtlSeconds
+        : 3600;
+    const ttlMs = Math.max(1, cacheTtlSeconds) * 1000;
+    jwksCache.set(cacheKey, { jwks, expiresAtMs: nowMs + ttlMs });
+    return { jwks, cacheHit: false };
+};
+const resolveJwkFromJwks = (header, jwks, algorithm) => {
+    const kid = typeof header['kid'] === 'string' ? header['kid'].trim() : '';
+    if (kid === '') {
+        return toFailure('missing_kid', 'JWT header must include a kid when verifying with JWKS');
+    }
+    const jwk = jwks.keys.find((item) => {
+        if (item.kid !== kid)
+            return false;
+        if (isNonEmptyString(item.alg) && item.alg !== algorithm)
+            return false;
+        if (isNonEmptyString(item.use) && item.use !== 'sig')
+            return false;
+        return true;
+    });
+    if (jwk === undefined) {
+        return toFailure('key_not_found', 'No matching JWK was found for the JWT kid', { kid });
+    }
+    return jwk;
+};
+const verifyTokenWithJwk = async (input, jwk, cacheHit) => {
+    const tokenParts = parseTokenParts(input.token);
+    if (isFailure(tokenParts))
+        return tokenParts;
+    const header = parseHeader(tokenParts.encodedHeader);
+    if (isFailure(header))
+        return header;
+    const payload = parsePayload(tokenParts.encodedPayload);
+    if (isFailure(payload))
+        return payload;
+    const algorithm = getAlgorithm(input.algorithm);
+    const headerFailure = validateHeaderAlgorithm(header, algorithm);
+    if (headerFailure !== undefined)
+        return headerFailure;
+    const jwkFailure = validateJwkForAlgorithm(jwk, algorithm);
+    if (jwkFailure !== undefined)
+        return jwkFailure;
+    const signatureCheck = await verifyRs256Signature({
+        jwk,
+        signingInput: `${tokenParts.encodedHeader}.${tokenParts.encodedPayload}`,
+        encodedSignature: tokenParts.encodedSignature,
+    });
+    if (signatureCheck !== true) {
+        return signatureCheck === false
+            ? toFailure('invalid_signature', 'JWT signature could not be verified')
+            : signatureCheck;
+    }
+    const claimsFailure = validateClaims(payload, input);
+    if (claimsFailure !== undefined)
+        return claimsFailure;
+    return { ok: true, payload, header, jwk, ...(cacheHit === undefined ? {} : { cacheHit }) };
+};
+const verifyWithJwkResult = async (input) => {
+    return verifyTokenWithJwk(input, input.jwk);
+};
+const verifyWithJwksResult = async (input) => {
+    const tokenParts = parseTokenParts(input.token);
+    if (isFailure(tokenParts))
+        return tokenParts;
+    const header = parseHeader(tokenParts.encodedHeader);
+    if (isFailure(header))
+        return header;
+    const algorithm = getAlgorithm(input.algorithm);
+    const headerFailure = validateHeaderAlgorithm(header, algorithm);
+    if (headerFailure !== undefined)
+        return headerFailure;
+    const kid = typeof header['kid'] === 'string' ? header['kid'].trim() : '';
+    if (kid === '') {
+        return toFailure('missing_kid', 'JWT header must include a kid when verifying with JWKS');
+    }
+    const fetched = await fetchJwks(input);
+    if (isFailure(fetched))
+        return fetched;
+    const jwk = resolveJwkFromJwks(header, fetched.jwks, algorithm);
+    if (isFailure(jwk))
+        return jwk;
+    return verifyTokenWithJwk(input, jwk, fetched.cacheHit);
+};
+const verifyWithJwk = async (input) => {
+    const result = await verifyWithJwkResult(input);
+    if (!result.ok)
+        throw toThrownError(result);
+    return result.payload;
+};
+const verifyWithJwks = async (input) => {
+    const result = await verifyWithJwksResult(input);
+    if (!result.ok)
+        throw toThrownError(result);
+    return result.payload;
+};
+const clearCache = (cacheKey) => {
+    if (!isNonEmptyString(cacheKey)) {
+        jwksCache.clear();
+        return;
+    }
+    jwksCache.delete(cacheKey.trim());
+};
+export const JwtVerifier = Object.freeze({
+    clearCache,
+    verifyWithJwk,
+    verifyWithJwkResult,
+    verifyWithJwks,
+    verifyWithJwksResult,
+});
+export default JwtVerifier;

package/src/templates/project/basic/app/Controllers/AuthController.ts.tpl

@@ -59,7 +59,7 @@ const getIssuedToken = (issued: unknown): string => {
     }
   }
 
-  throw ErrorFactory.createSecurityError('LoginFlow jwt issuer returned an invalid access token');
+  throw ErrorFactory.createSecurityError('LoginFlow issuer returned an invalid access token');
 };
 
 const getIssuedString = (issued: unknown, key: string): string | undefined => {

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

@@ -0,0 +1,73 @@
+import { Env } from '@zintrust/core';
+import type { TraceConfigOverrides } from '@zintrust/trace';
+
+/**
+ * SystemTrace Configuration
+ *
+ * Keep this file declarative:
+ * - Package owns defaults and type validation.
+ * - Edit values below to override for this project.
+ *
+ * Usage: import '@zintrust/trace/register' in your bootstrap.
+ * Protect /trace with your own middleware (auth, admin role, etc.).
+ */
+
+export default {
+  enabled: Env.getBool('TRACE_ENABLED', false),
+
+  // Optional: use a separate DB connection for trace tables.
+  // Leave undefined to fall back to the app's default connection.
+  connection: Env.get('TRACE_DB_CONNECTION', '') || undefined,
+
+  pruneAfterHours: Env.getInt('TRACE_PRUNE_HOURS', 72),
+
+  ignoreRoutes: ['/trace', '/health', '/ping', '/metrics', '/api-docs', '/api-docs-json'],
+
+  ignorePaths: [
+    '/telemetry',
+    '/favicon.ico',
+    '/robots.txt',
+    '/sitemap.xml',
+    '/workers',
+    '/queue-monitor',
+    '.js',
+    '.css',
+  ],
+
+  slowQueryThreshold: Env.getInt('TRACE_SLOW_QUERY_MS', 100),
+
+  logMinLevel: Env.get('TRACE_LOG_LEVEL', 'warn') as 'debug' | 'info' | 'warn' | 'error' | 'fatal',
+
+  watchers: {
+    // Set a watcher to false to disable it entirely.
+    // All watchers are enabled by default when trace is enabled.
+    // Include/exclude filters are contains-based and can be applied per watcher.
+    // request: {
+    //   get: { exclude: ['report','workers/events'] },
+    //   post: { include: ['auth'] },
+    //   patch: { include: ['profile'] },
+    //   delete: { exclude: ['internal'] },
+    // },
+    // log: { exclude: ['healthcheck'] },
+    // exception: { include: ['trace'] },
+    // clientRequest: {
+    //   exclude: ['internal-http'],
+    //   sources: {
+    //     termii: { enabled: false },
+    //     sendgrid: { responseBody: false },
+    //     s3: { requestHeaders: false, responseHeaders: false },
+    //   },
+    // },
+    // cache: { include: ['session:'] },
+    // dump: false,  // DumpWatcher is opt-in — enable explicitly if needed
+  },
+
+  redaction: {
+    // Extra keys to mask recursively before trace entries are persisted.
+    // You can also provide these via TRACE_REDACT_KEYS as JSON or CSV.
+    keys: ['password', 'token', 'secret', 'authorization', 'card', 'cardNumber', 'cvv'],
+    headers: ['authorization', 'cookie', 'x-api-key', 'x-auth-token'],
+    body: ['password', 'token', 'secret', 'apiKey', 'api_key', 'jwt', 'bearer'],
+    query: [],
+  },
+} satisfies TraceConfigOverrides;

package/src/templates/project/basic/package.json.tpl

@@ -12,7 +12,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@zintrust/core": "^{{coreVersion}}"
+    "@zintrust/core": "{{coreVersion}}"
   },
   "devDependencies": {
     "@zintrust/governance": "{{governanceVersion}}",

package/src/zintrust.plugins.d.ts

@@ -1,10 +1,7 @@
 /**
- * ZinTrust plugin auto-imports
- *
- * In real projects, this file is managed by `zin plugin install` and contains
- * side-effect imports (e.g. `@zintrust/db-sqlite/register`) that register
- * optional adapters/drivers into core registries.
- *
+ * Auto-generated fallback module.
+ * This file is created by scripts/ensure-worker-plugins.mjs when missing.
+ * It allows optional runtime plugin imports to resolve in CI/scaffolded setups.
  */
 export type {};
 export declare const __zintrustGeneratedPluginStub = "zintrust.plugins.ts";

package/src/zintrust.plugins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zintrust.plugins.d.ts","sourceRoot":"","sources":["../../src/zintrust.plugins.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,YAAY,EAAE,CAAC;AAgBf,eAAO,MAAM,6BAA6B,wBAAwB,CAAC;;AACnE,wBAAkB"}
+{"version":3,"file":"zintrust.plugins.d.ts","sourceRoot":"","sources":["../../src/zintrust.plugins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAC;AAgBf,eAAO,MAAM,6BAA6B,wBAAwB,CAAC;;AACnE,wBAAkB"}

package/src/zintrust.plugins.js

@@ -1,10 +1,7 @@
 /**
- * ZinTrust plugin auto-imports
- *
- * In real projects, this file is managed by `zin plugin install` and contains
- * side-effect imports (e.g. `@zintrust/db-sqlite/register`) that register
- * optional adapters/drivers into core registries.
- *
+ * Auto-generated fallback module.
+ * This file is created by scripts/ensure-worker-plugins.mjs when missing.
+ * It allows optional runtime plugin imports to resolve in CI/scaffolded setups.
  */
 import * as TraceRuntime from './runtime/plugins/trace-runtime.js';
 globalThis.__zintrust_system_trace_plugin_requested__ = true;