@ttoss/http-server-auth 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, Terezinha Tech Operations (ttoss)
+
+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.

package/README.md

@@ -0,0 +1,121 @@
+# @ttoss/http-server-auth
+
+Authentication middleware for `@ttoss/http-server` (Koa). Wraps `@ttoss/auth-core` primitives into a ready-to-use Bearer-token strategy chain.
+
+## Installation
+
+```bash
+pnpm add @ttoss/http-server-auth
+```
+
+## Usage
+
+### Global middleware
+
+```ts
+import { authMiddleware } from '@ttoss/http-server-auth';
+import { App } from '@ttoss/http-server';
+
+const app = new App();
+
+app.use(
+  authMiddleware({
+    strategies: ['jwt', 'apiToken', 'system'],
+
+    jwt: {
+      secret: process.env.JWT_SECRET,
+    },
+
+    apiToken: {
+      lookup: async (tokenHash) => {
+        const record = await ApiTokenModel.findOne({
+          where: { tokenHash, revoked: false },
+        });
+        if (!record) return null;
+        await record.update({ lastUsedAt: new Date() });
+        return { id: record.user.publicId, email: record.user.email };
+      },
+    },
+
+    system: {
+      secret: process.env.INTERNAL_API_SECRET,
+      user: { id: 'system', email: 'system@internal' },
+    },
+
+    allowedOrigins: [
+      process.env.APP_URL,
+      'http://localhost:3000',
+      /\.vercel\.app$/,
+    ],
+
+    required: true, // default
+  })
+);
+```
+
+### Per-route middleware
+
+```ts
+import { requireAuth } from '@ttoss/http-server-auth';
+import { Router } from '@ttoss/http-server';
+
+const router = new Router();
+
+router.get(
+  '/internal/revalidate',
+  requireAuth({
+    strategies: ['system'],
+    system: { secret: process.env.INTERNAL_API_SECRET, user: { id: 'system' } },
+  }),
+  handler
+);
+
+router.get(
+  '/me',
+  requireAuth({
+    strategies: ['jwt', 'apiToken'],
+    jwt: { secret: process.env.JWT_SECRET },
+    apiToken: { lookup },
+  }),
+  handler
+);
+```
+
+### Optional auth
+
+```ts
+app.use(
+  authMiddleware({
+    strategies: ['jwt'],
+    jwt: { secret: process.env.JWT_SECRET },
+    required: false, // unauthenticated requests pass through with ctx.state.user === undefined
+  })
+);
+```
+
+## Context types
+
+On successful authentication the middleware sets:
+
+```ts
+ctx.state.user; // AuthenticatedUser
+ctx.state.authStrategy; // 'jwt' | 'apiToken' | 'system'
+```
+
+```ts
+type AuthenticatedUser = {
+  id: string;
+  email?: string;
+  [key: string]: unknown;
+};
+```
+
+## Behavior
+
+1. Reads `Authorization: Bearer <token>`; missing header → 401 if `required`.
+2. If `allowedOrigins` is configured and the `Origin` header doesn't match → 403. Requests without an Origin header are never rejected.
+3. Tries each strategy in `strategies` order; first match wins.
+   - `jwt` — verifies HS256 JWT via `@ttoss/auth-core verifyJwt`; maps `sub`/`email` to user (override with `jwt.mapPayload`).
+   - `apiToken` — hashes the token (SHA-256) and calls `apiToken.lookup(hash)`.
+   - `system` — constant-time comparison against `system.secret`.
+4. All strategies fail and `required` → 401. Failure reason is never leaked.

package/dist/index.cjs

@@ -0,0 +1,135 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+Object.defineProperty(exports, Symbol.toStringTag, {
+  value: 'Module'
+});
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+      key = keys[i];
+      if (!__hasOwnProp.call(to, key) && key !== except) {
+        __defProp(to, key, {
+          get: (k => from[k]).bind(null, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+      }
+    }
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+  value: mod,
+  enumerable: true
+}) : target, mod));
+
+//#endregion
+let node_crypto = require("node:crypto");
+node_crypto = __toESM(node_crypto, 1);
+let _ttoss_auth_core = require("@ttoss/auth-core");
+
+//#region src/origin.ts
+/**
+* Returns true if origin matches any entry in the allowlist.
+* Strings are compared exactly; RegExps are tested.
+*/
+var isOriginAllowed = (origin, allowedOrigins) => {
+  for (const entry of allowedOrigins) {
+    if (entry === void 0) continue;
+    if (typeof entry === "string") {
+      if (entry === origin) return true;
+    } else if (entry.test(origin)) return true;
+  }
+  return false;
+};
+
+//#endregion
+//#region src/authMiddleware.ts
+var tryJwt = (token, opts) => {
+  const payload = (0, _ttoss_auth_core.verifyJwt)({
+    token,
+    secret: opts.secret
+  });
+  if (!payload) return null;
+  if (opts.mapPayload) return opts.mapPayload(payload);
+  return {
+    id: String(payload.sub ?? ""),
+    ...(payload.email !== void 0 && {
+      email: String(payload.email)
+    })
+  };
+};
+var tryApiToken = async (token, opts) => {
+  return opts.lookup((0, _ttoss_auth_core.hashApiToken)(token));
+};
+var trySystem = (token, opts) => {
+  const a = Buffer.from(token);
+  const b = Buffer.from(opts.secret);
+  if (a.length !== b.length || !node_crypto.default.timingSafeEqual(a, b)) return null;
+  return opts.user;
+};
+var resolveUser = async (token, options) => {
+  for (const strategy of options.strategies) {
+    let user = null;
+    if (strategy === "jwt" && options.jwt) user = tryJwt(token, options.jwt);else if (strategy === "apiToken" && options.apiToken) user = await tryApiToken(token, options.apiToken);else if (strategy === "system" && options.system) user = trySystem(token, options.system);
+    if (user) return {
+      user,
+      strategy
+    };
+  }
+  return null;
+};
+/**
+* Koa middleware that authenticates requests via Bearer token.
+* Supports JWT, hashed API tokens, and a shared system secret.
+* Sets `ctx.state.user` and `ctx.state.authStrategy` on success.
+*/
+var authMiddleware = options => {
+  const required = options.required ?? true;
+  return async (ctx, next) => {
+    if (options.allowedOrigins) {
+      const origin = ctx.get("Origin");
+      if (origin && !isOriginAllowed(origin, options.allowedOrigins)) ctx.throw(403, "Invalid origin");
+    }
+    const authHeader = ctx.get("Authorization");
+    const token = authHeader && authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+    if (!token) {
+      if (required) ctx.throw(401, "Unauthorized");
+      return next();
+    }
+    const result = await resolveUser(token, options);
+    if (!result) {
+      if (required) ctx.throw(401, "Unauthorized");
+      return next();
+    }
+    ctx.state.user = result.user;
+    ctx.state.authStrategy = result.strategy;
+    return next();
+  };
+};
+
+//#endregion
+//#region src/requireAuth.ts
+/**
+* Route-level authentication middleware. Same options as `authMiddleware`,
+* `required` defaults to true.
+*
+* @example
+* router.get('/me', requireAuth({ strategies: ['jwt', 'apiToken'] }), handler);
+*/
+var requireAuth = options => {
+  return authMiddleware({
+    required: true,
+    ...options
+  });
+};
+
+//#endregion
+exports.authMiddleware = authMiddleware;
+exports.isOriginAllowed = isOriginAllowed;
+exports.requireAuth = requireAuth;

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+
+import { Context, Next } from "@ttoss/http-server";
+
+//#region src/types.d.ts
+type AuthenticatedUser = {
+  id: string;
+  email?: string;
+  [key: string]: unknown;
+};
+type AuthStrategy = 'jwt' | 'apiToken' | 'system';
+type JwtOptions = {
+  secret: string;
+  /**
+   * Override how the JWT payload maps to an AuthenticatedUser.
+   * Defaults to `{ id: payload.sub, email: payload.email }`.
+   */
+  mapPayload?: (payload: Record<string, unknown>) => AuthenticatedUser | null;
+};
+type ApiTokenOptions = {
+  /**
+   * Receives the SHA-256 hash of the presented token and returns the
+   * authenticated user, or null if not found / revoked.
+   */
+  lookup: (tokenHash: string) => Promise<AuthenticatedUser | null>;
+};
+type SystemOptions = {
+  secret: string; /** User attached to ctx.state.user for system calls. */
+  user: AuthenticatedUser;
+};
+type AuthMiddlewareOptions = {
+  /** Ordered list of strategies to attempt. First match wins. */strategies: AuthStrategy[];
+  jwt?: JwtOptions;
+  apiToken?: ApiTokenOptions;
+  system?: SystemOptions;
+  /**
+   * Optional origin allowlist. Strings are exact-matched; RegExps are tested.
+   * Requests without an Origin header are never rejected by this check.
+   */
+  allowedOrigins?: Array<string | RegExp | undefined>;
+  /**
+   * When true (default), unauthenticated requests receive 401.
+   * When false, they pass through with ctx.state.user === undefined.
+   */
+  required?: boolean;
+};
+//#endregion
+//#region src/authMiddleware.d.ts
+/**
+ * Koa middleware that authenticates requests via Bearer token.
+ * Supports JWT, hashed API tokens, and a shared system secret.
+ * Sets `ctx.state.user` and `ctx.state.authStrategy` on success.
+ */
+declare const authMiddleware: (options: AuthMiddlewareOptions) => (ctx: Context, next: Next) => Promise<void>;
+//#endregion
+//#region src/origin.d.ts
+/**
+ * Returns true if origin matches any entry in the allowlist.
+ * Strings are compared exactly; RegExps are tested.
+ */
+declare const isOriginAllowed: (origin: string, allowedOrigins: Array<string | RegExp | undefined>) => boolean;
+//#endregion
+//#region src/requireAuth.d.ts
+/**
+ * Route-level authentication middleware. Same options as `authMiddleware`,
+ * `required` defaults to true.
+ *
+ * @example
+ * router.get('/me', requireAuth({ strategies: ['jwt', 'apiToken'] }), handler);
+ */
+declare const requireAuth: (options: AuthMiddlewareOptions) => ((ctx: Context, next: Next) => Promise<void>);
+//#endregion
+export { type ApiTokenOptions, type AuthMiddlewareOptions, type AuthStrategy, type AuthenticatedUser, type JwtOptions, type SystemOptions, authMiddleware, isOriginAllowed, requireAuth };

package/dist/index.d.mts

@@ -0,0 +1,72 @@
+
+import { Context, Next } from "@ttoss/http-server";
+
+//#region src/types.d.ts
+type AuthenticatedUser = {
+  id: string;
+  email?: string;
+  [key: string]: unknown;
+};
+type AuthStrategy = 'jwt' | 'apiToken' | 'system';
+type JwtOptions = {
+  secret: string;
+  /**
+   * Override how the JWT payload maps to an AuthenticatedUser.
+   * Defaults to `{ id: payload.sub, email: payload.email }`.
+   */
+  mapPayload?: (payload: Record<string, unknown>) => AuthenticatedUser | null;
+};
+type ApiTokenOptions = {
+  /**
+   * Receives the SHA-256 hash of the presented token and returns the
+   * authenticated user, or null if not found / revoked.
+   */
+  lookup: (tokenHash: string) => Promise<AuthenticatedUser | null>;
+};
+type SystemOptions = {
+  secret: string; /** User attached to ctx.state.user for system calls. */
+  user: AuthenticatedUser;
+};
+type AuthMiddlewareOptions = {
+  /** Ordered list of strategies to attempt. First match wins. */strategies: AuthStrategy[];
+  jwt?: JwtOptions;
+  apiToken?: ApiTokenOptions;
+  system?: SystemOptions;
+  /**
+   * Optional origin allowlist. Strings are exact-matched; RegExps are tested.
+   * Requests without an Origin header are never rejected by this check.
+   */
+  allowedOrigins?: Array<string | RegExp | undefined>;
+  /**
+   * When true (default), unauthenticated requests receive 401.
+   * When false, they pass through with ctx.state.user === undefined.
+   */
+  required?: boolean;
+};
+//#endregion
+//#region src/authMiddleware.d.ts
+/**
+ * Koa middleware that authenticates requests via Bearer token.
+ * Supports JWT, hashed API tokens, and a shared system secret.
+ * Sets `ctx.state.user` and `ctx.state.authStrategy` on success.
+ */
+declare const authMiddleware: (options: AuthMiddlewareOptions) => (ctx: Context, next: Next) => Promise<void>;
+//#endregion
+//#region src/origin.d.ts
+/**
+ * Returns true if origin matches any entry in the allowlist.
+ * Strings are compared exactly; RegExps are tested.
+ */
+declare const isOriginAllowed: (origin: string, allowedOrigins: Array<string | RegExp | undefined>) => boolean;
+//#endregion
+//#region src/requireAuth.d.ts
+/**
+ * Route-level authentication middleware. Same options as `authMiddleware`,
+ * `required` defaults to true.
+ *
+ * @example
+ * router.get('/me', requireAuth({ strategies: ['jwt', 'apiToken'] }), handler);
+ */
+declare const requireAuth: (options: AuthMiddlewareOptions) => ((ctx: Context, next: Next) => Promise<void>);
+//#endregion
+export { type ApiTokenOptions, type AuthMiddlewareOptions, type AuthStrategy, type AuthenticatedUser, type JwtOptions, type SystemOptions, authMiddleware, isOriginAllowed, requireAuth };

package/dist/index.mjs

@@ -0,0 +1,102 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import crypto from "node:crypto";
+import { hashApiToken, verifyJwt } from "@ttoss/auth-core";
+
+//#region src/origin.ts
+/**
+* Returns true if origin matches any entry in the allowlist.
+* Strings are compared exactly; RegExps are tested.
+*/
+var isOriginAllowed = (origin, allowedOrigins) => {
+  for (const entry of allowedOrigins) {
+    if (entry === void 0) continue;
+    if (typeof entry === "string") {
+      if (entry === origin) return true;
+    } else if (entry.test(origin)) return true;
+  }
+  return false;
+};
+
+//#endregion
+//#region src/authMiddleware.ts
+var tryJwt = (token, opts) => {
+  const payload = verifyJwt({
+    token,
+    secret: opts.secret
+  });
+  if (!payload) return null;
+  if (opts.mapPayload) return opts.mapPayload(payload);
+  return {
+    id: String(payload.sub ?? ""),
+    ...(payload.email !== void 0 && {
+      email: String(payload.email)
+    })
+  };
+};
+var tryApiToken = async (token, opts) => {
+  return opts.lookup(hashApiToken(token));
+};
+var trySystem = (token, opts) => {
+  const a = Buffer.from(token);
+  const b = Buffer.from(opts.secret);
+  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return null;
+  return opts.user;
+};
+var resolveUser = async (token, options) => {
+  for (const strategy of options.strategies) {
+    let user = null;
+    if (strategy === "jwt" && options.jwt) user = tryJwt(token, options.jwt);else if (strategy === "apiToken" && options.apiToken) user = await tryApiToken(token, options.apiToken);else if (strategy === "system" && options.system) user = trySystem(token, options.system);
+    if (user) return {
+      user,
+      strategy
+    };
+  }
+  return null;
+};
+/**
+* Koa middleware that authenticates requests via Bearer token.
+* Supports JWT, hashed API tokens, and a shared system secret.
+* Sets `ctx.state.user` and `ctx.state.authStrategy` on success.
+*/
+var authMiddleware = options => {
+  const required = options.required ?? true;
+  return async (ctx, next) => {
+    if (options.allowedOrigins) {
+      const origin = ctx.get("Origin");
+      if (origin && !isOriginAllowed(origin, options.allowedOrigins)) ctx.throw(403, "Invalid origin");
+    }
+    const authHeader = ctx.get("Authorization");
+    const token = authHeader && authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+    if (!token) {
+      if (required) ctx.throw(401, "Unauthorized");
+      return next();
+    }
+    const result = await resolveUser(token, options);
+    if (!result) {
+      if (required) ctx.throw(401, "Unauthorized");
+      return next();
+    }
+    ctx.state.user = result.user;
+    ctx.state.authStrategy = result.strategy;
+    return next();
+  };
+};
+
+//#endregion
+//#region src/requireAuth.ts
+/**
+* Route-level authentication middleware. Same options as `authMiddleware`,
+* `required` defaults to true.
+*
+* @example
+* router.get('/me', requireAuth({ strategies: ['jwt', 'apiToken'] }), handler);
+*/
+var requireAuth = options => {
+  return authMiddleware({
+    required: true,
+    ...options
+  });
+};
+
+//#endregion
+export { authMiddleware, isOriginAllowed, requireAuth };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ttoss/http-server-auth",
+  "version": "0.2.0",
+  "description": "Authentication middleware for @ttoss/http-server",
+  "keywords": [
+    "auth",
+    "authentication",
+    "koa",
+    "middleware",
+    "ttoss"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ttoss/ttoss.git",
+    "directory": "packages/http-server-auth"
+  },
+  "license": "MIT",
+  "author": "ttoss",
+  "contributors": [
+    "Pedro Arantes <pedro@arantespp.com> (https://arantespp.com)"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ttoss/auth-core": "^0.5.1"
+  },
+  "devDependencies": {
+    "@types/koa": "^3.0.3",
+    "jest": "^30.4.2",
+    "supertest": "^7.2.2",
+    "tsdown": "^0.22.2",
+    "@ttoss/http-server": "^0.6.1",
+    "@ttoss/config": "^1.37.17"
+  },
+  "peerDependencies": {
+    "@ttoss/http-server": "^0.6.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "jest --projects tests/unit"
+  }
+}