@zintrust/core 0.7.8 → 0.7.9

package/src/security/BulletproofDeviceStore.js

@@ -17,6 +17,18 @@ const getTable = () => {
 const normalizeString = (value) => {
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
 };
+const normalizeRequiredDeviceId = (value) => {
+    const normalized = normalizeString(value);
+    if (normalized !== undefined)
+        return normalized;
+    throw ErrorFactory.createValidationError('Bulletproof device store requires a non-empty deviceId');
+};
+const normalizeRequiredSigningSecret = (value) => {
+    const normalized = normalizeString(value);
+    if (normalized !== undefined)
+        return normalized;
+    throw ErrorFactory.createValidationError('Bulletproof device store requires a non-empty signingSecret');
+};
 const normalizeDate = (value) => {
     if (value instanceof Date && Number.isFinite(value.getTime()))
         return value;
@@ -26,10 +38,36 @@ const normalizeDate = (value) => {
     }
     return undefined;
 };
-const createMissingTableError = (table, error) => {
-    return ErrorFactory.createConfigError(`Bulletproof device store table '${table}' is missing required columns (run migrations)`, {
+const getErrorMessage = (error) => {
+    return error instanceof Error ? error.message : String(error);
+};
+const isSchemaError = (error) => {
+    const message = getErrorMessage(error).toLowerCase();
+    return (message.includes('no such table') ||
+        message.includes('no such column') ||
+        message.includes('unknown column') ||
+        message.includes('does not exist') ||
+        message.includes('undefined column') ||
+        message.includes('missing column'));
+};
+const createStoreError = (table, operation, error, details) => {
+    if (typeof error === 'object' && error !== null) {
+        const code = error.code;
+        if (typeof code === 'string' && code === 'CONFIG_ERROR') {
+            return error;
+        }
+    }
+    const message = getErrorMessage(error);
+    const detailPayload = { table, operation, error: message, ...details };
+    if (isSchemaError(error)) {
+        return ErrorFactory.createConfigError(`Bulletproof device store table '${table}' is missing required columns (run migrations)`, detailPayload);
+    }
+    return ErrorFactory.createDatabaseError(`Bulletproof device store ${operation} failed`, detailPayload);
+};
+const createInvalidStoredRecordError = (table, deviceId) => {
+    return ErrorFactory.createConfigError('Bulletproof device store returned an invalid record', {
         table,
-        error: error instanceof Error ? error.message : String(error),
+        ...(deviceId === undefined ? {} : { deviceId }),
     });
 };
 const toStoredRecord = (row) => {
@@ -57,63 +95,135 @@ const toStoredRecord = (row) => {
             : { updatedAt: normalizeDate(row['updated_at']) }),
     };
 };
-const toPayload = (record) => {
+const buildInsertPayload = (record) => {
     const lastSeenAt = record.lastSeenAt.toISOString();
+    const deviceId = normalizeRequiredDeviceId(record.deviceId);
+    const signingSecret = normalizeRequiredSigningSecret(record.signingSecret);
     return {
         user_id: normalizeString(record.userId) ?? null,
-        device_id: record.deviceId,
-        signing_secret: record.signingSecret,
+        device_id: deviceId,
+        signing_secret: signingSecret,
         user_agent: normalizeString(record.userAgent) ?? null,
         last_seen_at: lastSeenAt,
         created_at: lastSeenAt,
         updated_at: lastSeenAt,
     };
 };
+const buildUpdatePayload = (record) => {
+    const lastSeenAt = record.lastSeenAt.toISOString();
+    const signingSecret = normalizeRequiredSigningSecret(record.signingSecret);
+    return {
+        user_id: normalizeString(record.userId) ?? null,
+        signing_secret: signingSecret,
+        user_agent: normalizeString(record.userAgent) ?? null,
+        last_seen_at: lastSeenAt,
+        updated_at: lastSeenAt,
+    };
+};
+const buildIgnoreInsert = (db, table, columns, conflictColumns) => {
+    const columnList = columns.join(', ');
+    const placeholders = columns.map(() => '?').join(', ');
+    const driver = db.getType();
+    if (driver === 'sqlite' || driver === 'd1' || driver === 'd1-remote') {
+        return `INSERT OR IGNORE INTO ${table} (${columnList}) VALUES (${placeholders})`;
+    }
+    if (driver === 'mysql') {
+        return `INSERT IGNORE INTO ${table} (${columnList}) VALUES (${placeholders})`;
+    }
+    if (driver === 'postgresql') {
+        return `INSERT INTO ${table} (${columnList}) VALUES (${placeholders}) ON CONFLICT (${conflictColumns.join(', ')}) DO NOTHING`;
+    }
+    if (driver === 'sqlserver') {
+        const sourceColumns = columns.map((_, index) => `v${index + 1}`);
+        const selectClause = sourceColumns.map((name) => `? AS ${name}`).join(', ');
+        const conflictClause = conflictColumns
+            .map((column) => `target.${column} = source.${column}`)
+            .join(' AND ');
+        const insertValues = columns.map((column) => `source.${column}`).join(', ');
+        const sourceProjection = columns
+            .map((column, index) => `${sourceColumns[index]} AS ${column}`)
+            .join(', ');
+        return [
+            `MERGE INTO ${table} WITH (HOLDLOCK) AS target`,
+            `USING (SELECT ${sourceProjection} FROM (SELECT ${selectClause}) seed) AS source`,
+            `ON ${conflictClause}`,
+            `WHEN NOT MATCHED THEN INSERT (${columnList}) VALUES (${insertValues});`,
+        ].join(' ');
+    }
+    return `INSERT INTO ${table} (${columnList}) VALUES (${placeholders})`;
+};
 export const BulletproofDeviceStore = Object.freeze({
     async findByDeviceId(deviceId) {
         if (!isNonEmptyString(deviceId))
             return null;
         const db = useDatabase(undefined, getConnection());
         const table = getTable();
+        const normalizedDeviceId = deviceId.trim();
         try {
             const row = await db
                 .table(table)
-                .where('device_id', '=', deviceId.trim())
+                .where('device_id', '=', normalizedDeviceId)
                 .first();
-            return row === null ? null : toStoredRecord(row);
+            if (row === null) {
+                return null;
+            }
+            const normalized = toStoredRecord(row);
+            if (normalized === null) {
+                throw createInvalidStoredRecordError(table, normalizedDeviceId);
+            }
+            return normalized;
         }
         catch (error) {
-            throw createMissingTableError(table, error);
+            throw createStoreError(table, 'lookup', error, { deviceId: normalizedDeviceId });
         }
     },
     async upsert(record) {
         const db = useDatabase(undefined, getConnection());
         const table = getTable();
-        const payload = toPayload(record);
+        const deviceId = normalizeRequiredDeviceId(record.deviceId);
+        const normalizedUserId = normalizeString(record.userId);
+        const normalizedUserAgent = normalizeString(record.userAgent);
+        const normalizedRecord = {
+            ...record,
+            deviceId,
+            signingSecret: normalizeRequiredSigningSecret(record.signingSecret),
+            ...(normalizedUserId === undefined ? {} : { userId: normalizedUserId }),
+            ...(normalizedUserAgent === undefined ? {} : { userAgent: normalizedUserAgent }),
+        };
+        const insertPayload = buildInsertPayload(normalizedRecord);
+        const updatePayload = buildUpdatePayload(normalizedRecord);
+        const insertColumns = Object.keys(insertPayload);
+        const insertValues = insertColumns.map((column) => insertPayload[column]);
+        const insertSql = buildIgnoreInsert(db, table, insertColumns, ['device_id']);
         try {
-            await db.table(table).where('device_id', '=', record.deviceId).update(payload);
-            const existing = await db
-                .table(table)
-                .where('device_id', '=', record.deviceId)
-                .first();
-            if (existing === null) {
-                await db.table(table).insert(payload);
-            }
-            const stored = await db
-                .table(table)
-                .where('device_id', '=', record.deviceId)
-                .first();
-            const normalized = stored === null ? null : toStoredRecord(stored);
-            if (normalized === null) {
-                throw ErrorFactory.createConfigError('Bulletproof device store returned an invalid record', {
-                    table,
-                    deviceId: record.deviceId,
-                });
-            }
-            return normalized;
+            return await db.transaction(async (transactionDb) => {
+                await transactionDb.table(table).where('device_id', '=', deviceId).update(updatePayload);
+                try {
+                    await transactionDb.execute(insertSql, insertValues);
+                }
+                catch (error) {
+                    const duplicateMessage = getErrorMessage(error).toLowerCase();
+                    const isDuplicateKeyError = duplicateMessage.includes('duplicate') ||
+                        duplicateMessage.includes('unique constraint') ||
+                        duplicateMessage.includes('unique failed') ||
+                        duplicateMessage.includes('duplicate key');
+                    if (!isDuplicateKeyError) {
+                        throw error;
+                    }
+                }
+                const stored = await transactionDb
+                    .table(table)
+                    .where('device_id', '=', deviceId)
+                    .first();
+                const normalized = stored === null ? null : toStoredRecord(stored);
+                if (normalized === null) {
+                    throw createInvalidStoredRecordError(table, deviceId);
+                }
+                return normalized;
+            });
         }
         catch (error) {
-            throw createMissingTableError(table, error);
+            throw createStoreError(table, 'upsert', error, { deviceId });
         }
     },
     async removeByDeviceId(deviceId) {
@@ -121,11 +231,12 @@ export const BulletproofDeviceStore = Object.freeze({
             return;
         const db = useDatabase(undefined, getConnection());
         const table = getTable();
+        const normalizedDeviceId = deviceId.trim();
         try {
-            await db.table(table).where('device_id', '=', deviceId.trim()).delete();
+            await db.table(table).where('device_id', '=', normalizedDeviceId).delete();
         }
         catch (error) {
-            throw createMissingTableError(table, error);
+            throw createStoreError(table, 'delete', error, { deviceId: normalizedDeviceId });
         }
     },
 });

package/src/security/JwtVerifier.d.ts

@@ -0,0 +1,75 @@
+import type { JwtPayload } from './JwtManager';
+export type JwtVerifierAlgorithm = 'RS256';
+type JwtVerifierJsonWebKey = Readonly<{
+    alg?: string;
+    crv?: string;
+    d?: string;
+    dp?: string;
+    dq?: string;
+    e?: string;
+    ext?: boolean;
+    k?: string;
+    key_ops?: string[];
+    kid?: string;
+    kty?: string;
+    n?: string;
+    oth?: unknown[];
+    p?: string;
+    q?: string;
+    qi?: string;
+    use?: string;
+    x?: string;
+    x5c?: string[];
+    x5t?: string;
+    'x5t#S256'?: string;
+    x5u?: string;
+    y?: string;
+}>;
+export type JwtVerifierJwk = JwtVerifierJsonWebKey & Readonly<{
+    kid?: string;
+    alg?: string;
+    use?: string;
+}>;
+export type JwtVerifierJwksDocument = Readonly<{
+    keys: readonly JwtVerifierJwk[];
+}>;
+export type JwtVerifierFailureReason = 'invalid_token_format' | 'invalid_header' | 'invalid_payload' | 'missing_kid' | 'key_not_found' | 'jwks_fetch_failed' | 'invalid_jwks' | 'unsupported_algorithm' | 'invalid_jwk' | 'invalid_signature' | 'issuer_mismatch' | 'audience_mismatch' | 'token_expired' | 'token_not_yet_valid';
+export type JwtVerifierFailure = Readonly<{
+    ok: false;
+    reason: JwtVerifierFailureReason;
+    message: string;
+    details?: unknown;
+}>;
+export type JwtVerifierSuccess = Readonly<{
+    ok: true;
+    payload: JwtPayload;
+    header: Readonly<Record<string, unknown>>;
+    jwk: JwtVerifierJwk;
+    cacheHit?: boolean;
+}>;
+export type JwtVerifierResult = JwtVerifierSuccess | JwtVerifierFailure;
+export type JwtVerifierCommonInput = Readonly<{
+    token: string;
+    algorithm?: JwtVerifierAlgorithm;
+    issuer?: string | readonly string[];
+    audience?: string | readonly string[];
+    nowMs?: number;
+}>;
+export type JwtVerifierWithJwkInput = JwtVerifierCommonInput & Readonly<{
+    jwk: JwtVerifierJwk;
+}>;
+export type JwtVerifierWithJwksInput = JwtVerifierCommonInput & Readonly<{
+    jwksUrl: string;
+    cacheKey?: string;
+    cacheTtlSeconds?: number;
+    fetcher?: typeof fetch;
+}>;
+export declare const JwtVerifier: Readonly<{
+    clearCache: (cacheKey?: string) => void;
+    verifyWithJwk: (input: JwtVerifierWithJwkInput) => Promise<JwtPayload>;
+    verifyWithJwkResult: (input: JwtVerifierWithJwkInput) => Promise<JwtVerifierResult>;
+    verifyWithJwks: (input: JwtVerifierWithJwksInput) => Promise<JwtPayload>;
+    verifyWithJwksResult: (input: JwtVerifierWithJwksInput) => Promise<JwtVerifierResult>;
+}>;
+export default JwtVerifier;
+//# sourceMappingURL=JwtVerifier.d.ts.map

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

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

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 => {