expediate 1.0.4 → 1.0.6

package/dist/jwt-auth.js

@@ -1,4 +1,3 @@
-"use strict";
 /* Copyright 2021 Fabien Bavent
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
@@ -25,30 +24,24 @@
  * JWT authentication plugin for the Expediate router.
  *
  * Provides:
- * - Stateless access tokens (HS256 / HS384 / HS512 HMAC-signed JWTs).
- * - Opaque refresh tokens with server-side storage and automatic rotation.
+ * - Stateless access tokens signed with HS256/HS384/HS512 (shared secret) or
+ *   RS256/RS384/RS512/ES256/ES384/ES512 (asymmetric PEM key pairs).
+ * - Signed JWT refresh tokens with JTI-based server-side revocation.
  * - Route handlers for login, token refresh, and logout.
  * - Middleware for token validation, authorisation, role checks, and
  *   permission checks.
+ * - A `createMapTokenStore()` factory for in-process token storage.
  *
  * Security notes:
  * - Passwords are hashed with SHA-256 for demonstration purposes only.
  *   Replace with bcrypt / argon2 in production.
  * - The default secrets are placeholders — always override them in production.
- * - Refresh token storage defaults to an in-process Map; replace with a
- *   persistent store (Redis, database) for multi-instance deployments.
+ * - `createMapTokenStore()` is an in-process store; replace with a Redis or
+ *   database adapter for multi-instance deployments.
+ * - Refresh tokens are only issued when `refreshTokenStore` is configured.
+ *   Absence of a store disables refresh-token support entirely.
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.userDatabase = void 0;
-exports.hashPassword = hashPassword;
-exports._hashPassword = hashPassword;
-exports.createJwtPlugin = createJwtPlugin;
-exports.signToken = signToken;
-exports.verifyToken = verifyToken;
-const crypto_1 = __importDefault(require("crypto"));
+import crypto from 'crypto';
 // ---------------------------------------------------------------------------
 // Sample user database (replace or extend for real applications)
 // ---------------------------------------------------------------------------
@@ -61,8 +54,8 @@ const crypto_1 = __importDefault(require("crypto"));
  * @param password - The plain-text password to hash.
  * @returns A 64-character lowercase hex string.
  */
-function hashPassword(password) {
-    return crypto_1.default.createHash('sha256').update(password).digest('hex');
+export function hashPassword(password) {
+    return crypto.createHash('sha256').update(password).digest('hex');
 }
 /**
  * Default in-memory user database used when no custom `fetchUser` is
@@ -71,7 +64,7 @@ function hashPassword(password) {
  *
  * Replace or ignore this map entirely when you supply your own `fetchUser`.
  */
-exports.userDatabase = new Map([
+export const userDatabase = new Map([
     ['alice', {
             id: 'usr_001',
             username: 'alice',
@@ -95,8 +88,50 @@ exports.userDatabase = new Map([
         }],
 ]);
 // ---------------------------------------------------------------------------
+// Token store factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an in-process {@link TokenStore} backed by a `Map`.
+ *
+ * Expired records are cleaned up lazily on `get()` — no background timer is
+ * needed.  This store is **not** suitable for multi-instance deployments
+ * because it is local to the current Node.js process.  Replace with a Redis
+ * or database adapter for production use.
+ *
+ * @returns A new {@link TokenStore} instance.
+ */
+export function createMapTokenStore() {
+    const map = new Map();
+    return {
+        set(jti, record) {
+            map.set(jti, record);
+        },
+        get(jti) {
+            const record = map.get(jti);
+            if (!record)
+                return undefined;
+            // Lazy expiry — clean up the record if it has passed its expiry time.
+            if (Date.now() > record.expiresAt) {
+                map.delete(jti);
+                return undefined;
+            }
+            return record;
+        },
+        delete(jti) {
+            map.delete(jti);
+        },
+        deleteBySubject(sub) {
+            for (const [jti, record] of map) {
+                if (record.sub === sub)
+                    map.delete(jti);
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
 // Default configuration
 // ---------------------------------------------------------------------------
+/** Default configuration values (refreshTokenStore absent — refresh disabled). */
 const DEFAULT_CONFIG = {
     accessTokenSecret: 'access-secret-change-in-production',
     refreshTokenSecret: 'refresh-secret-change-in-production',
@@ -106,21 +141,145 @@ const DEFAULT_CONFIG = {
     checkIssuer: false,
     alg: 'HS256',
     username: (user) => user.username,
-    fetchUser: (username) => exports.userDatabase.get(username),
-    // BUG FIX: the original callback was named `checkPassword` and returned
-    // `true` when the password was WRONG (inverted logic). Renamed to
-    // `isPasswordValid` and inverted so it returns `true` on a match.
+    fetchUser: (sub) => userDatabase.get(sub),
     isPasswordValid: (user, password) => user.passwordHash === hashPassword(password),
     payload: (user) => ({
-        sub: user.id,
-        username: user.username,
+        sub: user.username,
         roles: user.roles,
         permissions: user.permissions,
     }),
-    refreshTokenStore: new Map(),
 };
 // ---------------------------------------------------------------------------
-// JWT utilities — manual Base64URL implementation
+// Algorithm helpers
+// ---------------------------------------------------------------------------
+/** True for HMAC-based algorithms (HS256 / HS384 / HS512). */
+function isHmac(alg) { return alg.startsWith('H'); }
+/** True for ECDSA-based algorithms (ES256 / ES384 / ES512). */
+function isEc(alg) { return alg.startsWith('E'); }
+/**
+ * Return the Node.js crypto hash algorithm string for a JwtAlgorithm.
+ * e.g. 'RS256' → 'SHA256', 'ES384' → 'SHA384'.
+ */
+function nodeHashAlg(alg) { return `SHA${alg.slice(2)}`; }
+/**
+ * Return the fixed byte length of each scalar (r or s) for an ECDSA curve.
+ *
+ * | Algorithm | Curve | Byte length |
+ * |-----------|-------|-------------|
+ * | ES256     | P-256 | 32          |
+ * | ES384     | P-384 | 48          |
+ * | ES512     | P-521 | 66          |
+ */
+function ecByteLength(alg) {
+    if (alg === 'ES256')
+        return 32;
+    if (alg === 'ES384')
+        return 48;
+    if (alg === 'ES512')
+        return 66;
+    throw new Error(`Not an EC algorithm: ${alg}`);
+}
+// ---------------------------------------------------------------------------
+// DER ↔ JOSE signature conversion (ECDSA only)
+// ---------------------------------------------------------------------------
+/**
+ * Encode a DER length field.
+ * Uses short form for values < 128, otherwise one- or two-byte long form.
+ */
+function encodeDerLength(len) {
+    if (len < 128)
+        return Buffer.from([len]);
+    if (len < 256)
+        return Buffer.from([0x81, len]);
+    return Buffer.from([0x82, len >> 8, len & 0xff]);
+}
+/**
+ * Convert a DER-encoded ECDSA signature (as produced by Node.js
+ * `crypto.sign()`) into the compact IEEE P1363 / JOSE format required by JWT:
+ * the concatenation of the fixed-width big-endian encodings of `r` and `s`.
+ *
+ * DER structure: `SEQUENCE { INTEGER r, INTEGER s }`
+ *
+ * @param der - DER-encoded ECDSA signature buffer.
+ * @param alg - ECDSA algorithm identifier used to determine the byte width.
+ * @returns A buffer of length `2 * ecByteLength(alg)`.
+ */
+function derToJose(der, alg) {
+    const n = ecByteLength(alg);
+    let i = 0;
+    // SEQUENCE tag (0x30)
+    if (der[i++] !== 0x30)
+        throw new Error('ECDSA DER: expected SEQUENCE tag 0x30');
+    // SEQUENCE length (may be multi-byte for ES512)
+    if (der[i] & 0x80)
+        i += (der[i] & 0x7f) + 1;
+    else
+        i++;
+    /** Parse a single DER INTEGER and return its unsigned value as a Buffer. */
+    function readInt() {
+        if (der[i++] !== 0x02)
+            throw new Error('ECDSA DER: expected INTEGER tag 0x02');
+        let len = der[i++];
+        if (len & 0x80) {
+            const nb = len & 0x7f;
+            len = 0;
+            for (let k = 0; k < nb; k++)
+                len = (len << 8) | der[i++];
+        }
+        // Skip the leading 0x00 padding byte used to mark a positive integer.
+        if (der[i] === 0x00 && len > 1) {
+            i++;
+            len--;
+        }
+        const val = der.slice(i, i + len);
+        i += len;
+        return val;
+    }
+    const r = readInt();
+    const s = readInt();
+    const out = Buffer.alloc(2 * n, 0);
+    // Right-align within each fixed-width half (leading zeros already in buf).
+    r.copy(out, n - r.length);
+    s.copy(out, 2 * n - s.length);
+    return out;
+}
+/**
+ * Convert a compact IEEE P1363 / JOSE ECDSA signature (as used in JWT) back
+ * to the DER format expected by Node.js `crypto.verify()`.
+ *
+ * @param jose - Buffer of length `2 * ecByteLength(alg)` containing `r || s`.
+ * @param alg  - ECDSA algorithm identifier used to determine the byte width.
+ * @returns A DER-encoded ECDSA signature buffer.
+ */
+function joseToDer(jose, alg) {
+    const n = ecByteLength(alg);
+    const r = jose.slice(0, n);
+    const s = jose.slice(n);
+    /**
+     * Encode an unsigned integer as a DER INTEGER:
+     * strips leading zeros, prepends 0x00 when the MSB would be set,
+     * then wraps with tag (0x02) and length.
+     */
+    function encodeInt(buf) {
+        // Trim leading zeros (but keep at least one byte).
+        let start = 0;
+        while (start < buf.length - 1 && buf[start] === 0x00)
+            start++;
+        const trimmed = buf.slice(start);
+        // Prepend 0x00 if the MSB would be interpreted as a sign bit.
+        const padded = (trimmed[0] & 0x80)
+            ? Buffer.concat([Buffer.from([0x00]), trimmed])
+            : trimmed;
+        return Buffer.concat([Buffer.from([0x02, padded.length]), padded]);
+    }
+    const rDer = encodeInt(r);
+    const sDer = encodeInt(s);
+    const content = Buffer.concat([rDer, sDer]);
+    const lenBuf = encodeDerLength(content.length);
+    return Buffer.concat([Buffer.from([0x30]), lenBuf, content]);
+}
+// ---------------------------------------------------------------------------
+// JWT utilities — manual Base64URL + sign/verify implementation
 // ---------------------------------------------------------------------------
 /**
  * Encode an arbitrary object as a Base64URL-encoded JSON string, suitable
@@ -148,53 +307,91 @@ function base64UrlDecode(str) {
     return JSON.parse(Buffer.from(padded.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
 }
 /**
- * Compute the Base64URL-encoded HMAC signature for a JWT.
+ * Compute the Base64URL-encoded signature for a JWT signing input
+ * (`"<encodedHeader>.<encodedPayload>"`).
  *
- * Receives the **already-encoded** header and payload strings (i.e. the
- * first two dot-separated segments of the token) and signs the
- * `"<header>.<payload>"` string with the given secret.
+ * Dispatches to the correct signing primitive based on `alg`:
+ * - **HS*** — `crypto.createHmac()` with `key` as shared secret.
+ * - **RS*** — `crypto.sign()` with `key` as PEM RSA private key (PKCS#1 v1.5).
+ * - **ES*** — `crypto.sign()` with `key` as PEM EC private key; the resulting
+ *   DER-encoded signature is converted to compact JOSE (P1363) format.
  *
- * Currently supports the HS (HMAC-SHA) family: `HS256`, `HS384`, `HS512`.
+ * @param encodedHeader  - Base64URL-encoded JWT header.
+ * @param encodedPayload - Base64URL-encoded JWT payload.
+ * @param key            - HMAC secret (HS*) or PEM private key (RS* / ES*).
+ * @param alg            - JWT algorithm identifier.
+ * @returns Base64URL-encoded signature string.
+ */
+function computeSignature(encodedHeader, encodedPayload, key, alg) {
+    const signingInput = `${encodedHeader}.${encodedPayload}`;
+    if (isHmac(alg)) {
+        return crypto
+            .createHmac(`sha${alg.slice(2)}`, key)
+            .update(signingInput)
+            .digest('base64')
+            .replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+    }
+    // Asymmetric: RS* or ES*
+    const hashAlg = nodeHashAlg(alg); // e.g. 'SHA256'
+    const derOrRaw = crypto.sign(hashAlg, Buffer.from(signingInput), key);
+    const sigBytes = isEc(alg) ? derToJose(derOrRaw, alg) : derOrRaw;
+    return sigBytes.toString('base64')
+        .replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+/**
+ * Verify the signature of a JWT against the provided key.
+ *
+ * For HS* algorithms: computes the expected HMAC and compares using
+ * `crypto.timingSafeEqual()` to prevent timing attacks.
+ *
+ * For RS* / ES* algorithms: converts the Base64URL signature back to the format
+ * expected by Node.js (`raw` for RSA, `DER` for ECDSA) then calls
+ * `crypto.verify()`.
  *
- * @param encodedHeader  - Base64URL-encoded JWT header string.
- * @param encodedPayload - Base64URL-encoded JWT payload string.
- * @param secret         - HMAC secret key.
- * @param alg            - Algorithm identifier (must be HS256, HS384, or HS512).
- * @returns A Base64URL-encoded signature string.
- * @throws {Error} When `alg` is not a supported HS algorithm.
+ * @param encodedHeader  - Base64URL-encoded JWT header.
+ * @param encodedPayload - Base64URL-encoded JWT payload.
+ * @param b64sig         - Base64URL-encoded signature from the token.
+ * @param key            - HMAC secret (HS*) or PEM public key (RS* / ES*).
+ * @param alg            - JWT algorithm identifier.
+ * @returns `true` when the signature is valid, `false` otherwise.
  */
-function createSignature(encodedHeader, encodedPayload, secret, alg) {
-    // BUG FIX: the original code called `header.alg` where `header` was already
-    // a Base64URL *string*, not a decoded object. Accessing `.alg` on a string
-    // always returns `undefined`, causing every signature to fail. The algorithm
-    // is now passed explicitly as a parameter instead of being read from the header.
-    const shaVariant = `sha${alg.substring(2)}`; // 'sha256', 'sha384', 'sha512'
-    return crypto_1.default
-        .createHmac(shaVariant, secret)
-        .update(`${encodedHeader}.${encodedPayload}`)
-        .digest('base64')
-        .replace(/=/g, '')
-        .replace(/\+/g, '-')
-        .replace(/\//g, '_');
+function checkSignature(encodedHeader, encodedPayload, b64sig, key, alg) {
+    if (isHmac(alg)) {
+        const expected = computeSignature(encodedHeader, encodedPayload, key, alg);
+        const sigBuf = Buffer.from(b64sig);
+        const expectedBuf = Buffer.from(expected);
+        return sigBuf.length === expectedBuf.length &&
+            crypto.timingSafeEqual(sigBuf, expectedBuf);
+    }
+    // Asymmetric verification.
+    try {
+        const hashAlg = nodeHashAlg(alg);
+        const rawSig = Buffer.from(b64sig.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+        const verBuf = isEc(alg) ? joseToDer(rawSig, alg) : rawSig;
+        const input = Buffer.from(`${encodedHeader}.${encodedPayload}`);
+        return crypto.verify(hashAlg, input, key, verBuf);
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Sign a payload object and return a compact JWT string.
  *
- * Automatically adds the `iat` (issued-at) and `exp` (expiration) claims.
- * Any claims already present in `payload` are preserved and take precedence
- * over `iat`/`exp` (use this to override expiry if needed).
+ * Automatically adds the `iat` (issued-at) and `exp` (expiration) claims,
+ * overriding any values already present in `payload`.
  *
  * @param payload   - JWT payload claims (must be JSON-serialisable).
- * @param secret    - HMAC secret used to sign the token.
+ * @param key       - HMAC secret (HS*) or PEM private key (RS* / ES*).
  * @param expiresIn - Validity window in **seconds** from the current time.
  * @param alg       - Signing algorithm. Defaults to `'HS256'`.
  * @returns A compact JWT string in the form `header.payload.signature`.
  */
-function signToken(payload, secret, expiresIn, alg = 'HS256') {
+function signToken(payload, key, expiresIn, alg = 'HS256') {
     const now = Math.floor(Date.now() / 1000);
     const encodedHeader = base64UrlEncode({ alg, typ: 'JWT' });
     const fullPayload = base64UrlEncode({ ...payload, iat: now, exp: now + expiresIn });
-    const signature = createSignature(encodedHeader, fullPayload, secret, alg);
+    const signature = computeSignature(encodedHeader, fullPayload, key, alg);
     return `${encodedHeader}.${fullPayload}.${signature}`;
 }
 /**
@@ -203,41 +400,28 @@ function signToken(payload, secret, expiresIn, alg = 'HS256') {
  * Performs the following checks in order:
  * 1. Structural validity (exactly three dot-separated segments).
  * 2. Algorithm consistency (header `alg` matches the expected `alg`).
- * 3. Signature integrity (timing-safe HMAC comparison).
+ * 3. Signature integrity.
  * 4. Expiration (`exp` claim is in the future).
  *
  * All errors are returned as `{ valid: false, error }` — no exception is
  * thrown to the caller.
  *
- * @param token  - The compact JWT string to verify.
- * @param secret - HMAC secret that was used to sign the token.
- * @param alg    - Expected signing algorithm.
+ * @param token - The compact JWT string to verify.
+ * @param key   - HMAC secret (HS*) or PEM public key (RS* / ES*).
+ * @param alg   - Expected signing algorithm.
  * @returns A {@link VerifyResult} discriminated union.
  */
-function verifyToken(token, secret, alg) {
+function verifyToken(token, key, alg) {
     try {
         const parts = token.split('.');
         if (parts.length !== 3)
             return { valid: false, error: 'Invalid token format' };
         const [encodedHeader, encodedPayload, signature] = parts;
-        // BUG FIX: the original code accessed `header.alg` where `header` is a
-        // Base64URL *string*. `.alg` on a string is always `undefined`, so the
-        // algorithm check always failed and every token was rejected. The header
-        // must be decoded first.
         const decodedHeader = base64UrlDecode(encodedHeader);
         if (decodedHeader.alg !== alg)
             return { valid: false, error: 'Unauthorised signing algorithm' };
-        const expectedSig = createSignature(encodedHeader, encodedPayload, secret, alg);
-        // BUG FIX: `timingSafeEqual` requires both Buffers to have the same
-        // length. When a forged token has a signature of a different length,
-        // Node throws a RangeError instead of returning `false`. Guard against
-        // this by checking lengths before calling timingSafeEqual.
-        const sigBuf = Buffer.from(signature);
-        const expectedBuf = Buffer.from(expectedSig);
-        if (sigBuf.length !== expectedBuf.length ||
-            !crypto_1.default.timingSafeEqual(sigBuf, expectedBuf)) {
+        if (!checkSignature(encodedHeader, encodedPayload, signature, key, alg))
             return { valid: false, error: 'Invalid signature' };
-        }
         const payload = base64UrlDecode(encodedPayload);
         const now = Math.floor(Date.now() / 1000);
         if (payload.exp && payload.exp < now)
@@ -248,63 +432,101 @@ function verifyToken(token, secret, alg) {
         return { valid: false, error: 'Malformed token' };
     }
 }
-/**
- * Generate a cryptographically secure opaque refresh token.
- *
- * The token is 128 hex characters (64 random bytes), providing 512 bits of
- * entropy — far beyond any brute-force threat.
- *
- * @returns A 128-character lowercase hex string.
- */
-function generateRefreshToken() {
-    return crypto_1.default.randomBytes(64).toString('hex');
-}
 // ---------------------------------------------------------------------------
 // Business logic
 // ---------------------------------------------------------------------------
+/**
+ * Resolve the key used to **sign** access tokens.
+ * Returns the PEM private key for RS* / ES* algorithms, or the shared secret
+ * for HS* algorithms.
+ */
+function accessSignKey(cfg) {
+    return isHmac(cfg.alg)
+        ? cfg.accessTokenSecret
+        : (cfg.accessTokenPrivateKey);
+}
+/**
+ * Resolve the key used to **verify** access tokens.
+ * Returns the PEM public key for RS* / ES* algorithms, or the shared secret
+ * for HS* algorithms.
+ */
+function accessVerifyKey(cfg) {
+    return isHmac(cfg.alg)
+        ? cfg.accessTokenSecret
+        : (cfg.accessTokenPublicKey);
+}
+/**
+ * Resolve the key used to **sign** refresh tokens.
+ * Falls back to the access-token private key when no refresh-specific key
+ * is configured.
+ */
+function refreshSignKey(cfg) {
+    return isHmac(cfg.alg)
+        ? cfg.refreshTokenSecret
+        : (cfg.refreshTokenPrivateKey ?? cfg.accessTokenPrivateKey);
+}
+/**
+ * Resolve the key used to **verify** refresh tokens.
+ * Falls back to the access-token public key when no refresh-specific key
+ * is configured.
+ */
+function refreshVerifyKey(cfg) {
+    return isHmac(cfg.alg)
+        ? cfg.refreshTokenSecret
+        : (cfg.refreshTokenPublicKey ?? cfg.accessTokenPublicKey);
+}
 /**
  * Authenticate a user by username and password and, on success, issue a new
- * access + refresh token pair.
+ * access token (and refresh token if a store is configured).
  *
  * @param username - The username supplied by the client.
  * @param password - The plain-text password supplied by the client.
  * @param config   - Resolved plugin configuration.
  * @returns An {@link AuthResult} discriminated union.
  */
-function authenticateUser(username, password, config) {
-    const user = config.fetchUser(username);
+async function authenticateUser(username, password, config) {
+    const user = await config.fetchUser(username);
     if (!user)
         return { success: false, error: 'User not found' };
-    // BUG FIX: the original used `checkPassword` which returned `true` when
-    // the password was WRONG (negated logic). `isPasswordValid` returns `true`
-    // when the password is correct.
-    if (!config.isPasswordValid(user, password))
+    if (!await config.isPasswordValid(user, password))
         return { success: false, error: 'Incorrect password' };
     return issueTokenPair(user, config);
 }
 /**
- * Build and store a new access + refresh token pair for the given user.
+ * Build and store a new access token (and refresh token) for the given user.
  *
- * The refresh token is stored in `config.refreshTokenStore` with its
- * expiration timestamp so it can be validated on subsequent renewal requests.
+ * When `config.refreshTokenStore` is absent no refresh token is issued and
+ * the response omits the `refreshToken` field.  When a store is present, a
+ * signed JWT refresh token is generated with a UUID v4 `jti` claim, the
+ * corresponding record is written to the store, and the full token string is
+ * returned.
  *
  * @param user   - The authenticated user record.
  * @param config - Resolved plugin configuration.
  * @returns An {@link AuthResult} with `success: true`.
  */
-function issueTokenPair(user, config) {
-    const username = config.username(user);
-    const claims = config.payload(user);
+async function issueTokenPair(user, config) {
+    const claims = await config.payload(user);
     // Inject standard claims; caller-supplied claims take precedence.
     const fullClaims = {
-        sub: username, // fallback subject — overridden by payload() if it sets sub
+        sub: config.username(user), // fallback subject — overridden by payload() if it sets sub
         ...claims,
         iss: config.issuer,
     };
-    const accessToken = signToken(fullClaims, config.accessTokenSecret, config.accessTokenExpiry, config.alg);
-    const refreshToken = generateRefreshToken();
-    config.refreshTokenStore.set(refreshToken, {
-        username,
+    const accessToken = signToken(fullClaims, accessSignKey(config), config.accessTokenExpiry, config.alg);
+    if (!config.refreshTokenStore) {
+        // No store configured — issue access token only.
+        return { success: true, accessToken, expiresIn: config.accessTokenExpiry, tokenType: 'Bearer' };
+    }
+    // Issue a signed JWT refresh token identified by a unique JTI.
+    const jti = crypto.randomUUID();
+    const sub = fullClaims.sub;
+    const refreshClaims = {
+        sub, jti, type: 'refresh', iss: config.issuer,
+    };
+    const refreshToken = signToken(refreshClaims, refreshSignKey(config), config.refreshTokenExpiry, config.alg);
+    await config.refreshTokenStore.set(jti, {
+        sub,
         issuedAt: Date.now(),
         expiresAt: Date.now() + config.refreshTokenExpiry * 1000,
     });
@@ -317,68 +539,89 @@ function issueTokenPair(user, config) {
     };
 }
 /**
- * Renew an access token using a valid refresh token.
+ * Renew an access token using a valid refresh token JWT.
  *
- * Implements **refresh token rotation**: the presented refresh token is
- * always invalidated and a brand-new pair is issued on success.  This means
- * a stolen refresh token can only be used once before it is invalidated by
- * the legitimate holder's next renewal.
+ * Implements **refresh token rotation**: the presented JTI is always
+ * invalidated and a brand-new pair is issued on success.  A stolen refresh
+ * token can only be used once before it is invalidated by the legitimate
+ * holder's next renewal.
  *
- * @param username     - The username from the renewal request body.
- * @param refreshToken - The opaque refresh token string.
+ * @param refreshToken - The signed JWT refresh token string.
  * @param config       - Resolved plugin configuration.
  * @returns An {@link AuthResult} discriminated union.
  */
-function renewAccessToken(username, refreshToken, config) {
-    const tokenData = config.refreshTokenStore.get(refreshToken);
-    // Verify the token exists and belongs to the claimed user.
-    if (!tokenData || tokenData.username !== username)
+async function renewAccessToken(refreshToken, config) {
+    if (!config.refreshTokenStore)
+        return { success: false, error: 'Refresh tokens are not configured' };
+    // Verify the refresh token JWT (uses refreshVerifyKey, not accessVerifyKey).
+    const result = verifyToken(refreshToken, refreshVerifyKey(config), config.alg);
+    if (!result.valid)
         return { success: false, error: 'Invalid or revoked refresh token' };
-    if (Date.now() > tokenData.expiresAt) {
-        config.refreshTokenStore.delete(refreshToken);
-        return { success: false, error: 'Refresh token expired' };
-    }
-    const user = config.fetchUser(tokenData.username);
+    const refreshPayload = result.payload;
+    if (refreshPayload.type !== 'refresh')
+        return { success: false, error: 'Invalid token type' };
+    const jti = refreshPayload.jti;
+    if (!jti)
+        return { success: false, error: 'Invalid refresh token: missing jti' };
+    // Validate against the store (catches revoked or already-rotated tokens).
+    const record = await config.refreshTokenStore.get(jti);
+    if (!record)
+        return { success: false, error: 'Invalid or revoked refresh token' };
+    const user = await config.fetchUser(record.sub);
     if (!user) {
-        config.refreshTokenStore.delete(refreshToken);
+        await config.refreshTokenStore.delete(jti);
         return { success: false, error: 'User not found' };
     }
-    // Rotate: invalidate the used token before issuing a new pair.
-    config.refreshTokenStore.delete(refreshToken);
+    // Rotate: invalidate the consumed JTI before issuing a new pair.
+    await config.refreshTokenStore.delete(jti);
     return issueTokenPair(user, config);
 }
 /**
- * Revoke a refresh token, preventing it from being used to obtain new access
- * tokens.  Idempotent — revoking an already-revoked token is not an error.
+ * Revoke a refresh token by extracting its JTI and removing it from the
+ * store.  Idempotent — revoking an already-revoked or malformed token is not
+ * an error.
  *
- * @param refreshToken - The opaque refresh token string to revoke.
+ * @param refreshToken - The signed JWT refresh token string to revoke.
  * @param config       - Resolved plugin configuration.
- * @returns `true` if the token existed and was removed, `false` if it was
- *          already absent.
  */
-function revokeRefreshToken(refreshToken, config) {
-    // BUG FIX: the original function referenced `config` as a free variable but
-    // `config` only exists inside `createJwtPlugin`. The function was declared
-    // at module level and crashed with a ReferenceError at runtime. `config` is
-    // now a required parameter.
-    const existed = config.refreshTokenStore.has(refreshToken);
-    config.refreshTokenStore.delete(refreshToken);
-    return existed;
+async function revokeRefreshToken(refreshToken, config) {
+    if (!config.refreshTokenStore)
+        return;
+    const result = verifyToken(refreshToken, refreshVerifyKey(config), config.alg);
+    if (!result.valid)
+        return;
+    const jti = result.payload.jti;
+    if (jti)
+        await config.refreshTokenStore.delete(jti);
 }
 /**
  * Create a JWT authentication plugin pre-configured with the given options.
  *
- * All config fields have safe defaults for development.  At minimum, set
- * `accessTokenSecret` (and `refreshTokenSecret` if you plan to use it) to
- * random values in production.
+ * For **asymmetric algorithms** (RS* / ES*) you must provide at minimum
+ * `accessTokenPrivateKey` and `accessTokenPublicKey` in addition to setting
+ * `alg`.  The refresh-token keys fall back to the access-token keys when
+ * `refreshTokenPrivateKey` / `refreshTokenPublicKey` are not set.
+ *
+ * Refresh tokens are only issued when `refreshTokenStore` is provided.
+ * Use {@link createMapTokenStore} for a simple in-process store.
  *
  * @param userConfig - Partial {@link JwtConfig} overrides.
  * @returns A {@link JwtPlugin} object exposing handlers and middleware.
+ * @throws {Error} When `alg` is RS* or ES* but the required PEM keys are absent.
  */
-function createJwtPlugin(userConfig = {}) {
+export function createJwtPlugin(userConfig = {}) {
     const config = { ...DEFAULT_CONFIG, ...userConfig };
-    // Helper: write a JSON response (our router's res.send() does not add
-    // Content-Type automatically, so we set it manually).
+    // Validate asymmetric key requirements up front.
+    if (!isHmac(config.alg)) {
+        if (!config.accessTokenPrivateKey || !config.accessTokenPublicKey) {
+            throw new Error(`Algorithm '${config.alg}' requires both 'accessTokenPrivateKey' and ` +
+                `'accessTokenPublicKey' in JwtConfig.`);
+        }
+    }
+    /**
+     * Write a JSON response.  Sets `Content-Type` explicitly since the router's
+     * `res.send()` does not add it automatically.
+     */
     function sendJson(res, status, data) {
         const body = JSON.stringify(data);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
@@ -388,55 +631,60 @@ function createJwtPlugin(userConfig = {}) {
     /**
      * Login handler.  Reads `{ username, password }` from `req.body` (requires
      * a JSON body-parsing middleware such as `json()` to run first).
+     * When `refreshTokenStore` is absent the response omits `refreshToken`.
      */
     const login = (req, res) => {
-        const { username, password } = req.body ?? {};
-        if (!username || !password) {
-            sendJson(res, 400, { error: "Fields 'username' and 'password' are required" });
-            return;
-        }
-        const result = authenticateUser(username, password, config);
-        if (!result.success) {
-            sendJson(res, 401, { error: result.error });
-            return;
-        }
-        sendJson(res, 200, {
-            message: 'Authentication successful',
-            accessToken: result.accessToken,
-            refreshToken: result.refreshToken,
-            expiresIn: result.expiresIn,
-            tokenType: result.tokenType,
-        });
+        (async () => {
+            const { username, password } = (req.body ?? {});
+            if (!username || !password) {
+                sendJson(res, 400, { error: "Fields 'username' and 'password' are required" });
+                return;
+            }
+            const result = await authenticateUser(username, password, config);
+            if (!result.success) {
+                sendJson(res, 401, { error: result.error });
+                return;
+            }
+            const body = {
+                message: 'Authentication successful',
+                accessToken: result.accessToken,
+                expiresIn: result.expiresIn,
+                tokenType: result.tokenType,
+            };
+            if (result.refreshToken !== undefined)
+                body.refreshToken = result.refreshToken;
+            sendJson(res, 200, body);
+        })().catch(() => sendJson(res, 500, { error: 'Internal server error' }));
     };
     // ── POST /auth/refresh ──────────────────────────────────────────────────
     /**
-     * Token-renewal handler.  Reads `{ username, refreshToken }` from
-     * `req.body`.
-     *
-     * BUG FIX: the original accepted a renewal request without `username`,
-     * allowing `renewAccessToken(undefined, token, config)` to be called.
-     * Because `tokenData.username !== undefined` is always `true` for any real
-     * token, any holder of a refresh token could silently impersonate its owner.
-     * `username` is now validated as a required field.
+     * Token-renewal handler.  Reads `{ refreshToken }` from `req.body`.
+     * Responds with 501 when no `refreshTokenStore` is configured.
      */
     const refresh = (req, res) => {
-        const { username, refreshToken } = req.body ?? {};
-        if (!username || !refreshToken) {
-            sendJson(res, 400, { error: "Fields 'username' and 'refreshToken' are required" });
-            return;
-        }
-        const result = renewAccessToken(username, refreshToken, config);
-        if (!result.success) {
-            sendJson(res, 401, { error: result.error });
-            return;
-        }
-        sendJson(res, 200, {
-            message: 'Token renewed successfully',
-            accessToken: result.accessToken,
-            refreshToken: result.refreshToken,
-            expiresIn: result.expiresIn,
-            tokenType: result.tokenType,
-        });
+        (async () => {
+            if (!config.refreshTokenStore) {
+                sendJson(res, 501, { error: 'Refresh tokens are not configured' });
+                return;
+            }
+            const { refreshToken } = (req.body ?? {});
+            if (!refreshToken) {
+                sendJson(res, 400, { error: "Field 'refreshToken' is required" });
+                return;
+            }
+            const result = await renewAccessToken(refreshToken, config);
+            if (!result.success) {
+                sendJson(res, 401, { error: result.error });
+                return;
+            }
+            sendJson(res, 200, {
+                message: 'Token renewed successfully',
+                accessToken: result.accessToken,
+                refreshToken: result.refreshToken,
+                expiresIn: result.expiresIn,
+                tokenType: result.tokenType,
+            });
+        })().catch(() => sendJson(res, 500, { error: 'Internal server error' }));
     };
     // ── POST /auth/logout ───────────────────────────────────────────────────
     /**
@@ -445,41 +693,36 @@ function createJwtPlugin(userConfig = {}) {
      * provided (to avoid leaking information about token existence).
      */
     const logout = (req, res) => {
-        const { refreshToken } = req.body ?? {};
-        if (refreshToken) {
-            // BUG FIX: the original called `revokeRefreshToken(refreshToken)` without
-            // passing `config`, which caused a ReferenceError because `config` is a
-            // local variable inside `createJwtPlugin`.
-            revokeRefreshToken(refreshToken, config);
-        }
-        sendJson(res, 200, { message: 'Logged out successfully' });
+        (async () => {
+            const { refreshToken } = (req.body ?? {});
+            if (refreshToken && config.refreshTokenStore) {
+                await revokeRefreshToken(refreshToken, config);
+            }
+            sendJson(res, 200, { message: 'Logged out successfully' });
+        })().catch(() => sendJson(res, 500, { error: 'Internal server error' }));
     };
     // ── authenticate middleware ─────────────────────────────────────────────
     /**
      * Validate the `Authorization: Bearer <token>` header and populate
-     * `req.user` with the decoded payload.
+     * `req.user` with the decoded access-token payload.
      *
      * Designed to be **non-blocking**: missing or invalid tokens cause `next()`
      * to be called without error, deferring the authentication decision to the
      * next middleware (typically {@link authorize} or a custom guard).
      *
      * `req.user` is explicitly cleared at the start of each invocation to
-     * prevent stale data from leaking across requests in unusual server setups.
+     * prevent stale data from leaking across requests.
      */
     const authenticate = (req, res, next) => {
         // Always clear any previously set user to prevent cross-request contamination.
         delete req.user;
-        const authHeader = req.headers['authorization'];
+        const authHeader = req.headers.authorization;
         if (!authHeader?.startsWith('Bearer '))
             return next();
         const token = authHeader.slice(7);
-        const result = verifyToken(token, config.accessTokenSecret, config.alg);
+        const result = verifyToken(token, accessVerifyKey(config), config.alg);
         if (!result.valid)
             return next();
-        // BUG FIX: the original compared `result.payload` (an object) to
-        // `config.issuer` (a string) with `!=`, which is always `true`, causing
-        // every token to be rejected when `checkIssuer` was enabled.
-        // The correct check reads the `iss` claim from the decoded payload.
         if (config.checkIssuer && result.payload.iss !== config.issuer)
             return next();
         req.user = result.payload;
@@ -505,9 +748,6 @@ function createJwtPlugin(userConfig = {}) {
      *
      * Responds with 401 when unauthenticated, 403 when none of the required
      * roles are present.
-     *
-     * BUG FIX: the original accessed `req.user.roles` without first checking
-     * that `req.user` exists, throwing a TypeError for unauthenticated requests.
      */
     function requireRole(...roles) {
         return [
@@ -537,8 +777,6 @@ function createJwtPlugin(userConfig = {}) {
      * **all** of the specified permissions.
      *
      * Responds with 401 when unauthenticated, 403 when any permission is absent.
-     *
-     * BUG FIX: same `req.user` undefined-access issue as `requireRole`.
      */
     function requirePermission(...permissions) {
         return [
@@ -571,5 +809,7 @@ function createJwtPlugin(userConfig = {}) {
         requirePermission,
     };
 }
-exports.default = createJwtPlugin;
+export default createJwtPlugin;
+// Re-export low-level utilities for testing and advanced use cases.
+export { signToken, verifyToken, hashPassword as _hashPassword };
 //# sourceMappingURL=jwt-auth.js.map