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();
+  });
+});