@fluojs/jwt 1.0.0-beta.1

package/dist/refresh/refresh-token.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { JwtConfigurationError, JwtExpiredTokenError, JwtInvalidTokenError } from '../errors.js';
+export function normalizeRefreshTokenOptions(options) {
+  if (!options) {
+    throw new JwtConfigurationError('JWT refresh token options are not configured.');
+  }
+  if (typeof options.secret !== 'string' || options.secret.length === 0) {
+    throw new JwtConfigurationError('JWT refresh token secret must be a non-empty string.');
+  }
+  if (!Number.isFinite(options.expiresInSeconds) || options.expiresInSeconds <= 0) {
+    throw new JwtConfigurationError('JWT refresh token expiresInSeconds must be a positive finite number.');
+  }
+  if (options.verifyMaxAgeSeconds !== undefined && (!Number.isFinite(options.verifyMaxAgeSeconds) || options.verifyMaxAgeSeconds < 0)) {
+    throw new JwtConfigurationError('JWT refresh token verifyMaxAgeSeconds must be a non-negative finite number.');
+  }
+  if (options.rotation && typeof options.store.consume !== 'function') {
+    throw new JwtConfigurationError('Refresh token rotation requires an atomic store.consume() implementation.');
+  }
+  return {
+    ...options
+  };
+}
+export class RefreshTokenService {
+  options;
+  constructor(options, signer, verifier) {
+    this.signer = signer;
+    this.verifier = verifier;
+    this.options = normalizeRefreshTokenOptions(options);
+  }
+  async issueRefreshToken(subject) {
+    const family = randomUUID();
+    return this.issueRefreshTokenWithFamily(subject, family);
+  }
+  async rotateRefreshToken(currentToken) {
+    const claims = await this.verifyRefreshClaims(currentToken);
+    if (this.options.rotation) {
+      if (!this.options.store.consume) {
+        throw new JwtConfigurationError('Refresh token rotation requires an atomic store.consume() implementation.');
+      }
+      const consumeResult = await this.options.store.consume({
+        family: claims.family,
+        now: new Date(),
+        subject: claims.sub,
+        tokenId: claims.jti
+      });
+      if (consumeResult === 'consumed') {
+        const refreshToken = await this.issueRefreshTokenWithFamily(claims.sub, claims.family);
+        const accessToken = await this.signer.signAccessToken({
+          sub: claims.sub
+        });
+        return {
+          accessToken,
+          refreshToken
+        };
+      }
+      if (consumeResult === 'already_used') {
+        await this.options.store.revokeBySubject(claims.sub);
+        throw new JwtInvalidTokenError('Refresh token reuse detected.');
+      }
+      if (consumeResult === 'expired') {
+        throw new JwtExpiredTokenError('Refresh token has expired.');
+      }
+      if (consumeResult === 'not_found' || consumeResult === 'invalid') {
+        throw new JwtInvalidTokenError('Refresh token record was not found.');
+      }
+      throw new JwtInvalidTokenError('Refresh token record does not match token claims.');
+    }
+    const record = await this.options.store.find(claims.jti);
+    if (!record) {
+      throw new JwtInvalidTokenError('Refresh token record was not found.');
+    }
+    if (record.subject !== claims.sub || record.family !== claims.family) {
+      throw new JwtInvalidTokenError('Refresh token record does not match token claims.');
+    }
+    if (record.expiresAt.getTime() <= Date.now()) {
+      throw new JwtExpiredTokenError('Refresh token has expired.');
+    }
+    if (record.used) {
+      await this.options.store.revokeBySubject(record.subject);
+      throw new JwtInvalidTokenError('Refresh token reuse detected.');
+    }
+    const accessToken = await this.signer.signAccessToken({
+      sub: record.subject
+    });
+    return {
+      accessToken,
+      refreshToken: currentToken
+    };
+  }
+  async revokeRefreshToken(tokenId) {
+    await this.options.store.revoke(tokenId);
+  }
+  async revokeAllForSubject(subject) {
+    await this.options.store.revokeBySubject(subject);
+  }
+  async issueRefreshTokenWithFamily(subject, family) {
+    const now = Math.floor(Date.now() / 1000);
+    const tokenId = randomUUID();
+    const expiresAt = new Date((now + this.options.expiresInSeconds) * 1000);
+    const tokenRecord = {
+      createdAt: new Date(now * 1000),
+      expiresAt,
+      family,
+      id: tokenId,
+      subject,
+      used: false
+    };
+    const claims = {
+      exp: Math.floor(expiresAt.getTime() / 1000),
+      family,
+      iat: now,
+      jti: tokenId,
+      sub: subject,
+      type: 'refresh'
+    };
+    const refreshToken = await this.signer.signRefreshToken(claims);
+    await this.options.store.save(tokenRecord);
+    return refreshToken;
+  }
+  async verifyRefreshClaims(token) {
+    const principal = await this.verifier.verifyRefreshToken(token);
+    const claims = principal.claims;
+    if (claims.type !== 'refresh') {
+      throw new JwtInvalidTokenError('JWT is not a refresh token.');
+    }
+    if (typeof claims.jti !== 'string' || claims.jti.length === 0) {
+      throw new JwtInvalidTokenError('Refresh token is missing jti.');
+    }
+    if (typeof claims.family !== 'string' || claims.family.length === 0) {
+      throw new JwtInvalidTokenError('Refresh token is missing family.');
+    }
+    if (typeof claims.sub !== 'string' || claims.sub.length === 0) {
+      throw new JwtInvalidTokenError('Refresh token is missing sub.');
+    }
+    return {
+      ...claims,
+      family: claims.family,
+      jti: claims.jti,
+      sub: claims.sub,
+      type: 'refresh'
+    };
+  }
+}

package/dist/service.d.ts

@@ -0,0 +1,149 @@
+import { DefaultJwtSigner } from './signing/signer.js';
+import type { JwtVerifierOptions } from './types.js';
+import { DefaultJwtVerifier } from './signing/verifier.js';
+type DurationUnit = 's' | 'm' | 'h' | 'd';
+/**
+ * Per-call claim overrides accepted by {@link JwtService.sign}.
+ *
+ * Use these options when one token needs narrower issuer, audience, subject, or
+ * lifetime semantics than the module-level signer defaults.
+ */
+export interface SignOptions {
+    /**
+     * Overrides the token `aud` claim for this signing call.
+     *
+     * Match this with the verifier-side `audience` expectation to prevent a token
+     * minted for one consumer from being accepted by another.
+     */
+    audience?: JwtVerifierOptions['audience'];
+    /**
+     * Sets the token lifetime relative to the current clock.
+     *
+     * Accepts seconds or a short duration literal such as `"60s"`, `"15m"`,
+     * `"1h"`, or `"7d"`.
+     */
+    expiresIn?: number | `${number}${DurationUnit}`;
+    /**
+     * Overrides the token `iss` claim for this signing call.
+     *
+     * Keep issuer values stable so downstream verifiers can reject tokens from
+     * unexpected environments or services.
+     */
+    issuer?: string;
+    /**
+     * Sets the `nbf` claim as a NumericDate in seconds.
+     *
+     * Tokens remain invalid until the verifier clock reaches this timestamp.
+     */
+    notBefore?: number;
+    /**
+     * Overrides the token `sub` claim for this signing call.
+     */
+    subject?: string;
+}
+/**
+ * Per-call verification overrides accepted by {@link JwtService.verify}.
+ *
+ * These options are merged on top of the module-level verifier policy for the
+ * current token check only.
+ */
+export interface VerifyOptions {
+    /**
+     * Restricts which JWT algorithms are allowed for this verification call.
+     */
+    algorithms?: JwtVerifierOptions['algorithms'];
+    /**
+     * Expected `aud` claim value or values.
+     *
+     * Provide this when a token should only be accepted for a specific API or
+     * client boundary.
+     */
+    audience?: JwtVerifierOptions['audience'];
+    /**
+     * Permitted clock skew in seconds when evaluating `exp`, `nbf`, and age-based
+     * checks.
+     */
+    clockSkewSeconds?: number;
+    /**
+     * Expected `iss` claim value for this verification call.
+     */
+    issuer?: string;
+    /**
+     * Maximum acceptable token age in seconds, calculated from the `iat` claim.
+     *
+     * When set, tokens without a finite `iat` claim are rejected.
+     */
+    maxAge?: number;
+    /**
+     * Controls whether `exp` must be present on the token.
+     *
+     * Leave this enabled for access tokens unless the issuing system explicitly
+     * documents a different contract.
+     */
+    requireExp?: boolean;
+}
+/**
+ * NestJS-style facade over Fluo's default JWT signer and verifier.
+ *
+ * @remarks
+ * This class keeps the low-level JWT behavior from {@link DefaultJwtSigner} and
+ * {@link DefaultJwtVerifier}, but exposes a smaller `sign` / `verify` /
+ * `decode` surface for applications migrating from similar auth service
+ * patterns.
+ */
+export declare class JwtService {
+    private readonly options;
+    private readonly signer;
+    private readonly verifier;
+    constructor(options: JwtVerifierOptions, signer: DefaultJwtSigner, verifier: DefaultJwtVerifier);
+    /**
+     * Signs a JWT access token from arbitrary claim payload plus optional claim overrides.
+     *
+     * @example
+     * ```ts
+     * const token = await jwtService.sign(
+     *   { role: 'admin' },
+     *   { audience: 'admin-ui', expiresIn: '15m', subject: 'user-123' },
+     * );
+     * ```
+     *
+     * @param payload Base JWT claims to embed in the token payload.
+     * @param options Optional per-call overrides for `aud`, `iss`, `sub`, `nbf`, and `exp`.
+     * @returns A signed JWT string suitable for bearer-token transport.
+     * @throws {Error} When `options.expiresIn` is not a supported non-negative duration.
+     */
+    sign(payload: object, options?: SignOptions): Promise<string>;
+    /**
+     * Verifies a JWT and returns the decoded claim bag typed as `T`.
+     *
+     * @example
+     * ```ts
+     * const claims = await jwtService.verify<{ sub: string; scope?: string }>(token, {
+     *   audience: 'admin-ui',
+     *   issuer: 'my-api',
+     *   requireExp: true,
+     * });
+     * ```
+     *
+     * @param token Compact JWT string to verify.
+     * @param options Optional per-call verifier overrides layered on top of module defaults.
+     * @returns The verified token claims cast to the requested generic type.
+     * @throws {JwtInvalidTokenError} When the token is malformed or violates issuer/audience/claim requirements.
+     * @throws {JwtExpiredTokenError} When the token is expired or exceeds `maxAge`.
+     * @throws {JwtConfigurationError} When the active verifier configuration cannot validate the token.
+     */
+    verify<T = unknown>(token: string, options?: VerifyOptions): Promise<T>;
+    /**
+     * Decodes the JWT payload segment without verifying signature or claims.
+     *
+     * @remarks
+     * Use this only for diagnostics or non-authoritative inspection. Call
+     * {@link JwtService.verify} before trusting any returned claim value.
+     *
+     * @param token Compact JWT string to inspect.
+     * @returns The decoded payload object, or `null` when the token is malformed.
+     */
+    decode(token: string): unknown;
+}
+export {};
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAa,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAe,MAAM,uBAAuB,CAAC;AAExE,KAAK,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAoD1C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,MAAM,GAAG,YAAY,EAAE,CAAC;IAChD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBACa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,kBAAkB;IAG/C;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBnE;;;;;;;;;;;;;;;;;;OAkBG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC;IAiB7E;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAmB/B"}

package/dist/service.js

@@ -0,0 +1,175 @@
+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 { Inject } from '@fluojs/core';
+import { DefaultJwtSigner } from './signing/signer.js';
+import { DefaultJwtVerifier, JWT_OPTIONS } from './signing/verifier.js';
+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 parseDurationUnitToSeconds(unit) {
+  switch (unit) {
+    case 's':
+      return 1;
+    case 'm':
+      return 60;
+    case 'h':
+      return 60 * 60;
+    case 'd':
+      return 60 * 60 * 24;
+  }
+}
+function parseExpiresInSeconds(expiresIn) {
+  if (expiresIn === undefined) {
+    return undefined;
+  }
+  if (typeof expiresIn === 'number') {
+    if (!Number.isFinite(expiresIn) || expiresIn < 0) {
+      throw new Error('JwtService.sign() options.expiresIn must be a non-negative finite number.');
+    }
+    return Math.floor(expiresIn);
+  }
+  const trimmed = expiresIn.trim();
+  const match = trimmed.match(/^(\d+)([smhd])$/i);
+  if (!match) {
+    throw new Error('JwtService.sign() options.expiresIn must be a number or duration string like "60s", "15m", "1h", "7d".');
+  }
+  const value = Number.parseInt(match[1] ?? '', 10);
+  const rawUnit = match[2]?.toLowerCase();
+  if (!rawUnit || !['s', 'm', 'h', 'd'].includes(rawUnit)) {
+    throw new Error('JwtService.sign() options.expiresIn uses an unsupported duration unit.');
+  }
+  return value * parseDurationUnitToSeconds(rawUnit);
+}
+
+/**
+ * Per-call claim overrides accepted by {@link JwtService.sign}.
+ *
+ * Use these options when one token needs narrower issuer, audience, subject, or
+ * lifetime semantics than the module-level signer defaults.
+ */
+
+/**
+ * Per-call verification overrides accepted by {@link JwtService.verify}.
+ *
+ * These options are merged on top of the module-level verifier policy for the
+ * current token check only.
+ */
+let _JwtService;
+/**
+ * NestJS-style facade over Fluo's default JWT signer and verifier.
+ *
+ * @remarks
+ * This class keeps the low-level JWT behavior from {@link DefaultJwtSigner} and
+ * {@link DefaultJwtVerifier}, but exposes a smaller `sign` / `verify` /
+ * `decode` surface for applications migrating from similar auth service
+ * patterns.
+ */
+class JwtService {
+  static {
+    [_JwtService, _initClass] = _applyDecs(this, [Inject(JWT_OPTIONS, DefaultJwtSigner, DefaultJwtVerifier)], []).c;
+  }
+  constructor(options, signer, verifier) {
+    this.options = options;
+    this.signer = signer;
+    this.verifier = verifier;
+  }
+
+  /**
+   * Signs a JWT access token from arbitrary claim payload plus optional claim overrides.
+   *
+   * @example
+   * ```ts
+   * const token = await jwtService.sign(
+   *   { role: 'admin' },
+   *   { audience: 'admin-ui', expiresIn: '15m', subject: 'user-123' },
+   * );
+   * ```
+   *
+   * @param payload Base JWT claims to embed in the token payload.
+   * @param options Optional per-call overrides for `aud`, `iss`, `sub`, `nbf`, and `exp`.
+   * @returns A signed JWT string suitable for bearer-token transport.
+   * @throws {Error} When `options.expiresIn` is not a supported non-negative duration.
+   */
+  async sign(payload, options) {
+    const now = Math.floor(Date.now() / 1000);
+    const expiresInSeconds = parseExpiresInSeconds(options?.expiresIn);
+    const claims = {
+      ...payload,
+      aud: options?.audience ?? payload.aud,
+      exp: expiresInSeconds !== undefined ? now + expiresInSeconds : payload.exp,
+      iss: options?.issuer ?? payload.iss,
+      nbf: options?.notBefore ?? payload.nbf,
+      sub: options?.subject ?? payload.sub
+    };
+    return this.signer.signAccessToken(claims);
+  }
+
+  /**
+   * Verifies a JWT and returns the decoded claim bag typed as `T`.
+   *
+   * @example
+   * ```ts
+   * const claims = await jwtService.verify<{ sub: string; scope?: string }>(token, {
+   *   audience: 'admin-ui',
+   *   issuer: 'my-api',
+   *   requireExp: true,
+   * });
+   * ```
+   *
+   * @param token Compact JWT string to verify.
+   * @param options Optional per-call verifier overrides layered on top of module defaults.
+   * @returns The verified token claims cast to the requested generic type.
+   * @throws {JwtInvalidTokenError} When the token is malformed or violates issuer/audience/claim requirements.
+   * @throws {JwtExpiredTokenError} When the token is expired or exceeds `maxAge`.
+   * @throws {JwtConfigurationError} When the active verifier configuration cannot validate the token.
+   */
+  async verify(token, options) {
+    const verifier = options ? new DefaultJwtVerifier({
+      ...this.options,
+      algorithms: options.algorithms ?? this.options.algorithms,
+      audience: options.audience ?? this.options.audience,
+      clockSkewSeconds: options.clockSkewSeconds ?? this.options.clockSkewSeconds,
+      issuer: options.issuer ?? this.options.issuer,
+      maxAge: options.maxAge ?? this.options.maxAge,
+      requireExp: options.requireExp ?? this.options.requireExp
+    }) : this.verifier;
+    const principal = await verifier.verifyAccessToken(token);
+    return principal.claims;
+  }
+
+  /**
+   * Decodes the JWT payload segment without verifying signature or claims.
+   *
+   * @remarks
+   * Use this only for diagnostics or non-authoritative inspection. Call
+   * {@link JwtService.verify} before trusting any returned claim value.
+   *
+   * @param token Compact JWT string to inspect.
+   * @returns The decoded payload object, or `null` when the token is malformed.
+   */
+  decode(token) {
+    const segments = token.split('.');
+    if (segments.length !== 3) {
+      return null;
+    }
+    const [, payloadSegment] = segments;
+    if (!payloadSegment) {
+      return null;
+    }
+    try {
+      return JSON.parse(decodeBase64Url(payloadSegment).toString('utf8'));
+    } catch {
+      return null;
+    }
+  }
+  static {
+    _initClass();
+  }
+}
+export { _JwtService as JwtService };

package/dist/signing/jwks.d.ts

@@ -0,0 +1,12 @@
+import { type KeyObject } from 'node:crypto';
+export declare class JwksClient {
+    private readonly uri;
+    private readonly cacheTtl;
+    private readonly requestTimeoutMs;
+    private readonly cache;
+    constructor(uri: string, cacheTtl?: number, requestTimeoutMs?: number);
+    private isAbortError;
+    getSigningKey(kid: string): Promise<KeyObject>;
+    private fetchKeys;
+}
+//# sourceMappingURL=jwks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../../src/signing/jwks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAa9D,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IALnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4D;gBAG/D,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAgB,EAC1B,gBAAgB,GAAE,MAAc;IAGnD,OAAO,CAAC,YAAY;IAId,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;YA+BtC,SAAS;CAqCxB"}

package/dist/signing/jwks.js

@@ -0,0 +1,71 @@
+import { createPublicKey } from 'node:crypto';
+import { JwtConfigurationError, JwtInvalidTokenError } from '../errors.js';
+export class JwksClient {
+  cache = new Map();
+  constructor(uri, cacheTtl = 600_000, requestTimeoutMs = 5_000) {
+    this.uri = uri;
+    this.cacheTtl = cacheTtl;
+    this.requestTimeoutMs = requestTimeoutMs;
+  }
+  isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+  }
+  async getSigningKey(kid) {
+    const now = Date.now();
+    const cached = this.cache.get(kid);
+    if (cached && cached.expiresAt > now) {
+      return cached.key;
+    }
+    const keys = await this.fetchKeys();
+    const jwk = keys.find(entry => entry.kid === kid);
+    if (!jwk) {
+      throw new JwtInvalidTokenError('JWT key id was not found in JWKS.');
+    }
+    let key;
+    try {
+      key = createPublicKey({
+        format: 'jwk',
+        key: jwk
+      });
+    } catch {
+      throw new JwtConfigurationError('Unable to parse JWKS key into a public key.');
+    }
+    this.cache.set(kid, {
+      expiresAt: now + this.cacheTtl,
+      key
+    });
+    return key;
+  }
+  async fetchKeys() {
+    let response;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+      controller.abort();
+    }, this.requestTimeoutMs);
+    try {
+      response = await fetch(this.uri, {
+        signal: controller.signal
+      });
+    } catch (error) {
+      if (this.isAbortError(error)) {
+        throw new JwtConfigurationError(`JWKS fetch timed out after ${String(this.requestTimeoutMs)}ms.`);
+      }
+      throw new JwtConfigurationError(`Failed to fetch JWKS from "${this.uri}".`);
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!response.ok) {
+      throw new JwtConfigurationError(`JWKS endpoint returned HTTP ${response.status}.`);
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new JwtConfigurationError('JWKS endpoint did not return valid JSON.');
+    }
+    if (!Array.isArray(body.keys)) {
+      throw new JwtConfigurationError('JWKS endpoint did not return a keys array.');
+    }
+    return body.keys;
+  }
+}

package/dist/signing/signer.d.ts

@@ -0,0 +1,14 @@
+import type { JwtClaims, JwtVerifierOptions } from '../types.js';
+/**
+ * Issues access and refresh tokens with the configured signing keys and algorithms.
+ */
+export declare class DefaultJwtSigner {
+    private readonly options;
+    private readonly refreshAlgorithms;
+    constructor(options: JwtVerifierOptions);
+    signAccessToken(claims: JwtClaims): Promise<string>;
+    signRefreshToken(claims: JwtClaims): Promise<string>;
+    private resolveRefreshSigningOptions;
+    private signToken;
+}
+//# sourceMappingURL=signer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signing/signer.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,SAAS,EAAe,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAyB5F;;GAEG;AACH,qBACa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;gBAEtB,OAAO,EAAE,kBAAkB;IAMlD,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1D,OAAO,CAAC,4BAA4B;YAYtB,SAAS;CAkFxB"}