@fluojs/jwt 1.0.0-beta.1

package/dist/signing/signer.js

@@ -0,0 +1,124 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { createHmac, createSign } from 'node:crypto';
+import { Inject } from '@fluojs/core';
+import { JwtConfigurationError } from '../errors.js';
+import { normalizeRefreshTokenOptions } from '../refresh/refresh-token.js';
+import { ASYMMETRIC_HASH, HMAC_HASH, JWT_OPTIONS } from './verifier.js';
+function encodeBase64Url(value) {
+  return Buffer.from(value).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function resolveSigningKeyEntry(options, algorithm) {
+  const keys = options.keys;
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return undefined;
+  }
+  if (algorithm in HMAC_HASH) {
+    return keys.find(entry => typeof entry.secret === 'string' && entry.secret.length > 0);
+  }
+  return keys.find(entry => entry.privateKey !== undefined);
+}
+
+/**
+ * Issues access and refresh tokens with the configured signing keys and algorithms.
+ */
+let _DefaultJwtSigner;
+class DefaultJwtSigner {
+  static {
+    [_DefaultJwtSigner, _initClass] = _applyDecs(this, [Inject(JWT_OPTIONS)], []).c;
+  }
+  refreshAlgorithms;
+  constructor(options) {
+    this.options = options;
+    this.refreshAlgorithms = this.options.algorithms.filter(algorithm => algorithm in HMAC_HASH);
+  }
+  async signAccessToken(claims) {
+    return this.signToken(claims, this.options, false);
+  }
+  async signRefreshToken(claims) {
+    const refreshOptions = this.resolveRefreshSigningOptions();
+    return this.signToken(claims, refreshOptions, true);
+  }
+  resolveRefreshSigningOptions() {
+    const refreshToken = normalizeRefreshTokenOptions(this.options.refreshToken);
+    return {
+      audience: this.options.audience,
+      accessTokenTtlSeconds: refreshToken.expiresInSeconds,
+      algorithms: this.refreshAlgorithms,
+      issuer: this.options.issuer,
+      secret: refreshToken.secret
+    };
+  }
+  async signToken(claims, options, hmacOnly) {
+    const algorithm = options.algorithms.find(alg => {
+      if (hmacOnly) {
+        return alg in HMAC_HASH;
+      }
+      return alg in HMAC_HASH || alg in ASYMMETRIC_HASH;
+    });
+    if (!algorithm) {
+      if (hmacOnly) {
+        throw new JwtConfigurationError('JWT refresh token signer requires at least one HMAC algorithm (HS256/HS384/HS512) in the allowed algorithms list.');
+      }
+      throw new JwtConfigurationError('JWT signer requires at least one supported algorithm (HS256/HS384/HS512/RS256/RS384/RS512/ES256/ES384/ES512) in the allowed algorithms list.');
+    }
+    const isAsymmetric = algorithm in ASYMMETRIC_HASH;
+    const now = Math.floor(Date.now() / 1000);
+    const ttl = options.accessTokenTtlSeconds ?? 3600;
+    const payload = {
+      ...claims,
+      aud: claims.aud ?? options.audience,
+      exp: claims.exp ?? now + ttl,
+      iat: claims.iat ?? now,
+      iss: claims.iss ?? options.issuer
+    };
+    const activeKey = resolveSigningKeyEntry(options, algorithm);
+    const header = {
+      alg: algorithm,
+      typ: 'JWT',
+      ...(activeKey ? {
+        kid: activeKey.kid
+      } : {})
+    };
+    const headerSegment = encodeBase64Url(JSON.stringify(header));
+    const payloadSegment = encodeBase64Url(JSON.stringify(payload));
+    const signingInput = `${headerSegment}.${payloadSegment}`;
+    let signatureSegment;
+    if (isAsymmetric) {
+      const privateKey = activeKey?.privateKey ?? options.privateKey;
+      if (!privateKey) {
+        throw new JwtConfigurationError('JWT private key is not configured.');
+      }
+      const hash = ASYMMETRIC_HASH[algorithm];
+      if (!hash) {
+        throw new JwtConfigurationError(`No hash mapping for asymmetric algorithm "${algorithm}".`);
+      }
+      const signer = createSign(hash);
+      signer.update(signingInput);
+      const isEc = algorithm.startsWith('ES');
+      signatureSegment = isEc ? signer.sign({
+        dsaEncoding: 'ieee-p1363',
+        key: privateKey
+      }, 'base64url') : signer.sign(privateKey, 'base64url');
+    } else {
+      const secret = activeKey?.secret ?? options.secret;
+      if (!secret) {
+        throw new JwtConfigurationError('JWT secret is not configured.');
+      }
+      const hash = HMAC_HASH[algorithm];
+      if (!hash) {
+        throw new JwtConfigurationError(`No hash mapping for HMAC algorithm "${algorithm}".`);
+      }
+      signatureSegment = encodeBase64Url(createHmac(hash, secret).update(signingInput).digest());
+    }
+    return `${headerSegment}.${payloadSegment}.${signatureSegment}`;
+  }
+  static {
+    _initClass();
+  }
+}
+export { _DefaultJwtSigner as DefaultJwtSigner };

package/dist/signing/verifier.d.ts

@@ -0,0 +1,38 @@
+import type { JwtAlgorithm, JwtPrincipal, JwtVerifierOptions } from '../types.js';
+/**
+ * Provides the resolved JWT verifier options through dependency injection.
+ */
+export declare const JWT_OPTIONS: unique symbol;
+/**
+ * Maps supported HMAC JWT algorithms to their Node.js hash names.
+ */
+export declare const HMAC_HASH: Partial<Record<JwtAlgorithm, string>>;
+/**
+ * Maps supported asymmetric JWT algorithms to their Node.js hash names.
+ */
+export declare const ASYMMETRIC_HASH: Partial<Record<JwtAlgorithm, string>>;
+/**
+ * Verifies JWT access and refresh tokens against the configured key sources.
+ */
+export declare class DefaultJwtVerifier {
+    private readonly options;
+    private readonly jwksClient;
+    private readonly keyResolutionState;
+    private readonly refreshKeyResolutionState;
+    private readonly refreshVerificationOptions;
+    constructor(options: JwtVerifierOptions);
+    verifyAccessToken(token: string): Promise<JwtPrincipal>;
+    verifyRefreshToken(token: string): Promise<JwtPrincipal>;
+    private createRefreshVerificationOptions;
+    private verifyToken;
+    private parseTokenSegments;
+    private verifyTokenSignature;
+    private verifyHmacTokenSignature;
+    private verifyAsymmetricTokenSignature;
+    private resolveProviderKey;
+    private validateTokenClaims;
+    private validateMaxAgeClaims;
+    private validateIssuerAndAudience;
+    private resolveJwksPublicKey;
+}
+//# sourceMappingURL=verifier.d.ts.map

package/dist/signing/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/signing/verifier.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,WAAW,eAAiC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAI3D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAOjE,CAAC;AAuMF;;GAEG;AACH,qBACa,kBAAkB;IAMjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAqB;IAC/D,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAiC;gBAE/C,OAAO,EAAE,kBAAkB;IAYlD,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIvD,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ9D,OAAO,CAAC,gCAAgC;YAsB1B,WAAW;IA+BzB,OAAO,CAAC,kBAAkB;YAUZ,oBAAoB;YAgBpB,wBAAwB;YAsBxB,8BAA8B;YAsB9B,kBAAkB;IAWhC,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,yBAAyB;YAiBnB,oBAAoB;CAOnC"}

package/dist/signing/verifier.js

@@ -0,0 +1,319 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { createHmac, createVerify, timingSafeEqual } from 'node:crypto';
+import { Inject } from '@fluojs/core';
+import { JwtConfigurationError, JwtExpiredTokenError, JwtInvalidTokenError } from '../errors.js';
+import { JwksClient } from './jwks.js';
+import { normalizeRefreshTokenOptions } from '../refresh/refresh-token.js';
+/**
+ * Provides the resolved JWT verifier options through dependency injection.
+ */
+export const JWT_OPTIONS = Symbol.for('fluo.jwt.options');
+
+/**
+ * Maps supported HMAC JWT algorithms to their Node.js hash names.
+ */
+export const HMAC_HASH = {
+  HS256: 'sha256',
+  HS384: 'sha384',
+  HS512: 'sha512'
+};
+
+/**
+ * Maps supported asymmetric JWT algorithms to their Node.js hash names.
+ */
+export const ASYMMETRIC_HASH = {
+  RS256: 'sha256',
+  RS384: 'sha384',
+  RS512: 'sha512',
+  ES256: 'sha256',
+  ES384: 'sha384',
+  ES512: 'sha512'
+};
+function isAllowedAlgorithm(alg, allowed) {
+  return typeof alg === 'string' && allowed.includes(alg) && (alg in HMAC_HASH || alg in ASYMMETRIC_HASH);
+}
+function isFiniteNumericDate(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+function createKeyResolutionState(keys) {
+  const state = {
+    hmacKeyCount: 0,
+    keyByKid: new Map(),
+    publicKeyCount: 0
+  };
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return state;
+  }
+  for (const entry of keys) {
+    state.keyByKid.set(entry.kid, entry);
+    if (typeof entry.secret === 'string' && entry.secret.length > 0) {
+      state.hmacKeyCount += 1;
+      state.defaultHmacSecret = state.hmacKeyCount === 1 ? entry.secret : undefined;
+    }
+    if (entry.publicKey !== undefined) {
+      state.publicKeyCount += 1;
+      state.defaultPublicKey = state.publicKeyCount === 1 ? entry.publicKey : undefined;
+    }
+  }
+  return state;
+}
+function resolveHmacSecret(options, keyState, kid) {
+  if (typeof kid === 'string' && kid.length > 0) {
+    const matchingKey = keyState.keyByKid.get(kid);
+    if (!matchingKey) {
+      throw new JwtInvalidTokenError('JWT key id (kid) is not recognized.');
+    }
+    if (typeof matchingKey.secret !== 'string' || matchingKey.secret.length === 0) {
+      throw new JwtConfigurationError(`JWT key "${kid}" does not provide an HMAC secret.`);
+    }
+    return matchingKey.secret;
+  }
+  if (keyState.hmacKeyCount > 1) {
+    throw new JwtInvalidTokenError('JWT is missing key id (kid) for multi-key HMAC verification.');
+  }
+  return keyState.defaultHmacSecret ?? options.secret;
+}
+function resolveStaticPublicKey(options, keyState, kid) {
+  if (typeof kid === 'string' && kid.length > 0) {
+    // Only consult keyByKid when a multi-key keys[] array was provided.
+    // When the verifier is configured with a single options.publicKey, the
+    // map is empty and a kid header in the token should be ignored so that
+    // verification proceeds with the single configured key.
+    if (keyState.keyByKid.size > 0) {
+      const matchingKey = keyState.keyByKid.get(kid);
+      if (!matchingKey) {
+        throw new JwtInvalidTokenError('JWT key id (kid) is not recognized.');
+      }
+      if (matchingKey.publicKey === undefined) {
+        throw new JwtConfigurationError(`JWT key "${kid}" does not provide a public key.`);
+      }
+      return matchingKey.publicKey;
+    }
+  }
+  if (keyState.publicKeyCount > 1) {
+    throw new JwtInvalidTokenError('JWT is missing key id (kid) for multi-key public key verification.');
+  }
+  return keyState.defaultPublicKey ?? options.publicKey;
+}
+function verifyHmacSignature(algorithm, secret, signingInput, signatureSegment) {
+  const hash = HMAC_HASH[algorithm];
+  if (!hash) {
+    throw new JwtInvalidTokenError();
+  }
+  const expected = encodeBase64Url(createHmac(hash, secret).update(signingInput).digest());
+  const expectedBuf = Buffer.from(expected, 'base64url');
+  const actualBuf = Buffer.from(signatureSegment, 'base64url');
+  if (expectedBuf.length !== actualBuf.length || !timingSafeEqual(expectedBuf, actualBuf)) {
+    throw new JwtInvalidTokenError();
+  }
+}
+function verifyAsymmetricSignature(algorithm, publicKey, signingInput, signatureSegment) {
+  const hash = ASYMMETRIC_HASH[algorithm];
+  if (!hash) {
+    throw new JwtInvalidTokenError();
+  }
+  const verifier = createVerify(hash);
+  verifier.update(signingInput);
+  const isEc = algorithm.startsWith('ES');
+  const valid = verifier.verify(isEc ? {
+    dsaEncoding: 'ieee-p1363',
+    key: publicKey
+  } : publicKey, signatureSegment, 'base64url');
+  if (!valid) {
+    throw new JwtInvalidTokenError();
+  }
+}
+function decodeBase64Url(value) {
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = normalized.length % 4 === 0 ? '' : '='.repeat(4 - normalized.length % 4);
+  return Buffer.from(normalized + padding, 'base64');
+}
+function parseJwtPart(value) {
+  try {
+    return JSON.parse(decodeBase64Url(value).toString('utf8'));
+  } catch {
+    throw new JwtInvalidTokenError();
+  }
+}
+function encodeBase64Url(value) {
+  return value.toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function normalizePrincipal(claims) {
+  if (typeof claims.sub !== 'string' || claims.sub.length === 0) {
+    throw new JwtInvalidTokenError('JWT is missing a valid subject claim.');
+  }
+  const scopes = Array.isArray(claims.scopes) ? claims.scopes.filter(scope => typeof scope === 'string') : typeof claims.scope === 'string' ? claims.scope.split(' ').filter(Boolean) : undefined;
+  const roles = Array.isArray(claims.roles) ? claims.roles.filter(role => typeof role === 'string') : undefined;
+  return {
+    audience: claims.aud,
+    claims: {
+      ...claims
+    },
+    issuer: claims.iss,
+    roles,
+    scopes,
+    subject: claims.sub
+  };
+}
+
+/**
+ * Verifies JWT access and refresh tokens against the configured key sources.
+ */
+let _DefaultJwtVerifier;
+class DefaultJwtVerifier {
+  static {
+    [_DefaultJwtVerifier, _initClass] = _applyDecs(this, [Inject(JWT_OPTIONS)], []).c;
+  }
+  jwksClient;
+  keyResolutionState;
+  refreshKeyResolutionState;
+  refreshVerificationOptions;
+  constructor(options) {
+    this.options = options;
+    this.jwksClient = options.jwksUri ? new JwksClient(options.jwksUri, options.jwksCacheTtl, options.jwksRequestTimeoutMs) : undefined;
+    this.keyResolutionState = createKeyResolutionState(options.keys);
+    this.refreshVerificationOptions = options.refreshToken ? this.createRefreshVerificationOptions(normalizeRefreshTokenOptions(options.refreshToken)) : undefined;
+    this.refreshKeyResolutionState = createKeyResolutionState(this.refreshVerificationOptions?.keys);
+  }
+  async verifyAccessToken(token) {
+    return this.verifyToken(token, this.options, this.keyResolutionState, this.jwksClient);
+  }
+  async verifyRefreshToken(token) {
+    if (!this.refreshVerificationOptions) {
+      throw new JwtConfigurationError('JWT refresh token options are not configured.');
+    }
+    return this.verifyToken(token, this.refreshVerificationOptions, this.refreshKeyResolutionState, undefined);
+  }
+  createRefreshVerificationOptions(refreshToken) {
+    const algorithms = this.options.algorithms.filter(algorithm => algorithm in HMAC_HASH);
+    if (algorithms.length === 0) {
+      throw new JwtConfigurationError('JWT refresh token verifier requires at least one HMAC algorithm (HS256/HS384/HS512) in the allowed algorithms list.');
+    }
+    return {
+      algorithms,
+      audience: this.options.audience,
+      clockSkewSeconds: this.options.clockSkewSeconds,
+      issuer: this.options.issuer,
+      maxAge: refreshToken.verifyMaxAgeSeconds,
+      requireExp: true,
+      secret: refreshToken.secret
+    };
+  }
+  async verifyToken(token, options, keyResolutionState, jwksClient) {
+    const [headerSegment, payloadSegment, signatureSegment] = this.parseTokenSegments(token);
+    const header = parseJwtPart(headerSegment);
+    const algorithms = options.algorithms;
+    if (!isAllowedAlgorithm(header.alg, algorithms)) {
+      throw new JwtInvalidTokenError('JWT algorithm is not allowed.');
+    }
+    const signingInput = `${headerSegment}.${payloadSegment}`;
+    await this.verifyTokenSignature({
+      ...header,
+      alg: header.alg
+    }, signingInput, signatureSegment, options, keyResolutionState, jwksClient);
+    const payload = parseJwtPart(payloadSegment);
+    this.validateTokenClaims(payload, options);
+    return normalizePrincipal(payload);
+  }
+  parseTokenSegments(token) {
+    const segments = token.split('.');
+    if (segments.length !== 3) {
+      throw new JwtInvalidTokenError();
+    }
+    return segments;
+  }
+  async verifyTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState, jwksClient) {
+    if (header.alg in HMAC_HASH) {
+      await this.verifyHmacTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState);
+      return;
+    }
+    await this.verifyAsymmetricTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState, jwksClient);
+  }
+  async verifyHmacTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState) {
+    const providerKey = await this.resolveProviderKey(options, header);
+    if (providerKey !== undefined && typeof providerKey !== 'string') {
+      throw new JwtConfigurationError('secretOrKeyProvider must return a string for HMAC algorithms.');
+    }
+    const secret = providerKey ?? resolveHmacSecret(options, keyResolutionState, header.kid);
+    if (!secret) {
+      throw new JwtConfigurationError('JWT secret is not configured.');
+    }
+    verifyHmacSignature(header.alg, secret, signingInput, signatureSegment);
+  }
+  async verifyAsymmetricTokenSignature(header, signingInput, signatureSegment, options, keyResolutionState, jwksClient) {
+    const providerKey = await this.resolveProviderKey(options, header);
+    const publicKey = providerKey ?? (jwksClient ? await this.resolveJwksPublicKey(header.kid, jwksClient) : resolveStaticPublicKey(options, keyResolutionState, header.kid));
+    if (!publicKey) {
+      throw new JwtConfigurationError('JWT public key is not configured.');
+    }
+    verifyAsymmetricSignature(header.alg, publicKey, signingInput, signatureSegment);
+  }
+  async resolveProviderKey(options, header) {
+    if (!options.secretOrKeyProvider) {
+      return undefined;
+    }
+    return options.secretOrKeyProvider({
+      ...header
+    });
+  }
+  validateTokenClaims(payload, options) {
+    const now = Math.floor(Date.now() / 1000);
+    const clockSkew = options.clockSkewSeconds ?? 0;
+    if (options.requireExp !== false && typeof payload.exp !== 'number') {
+      throw new JwtInvalidTokenError('JWT is missing a required expiration claim.');
+    }
+    this.validateMaxAgeClaims(payload, options.maxAge, clockSkew, now);
+    if (typeof payload.exp === 'number' && payload.exp + clockSkew < now) {
+      throw new JwtExpiredTokenError();
+    }
+    if (typeof payload.nbf === 'number' && payload.nbf - clockSkew > now) {
+      throw new JwtInvalidTokenError('JWT is not active yet.');
+    }
+    this.validateIssuerAndAudience(payload, options);
+  }
+  validateMaxAgeClaims(payload, maxAge, clockSkew, now) {
+    if (typeof maxAge !== 'number') {
+      return;
+    }
+    if (!Number.isFinite(maxAge) || maxAge < 0) {
+      throw new JwtConfigurationError('JWT maxAge must be a non-negative finite number.');
+    }
+    if (!isFiniteNumericDate(payload.iat)) {
+      throw new JwtInvalidTokenError('JWT iat claim must be a finite numeric date when maxAge is configured.');
+    }
+    if (payload.iat - clockSkew > now) {
+      throw new JwtInvalidTokenError('JWT iat claim cannot be in the future.');
+    }
+    if (now - payload.iat > maxAge + clockSkew) {
+      throw new JwtExpiredTokenError('JWT exceeds maxAge.');
+    }
+  }
+  validateIssuerAndAudience(payload, options) {
+    if (options.issuer && payload.iss !== options.issuer) {
+      throw new JwtInvalidTokenError('JWT issuer does not match.');
+    }
+    if (!options.audience) {
+      return;
+    }
+    const expectedAudience = Array.isArray(options.audience) ? options.audience : [options.audience];
+    const actualAudience = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
+    if (!expectedAudience.some(audience => actualAudience.includes(audience))) {
+      throw new JwtInvalidTokenError('JWT audience does not match.');
+    }
+  }
+  async resolveJwksPublicKey(kid, jwksClient) {
+    if (typeof kid !== 'string' || kid.length === 0) {
+      throw new JwtInvalidTokenError('JWT is missing key id (kid) for JWKS resolution.');
+    }
+    return jwksClient.getSigningKey(kid);
+  }
+  static {
+    _initClass();
+  }
+}
+export { _DefaultJwtVerifier as DefaultJwtVerifier };

package/dist/status.d.ts

@@ -0,0 +1,19 @@
+import type { PlatformDiagnosticIssue, PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+export interface JwtPlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+export interface JwtStatusAdapterInput {
+    componentId?: string;
+    readinessCritical?: boolean;
+    refreshTokenEnabled?: boolean;
+    refreshTokenStoreReady?: boolean;
+    refreshTokenStoreReason?: string;
+    refreshTokenDependencyId?: string;
+    signingKeySource?: 'shared-secret' | 'key-pair' | 'jwks' | 'key-provider';
+}
+export declare function createJwtPlatformStatusSnapshot(input: JwtStatusAdapterInput): JwtPlatformStatusSnapshot;
+export declare function createJwtPlatformDiagnosticIssues(input: JwtStatusAdapterInput): PlatformDiagnosticIssue[];
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,gBAAgB,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,MAAM,GAAG,cAAc,CAAC;CAC3E;AAwCD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,qBAAqB,GAAG,yBAAyB,CA4CvG;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB,EAAE,CAqBzG"}

package/dist/status.js

@@ -0,0 +1,83 @@
+function isRefreshTokenStoreReady(input) {
+  if (!input.refreshTokenEnabled) {
+    return true;
+  }
+  return input.refreshTokenStoreReady ?? true;
+}
+function createReadiness(input) {
+  const critical = input.readinessCritical ?? false;
+  if (isRefreshTokenStoreReady(input)) {
+    return {
+      critical,
+      status: 'ready'
+    };
+  }
+  return {
+    critical,
+    reason: input.refreshTokenStoreReason ?? 'JWT refresh token backing store is unavailable.',
+    status: critical ? 'not-ready' : 'degraded'
+  };
+}
+function createHealth(input) {
+  if (isRefreshTokenStoreReady(input)) {
+    return {
+      status: 'healthy'
+    };
+  }
+  return {
+    reason: input.refreshTokenStoreReason ?? 'JWT refresh token backing store is unavailable.',
+    status: 'degraded'
+  };
+}
+export function createJwtPlatformStatusSnapshot(input) {
+  const componentId = input.componentId ?? 'jwt.default';
+  const refreshStoreReady = isRefreshTokenStoreReady(input);
+  return {
+    details: {
+      policyBoundary: {
+        applicationOwned: ['login credential validation', 'session lifecycle policy', 'consent and account linking orchestration'],
+        frameworkOwned: ['jwt sign/verify primitives', 'claim normalization', 'refresh token primitive lifecycle']
+      },
+      refreshToken: {
+        backingStore: {
+          dependencyId: input.refreshTokenDependencyId,
+          reason: input.refreshTokenStoreReason,
+          ready: refreshStoreReady
+        },
+        enabled: input.refreshTokenEnabled ?? false
+      },
+      signingKeySource: input.signingKeySource ?? 'shared-secret',
+      telemetry: {
+        labels: {
+          component_id: componentId,
+          component_kind: 'jwt',
+          operation: 'token-verify',
+          result: refreshStoreReady ? 'ready' : 'degraded'
+        },
+        namespace: 'jwt'
+      }
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: true,
+      ownsResources: false
+    },
+    readiness: createReadiness(input)
+  };
+}
+export function createJwtPlatformDiagnosticIssues(input) {
+  if (isRefreshTokenStoreReady(input)) {
+    return [];
+  }
+  const componentId = input.componentId ?? 'jwt.default';
+  const critical = input.readinessCritical ?? false;
+  return [{
+    code: 'AUTH_JWT_REFRESH_TOKEN_BACKING_STORE_NOT_READY',
+    componentId,
+    cause: input.refreshTokenStoreReason,
+    dependsOn: input.refreshTokenDependencyId ? [input.refreshTokenDependencyId] : undefined,
+    fixHint: 'Restore refresh-token store connectivity or disable refresh token mode for this environment.',
+    message: critical ? 'JWT refresh token mode is configured as critical, but its backing store is not ready.' : 'JWT refresh token backing store is degraded; access-token verification remains available.',
+    severity: critical ? 'error' : 'warning'
+  }];
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import type { KeyObject } from 'node:crypto';
+import type { RefreshTokenOptions } from './refresh/refresh-token.js';
+export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512';
+export interface JwtKeyEntry {
+    kid: string;
+    secret?: string;
+    privateKey?: string | KeyObject;
+    publicKey?: string | KeyObject;
+}
+export interface JwtVerifierOptions {
+    algorithms: JwtAlgorithm[];
+    accessTokenTtlSeconds?: number;
+    audience?: string | string[];
+    clockSkewSeconds?: number;
+    issuer?: string;
+    jwksCacheTtl?: number;
+    jwksRequestTimeoutMs?: number;
+    jwksUri?: string;
+    keys?: JwtKeyEntry[];
+    maxAge?: number;
+    requireExp?: boolean;
+    secretOrKeyProvider?: (header: {
+        alg: string;
+        kid?: string;
+        [key: string]: unknown;
+    }) => Promise<string | KeyObject>;
+    secret?: string;
+    privateKey?: string | KeyObject;
+    publicKey?: string | KeyObject;
+    refreshToken?: RefreshTokenOptions;
+}
+export interface JwtClaims extends Record<string, unknown> {
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    iss?: string;
+    nbf?: number;
+    scope?: string;
+    scopes?: string[];
+    sub?: string;
+}
+export interface JwtPrincipal {
+    subject: string;
+    issuer?: string;
+    audience?: string | string[];
+    roles?: string[];
+    scopes?: string[];
+    claims: Record<string, unknown>;
+}
+export interface JwtVerifier {
+    verifyAccessToken(token: string): Promise<JwtPrincipal>;
+}
+export interface JwtSigner {
+    signAccessToken(claims: JwtClaims): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED,MAAM,WAAW,SAAU,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,SAAS;IACxB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};