Bearer auth middleware

Author: jspahrsummers

src/server/auth/errors.ts

@@ -179,4 +179,13 @@ export class InvalidClientMetadataError extends OAuthError {
  constructor(message: string, errorUri?: string) {
  super("invalid_client_metadata", message, errorUri);
  }
-}
+}
+
+/**
+ * Insufficient scope error - The request requires higher privileges than provided by the access token.
+ */
+export class InsufficientScopeError extends OAuthError {
+ constructor(message: string, errorUri?: string) {
+ super("insufficient_scope", message, errorUri);
+ }
+}

src/server/auth/handlers/authorize.test.ts

@@ -4,6 +4,8 @@ import { OAuthRegisteredClientsStore } from '../clients.js';
 import { OAuthClientInformationFull, OAuthTokens } from '../../../shared/auth.js';
 import express, { Response } from 'express';
 import supertest from 'supertest';
+import { AuthInfo } from '../types.js';
+import { InvalidTokenError } from '../errors.js';
 
 describe('Authorization Handler', () => {
  // Mock client data
@@ -72,6 +74,18 @@ describe('Authorization Handler', () => {
  };
  },
 
+ async verifyAccessToken(token: string): Promise<AuthInfo> {
+ if (token === 'valid_token') {
+ return {
+ token,
+ clientId: 'valid-client',
+ scopes: ['read', 'write'],
+ expiresAt: Date.now() / 1000 + 3600
+ };
+ }
+ throw new InvalidTokenError('Token is invalid or expired');
+ },
+
  async revokeToken(): Promise<void> {
  // Do nothing in mock
  }

src/server/auth/handlers/revoke.test.ts

@@ -4,6 +4,8 @@ import { OAuthRegisteredClientsStore } from '../clients.js';
 import { OAuthClientInformationFull, OAuthTokenRevocationRequest, OAuthTokens } from '../../../shared/auth.js';
 import express, { Response } from 'express';
 import supertest from 'supertest';
+import { AuthInfo } from '../types.js';
+import { InvalidTokenError } from '../errors.js';
 
 describe('Revocation Handler', () => {
  // Mock client data
@@ -53,6 +55,18 @@ describe('Revocation Handler', () => {
  };
  },
 
+ async verifyAccessToken(token: string): Promise<AuthInfo> {
+ if (token === 'valid_token') {
+ return {
+ token,
+ clientId: 'valid-client',
+ scopes: ['read', 'write'],
+ expiresAt: Date.now() / 1000 + 3600
+ };
+ }
+ throw new InvalidTokenError('Token is invalid or expired');
+ },
+
  async revokeToken(_client: OAuthClientInformationFull, _request: OAuthTokenRevocationRequest): Promise<void> {
  // Success - do nothing in mock
  }
@@ -86,6 +100,18 @@ describe('Revocation Handler', () => {
  expires_in: 3600,
  refresh_token: 'new_mock_refresh_token'
  };
+ },
+
+ async verifyAccessToken(token: string): Promise<AuthInfo> {
+ if (token === 'valid_token') {
+ return {
+ token,
+ clientId: 'valid-client',
+ scopes: ['read', 'write'],
+ expiresAt: Date.now() / 1000 + 3600
+ };
+ }
+ throw new InvalidTokenError('Token is invalid or expired');
  }
  // No revokeToken method
  };

src/server/auth/handlers/token.test.ts

@@ -5,7 +5,8 @@ import { OAuthClientInformationFull, OAuthTokenRevocationRequest, OAuthTokens }
 import express, { Response } from 'express';
 import supertest from 'supertest';
 import * as pkceChallenge from 'pkce-challenge';
-import { InvalidGrantError } from '../errors.js';
+import { InvalidGrantError, InvalidTokenError } from '../errors.js';
+import { AuthInfo } from '../types.js';
 
 // Mock pkce-challenge
 jest.mock('pkce-challenge', () => ({
@@ -84,6 +85,18 @@ describe('Token Handler', () => {
  throw new InvalidGrantError('The refresh token is invalid or has expired');
  },
 
+ async verifyAccessToken(token: string): Promise<AuthInfo> {
+ if (token === 'valid_token') {
+ return {
+ token,
+ clientId: 'valid-client',
+ scopes: ['read', 'write'],
+ expiresAt: Date.now() / 1000 + 3600
+ };
+ }
+ throw new InvalidTokenError('Token is invalid or expired');
+ },
+
  async revokeToken(_client: OAuthClientInformationFull, _request: OAuthTokenRevocationRequest): Promise<void> {
  // Do nothing in mock
  }

src/server/auth/middleware/bearerAuth.test.ts

@@ -0,0 +1,252 @@
+import { Request, Response } from "express";
+import { requireBearerAuth } from "./bearerAuth.js";
+import { AuthInfo } from "../types.js";
+import { InsufficientScopeError, InvalidTokenError, OAuthError, ServerError } from "../errors.js";
+import { OAuthServerProvider } from "../provider.js";
+import { OAuthRegisteredClientsStore } from "../clients.js";
+
+// Mock provider
+const mockVerifyAccessToken = jest.fn();
+const mockProvider: OAuthServerProvider = {
+ clientsStore: {} as OAuthRegisteredClientsStore,
+ authorize: jest.fn(),
+ challengeForAuthorizationCode: jest.fn(),
+ exchangeAuthorizationCode: jest.fn(),
+ exchangeRefreshToken: jest.fn(),
+ verifyAccessToken: mockVerifyAccessToken,
+};
+
+describe("requireBearerAuth middleware", () => {
+ let mockRequest: Partial<Request>;
+ let mockResponse: Partial<Response>;
+ let nextFunction: jest.Mock;
+
+ beforeEach(() => {
+ mockRequest = {
+ headers: {},
+ };
+ mockResponse = {
+ status: jest.fn().mockReturnThis(),
+ json: jest.fn(),
+ set: jest.fn().mockReturnThis(),
+ };
+ nextFunction = jest.fn();
+ jest.clearAllMocks();
+ });
+
+ it("should call next when token is valid", async () => {
+ const validAuthInfo: AuthInfo = {
+ token: "valid-token",
+ clientId: "client-123",
+ scopes: ["read", "write"],
+ };
+ mockVerifyAccessToken.mockResolvedValue(validAuthInfo);
+
+ mockRequest.headers = {
+ authorization: "Bearer valid-token",
+ };
+
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("valid-token");
+ expect(mockRequest.auth).toEqual(validAuthInfo);
+ expect(nextFunction).toHaveBeenCalled();
+ expect(mockResponse.status).not.toHaveBeenCalled();
+ expect(mockResponse.json).not.toHaveBeenCalled();
+ });
+
+ it("should require specific scopes when configured", async () => {
+ const authInfo: AuthInfo = {
+ token: "valid-token",
+ clientId: "client-123",
+ scopes: ["read"],
+ };
+ mockVerifyAccessToken.mockResolvedValue(authInfo);
+
+ mockRequest.headers = {
+ authorization: "Bearer valid-token",
+ };
+
+ const middleware = requireBearerAuth({
+ provider: mockProvider,
+ requiredScopes: ["read", "write"]
+ });
+
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("valid-token");
+ expect(mockResponse.status).toHaveBeenCalledWith(403);
+ expect(mockResponse.set).toHaveBeenCalledWith(
+ "WWW-Authenticate",
+ expect.stringContaining('Bearer error="insufficient_scope"')
+ );
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({ error: "insufficient_scope", error_description: "Insufficient scope" })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+
+ it("should accept token with all required scopes", async () => {
+ const authInfo: AuthInfo = {
+ token: "valid-token",
+ clientId: "client-123",
+ scopes: ["read", "write", "admin"],
+ };
+ mockVerifyAccessToken.mockResolvedValue(authInfo);
+
+ mockRequest.headers = {
+ authorization: "Bearer valid-token",
+ };
+
+ const middleware = requireBearerAuth({
+ provider: mockProvider,
+ requiredScopes: ["read", "write"]
+ });
+
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("valid-token");
+ expect(mockRequest.auth).toEqual(authInfo);
+ expect(nextFunction).toHaveBeenCalled();
+ expect(mockResponse.status).not.toHaveBeenCalled();
+ expect(mockResponse.json).not.toHaveBeenCalled();
+ });
+
+ it("should return 401 when no Authorization header is present", async () => {
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).not.toHaveBeenCalled();
+ expect(mockResponse.status).toHaveBeenCalledWith(401);
+ expect(mockResponse.set).toHaveBeenCalledWith(
+ "WWW-Authenticate",
+ expect.stringContaining('Bearer error="invalid_token"')
+ );
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({ error: "invalid_token", error_description: "Missing Authorization header" })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+
+ it("should return 401 when Authorization header format is invalid", async () => {
+ mockRequest.headers = {
+ authorization: "InvalidFormat",
+ };
+
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).not.toHaveBeenCalled();
+ expect(mockResponse.status).toHaveBeenCalledWith(401);
+ expect(mockResponse.set).toHaveBeenCalledWith(
+ "WWW-Authenticate",
+ expect.stringContaining('Bearer error="invalid_token"')
+ );
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({
+ error: "invalid_token",
+ error_description: "Invalid Authorization header format, expected 'Bearer TOKEN'"
+ })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+
+ it("should return 401 when token verification fails with InvalidTokenError", async () => {
+ mockRequest.headers = {
+ authorization: "Bearer invalid-token",
+ };
+
+ mockVerifyAccessToken.mockRejectedValue(new InvalidTokenError("Token expired"));
+
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("invalid-token");
+ expect(mockResponse.status).toHaveBeenCalledWith(401);
+ expect(mockResponse.set).toHaveBeenCalledWith(
+ "WWW-Authenticate",
+ expect.stringContaining('Bearer error="invalid_token"')
+ );
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({ error: "invalid_token", error_description: "Token expired" })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+
+ it("should return 403 when access token has insufficient scopes", async () => {
+ mockRequest.headers = {
+ authorization: "Bearer valid-token",
+ };
+
+ mockVerifyAccessToken.mockRejectedValue(new InsufficientScopeError("Required scopes: read, write"));
+
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("valid-token");
+ expect(mockResponse.status).toHaveBeenCalledWith(403);
+ expect(mockResponse.set).toHaveBeenCalledWith(
+ "WWW-Authenticate",
+ expect.stringContaining('Bearer error="insufficient_scope"')
+ );
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({ error: "insufficient_scope", error_description: "Required scopes: read, write" })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+
+ it("should return 500 when a ServerError occurs", async () => {
+ mockRequest.headers = {
+ authorization: "Bearer valid-token",
+ };
+
+ mockVerifyAccessToken.mockRejectedValue(new ServerError("Internal server issue"));
+
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("valid-token");
+ expect(mockResponse.status).toHaveBeenCalledWith(500);
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({ error: "server_error", error_description: "Internal server issue" })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+
+ it("should return 400 for generic OAuthError", async () => {
+ mockRequest.headers = {
+ authorization: "Bearer valid-token",
+ };
+
+ mockVerifyAccessToken.mockRejectedValue(new OAuthError("custom_error", "Some OAuth error"));
+
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("valid-token");
+ expect(mockResponse.status).toHaveBeenCalledWith(400);
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({ error: "custom_error", error_description: "Some OAuth error" })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+
+ it("should return 500 when unexpected error occurs", async () => {
+ mockRequest.headers = {
+ authorization: "Bearer valid-token",
+ };
+
+ mockVerifyAccessToken.mockRejectedValue(new Error("Unexpected error"));
+
+ const middleware = requireBearerAuth({ provider: mockProvider });
+ await middleware(mockRequest as Request, mockResponse as Response, nextFunction);
+
+ expect(mockVerifyAccessToken).toHaveBeenCalledWith("valid-token");
+ expect(mockResponse.status).toHaveBeenCalledWith(500);
+ expect(mockResponse.json).toHaveBeenCalledWith(
+ expect.objectContaining({ error: "server_error", error_description: "Internal Server Error" })
+ );
+ expect(nextFunction).not.toHaveBeenCalled();
+ });
+});