@ttoss/http-server-auth 0.3.0 → 0.3.2

package/README.md

@@ -101,7 +101,7 @@ On successful authentication the middleware sets:
 
 ```ts
 ctx.state.user; // AuthenticatedUser
-ctx.state.authStrategy; // 'jwt' | 'apiToken' | 'system'
+ctx.state.authStrategy; // 'jwt' | 'apiToken' | 'system' | 'oauth'
 ```
 
 ```ts
@@ -120,6 +120,11 @@ type AuthenticatedUser = {
    - `jwt` — verifies HS256 JWT via `@ttoss/auth-core verifyJwt`; maps `sub`/`email` to user (override with `jwt.mapPayload(payload, ctx)`).
    - `apiToken` — hashes the token (SHA-256) and calls `apiToken.lookup(hash, ctx)`.
    - `system` — constant-time comparison against `system.secret`.
-4. All strategies fail and `required` → 401. Failure reason is never leaked.
+   - `oauth` — verifies an OAuth provider's Bearer token via `oauth.verify(token, ctx)` (wrap Cognito/Auth0/your own verifier); maps the payload to the user (claims like `scope` are preserved on `ctx.state.user`). A verified token missing an `oauth.requiredScopes` entry yields `403`.
+4. All strategies fail and `required` → 401. Failure reason is never leaked. Set `resourceMetadataUrl` to advertise the authorization server on `401` via `WWW-Authenticate` (RFC 9728).
 
 Both `apiToken.lookup` and `jwt.mapPayload` receive the Koa `ctx` as a second argument, enabling request-scoped work (e.g. reading a per-request connection off `ctx.db` or updating `lastUsedAt`). The single-argument signatures keep working — `ctx` is purely additive.
+
+## OAuth authorization server
+
+The package also ships `oauthServer()` — a Koa `Router` that issues tokens (`/authorize`, `/token`, `/register`, discovery), a thin adapter over `createOAuthHandlers` from [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core). Pair it with the `oauth` verification strategy above when one deployment both issues and verifies. See the [OAuth Authorization Server](https://ttoss.dev/docs/engineering/guidelines/oauth-authorization-server) guideline.

package/dist/index.cjs

@@ -32,6 +32,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let node_crypto = require("node:crypto");
 node_crypto = __toESM(node_crypto, 1);
 let _ttoss_auth_core = require("@ttoss/auth-core");
+let _ttoss_http_server = require("@ttoss/http-server");
 
 //#region src/origin.ts
 /**
@@ -73,38 +74,84 @@ var trySystem = (token, opts) => {
   if (a.length !== b.length || !node_crypto.default.timingSafeEqual(a, b)) return null;
   return opts.user;
 };
+/** Sentinel: token verified but missing a required scope → 403, not 401. */
+var FORBIDDEN = Symbol("forbidden");
+var hasRequiredScopes = (requiredScopes, payload) => {
+  const tokenScopes = (typeof payload.scope === "string" ? payload.scope : "").split(" ");
+  return requiredScopes.every(s => {
+    return tokenScopes.includes(s);
+  });
+};
+var tryOauth = async (token, opts, ctx) => {
+  let payload;
+  try {
+    payload = await opts.verify(token, ctx);
+  } catch {
+    return null;
+  }
+  if (!payload) return null;
+  if (opts.requiredScopes?.length && !hasRequiredScopes(opts.requiredScopes, payload)) return FORBIDDEN;
+  if (opts.mapPayload) return opts.mapPayload(payload, ctx);
+  return {
+    id: String(payload.sub ?? ""),
+    ...payload
+  };
+};
+var resolveStrategy = async (strategy, token, options, ctx) => {
+  if (strategy === "jwt" && options.jwt) return tryJwt(token, options.jwt, ctx);
+  if (strategy === "apiToken" && options.apiToken) return tryApiToken(token, options.apiToken, ctx);
+  if (strategy === "system" && options.system) return trySystem(token, options.system);
+  if (strategy === "oauth" && options.oauth) return tryOauth(token, options.oauth, ctx);
+  return null;
+};
 var resolveUser = async (token, options, ctx) => {
   for (const strategy of options.strategies) {
-    let user = null;
-    if (strategy === "jwt" && options.jwt) user = tryJwt(token, options.jwt, ctx);else if (strategy === "apiToken" && options.apiToken) user = await tryApiToken(token, options.apiToken, ctx);else if (strategy === "system" && options.system) user = trySystem(token, options.system);
-    if (user) return {
-      user,
+    const result = await resolveStrategy(strategy, token, options, ctx);
+    if (result === FORBIDDEN) return FORBIDDEN;
+    if (result) return {
+      user: result,
       strategy
     };
   }
   return null;
 };
+/** Throws 403 when an `allowedOrigins` list is set and the Origin doesn't match. */
+var enforceOrigin = (ctx, allowedOrigins) => {
+  if (!allowedOrigins) return;
+  const origin = ctx.get("Origin");
+  if (origin && !isOriginAllowed(origin, allowedOrigins)) ctx.throw(403, "Invalid origin");
+};
+/** Extracts the Bearer token from the Authorization header, or `null`. */
+var extractBearer = ctx => {
+  const authHeader = ctx.get("Authorization");
+  return authHeader && authHeader.startsWith("Bearer ") ? authHeader.slice(7) : 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.
+* Koa middleware that authenticates requests via Bearer token. Supports JWT,
+* hashed API tokens, a shared system secret, and OAuth provider tokens (the
+* `oauth` strategy — the resource-server role). Sets `ctx.state.user` and
+* `ctx.state.authStrategy` on success; emits `401` (with a `WWW-Authenticate`
+* header, RFC 9728 when `resourceMetadataUrl` is set) for missing/invalid
+* tokens, and `403` when a verified token is missing a required scope.
 */
 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 unauthorized = {
+    headers: {
+      "WWW-Authenticate": options.resourceMetadataUrl ? `Bearer resource_metadata="${options.resourceMetadataUrl}"` : "Bearer"
     }
-    const authHeader = ctx.get("Authorization");
-    const token = authHeader && authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+  };
+  return async (ctx, next) => {
+    enforceOrigin(ctx, options.allowedOrigins);
+    const token = extractBearer(ctx);
     if (!token) {
-      if (required) ctx.throw(401, "Unauthorized");
+      if (required) ctx.throw(401, "Unauthorized", unauthorized);
       return next();
     }
     const result = await resolveUser(token, options, ctx);
+    if (result === FORBIDDEN) ctx.throw(403, "Forbidden");
     if (!result) {
-      if (required) ctx.throw(401, "Unauthorized");
+      if (required) ctx.throw(401, "Unauthorized", unauthorized);
       return next();
     }
     ctx.state.user = result.user;
@@ -113,6 +160,89 @@ var authMiddleware = options => {
   };
 };
 
+//#endregion
+//#region src/oauthServer.ts
+/** Normalizes a Koa query/header value (which may be an array) to a string. */
+var firstValue = value => {
+  return Array.isArray(value) ? value[0] : value;
+};
+var toOAuthRequest = ctx => {
+  const query = {};
+  for (const [key, value] of Object.entries(ctx.query)) query[key] = firstValue(value);
+  const headers = {};
+  for (const [key, value] of Object.entries(ctx.headers)) headers[key] = firstValue(value);
+  return {
+    query,
+    body: ctx.request.body ?? {},
+    headers
+  };
+};
+var applyResponse = (ctx, res) => {
+  if (res.redirect !== void 0) {
+    ctx.redirect(res.redirect);
+    return;
+  }
+  ctx.status = res.status;
+  ctx.body = res.body;
+};
+/**
+* Mounts an OAuth 2.1 Authorization Server (issuing tokens) as a Koa `Router`,
+* adapting the runner-agnostic engine from `@ttoss/auth-core`. Exposes the
+* authorization endpoint (PKCE S256), token endpoint (`authorization_code` +
+* `refresh_token`), Dynamic Client Registration, and discovery metadata.
+*
+* This is the issuing side of OAuth; pair it with `authMiddleware`'s `oauth`
+* strategy (the verifying side) when one deployment both issues and verifies.
+*
+* @example
+* ```typescript
+* import { App, bodyParser } from '@ttoss/http-server';
+* import { oauthServer } from '@ttoss/http-server-auth';
+*
+* const app = new App();
+* app.use(bodyParser());
+* app.use(oauthServer({ issuer, clientStore, authCodeStore, issueTokens, onAuthorize }).routes());
+* ```
+*/
+var oauthServer = options => {
+  const engine = (0, _ttoss_auth_core.createOAuthHandlers)(options);
+  const router = new _ttoss_http_server.Router();
+  router.get("/.well-known/oauth-authorization-server", ctx => {
+    applyResponse(ctx, engine.authorizationServerMetadata());
+  });
+  const prm = engine.protectedResourceMetadata();
+  if (prm) router.get("/.well-known/oauth-protected-resource", ctx => {
+    applyResponse(ctx, prm);
+  });
+  router.get(engine.paths.authorize, async ctx => {
+    applyResponse(ctx, await engine.authorize(toOAuthRequest(ctx)));
+  });
+  router.post(engine.paths.token, async ctx => {
+    applyResponse(ctx, await engine.token(toOAuthRequest(ctx)));
+  });
+  router.post(engine.paths.register, async ctx => {
+    applyResponse(ctx, await engine.register(toOAuthRequest(ctx)));
+  });
+  return router;
+};
+/**
+* Koa middleware that serves `GET /.well-known/oauth-protected-resource`
+* (RFC 9728). Mount it **before** `authMiddleware` so the discovery endpoint
+* stays unauthenticated (clients fetch it before they have a token).
+*/
+var createProtectedResourceMetadataMiddleware = args => {
+  return async (ctx, next) => {
+    if (ctx.method === "GET" && ctx.path === "/.well-known/oauth-protected-resource") {
+      ctx.body = {
+        resource: args.resource,
+        authorization_servers: args.authorizationServers
+      };
+      return;
+    }
+    await next();
+  };
+};
+
 //#endregion
 //#region src/requireAuth.ts
 /**
@@ -131,5 +261,19 @@ var requireAuth = options => {
 
 //#endregion
 exports.authMiddleware = authMiddleware;
+Object.defineProperty(exports, 'createOAuthHandlers', {
+  enumerable: true,
+  get: function () {
+    return _ttoss_auth_core.createOAuthHandlers;
+  }
+});
+exports.createProtectedResourceMetadataMiddleware = createProtectedResourceMetadataMiddleware;
+Object.defineProperty(exports, 'getWwwAuthenticateHeader', {
+  enumerable: true,
+  get: function () {
+    return _ttoss_auth_core.getWwwAuthenticateHeader;
+  }
+});
 exports.isOriginAllowed = isOriginAllowed;
+exports.oauthServer = oauthServer;
 exports.requireAuth = requireAuth;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 
-import { Context, Next } from "@ttoss/http-server";
+import { Context, Middleware, Next, Router } from "@ttoss/http-server";
+import { AuthCodeStore, AuthorizeRequest, ClientStore, IssueTokensArgs, IssuedTokens, OAuthClient, OAuthClientMetadata, OAuthHandlers, OAuthServerOptions, OAuthServerOptions as OAuthServerOptions$1, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, StoredAuthorizationCode, createOAuthHandlers, getWwwAuthenticateHeader } from "@ttoss/auth-core";
 
 //#region src/types.d.ts
 type AuthenticatedUser = {
@@ -7,7 +8,7 @@ type AuthenticatedUser = {
   email?: string;
   [key: string]: unknown;
 };
-type AuthStrategy = 'jwt' | 'apiToken' | 'system';
+type AuthStrategy = 'jwt' | 'apiToken' | 'system' | 'oauth';
 type JwtOptions = {
   secret: string;
   /**
@@ -33,11 +34,41 @@ type SystemOptions = {
   secret: string; /** User attached to ctx.state.user for system calls. */
   user: AuthenticatedUser;
 };
+type OAuthOptions = {
+  /**
+   * Verifies a Bearer token issued by an OAuth provider (Cognito, Auth0,
+   * Keycloak, your own authorization server, …). Resolve with the verified
+   * payload, return `null`, or throw to reject — both rejection forms yield a
+   * `401`. Wrap a provider SDK here (e.g. `CognitoJwtVerifier` from
+   * `@ttoss/auth-core/amazon-cognito`) to keep this package provider-agnostic.
+   *
+   * Receives the Koa `ctx` as a second argument for request-scoped work.
+   */
+  verify: (token: string, ctx: Context) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+  /**
+   * Maps the verified payload to an AuthenticatedUser. Defaults to the payload
+   * itself with `id` taken from `sub`, so claims like `scope` remain available
+   * on `ctx.state.user`.
+   */
+  mapPayload?: (payload: Record<string, unknown>, ctx: Context) => AuthenticatedUser | null;
+  /**
+   * Scopes that must all be present on the token's space-separated `scope`
+   * claim. A verified token missing any of them yields a `403`.
+   */
+  requiredScopes?: string[];
+};
 type AuthMiddlewareOptions = {
   /** Ordered list of strategies to attempt. First match wins. */strategies: AuthStrategy[];
   jwt?: JwtOptions;
   apiToken?: ApiTokenOptions;
   system?: SystemOptions;
+  oauth?: OAuthOptions;
+  /**
+   * When set, a `401` response carries
+   * `WWW-Authenticate: Bearer resource_metadata="<url>"` (RFC 9728) so OAuth
+   * clients can discover the authorization server. Otherwise a bare `Bearer`.
+   */
+  resourceMetadataUrl?: string;
   /**
    * Optional origin allowlist. Strings are exact-matched; RegExps are tested.
    * Requests without an Origin header are never rejected by this check.
@@ -52,12 +83,46 @@ type AuthMiddlewareOptions = {
 //#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.
+ * Koa middleware that authenticates requests via Bearer token. Supports JWT,
+ * hashed API tokens, a shared system secret, and OAuth provider tokens (the
+ * `oauth` strategy — the resource-server role). Sets `ctx.state.user` and
+ * `ctx.state.authStrategy` on success; emits `401` (with a `WWW-Authenticate`
+ * header, RFC 9728 when `resourceMetadataUrl` is set) for missing/invalid
+ * tokens, and `403` when a verified token is missing a required scope.
  */
 declare const authMiddleware: (options: AuthMiddlewareOptions) => (ctx: Context, next: Next) => Promise<void>;
 //#endregion
+//#region src/oauthServer.d.ts
+/**
+ * Mounts an OAuth 2.1 Authorization Server (issuing tokens) as a Koa `Router`,
+ * adapting the runner-agnostic engine from `@ttoss/auth-core`. Exposes the
+ * authorization endpoint (PKCE S256), token endpoint (`authorization_code` +
+ * `refresh_token`), Dynamic Client Registration, and discovery metadata.
+ *
+ * This is the issuing side of OAuth; pair it with `authMiddleware`'s `oauth`
+ * strategy (the verifying side) when one deployment both issues and verifies.
+ *
+ * @example
+ * ```typescript
+ * import { App, bodyParser } from '@ttoss/http-server';
+ * import { oauthServer } from '@ttoss/http-server-auth';
+ *
+ * const app = new App();
+ * app.use(bodyParser());
+ * app.use(oauthServer({ issuer, clientStore, authCodeStore, issueTokens, onAuthorize }).routes());
+ * ```
+ */
+declare const oauthServer: (options: OAuthServerOptions$1) => Router;
+/**
+ * Koa middleware that serves `GET /.well-known/oauth-protected-resource`
+ * (RFC 9728). Mount it **before** `authMiddleware` so the discovery endpoint
+ * stays unauthenticated (clients fetch it before they have a token).
+ */
+declare const createProtectedResourceMetadataMiddleware: (args: {
+  /** The protected resource's identifier URI. */resource: string; /** Authorization server issuer URIs that issue tokens for this resource. */
+  authorizationServers: string[];
+}) => Middleware;
+//#endregion
 //#region src/origin.d.ts
 /**
  * Returns true if origin matches any entry in the allowlist.
@@ -75,4 +140,4 @@ declare const isOriginAllowed: (origin: string, allowedOrigins: Array<string | R
  */
 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 };
+export { type ApiTokenOptions, type AuthCodeStore, type AuthMiddlewareOptions, type AuthStrategy, type AuthenticatedUser, type AuthorizeRequest, type ClientStore, type IssueTokensArgs, type IssuedTokens, type JwtOptions, type OAuthClient, type OAuthClientMetadata, type OAuthHandlers, type OAuthOptions, type OAuthServerOptions, type OnAuthorizeArgs, type OnAuthorizeResult, type OnRefreshTokenArgs, type OnRefreshTokenResult, type StoredAuthorizationCode, type SystemOptions, authMiddleware, createOAuthHandlers, createProtectedResourceMetadataMiddleware, getWwwAuthenticateHeader, isOriginAllowed, oauthServer, requireAuth };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 
-import { Context, Next } from "@ttoss/http-server";
+import { AuthCodeStore, AuthorizeRequest, ClientStore, IssueTokensArgs, IssuedTokens, OAuthClient, OAuthClientMetadata, OAuthHandlers, OAuthServerOptions, OAuthServerOptions as OAuthServerOptions$1, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, StoredAuthorizationCode, createOAuthHandlers, getWwwAuthenticateHeader } from "@ttoss/auth-core";
+import { Context, Middleware, Next, Router } from "@ttoss/http-server";
 
 //#region src/types.d.ts
 type AuthenticatedUser = {
@@ -7,7 +8,7 @@ type AuthenticatedUser = {
   email?: string;
   [key: string]: unknown;
 };
-type AuthStrategy = 'jwt' | 'apiToken' | 'system';
+type AuthStrategy = 'jwt' | 'apiToken' | 'system' | 'oauth';
 type JwtOptions = {
   secret: string;
   /**
@@ -33,11 +34,41 @@ type SystemOptions = {
   secret: string; /** User attached to ctx.state.user for system calls. */
   user: AuthenticatedUser;
 };
+type OAuthOptions = {
+  /**
+   * Verifies a Bearer token issued by an OAuth provider (Cognito, Auth0,
+   * Keycloak, your own authorization server, …). Resolve with the verified
+   * payload, return `null`, or throw to reject — both rejection forms yield a
+   * `401`. Wrap a provider SDK here (e.g. `CognitoJwtVerifier` from
+   * `@ttoss/auth-core/amazon-cognito`) to keep this package provider-agnostic.
+   *
+   * Receives the Koa `ctx` as a second argument for request-scoped work.
+   */
+  verify: (token: string, ctx: Context) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+  /**
+   * Maps the verified payload to an AuthenticatedUser. Defaults to the payload
+   * itself with `id` taken from `sub`, so claims like `scope` remain available
+   * on `ctx.state.user`.
+   */
+  mapPayload?: (payload: Record<string, unknown>, ctx: Context) => AuthenticatedUser | null;
+  /**
+   * Scopes that must all be present on the token's space-separated `scope`
+   * claim. A verified token missing any of them yields a `403`.
+   */
+  requiredScopes?: string[];
+};
 type AuthMiddlewareOptions = {
   /** Ordered list of strategies to attempt. First match wins. */strategies: AuthStrategy[];
   jwt?: JwtOptions;
   apiToken?: ApiTokenOptions;
   system?: SystemOptions;
+  oauth?: OAuthOptions;
+  /**
+   * When set, a `401` response carries
+   * `WWW-Authenticate: Bearer resource_metadata="<url>"` (RFC 9728) so OAuth
+   * clients can discover the authorization server. Otherwise a bare `Bearer`.
+   */
+  resourceMetadataUrl?: string;
   /**
    * Optional origin allowlist. Strings are exact-matched; RegExps are tested.
    * Requests without an Origin header are never rejected by this check.
@@ -52,12 +83,46 @@ type AuthMiddlewareOptions = {
 //#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.
+ * Koa middleware that authenticates requests via Bearer token. Supports JWT,
+ * hashed API tokens, a shared system secret, and OAuth provider tokens (the
+ * `oauth` strategy — the resource-server role). Sets `ctx.state.user` and
+ * `ctx.state.authStrategy` on success; emits `401` (with a `WWW-Authenticate`
+ * header, RFC 9728 when `resourceMetadataUrl` is set) for missing/invalid
+ * tokens, and `403` when a verified token is missing a required scope.
  */
 declare const authMiddleware: (options: AuthMiddlewareOptions) => (ctx: Context, next: Next) => Promise<void>;
 //#endregion
+//#region src/oauthServer.d.ts
+/**
+ * Mounts an OAuth 2.1 Authorization Server (issuing tokens) as a Koa `Router`,
+ * adapting the runner-agnostic engine from `@ttoss/auth-core`. Exposes the
+ * authorization endpoint (PKCE S256), token endpoint (`authorization_code` +
+ * `refresh_token`), Dynamic Client Registration, and discovery metadata.
+ *
+ * This is the issuing side of OAuth; pair it with `authMiddleware`'s `oauth`
+ * strategy (the verifying side) when one deployment both issues and verifies.
+ *
+ * @example
+ * ```typescript
+ * import { App, bodyParser } from '@ttoss/http-server';
+ * import { oauthServer } from '@ttoss/http-server-auth';
+ *
+ * const app = new App();
+ * app.use(bodyParser());
+ * app.use(oauthServer({ issuer, clientStore, authCodeStore, issueTokens, onAuthorize }).routes());
+ * ```
+ */
+declare const oauthServer: (options: OAuthServerOptions$1) => Router;
+/**
+ * Koa middleware that serves `GET /.well-known/oauth-protected-resource`
+ * (RFC 9728). Mount it **before** `authMiddleware` so the discovery endpoint
+ * stays unauthenticated (clients fetch it before they have a token).
+ */
+declare const createProtectedResourceMetadataMiddleware: (args: {
+  /** The protected resource's identifier URI. */resource: string; /** Authorization server issuer URIs that issue tokens for this resource. */
+  authorizationServers: string[];
+}) => Middleware;
+//#endregion
 //#region src/origin.d.ts
 /**
  * Returns true if origin matches any entry in the allowlist.
@@ -75,4 +140,4 @@ declare const isOriginAllowed: (origin: string, allowedOrigins: Array<string | R
  */
 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 };
+export { type ApiTokenOptions, type AuthCodeStore, type AuthMiddlewareOptions, type AuthStrategy, type AuthenticatedUser, type AuthorizeRequest, type ClientStore, type IssueTokensArgs, type IssuedTokens, type JwtOptions, type OAuthClient, type OAuthClientMetadata, type OAuthHandlers, type OAuthOptions, type OAuthServerOptions, type OnAuthorizeArgs, type OnAuthorizeResult, type OnRefreshTokenArgs, type OnRefreshTokenResult, type StoredAuthorizationCode, type SystemOptions, authMiddleware, createOAuthHandlers, createProtectedResourceMetadataMiddleware, getWwwAuthenticateHeader, isOriginAllowed, oauthServer, requireAuth };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import crypto from "node:crypto";
-import { hashApiToken, verifyJwt } from "@ttoss/auth-core";
+import { createOAuthHandlers, createOAuthHandlers as createOAuthHandlers$1, getWwwAuthenticateHeader, hashApiToken, verifyJwt } from "@ttoss/auth-core";
+import { Router } from "@ttoss/http-server";
 
 //#region src/origin.ts
 /**
@@ -42,38 +43,84 @@ var trySystem = (token, opts) => {
   if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return null;
   return opts.user;
 };
+/** Sentinel: token verified but missing a required scope → 403, not 401. */
+var FORBIDDEN = Symbol("forbidden");
+var hasRequiredScopes = (requiredScopes, payload) => {
+  const tokenScopes = (typeof payload.scope === "string" ? payload.scope : "").split(" ");
+  return requiredScopes.every(s => {
+    return tokenScopes.includes(s);
+  });
+};
+var tryOauth = async (token, opts, ctx) => {
+  let payload;
+  try {
+    payload = await opts.verify(token, ctx);
+  } catch {
+    return null;
+  }
+  if (!payload) return null;
+  if (opts.requiredScopes?.length && !hasRequiredScopes(opts.requiredScopes, payload)) return FORBIDDEN;
+  if (opts.mapPayload) return opts.mapPayload(payload, ctx);
+  return {
+    id: String(payload.sub ?? ""),
+    ...payload
+  };
+};
+var resolveStrategy = async (strategy, token, options, ctx) => {
+  if (strategy === "jwt" && options.jwt) return tryJwt(token, options.jwt, ctx);
+  if (strategy === "apiToken" && options.apiToken) return tryApiToken(token, options.apiToken, ctx);
+  if (strategy === "system" && options.system) return trySystem(token, options.system);
+  if (strategy === "oauth" && options.oauth) return tryOauth(token, options.oauth, ctx);
+  return null;
+};
 var resolveUser = async (token, options, ctx) => {
   for (const strategy of options.strategies) {
-    let user = null;
-    if (strategy === "jwt" && options.jwt) user = tryJwt(token, options.jwt, ctx);else if (strategy === "apiToken" && options.apiToken) user = await tryApiToken(token, options.apiToken, ctx);else if (strategy === "system" && options.system) user = trySystem(token, options.system);
-    if (user) return {
-      user,
+    const result = await resolveStrategy(strategy, token, options, ctx);
+    if (result === FORBIDDEN) return FORBIDDEN;
+    if (result) return {
+      user: result,
       strategy
     };
   }
   return null;
 };
+/** Throws 403 when an `allowedOrigins` list is set and the Origin doesn't match. */
+var enforceOrigin = (ctx, allowedOrigins) => {
+  if (!allowedOrigins) return;
+  const origin = ctx.get("Origin");
+  if (origin && !isOriginAllowed(origin, allowedOrigins)) ctx.throw(403, "Invalid origin");
+};
+/** Extracts the Bearer token from the Authorization header, or `null`. */
+var extractBearer = ctx => {
+  const authHeader = ctx.get("Authorization");
+  return authHeader && authHeader.startsWith("Bearer ") ? authHeader.slice(7) : 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.
+* Koa middleware that authenticates requests via Bearer token. Supports JWT,
+* hashed API tokens, a shared system secret, and OAuth provider tokens (the
+* `oauth` strategy — the resource-server role). Sets `ctx.state.user` and
+* `ctx.state.authStrategy` on success; emits `401` (with a `WWW-Authenticate`
+* header, RFC 9728 when `resourceMetadataUrl` is set) for missing/invalid
+* tokens, and `403` when a verified token is missing a required scope.
 */
 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 unauthorized = {
+    headers: {
+      "WWW-Authenticate": options.resourceMetadataUrl ? `Bearer resource_metadata="${options.resourceMetadataUrl}"` : "Bearer"
     }
-    const authHeader = ctx.get("Authorization");
-    const token = authHeader && authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+  };
+  return async (ctx, next) => {
+    enforceOrigin(ctx, options.allowedOrigins);
+    const token = extractBearer(ctx);
     if (!token) {
-      if (required) ctx.throw(401, "Unauthorized");
+      if (required) ctx.throw(401, "Unauthorized", unauthorized);
       return next();
     }
     const result = await resolveUser(token, options, ctx);
+    if (result === FORBIDDEN) ctx.throw(403, "Forbidden");
     if (!result) {
-      if (required) ctx.throw(401, "Unauthorized");
+      if (required) ctx.throw(401, "Unauthorized", unauthorized);
       return next();
     }
     ctx.state.user = result.user;
@@ -82,6 +129,89 @@ var authMiddleware = options => {
   };
 };
 
+//#endregion
+//#region src/oauthServer.ts
+/** Normalizes a Koa query/header value (which may be an array) to a string. */
+var firstValue = value => {
+  return Array.isArray(value) ? value[0] : value;
+};
+var toOAuthRequest = ctx => {
+  const query = {};
+  for (const [key, value] of Object.entries(ctx.query)) query[key] = firstValue(value);
+  const headers = {};
+  for (const [key, value] of Object.entries(ctx.headers)) headers[key] = firstValue(value);
+  return {
+    query,
+    body: ctx.request.body ?? {},
+    headers
+  };
+};
+var applyResponse = (ctx, res) => {
+  if (res.redirect !== void 0) {
+    ctx.redirect(res.redirect);
+    return;
+  }
+  ctx.status = res.status;
+  ctx.body = res.body;
+};
+/**
+* Mounts an OAuth 2.1 Authorization Server (issuing tokens) as a Koa `Router`,
+* adapting the runner-agnostic engine from `@ttoss/auth-core`. Exposes the
+* authorization endpoint (PKCE S256), token endpoint (`authorization_code` +
+* `refresh_token`), Dynamic Client Registration, and discovery metadata.
+*
+* This is the issuing side of OAuth; pair it with `authMiddleware`'s `oauth`
+* strategy (the verifying side) when one deployment both issues and verifies.
+*
+* @example
+* ```typescript
+* import { App, bodyParser } from '@ttoss/http-server';
+* import { oauthServer } from '@ttoss/http-server-auth';
+*
+* const app = new App();
+* app.use(bodyParser());
+* app.use(oauthServer({ issuer, clientStore, authCodeStore, issueTokens, onAuthorize }).routes());
+* ```
+*/
+var oauthServer = options => {
+  const engine = createOAuthHandlers$1(options);
+  const router = new Router();
+  router.get("/.well-known/oauth-authorization-server", ctx => {
+    applyResponse(ctx, engine.authorizationServerMetadata());
+  });
+  const prm = engine.protectedResourceMetadata();
+  if (prm) router.get("/.well-known/oauth-protected-resource", ctx => {
+    applyResponse(ctx, prm);
+  });
+  router.get(engine.paths.authorize, async ctx => {
+    applyResponse(ctx, await engine.authorize(toOAuthRequest(ctx)));
+  });
+  router.post(engine.paths.token, async ctx => {
+    applyResponse(ctx, await engine.token(toOAuthRequest(ctx)));
+  });
+  router.post(engine.paths.register, async ctx => {
+    applyResponse(ctx, await engine.register(toOAuthRequest(ctx)));
+  });
+  return router;
+};
+/**
+* Koa middleware that serves `GET /.well-known/oauth-protected-resource`
+* (RFC 9728). Mount it **before** `authMiddleware` so the discovery endpoint
+* stays unauthenticated (clients fetch it before they have a token).
+*/
+var createProtectedResourceMetadataMiddleware = args => {
+  return async (ctx, next) => {
+    if (ctx.method === "GET" && ctx.path === "/.well-known/oauth-protected-resource") {
+      ctx.body = {
+        resource: args.resource,
+        authorization_servers: args.authorizationServers
+      };
+      return;
+    }
+    await next();
+  };
+};
+
 //#endregion
 //#region src/requireAuth.ts
 /**
@@ -99,4 +229,4 @@ var requireAuth = options => {
 };
 
 //#endregion
-export { authMiddleware, isOriginAllowed, requireAuth };
+export { authMiddleware, createOAuthHandlers, createProtectedResourceMetadataMiddleware, getWwwAuthenticateHeader, isOriginAllowed, oauthServer, requireAuth };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-auth",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Authentication middleware for @ttoss/http-server",
   "keywords": [
     "auth",
@@ -32,18 +32,18 @@
     "dist"
   ],
   "dependencies": {
-    "@ttoss/auth-core": "^0.6.0"
+    "@ttoss/auth-core": "^0.6.2"
   },
   "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"
+    "@ttoss/config": "^1.37.17",
+    "@ttoss/http-server": "^0.7.1"
   },
   "peerDependencies": {
-    "@ttoss/http-server": "^0.6.1"
+    "@ttoss/http-server": "^0.7.1"
   },
   "publishConfig": {
     "access": "public",