@uphold/fastify-openapi-router-plugin 0.6.0 → 0.7.1

package/README.md

@@ -136,6 +136,8 @@ await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
 });
 ```
 
+Any error thrown by the security handler will be internally wrapped in a `SecurityHandlerError` with `fatal = true`, which will stop further security blocks to be executed. If you wish to continue with the next security block, you can `throw createSecurityHandlerError(error, false)` in your handler.
+
 > [!TIP]
 > The `scopes` returned by the security handler can contain trailing **wildcards**. For example, if the security handler returns `{ scopes: ['pets:*'] }`, the route will be authorized for any security scope that starts with `pets:`.
 
@@ -171,8 +173,8 @@ The `securityReport` property of the unauthorized error contains an array of obj
     schemes: {
       OAuth2: {
         ok: false,
-        // Error thrown by the security handler or fastify.oas.errors.ScopesMismatchError if the scopes were not satisfied.
-        error: new Error(),
+        // The error will be either be a `fastify.oas.errors.SecurityHandlerError` or a `fastify.oas.errors.ScopesMismatchError` if the scopes were not satisfied.
+        error: <Error>,
       }
     }
   }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@uphold/fastify-openapi-router-plugin",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "A plugin for Fastify to connect routes with a OpenAPI 3.x specification",
   "main": "./src/index.js",
-  "types": "types/index.d.ts",
+  "types": "./types/index.d.ts",
   "type": "module",
   "files": [
-    "src"
+    "src",
+    "types"
   ],
   "scripts": {
     "release": "release-it",

package/src/errors/index.js

@@ -1,9 +1,11 @@
 import { ScopesMismatchError, createScopesMismatchError } from './scopes-mismatch-error.js';
+import { SecurityHandlerError, createSecurityHandlerError } from './security-handler-error.js';
 import { UnauthorizedError, createUnauthorizedError } from './unauthorized-error.js';
 
 const errors = {
   ScopesMismatchError,
+  SecurityHandlerError,
   UnauthorizedError
 };
 
-export { createScopesMismatchError, createUnauthorizedError, errors };
+export { createScopesMismatchError, createUnauthorizedError, createSecurityHandlerError, errors };

package/src/errors/security-handler-error.js

@@ -0,0 +1,14 @@
+import createError from '@fastify/error';
+
+const SecurityHandlerError = createError('FST_OAS_SECURITY_HANDLER_ERROR', 'Security handler has thrown an error', 403);
+
+const createSecurityHandlerError = (handlerError, fatal = true) => {
+  const err = new SecurityHandlerError();
+
+  err.fatal = fatal;
+  err.cause = handlerError;
+
+  return err;
+};
+
+export { SecurityHandlerError, createSecurityHandlerError };

package/src/parser/security.js

@@ -1,5 +1,6 @@
 import { DECORATOR_NAME } from '../utils/constants.js';
-import { createScopesMismatchError, createUnauthorizedError } from '../errors/index.js';
+import { SecurityHandlerError } from '../errors/security-handler-error.js';
+import { createScopesMismatchError, createSecurityHandlerError, createUnauthorizedError } from '../errors/index.js';
 import { extractSecuritySchemeValueFromRequest, verifyScopes } from '../utils/security.js';
 import _ from 'lodash-es';
 import pProps from 'p-props';
@@ -44,7 +45,17 @@ export const applySecurity = (operation, spec, securityHandlers, securityErrorMa
         promisesCache.set(name, promise);
       }
 
-      return await promise;
+      try {
+        return await promise;
+      } catch (error) {
+        let handlerError = error;
+
+        if (!(handlerError instanceof SecurityHandlerError)) {
+          handlerError = createSecurityHandlerError(error, true);
+        }
+
+        throw handlerError;
+      }
     };
 
     // Iterate over each security on the array, calling each one a `block`.
@@ -62,7 +73,7 @@ export const applySecurity = (operation, spec, securityHandlers, securityErrorMa
       }
 
       // Iterate over each security scheme in the block and call the security handler.
-      // We leverage cache when calling the handler to avoid multiple calls to the same function
+      // We leverage cache when calling the handler to avoid multiple calls to the same function.
       const blockResults = await pProps(block, async (requiredScopes, name) => {
         try {
           const resolved = await callSecurityHandler(name);
@@ -83,11 +94,15 @@ export const applySecurity = (operation, spec, securityHandlers, securityErrorMa
 
       // Requirements in a block are AND'd together.
       const ok = Object.values(blockResults).every(result => result.ok);
+      const fatal = Object.values(blockResults).some(
+        result => result.error instanceof SecurityHandlerError && result.error.fatal
+      );
 
       report.push({ ok, schemes: blockResults });
 
       // Blocks themselves are OR'd together, so we can break early if one block passes.
-      if (ok) {
+      // If a fatal error is found in a block, we can break early as well.
+      if (ok || fatal) {
         break;
       }
     }

package/src/parser/security.test.js

@@ -1,7 +1,17 @@
 import { DECORATOR_NAME } from '../utils/constants.js';
+import { SecurityHandlerError } from '../errors/security-handler-error.js';
 import { applySecurity, validateSecurity } from './security.js';
+import { createSecurityHandlerError, errors } from '../errors/index.js';
 import { describe, expect, it, vi } from 'vitest';
-import { errors } from '../errors/index.js';
+
+expect.addSnapshotSerializer({
+  serialize(val, config, indentation, depth, refs, printer) {
+    val.cause.message = `${val.message}: ${val.cause.message}`;
+
+    return printer(val.cause, config, indentation, depth, refs);
+  },
+  test: val => val instanceof SecurityHandlerError
+});
 
 describe('validateSecurity()', () => {
   it('should throw on invalid security handler option', () => {
@@ -154,7 +164,7 @@ describe('applySecurity()', () => {
     `);
   });
 
-  it('should try second security block if the first one fails', async () => {
+  it('should try second security block if the first one fails with a non-fatal error', async () => {
     const request = {
       [DECORATOR_NAME]: {},
       headers: {
@@ -175,7 +185,7 @@ describe('applySecurity()', () => {
     };
     const securityHandlers = {
       ApiKey: vi.fn(() => {
-        throw new Error('ApiKey error');
+        throw createSecurityHandlerError(new Error('ApiKey error'), false);
       }),
       OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
     };
@@ -195,7 +205,7 @@ describe('applySecurity()', () => {
           "ok": false,
           "schemes": {
             "ApiKey": {
-              "error": [Error: ApiKey error],
+              "error": [Error: Security handler has thrown an error: ApiKey error],
               "ok": false,
             },
           },
@@ -213,7 +223,7 @@ describe('applySecurity()', () => {
     `);
   });
 
-  it('should throw an error if all security blocks fail', async () => {
+  it('should stop when a security block fails with a fatal error', async () => {
     const request = {
       [DECORATOR_NAME]: {},
       headers: {
@@ -236,8 +246,56 @@ describe('applySecurity()', () => {
       ApiKey: vi.fn(() => {
         throw new Error('ApiKey error');
       }),
+      OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
+    };
+
+    const onRequest = applySecurity(operation, spec, securityHandlers);
+
+    try {
+      await onRequest(request);
+    } catch (error) {
+      expect(error).toBeInstanceOf(errors.UnauthorizedError);
+      expect(error.securityReport).toMatchInlineSnapshot(`
+        [
+          {
+            "ok": false,
+            "schemes": {
+              "ApiKey": {
+                "error": [Error: Security handler has thrown an error: ApiKey error],
+                "ok": false,
+              },
+            },
+          },
+        ]
+      `);
+    }
+  });
+
+  it('should throw an error if all security blocks fail', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        'X-API-KEY': 'api key',
+        authorization: 'Bearer bearer token'
+      }
+    };
+    const operation = {
+      security: [{ ApiKey: [] }, { OAuth2: [] }]
+    };
+    const spec = {
+      components: {
+        securitySchemes: {
+          ApiKey: { in: 'header', name: 'X-API-KEY', type: 'apiKey' },
+          OAuth2: { type: 'oauth2' }
+        }
+      }
+    };
+    const securityHandlers = {
+      ApiKey: vi.fn(() => {
+        throw createSecurityHandlerError(new Error('ApiKey error'), false);
+      }),
       OAuth2: vi.fn(() => {
-        throw new Error('OAuth2 error');
+        throw createSecurityHandlerError(new Error('OAuth2 error'), false);
       })
     };
 
@@ -255,7 +313,7 @@ describe('applySecurity()', () => {
             "ok": false,
             "schemes": {
               "ApiKey": {
-                "error": [Error: ApiKey error],
+                "error": [Error: Security handler has thrown an error: ApiKey error],
                 "ok": false,
               },
             },
@@ -264,7 +322,7 @@ describe('applySecurity()', () => {
             "ok": false,
             "schemes": {
               "OAuth2": {
-                "error": [Error: OAuth2 error],
+                "error": [Error: Security handler has thrown an error: OAuth2 error],
                 "ok": false,
               },
             },

package/types/index.d.ts

@@ -0,0 +1,68 @@
+import { RouteOptions as FastifyRouteOptions, FastifyPluginCallback, FastifyRequest } from 'fastify'
+import OpenAPI from 'openapi-types';
+import { DECORATOR_NAME } from '../src/utils/constants'
+import { errors } from '../src'
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    [DECORATOR_NAME]: {
+      operation: OpenAPI.OpenAPIV3_1.OperationObject,
+      security: SecurityData
+      securityReport: SecurityReport
+    }
+  }
+
+  interface FastifyInstance {
+    [DECORATOR_NAME]: {
+      errors: typeof errors
+      route: (opts: RouteOptions) => FastifyInstance;
+    }
+  }
+}
+
+export interface SecurityData {
+  [key:string]: any
+}
+
+export type SecurityReport = SecurityReportBlock[]
+
+export interface SecurityReportBlock {
+  ok: boolean
+  schemes: {
+    [key:string]: {
+      ok: boolean,
+      data?: any
+      error?: any
+    }
+  }
+}
+
+export type SecurityHandler = (value: string, request: FastifyRequest) => SecurityHandlerReturn | undefined
+
+export interface SecurityHandlerReturn { data?: any, scopes?: string[] }
+
+export interface RouteOptions extends Omit<FastifyRouteOptions, "method" | "schema" | "url"> {
+  operationId: string
+}
+
+export interface PluginOptions {
+  spec?: string | OpenAPI.OpenAPIV3.Document | OpenAPI.OpenAPIV3_1.Document
+  securityErrorMapper: (error: errors.UnauthorizedError) => Error | undefined
+  securityHandlers?: {
+    [key:string]: SecurityHandler
+  }
+}
+
+export const openApiRouterPlugin: FastifyPluginCallback<PluginOptions>
+
+export function verifyScopes(providedScopes: string[], requiredScopes: string[]): string[]
+
+export function createSecurityHandlerError(error: Error, force?: boolean): typeof errors.SecurityHandlerError
+
+export function createScopesMismatchError(providedScopes: string[], requiredScopes: string[], missingScopes: string[]): typeof errors.ScopesMismatchError
+
+export function createUnauthorizedError(securityReport: SecurityReport): typeof errors.UnauthorizedError
+
+export { errors }
+
+export default openApiRouterPlugin