@beespoke/micro-server-jwt 0.0.0-stage → 2.0.5

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @beespoke/micro-server-jwt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+JWT signing, verification, authentication middleware, and a plugin-owned authentication service. Independent of Sequelize. Supports Node 24+ and Bun 1.3.14+.
+
+## Install
+
+```sh
+npm install @beespoke/micro-server @beespoke/micro-server-jwt
+```
+
+## Configure protected routes
+
+```ts
+import { defineConfig } from '@beespoke/micro-server';
+
+export default defineConfig({
+    plugins: ['@beespoke/micro-server-jwt'],
+    pluginOptions: {
+        '@beespoke/micro-server-jwt': {
+            secret: process.env.JWT_SECRET_KEY!,
+            issuer: 'my-api',
+            expiresIn: '15m',
+        },
+    },
+    routes: {
+        folderName: './routes',
+        context: 'api',
+        authenticate: '@beespoke/micro-server-jwt',
+    },
+});
+```
+
+Supply a strong signing secret and create the route directory before startup. Core validates that the authentication plugin is enabled before initializing resources. Signing helpers use the active plugin configuration after bootstrap. Optional `refreshSecret` and `refreshExpiresIn` configure refresh tokens; refresh secret falls back to the access secret if omitted.
+
+## Start the application
+
+Save the configuration as `micro-server.config.ts` next to your application's `package.json`, then create `index.ts`:
+
+```ts
+import { ApplicationServer } from '@beespoke/micro-server';
+
+await ApplicationServer.bootstrap();
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => {
+        void ApplicationServer.close().catch(error => {
+            console.error(error);
+            process.exitCode = 1;
+        });
+    });
+}
+```
+
+Run `bun index.ts` or `node --env-file-if-exists=.env index.ts`. Node requires ESM (`"type": "module"` in package.json). When using Bun, load configuration secrets from the application environment or its `.env` file.
+
+## Issue and verify tokens
+
+After bootstrap, issue tokens only after application-owned user authentication:
+
+```ts
+import { generate, verify } from '@beespoke/micro-server-jwt';
+
+const token = generate({ sub: '123' });
+const payload = verify(token);
+console.log(payload.sub);
+```
+
+Send access tokens as `Authorization: Bearer <token>`. Configured authentication verifies with the trusted signing secret, HS256, and the configured issuer. Missing, invalid, or expired tokens receive HTTP 401. Token-provided keys are never trusted. `decode` reads a payload without verifying it; use `verify` when trust matters. `generateRefreshToken` creates refresh tokens; applications own refresh endpoint policy and token revocation.
+
+## Public routes
+
+Set `grantPublicAccess = true` on a discovered route class to exempt its entire router. Public routes skip authentication and do not populate a user from an untrusted token. Directory names such as `public` or `dev` do not implicitly exempt routes. All other discovered routes require a valid token with this configuration.
+
+The plugin does not implement login endpoints, password validation, account storage, or authorization rules. Manually mounted routes under `configureRoutes` require application-owned authentication middleware. Exported `authenticate`, `getUserFromRequest`, and `validateRequest` helpers are available for explicit use. `AuthenticatedRequest` and `RequestUserType` describe authenticated request data.
+
+## Standalone use
+
+The root helpers can be used without HTTP core. Explicitly configure `JWT_SECRET_KEY`, `JWT_ISSUER`, and expiry variables before signing/verifying. Refresh helpers additionally use `JWT_SECRET_KEY_REFRESH` and `JWT_EXPIRY_REFRESH`. Plugin mode validates options and restores previous helper configuration on close. Do not depend on standalone fallback secrets.
+
+## TypeScript and lifecycle
+
+Add this type-only import to an application-owned `plugin-types.d.ts` for configuration autocomplete:
+
+```ts
+import type {} from '@beespoke/micro-server-jwt/plugin';
+```
+
+Core validates plugin options before setup and owns cleanup after successful startup or startup failure. Await `ApplicationServer.bootstrap()` before using the configured client, and call `ApplicationServer.close()` during application shutdown. Importing the package does not open a connection. Relative plugin paths resolve from the selected configuration file's directory.
+
+The root export can also be used without HTTP core. In that case, explicitly initialize and close the client. The `/plugin` entry is the integration adapter for `@beespoke/micro-server`.

package/dist/JwtPlugin.d.ts

@@ -0,0 +1,20 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { JwtOptions } from './configuration.js';
+import type { RequestUserType } from './types.js';
+export interface JwtPluginContext {
+    provideService<T>(name: string, value: T): void;
+    onClose(hook: () => void | Promise<void>): void;
+}
+export interface JwtPlugin {
+    readonly name: string;
+    setup(context: JwtPluginContext): void;
+}
+export interface JwtService {
+    authenticate(req: Request, res: Response, next: NextFunction): void;
+    generate(payload: string | Buffer | object): string;
+    generateRefreshToken(payload: string | Buffer | object): string;
+    verify(token: string): RequestUserType;
+}
+export declare function validateJwtOptions(options: unknown): void;
+/** Inert until setup; services retain their server's keys independently of root helpers. */
+export declare function createJwtPlugin(options?: JwtOptions): JwtPlugin;

package/dist/TokenGenerator.d.ts

@@ -0,0 +1,11 @@
+import { Request } from 'express';
+import { RequestUserType } from './types.js';
+/**
+ * generate jwt token from the payload
+ * @param payload
+ * @returns
+ */
+export declare function generate(payload: string | Buffer | object): string;
+export declare function generateRefreshToken(payload: string | Buffer | object): string;
+export declare function verify(token: string, secret?: string): RequestUserType;
+export declare function decode(val: string | Request): RequestUserType;

package/dist/authentication.d.ts

@@ -0,0 +1,7 @@
+import type { NextFunction, Request, Response } from 'express';
+/** Relocated from RouterFactory.authenticate; pass true to allow public access. */
+export declare function authenticate(req: Request, res: Response, next: NextFunction, grantPublicAccess?: boolean): void;
+/** Public routes may decode available identity without treating it as verified. */
+export declare function getUserFromRequest(req: Request): void;
+/** Retains the existing JWT / clientSecret verification policy. */
+export declare function validateRequest(req: Request): Boolean;

package/dist/configuration.d.ts

@@ -0,0 +1,19 @@
+import type { SignOptions } from 'jsonwebtoken';
+export interface JwtOptions {
+    secret?: string;
+    expiresIn?: SignOptions['expiresIn'];
+    issuer?: string;
+    refreshSecret?: string;
+    refreshExpiresIn?: SignOptions['expiresIn'];
+}
+export interface JwtConfiguration {
+    readonly secret: string;
+    readonly expiresIn: SignOptions['expiresIn'];
+    readonly issuer: string;
+    readonly refreshSecret: string;
+    readonly refreshExpiresIn: SignOptions['expiresIn'];
+}
+export declare function configuredJwt(): JwtConfiguration | undefined;
+/** Restore the previous active configuration even when servers close out of order. */
+export declare function configureJwt(configuration: JwtConfiguration): () => void;
+export declare function resolveJwtOptions(options: unknown): JwtConfiguration;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { generate, generateRefreshToken, verify, decode } from './TokenGenerator.js';
+export { authenticate, getUserFromRequest, validateRequest } from './authentication.js';
+export type { RequestUserType, AuthenticatedRequest } from './types.js';
+export { createJwtPlugin, validateJwtOptions } from './JwtPlugin.js';
+export type { JwtService, JwtPlugin, JwtPluginContext } from './JwtPlugin.js';
+export type { JwtOptions } from './configuration.js';

package/dist/index.js

@@ -0,0 +1,165 @@
+// src/TokenGenerator.ts
+import jwt from "jsonwebtoken";
+
+// src/configuration.ts
+var configurations = [];
+function configuredJwt() {
+  return configurations[configurations.length - 1];
+}
+function configureJwt(configuration) {
+  const entry = { ...configuration };
+  configurations.push(entry);
+  return () => {
+    const index = configurations.indexOf(entry);
+    if (index !== -1)
+      configurations.splice(index, 1);
+  };
+}
+function resolveJwtOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("JWT options must be an object");
+  }
+  const allowed = new Set(["secret", "expiresIn", "issuer", "refreshSecret", "refreshExpiresIn"]);
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key))
+      throw new TypeError(`Unknown JWT option: ${key}`);
+  }
+  const value = options;
+  for (const field of ["secret", "refreshSecret", "issuer"]) {
+    if (value[field] !== undefined && (typeof value[field] !== "string" || !value[field].trim())) {
+      throw new TypeError(`JWT ${field} must be a nonempty string`);
+    }
+  }
+  const secret = value.secret ?? process.env.JWT_SECRET_KEY;
+  if (!secret?.trim() || secret === "your-secret-key-here") {
+    throw new TypeError("JWT requires a trusted nonempty secret (secret or JWT_SECRET_KEY)");
+  }
+  const refreshSecret = value.refreshSecret ?? process.env.JWT_SECRET_KEY_REFRESH ?? secret;
+  if (!refreshSecret.trim() || refreshSecret === "your-secret-key-here") {
+    throw new TypeError("JWT refreshSecret must be a trusted nonempty string");
+  }
+  const expiresIn = value.expiresIn ?? process.env.JWT_EXPIRY ?? "15m";
+  const refreshExpiresIn = value.refreshExpiresIn ?? process.env.JWT_EXPIRY_REFRESH ?? "15m";
+  validateExpiry(expiresIn, "expiresIn");
+  validateExpiry(refreshExpiresIn, "refreshExpiresIn");
+  const issuer = value.issuer ?? process.env.JWT_ISSUER ?? "*.service";
+  if (!issuer.trim())
+    throw new TypeError("JWT issuer must be a nonempty string");
+  return { secret, refreshSecret, expiresIn, refreshExpiresIn, issuer };
+}
+function validateExpiry(value, field) {
+  const duration = /^(?:\d+(?:\.\d+)?|\.\d+)\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)?$/i;
+  if (typeof value === "number" ? Number.isFinite(value) && Number.isInteger(value) && value > 0 : typeof value === "string" && value.length <= 100 && duration.test(value) && parseFloat(value) > 0)
+    return;
+  throw new TypeError(`JWT ${field} must be a positive number of seconds or a duration string`);
+}
+
+// src/TokenGenerator.ts
+function generate(payload) {
+  const configured = configuredJwt();
+  const SECRET_KEY = configured?.secret ?? process.env.JWT_SECRET_KEY ?? "your-secret-key-here";
+  const EXPIRY = configured?.expiresIn ?? process.env.JWT_EXPIRY ?? "15m";
+  const ISSUER = configured?.issuer ?? process.env.JWT_ISSUER ?? "*.service";
+  return jwt.sign(payload, SECRET_KEY, { expiresIn: EXPIRY, issuer: ISSUER });
+}
+function generateRefreshToken(payload) {
+  const configured = configuredJwt();
+  const SECRET_KEY = configured?.refreshSecret ?? process.env.JWT_SECRET_KEY_REFRESH ?? "your-secret-key-here";
+  const EXPIRY = configured?.refreshExpiresIn ?? process.env.JWT_EXPIRY_REFRESH ?? "15m";
+  const ISSUER = configured?.issuer ?? process.env.JWT_ISSUER ?? "*.service";
+  return jwt.sign(payload, SECRET_KEY, { expiresIn: EXPIRY, issuer: ISSUER });
+}
+function verify(token, secret) {
+  const configured = configuredJwt();
+  const SECRET_KEY = configured?.secret ?? process.env.JWT_SECRET_KEY;
+  let decoded = jwt.verify(token, secret || SECRET_KEY, configured ? { issuer: configured.issuer, algorithms: ["HS256"] } : undefined);
+  return decoded;
+}
+function decode(val) {
+  let token = "";
+  if (typeof val !== "string") {
+    token = val.headers["access-token"];
+  } else {
+    token = val;
+  }
+  let decoded = jwt.decode(token);
+  return decoded;
+}
+// src/authentication.ts
+function authenticate(req, res, next, grantPublicAccess = false) {
+  try {
+    if (grantPublicAccess) {
+      if (!configuredJwt())
+        getUserFromRequest(req);
+    } else if (!validateRequest(req)) {
+      res.status(401).send({ success: false, error: 1004, errorMessage: "Unauthorized. Invalid Access Token." });
+      return;
+    }
+    next();
+  } catch (error) {
+    res.status(401).send({ success: false, error: 1005, errorMessage: error.message });
+  }
+}
+function getUserFromRequest(req) {
+  const token = bearerToken(req);
+  if (token)
+    req.user = decode(token);
+}
+function validateRequest(req) {
+  const token = bearerToken(req);
+  if (!token)
+    return false;
+  const configured = configuredJwt();
+  const secret = configured ? configured.secret : decode(token)?.clientSecret;
+  req.user = verify(token, secret);
+  return true;
+}
+function bearerToken(req) {
+  return /^Bearer\s+(\S+)\s*$/i.exec(req.headers.authorization || "")?.[1];
+}
+// src/JwtPlugin.ts
+import jwt2 from "jsonwebtoken";
+function validateJwtOptions(options) {
+  resolveJwtOptions(options);
+}
+function createJwtPlugin(options = {}) {
+  const configuration = resolveJwtOptions(options);
+  const service = {
+    generate: (payload) => jwt2.sign(payload, configuration.secret, { expiresIn: configuration.expiresIn, issuer: configuration.issuer }),
+    generateRefreshToken: (payload) => jwt2.sign(payload, configuration.refreshSecret, { expiresIn: configuration.refreshExpiresIn, issuer: configuration.issuer }),
+    verify: (token) => jwt2.verify(token, configuration.secret, { issuer: configuration.issuer, algorithms: ["HS256"] }),
+    authenticate(req, res, next) {
+      const token = /^Bearer\s+(\S+)\s*$/i.exec(req.headers.authorization || "")?.[1];
+      if (!token) {
+        res.status(401).send({ success: false, error: 1004, errorMessage: "Unauthorized. Invalid Access Token." });
+        return;
+      }
+      try {
+        req.user = service.verify(token);
+      } catch {
+        res.status(401).send({ success: false, error: 1005, errorMessage: "Unauthorized. Invalid Access Token." });
+        return;
+      }
+      next();
+    }
+  };
+  return {
+    name: "@beespoke/micro-server-jwt",
+    setup(context) {
+      context.provideService("@beespoke/micro-server-jwt", service);
+      const restore = configureJwt(configuration);
+      context.onClose(restore);
+    }
+  };
+}
+export {
+  verify,
+  validateRequest,
+  validateJwtOptions,
+  getUserFromRequest,
+  generateRefreshToken,
+  generate,
+  decode,
+  createJwtPlugin,
+  authenticate
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,9 @@
+import type { PluginDefinition } from '@beespoke/micro-server';
+import type { JwtOptions } from '../index.js';
+declare module '@beespoke/micro-server' {
+    interface PluginOptionsRegistry {
+        '@beespoke/micro-server-jwt': JwtOptions;
+    }
+}
+declare const definition: PluginDefinition<JwtOptions>;
+export default definition;

package/dist/plugin/index.js

@@ -0,0 +1,11 @@
+// src/plugin/index.ts
+import { createJwtPlugin, validateJwtOptions } from "../index.js";
+var definition = {
+  name: "@beespoke/micro-server-jwt",
+  validate: validateJwtOptions,
+  create: createJwtPlugin
+};
+var plugin_default = definition;
+export {
+  plugin_default as default
+};

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+import type { Request } from 'express';
+/** Authentication payload shape retained independently of Sequelize. */
+export type RequestUserType = {
+    id?: number;
+    email?: string;
+    clientSecret?: string;
+    type?: string;
+    [claim: string]: any;
+};
+export type AuthenticatedRequest = Request & {
+    user?: RequestUserType;
+};
+declare global {
+    namespace Express {
+        interface Request {
+            user?: any;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@beespoke/micro-server-jwt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.5",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts",
+    "test": "bun test tests"
+  },
+  "dependencies": {
+    "jsonwebtoken": "8.5.1",
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/express": "^4.17.21",
+    "@types/node": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@beespoke/micro-server": "^2.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@beespoke/micro-server": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "author": "CCCI Inc."
+}