expediate 1.0.4 → 1.0.6

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AAGH,OAAO,YAAY,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,YAAY,EACV,MAAM,EACN,aAAa,EACb,cAAc,EACd,UAAU,EACV,aAAa,EACb,YAAY,EACZ,KAAK,EACL,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,UAAU,CAAC;AAIlB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EACV,aAAa,EACb,IAAI,EACL,MAAM,UAAU,CAAC;AAIlB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC3D,YAAY,EACV,WAAW,EACX,aAAa,EACb,QAAQ,GACT,MAAM,QAAQ,CAAC;AAGhB,OAAO,eAAe,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,CAAA;AAC1B,YAAY,EACV,SAAS,EACT,SAAS,EACV,MAAM,YAAY,CAAC;AAGpB,OAAQ,UAAU,MAAM,OAAO,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,YAAY,EACR,iBAAiB,GACpB,MAAM,OAAO,CAAA;AAGd,OAAO,UAAU,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,YAAY,EACR,QAAQ,EACR,aAAa,EACb,eAAe,EACf,cAAc,EACd,QAAQ,EACR,iBAAiB,EACpB,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AAGH,OAAO,YAAY,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,YAAY,EACV,MAAM,EACN,aAAa,EACb,aAAa,EACb,cAAc,EACd,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,KAAK,EACL,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EACV,aAAa,EACb,IAAI,EACL,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAChI,YAAY,EACV,WAAW,EACX,eAAe,EACf,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,cAAc,EACd,WAAW,GACZ,MAAM,WAAW,CAAC;AAGnB,OAAO,eAAe,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,UAAU,GACX,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACjD,YAAY,EACR,iBAAiB,GACpB,MAAM,UAAU,CAAC;AAGlB,OAAO,UAAU,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACR,QAAQ,EACR,aAAa,EACb,eAAe,EACf,cAAc,EACd,QAAQ,EACR,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,EACL,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,mBAAmB,EACnB,UAAU,GACb,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACnF,YAAY,EACR,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,WAAW,EACX,UAAU,EACV,eAAe,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtH,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,4 +1,3 @@
-"use strict";
 /* Copyright 2021 Fabien Bavent
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
@@ -23,33 +22,25 @@
  * @module expediate
  * TypeScript package for web server routing.
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.apiBuilder = exports.gitHandler = exports.createJwtPlugin = exports.logger = exports.parseBody = exports.formData = exports.json = exports.mime = exports.sendFile = exports.serveFile = exports.serveStatic = exports.createRouter = void 0;
 // ── Router ────────────────────────────────────────────────────────────────────
-const router_1 = __importDefault(require("./router"));
-exports.createRouter = router_1.default;
+import createRouter from './router.js';
+export { createRouter };
 // ── Static ────────────────────────────────────────────────────────────────────
-var static_1 = require("./static");
-Object.defineProperty(exports, "serveStatic", { enumerable: true, get: function () { return static_1.serveStatic; } });
-Object.defineProperty(exports, "serveFile", { enumerable: true, get: function () { return static_1.serveFile; } });
-Object.defineProperty(exports, "sendFile", { enumerable: true, get: function () { return static_1.sendFile; } });
-Object.defineProperty(exports, "mime", { enumerable: true, get: function () { return static_1.mime; } });
+export { serveStatic, serveFile, sendFile, mime } from './static.js';
 // ── Miscallenous ──────────────────────────────────────────────────────────────
-var misc_1 = require("./misc");
-Object.defineProperty(exports, "json", { enumerable: true, get: function () { return misc_1.json; } });
-Object.defineProperty(exports, "formData", { enumerable: true, get: function () { return misc_1.formData; } });
-Object.defineProperty(exports, "parseBody", { enumerable: true, get: function () { return misc_1.parseBody; } });
-Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return misc_1.logger; } });
+export { json, formData, formEncoded, raw, text, parseBody, logger, cors, streamFormData, parseMultipartBody } from './misc.js';
 // ── JWT Authentication ────────────────────────────────────────────────────────
-const jwt_auth_1 = __importDefault(require("./jwt-auth"));
-exports.createJwtPlugin = jwt_auth_1.default;
+import createJwtPlugin from './jwt-auth.js';
+export { createJwtPlugin };
+export { createMapTokenStore } from './jwt-auth.js';
 // ── Git repository ────────────────────────────────────────────────────────────
-const git_1 = __importDefault(require("./git"));
-exports.gitHandler = git_1.default;
+export { gitHandler, gitCreate } from './git.js';
 // ── API Service ───────────────────────────────────────────────────────────────
-const apis_1 = __importDefault(require("./apis"));
-exports.apiBuilder = apis_1.default;
+import apiBuilder from './apis.js';
+export { apiBuilder };
+export { defineController } from './apis.js';
+// ── OpenAPI spec generation ───────────────────────────────────────────────────
+export { describe, openApiSpec, serializeSpec, DESCRIBE_META } from './openapi.js';
+// ── Middleware ────────────────────────────────────────────────────────────────
+export { compress, requestId, rateLimit, cacheControl, csrf, securityHeaders, conditionalGet } from './middleware.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;GAGG;;;;;;AAEH,iFAAiF;AACjF,sDAAoC;AAC3B,uBADF,gBAAY,CACE;AAcrB,iFAAiF;AAEjF,mCAAkE;AAAzD,qGAAA,WAAW,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,kGAAA,QAAQ,OAAA;AAAE,8FAAA,IAAI,OAAA;AAM/C,iFAAiF;AAEjF,+BAA2D;AAAlD,4FAAA,IAAI,OAAA;AAAE,gGAAA,QAAQ,OAAA;AAAE,iGAAA,SAAS,OAAA;AAAE,8FAAA,MAAM,OAAA;AAO1C,iFAAiF;AACjF,0DAAwC;AAC/B,0BADF,kBAAe,CACE;AAMxB,iFAAiF;AACjF,gDAA+B;AACtB,qBADD,aAAU,CACC;AAKnB,iFAAiF;AACjF,kDAA+B;AACtB,qBADF,cAAU,CACE"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;GAGG;AAEH,iFAAiF;AACjF,OAAO,YAAY,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,CAAA;AAmBvB,iFAAiF;AAEjF,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAMrE,iFAAiF;AAEjF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAWhI,iFAAiF;AACjF,OAAO,eAAe,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAUpD,iFAAiF;AACjF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAKjD,iFAAiF;AACjF,OAAO,UAAU,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAiB7C,iFAAiF;AACjF,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAiBnF,iFAAiF;AACjF,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/jwt-auth.d.ts

@@ -4,20 +4,35 @@
  * 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.
  */
 import type { Middleware } from './router.js';
+declare module './router.js' {
+    interface RouterRequest {
+        /**
+         * The decoded access-token payload for the authenticated user, set by the
+         * JWT plugin's {@link JwtPlugin.authenticate} middleware (and cleared at the
+         * start of each `authenticate` run). `undefined` when the request is
+         * unauthenticated.
+         */
+        user?: TokenPayload;
+    }
+}
 /** A user record as stored in (or returned by) the user database. */
 export interface UserRecord {
     /** Stable unique identifier (used as JWT `sub` claim when present). */
@@ -28,7 +43,7 @@ export interface UserRecord {
      * SHA-256 hex digest of the user's password.
      * Replace with a bcrypt/argon2 hash in production.
      */
-    passwordHash: string;
+    passwordHash?: string;
     /** Role labels assigned to this user (e.g. `'admin'`, `'editor'`). */
     roles?: string[];
     /**
@@ -41,13 +56,13 @@ export interface UserRecord {
 }
 /**
  * The decoded JWT access-token payload attached to `req.user` after
- * successful authentication.
+ * successful authentication.  The `sub` claim identifies the user (typically
+ * the username or a stable user ID).  Custom claims returned by
+ * `config.payload` are carried in the index-signature field.
  */
 export interface TokenPayload {
-    /** JWT subject — typically the user's stable ID. */
+    /** JWT subject — the user identifier (username or stable ID). */
     sub: string;
-    /** Username extracted from the user record. */
-    username: string;
     /** Issuer claim, set to `config.issuer`. */
     iss: string;
     /** Issued-at timestamp (Unix seconds). */
@@ -61,41 +76,99 @@ export interface TokenPayload {
     /** Any additional claims produced by `config.payload`. */
     [key: string]: unknown;
 }
-/** Internal metadata stored alongside each active refresh token. */
-interface RefreshTokenData {
-    /** Username the refresh token was issued to. */
-    username: string;
-    /** Unix ms timestamp of issuance. */
+/**
+ * Metadata stored in the token store for each active refresh token.
+ * The key used to address this record is the token's `jti` (JWT ID) claim.
+ */
+export interface RefreshTokenRecord {
+    /** Subject the refresh token was issued to (`sub` from the access token). */
+    sub: string;
+    /** Unix millisecond timestamp of issuance. */
     issuedAt: number;
-    /** Unix ms timestamp after which the token must be rejected. */
+    /** Unix millisecond timestamp after which the token must be rejected. */
     expiresAt: number;
 }
 /**
- * Minimal interface for the refresh-token store.
- * Any object implementing these four methods is accepted (Map, Redis client
- * adapter, database wrapper, etc.).
+ * Async-compatible interface for the refresh-token store.
+ *
+ * The store is addressed by JWT ID (`jti`) — a UUID v4 unique to each
+ * issued refresh token.  Every method may return its result either directly
+ * or as a Promise, enabling both synchronous (Map) and asynchronous (Redis,
+ * database) implementations.
+ *
+ * Cleanup of expired records is the store's responsibility.  The built-in
+ * {@link createMapTokenStore} performs lazy cleanup on `get()`.
  */
 export interface TokenStore {
-    set(key: string, value: RefreshTokenData): void;
-    get(key: string): RefreshTokenData | undefined;
-    delete(key: string): void;
-    has(key: string): boolean;
+    /**
+     * Persist a new refresh-token record.
+     * @param jti    - Unique JWT ID of the issued refresh token.
+     * @param record - Metadata to store alongside the token.
+     */
+    set(jti: string, record: RefreshTokenRecord): void | Promise<void>;
+    /**
+     * Retrieve the record for a given JTI, or `undefined` if not found or
+     * expired.  Implementations are encouraged to delete expired records lazily
+     * here rather than in a background job.
+     * @param jti - JWT ID to look up.
+     */
+    get(jti: string): RefreshTokenRecord | undefined | Promise<RefreshTokenRecord | undefined>;
+    /**
+     * Remove a single record by JTI.  Idempotent — deleting a non-existent
+     * key is not an error.
+     * @param jti - JWT ID to remove.
+     */
+    delete(jti: string): void | Promise<void>;
+    /**
+     * Revoke **all** refresh tokens belonging to a given subject (user).
+     * Optional — when absent, per-JTI revocation still works but bulk logout
+     * ("log out all sessions") is not available.
+     * @param sub - The subject identifier to revoke tokens for.
+     */
+    deleteBySubject?(sub: string): void | Promise<void>;
 }
 /**
- * Supported HMAC-SHA signing algorithms for JWT.
- * RS*, ES*, and PS* families are not yet implemented.
+ * Supported JWT signing algorithms.
+ *
+ * - **HS256 / HS384 / HS512** — HMAC-SHA family.  Uses a shared secret string
+ *   (`accessTokenSecret` / `refreshTokenSecret`).
+ * - **RS256 / RS384 / RS512** — RSA PKCS#1 v1.5 + SHA family.  Requires PEM
+ *   private key for signing and PEM public key for verification.
+ * - **ES256 / ES384 / ES512** — ECDSA + SHA family.  Requires a PEM private
+ *   key (P-256 / P-384 / P-521 curve respectively) for signing and the
+ *   corresponding PEM public key for verification.  Signatures are encoded in
+ *   the compact IEEE P1363 (JOSE) format rather than ASN.1 DER.
  */
-export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512';
+export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512';
 /**
  * Full configuration object for {@link createJwtPlugin}.
- * All fields have defaults; override only what you need.
+ * All fields except `accessTokenSecret` and `refreshTokenSecret` have defaults.
  */
 export interface JwtConfig {
-    /** HMAC secret used to sign access tokens. **Change in production.** */
+    /** HMAC secret used to sign access tokens (HS* algorithms). **Change in production.** */
     accessTokenSecret: string;
-    /** HMAC secret used to sign refresh tokens (currently unused — refresh   *
-     * tokens are opaque random strings, not JWTs). Reserved for future use. */
+    /** HMAC secret used to sign refresh tokens (HS* algorithms). **Change in production.** */
     refreshTokenSecret: string;
+    /**
+     * PEM-encoded **private** key used to sign access tokens (RS* / ES* algorithms).
+     * Required when `alg` is RS* or ES*.
+     */
+    accessTokenPrivateKey?: string;
+    /**
+     * PEM-encoded **public** key used to verify access tokens (RS* / ES* algorithms).
+     * Required when `alg` is RS* or ES*.
+     */
+    accessTokenPublicKey?: string;
+    /**
+     * PEM-encoded **private** key used to sign refresh tokens (RS* / ES* algorithms).
+     * Falls back to `accessTokenPrivateKey` when absent.
+     */
+    refreshTokenPrivateKey?: string;
+    /**
+     * PEM-encoded **public** key used to verify refresh tokens (RS* / ES* algorithms).
+     * Falls back to `accessTokenPublicKey` when absent.
+     */
+    refreshTokenPublicKey?: string;
     /** Access token lifetime in **seconds**. Defaults to 15 minutes. */
     accessTokenExpiry: number;
     /** Refresh token lifetime in **seconds**. Defaults to 7 days. */
@@ -112,14 +185,15 @@ export interface JwtConfig {
     alg: JwtAlgorithm;
     /**
      * Extract the login username from a user record.
+     * Used as the fallback `sub` claim when `payload()` does not set one.
      * Defaults to `(user) => user.username`.
      */
     username: (user: UserRecord) => string;
     /**
-     * Fetch a user record by username.
+     * Fetch a user record by subject (username or stable ID).
      * Return `undefined` (or any falsy value) when the user does not exist.
      */
-    fetchUser: (username: string) => UserRecord | undefined;
+    fetchUser: (sub: string) => UserRecord | undefined | Promise<UserRecord | undefined>;
     /**
      * Return `true` when the supplied plain-text `password` is valid for
      * `user`, `false` otherwise.
@@ -127,19 +201,23 @@ export interface JwtConfig {
      * The default implementation compares SHA-256 hashes; replace with a
      * timing-safe bcrypt/argon2 check in production.
      */
-    isPasswordValid: (user: UserRecord, password: string) => boolean;
+    isPasswordValid: (user: UserRecord, password: string) => boolean | Promise<boolean>;
     /**
-     * Build the JWT payload for a user.
-     * The `iss`, `iat`, `exp`, and `sub` claims are added automatically.
-     * Returning a partial object is fine — the plugin merges the rest.
+     * Build the JWT access-token payload for a user.
+     * The `iss`, `iat`, and `exp` claims are added automatically.
+     * When `sub` is absent from the returned object, `config.username(user)`
+     * is used as the fallback.
      */
-    payload: (user: UserRecord) => Partial<TokenPayload>;
+    payload: (user: UserRecord) => Partial<TokenPayload> | Promise<Partial<TokenPayload>>;
     /**
-     * Active refresh-token store.
-     * Defaults to an in-process `Map` (lost on restart; not suitable for
-     * multi-instance deployments).
+     * Refresh-token store.  When absent, refresh tokens are **not** issued:
+     * `POST /auth/login` omits `refreshToken` from its response, and
+     * `POST /auth/refresh` responds with `501 Not Implemented`.
+     *
+     * Use {@link createMapTokenStore} for a simple in-process store, or supply
+     * a custom adapter that implements {@link TokenStore}.
      */
-    refreshTokenStore: TokenStore;
+    refreshTokenStore?: TokenStore;
 }
 /** Result returned by {@link verifyToken}. */
 type VerifyResult = {
@@ -167,38 +245,48 @@ export declare function hashPassword(password: string): string;
  * Replace or ignore this map entirely when you supply your own `fetchUser`.
  */
 export declare const userDatabase: Map<string, UserRecord>;
+/**
+ * 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 declare function createMapTokenStore(): TokenStore;
 /**
  * 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`.
  */
-declare function signToken(payload: Partial<TokenPayload>, secret: string, expiresIn: number, alg?: JwtAlgorithm): string;
+declare function signToken(payload: Partial<TokenPayload>, key: string, expiresIn: number, alg?: JwtAlgorithm): string;
 /**
  * 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).
+ * 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.
  */
-declare function verifyToken(token: string, secret: string, alg: JwtAlgorithm): VerifyResult;
+declare function verifyToken(token: string, key: string, alg: JwtAlgorithm): VerifyResult;
 /**
  * The object returned by {@link createJwtPlugin}.
  *
@@ -206,7 +294,13 @@ declare function verifyToken(token: string, secret: string, alg: JwtAlgorithm):
  * routes:
  *
  * ```ts
- * const auth = createJwtPlugin({ accessTokenSecret: process.env.JWT_SECRET! });
+ * import { createRouter, json, createJwtPlugin, createMapTokenStore } from 'expediate';
+ *
+ * const auth = createJwtPlugin({
+ *   accessTokenSecret:  process.env.JWT_ACCESS_SECRET!,
+ *   refreshTokenSecret: process.env.JWT_REFRESH_SECRET!,
+ *   refreshTokenStore:  createMapTokenStore(),
+ * });
  *
  * app.post('/auth/login',   json(), auth.login);
  * app.post('/auth/refresh', json(), auth.refresh);
@@ -221,19 +315,21 @@ export interface JwtPlugin {
     /**
      * Route handler for `POST /auth/login`.
      * Expects a JSON body with `{ username, password }`.
-     * On success: responds with `{ accessToken, refreshToken, expiresIn, tokenType }`.
+     * On success: responds with `{ accessToken, expiresIn, tokenType }`.
+     * When a `refreshTokenStore` is configured, also includes `{ refreshToken }`.
      */
     login: Middleware;
     /**
      * Route handler for `POST /auth/refresh`.
-     * Expects a JSON body with `{ username, refreshToken }`.
+     * Expects a JSON body with `{ refreshToken }`.
+     * Returns `501` when no `refreshTokenStore` is configured.
      * On success: responds with a new `{ accessToken, refreshToken, ... }` pair.
      */
     refresh: Middleware;
     /**
      * Route handler for `POST /auth/logout`.
      * Expects a JSON body with `{ refreshToken }` (optional).
-     * Always responds with 200; revokes the refresh token if provided.
+     * Always responds with 200; revokes the refresh token if provided and valid.
      */
     logout: Middleware;
     /**
@@ -267,12 +363,17 @@ export interface JwtPlugin {
 /**
  * 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.
  */
 export declare function createJwtPlugin(userConfig?: Partial<JwtConfig>): JwtPlugin;
 export default createJwtPlugin;

package/dist/jwt-auth.d.ts.map

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