expediate 1.0.0 → 1.0.1

package/dist/jwt-auth.js

@@ -1,575 +0,0 @@
-"use strict";
-/* Copyright 2021 Fabien Bavent
- *
- * Permission is hereby granted, free of charge, to any person obtaining a
- * copy of this software and associated documentation files (the "Software"),
- * to deal in the Software without restriction, including without limitation
- * the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the
- * Software is furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included
- * in all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
- * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
- * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
- * DEALINGS IN THE SOFTWARE.
- */
-/**
- * jwt-auth.ts
- *
- * 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.
- * - Route handlers for login, token refresh, and logout.
- * - Middleware for token validation, authorisation, role checks, and
- *   permission checks.
- *
- * 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.
- */
-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"));
-// ---------------------------------------------------------------------------
-// Sample user database (replace or extend for real applications)
-// ---------------------------------------------------------------------------
-/**
- * Hash a plain-text password with SHA-256 and return the hex digest.
- *
- * > **⚠ Warning:** SHA-256 is fast and therefore unsuitable for password
- * > hashing in production.  Use bcrypt or argon2 instead.
- *
- * @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');
-}
-/**
- * Default in-memory user database used when no custom `fetchUser` is
- * provided.  Contains three demo accounts: alice (admin), bob (editor),
- * charlie (viewer).
- *
- * Replace or ignore this map entirely when you supply your own `fetchUser`.
- */
-exports.userDatabase = new Map([
-    ['alice', {
-            id: 'usr_001',
-            username: 'alice',
-            passwordHash: hashPassword('password123'),
-            roles: ['admin', 'editor'],
-            permissions: ['read', 'write', 'delete', 'manage_users'],
-        }],
-    ['bob', {
-            id: 'usr_002',
-            username: 'bob',
-            passwordHash: hashPassword('secret456'),
-            roles: ['editor'],
-            permissions: ['read', 'write'],
-        }],
-    ['charlie', {
-            id: 'usr_003',
-            username: 'charlie',
-            passwordHash: hashPassword('pass789'),
-            roles: ['viewer'],
-            permissions: ['read'],
-        }],
-]);
-// ---------------------------------------------------------------------------
-// Default configuration
-// ---------------------------------------------------------------------------
-const DEFAULT_CONFIG = {
-    accessTokenSecret: 'access-secret-change-in-production',
-    refreshTokenSecret: 'refresh-secret-change-in-production',
-    accessTokenExpiry: 15 * 60, // 15 minutes
-    refreshTokenExpiry: 7 * 24 * 3600, // 7 days
-    issuer: 'jwt-auth',
-    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.
-    isPasswordValid: (user, password) => user.passwordHash === hashPassword(password),
-    payload: (user) => ({
-        sub: user.id,
-        username: user.username,
-        roles: user.roles,
-        permissions: user.permissions,
-    }),
-    refreshTokenStore: new Map(),
-};
-// ---------------------------------------------------------------------------
-// JWT utilities — manual Base64URL implementation
-// ---------------------------------------------------------------------------
-/**
- * Encode an arbitrary object as a Base64URL-encoded JSON string, suitable
- * for use as a JWT header or payload segment.
- *
- * @param data - Any JSON-serialisable value.
- * @returns A Base64URL string with no padding characters.
- */
-function base64UrlEncode(data) {
-    return Buffer.from(JSON.stringify(data))
-        .toString('base64')
-        .replace(/=/g, '')
-        .replace(/\+/g, '-')
-        .replace(/\//g, '_');
-}
-/**
- * Decode a Base64URL-encoded JWT segment and parse it as JSON.
- *
- * @param str - A Base64URL string (padding optional).
- * @returns The parsed JSON value.
- * @throws When the string is not valid Base64URL JSON.
- */
-function base64UrlDecode(str) {
-    const padded = str + '='.repeat((4 - (str.length % 4)) % 4);
-    return JSON.parse(Buffer.from(padded.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
-}
-/**
- * Compute the Base64URL-encoded HMAC signature for a JWT.
- *
- * 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.
- *
- * Currently supports the HS (HMAC-SHA) family: `HS256`, `HS384`, `HS512`.
- *
- * @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.
- */
-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, '_');
-}
-/**
- * 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).
- *
- * @param payload   - JWT payload claims (must be JSON-serialisable).
- * @param secret    - HMAC secret used to sign the token.
- * @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') {
-    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);
-    return `${encodedHeader}.${fullPayload}.${signature}`;
-}
-/**
- * Verify a compact JWT string and return its decoded payload on success.
- *
- * 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).
- * 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.
- * @returns A {@link VerifyResult} discriminated union.
- */
-function verifyToken(token, secret, 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)) {
-            return { valid: false, error: 'Invalid signature' };
-        }
-        const payload = base64UrlDecode(encodedPayload);
-        const now = Math.floor(Date.now() / 1000);
-        if (payload.exp && payload.exp < now)
-            return { valid: false, error: 'Token expired' };
-        return { valid: true, payload };
-    }
-    catch {
-        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
-// ---------------------------------------------------------------------------
-/**
- * Authenticate a user by username and password and, on success, issue a new
- * access + refresh token pair.
- *
- * @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);
-    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))
-        return { success: false, error: 'Incorrect password' };
-    return issueTokenPair(user, config);
-}
-/**
- * Build and store a new access + refresh token pair 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.
- *
- * @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);
-    // Inject standard claims; caller-supplied claims take precedence.
-    const fullClaims = {
-        sub: username, // 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,
-        issuedAt: Date.now(),
-        expiresAt: Date.now() + config.refreshTokenExpiry * 1000,
-    });
-    return {
-        success: true,
-        accessToken,
-        refreshToken,
-        expiresIn: config.accessTokenExpiry,
-        tokenType: 'Bearer',
-    };
-}
-/**
- * Renew an access token using a valid refresh token.
- *
- * 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.
- *
- * @param username     - The username from the renewal request body.
- * @param refreshToken - The opaque 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)
-        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);
-    if (!user) {
-        config.refreshTokenStore.delete(refreshToken);
-        return { success: false, error: 'User not found' };
-    }
-    // Rotate: invalidate the used token before issuing a new pair.
-    config.refreshTokenStore.delete(refreshToken);
-    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.
- *
- * @param refreshToken - The opaque 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;
-}
-/**
- * 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.
- *
- * @param userConfig - Partial {@link JwtConfig} overrides.
- * @returns A {@link JwtPlugin} object exposing handlers and middleware.
- */
-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).
-    function sendJson(res, status, data) {
-        const body = JSON.stringify(data);
-        res.setHeader('Content-Type', 'application/json; charset=utf-8');
-        res.status(status).send(body);
-    }
-    // ── POST /auth/login ────────────────────────────────────────────────────
-    /**
-     * Login handler.  Reads `{ username, password }` from `req.body` (requires
-     * a JSON body-parsing middleware such as `json()` to run first).
-     */
-    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,
-        });
-    };
-    // ── 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.
-     */
-    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,
-        });
-    };
-    // ── POST /auth/logout ───────────────────────────────────────────────────
-    /**
-     * Logout handler.  Optionally reads `{ refreshToken }` from `req.body` and
-     * revokes it.  Always responds with 200 regardless of whether a token was
-     * 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' });
-    };
-    // ── authenticate middleware ─────────────────────────────────────────────
-    /**
-     * Validate the `Authorization: Bearer <token>` header and populate
-     * `req.user` with the decoded 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.
-     */
-    const authenticate = (req, res, next) => {
-        // Always clear any previously set user to prevent cross-request contamination.
-        delete req.user;
-        const authHeader = req.headers['authorization'];
-        if (!authHeader?.startsWith('Bearer '))
-            return next();
-        const token = authHeader.slice(7);
-        const result = verifyToken(token, config.accessTokenSecret, 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;
-        next();
-    };
-    // ── authorize middleware ────────────────────────────────────────────────
-    /**
-     * Reject the request with 401 when `req.user` is not set.
-     * Always place this **after** {@link authenticate}.
-     */
-    const authorize = (req, res, next) => {
-        if (!req.user) {
-            sendJson(res, 401, { error: 'Authentication required' });
-            return;
-        }
-        next();
-    };
-    // ── requireRole factory ─────────────────────────────────────────────────
-    /**
-     * Return a two-element middleware chain `[authenticate, roleCheck]` that
-     * allows the request to proceed only when the authenticated user holds at
-     * least one of the specified roles.
-     *
-     * 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 [
-            authenticate,
-            (req, res, next) => {
-                const user = req.user;
-                if (!user) {
-                    sendJson(res, 401, { error: 'Authentication required' });
-                    return;
-                }
-                const userRoles = user.roles ?? [];
-                if (!roles.some((r) => userRoles.includes(r))) {
-                    sendJson(res, 403, {
-                        error: `Access denied. Required role(s): ${roles.join(', ')}`,
-                        yourRoles: userRoles,
-                    });
-                    return;
-                }
-                next();
-            },
-        ];
-    }
-    // ── requirePermission factory ───────────────────────────────────────────
-    /**
-     * Return a two-element middleware chain `[authenticate, permCheck]` that
-     * allows the request to proceed only when the authenticated user holds
-     * **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 [
-            authenticate,
-            (req, res, next) => {
-                const user = req.user;
-                if (!user) {
-                    sendJson(res, 401, { error: 'Authentication required' });
-                    return;
-                }
-                const userPerms = user.permissions ?? [];
-                if (!permissions.every((p) => userPerms.includes(p))) {
-                    sendJson(res, 403, {
-                        error: `Insufficient permissions. Required: ${permissions.join(', ')}`,
-                        yourPermissions: userPerms,
-                    });
-                    return;
-                }
-                next();
-            },
-        ];
-    }
-    return {
-        login,
-        refresh,
-        logout,
-        authenticate,
-        authorize,
-        requireRole,
-        requirePermission,
-    };
-}
-exports.default = createJwtPlugin;
-//# sourceMappingURL=jwt-auth.js.map