@uphold/fastify-openapi-router-plugin 0.1.0

package/src/parser/security.test.js

@@ -0,0 +1,522 @@
+import { DECORATOR_NAME } from '../utils/constants.js';
+import { describe, expect, it, vi } from 'vitest';
+import { errors } from '../errors/index.js';
+import { parseSecurity, validateSecurity } from './security.js';
+
+describe('validateSecurity()', () => {
+  it('should throw on invalid security handler option', () => {
+    const spec = {
+      components: {
+        securitySchemes: {}
+      }
+    };
+
+    expect.assertions(2);
+
+    try {
+      validateSecurity(spec, {
+        securityHandlers: 'foo'
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(TypeError);
+      expect(error.message).toBe(`Expected 'options.securitySchemes' to be an object.`);
+    }
+  });
+
+  it('should throw on missing security handlers', () => {
+    const spec = {
+      components: {
+        securitySchemes: {
+          foo: {}
+        }
+      }
+    };
+
+    expect.assertions(2);
+
+    try {
+      validateSecurity(spec, {
+        securityHandlers: {}
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(TypeError);
+      expect(error.message).toBe(
+        `Missing or invalid 'options.securityHandlers.foo'. Please provide a function for the given security scheme.`
+      );
+    }
+  });
+
+  it('should throw on invalid security handlers', () => {
+    const spec = {
+      components: {
+        securitySchemes: {
+          foo: {}
+        }
+      }
+    };
+
+    expect.assertions(2);
+
+    try {
+      validateSecurity(spec, {
+        securityHandlers: { foo: {} }
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(TypeError);
+      expect(error.message).toBe(
+        `Missing or invalid 'options.securityHandlers.foo'. Please provide a function for the given security scheme.`
+      );
+    }
+  });
+
+  it('should not throw an error if all security handlers are present', () => {
+    const spec = {
+      components: {
+        securitySchemes: {
+          bar: {},
+          foo: {}
+        }
+      }
+    };
+
+    validateSecurity(spec, {
+      securityHandlers: { bar: () => {}, foo: () => {} }
+    });
+  });
+});
+
+describe('parseSecurity()', () => {
+  it('should return undefined if no security', async () => {
+    expect(parseSecurity({}, {}, {})).toBeUndefined();
+    expect(parseSecurity({ security: [] }, {}, {})).toBeUndefined();
+    expect(parseSecurity({}, { security: [] }, {})).toBeUndefined();
+  });
+
+  it('should return undefined if `security` is disabled in operation', async () => {
+    const onRequest = parseSecurity({ security: [] }, { security: [{ OAuth2: [] }] }, {});
+
+    expect(onRequest).toBeUndefined();
+  });
+
+  it('should stop at the first successful security block', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        'X-API-KEY': 'api key',
+        'X-API-KEY-2': 'api key 2',
+        authorization: 'Bearer bearer token'
+      }
+    };
+    const operation = {
+      security: [{ ApiKey: [], OAuth2: [] }, { ApiKey2: [] }]
+    };
+    const spec = {
+      components: {
+        securitySchemes: {
+          ApiKey: { in: 'header', name: 'X-API-KEY', type: 'apiKey' },
+          ApiKey2: { in: 'header', name: 'X-API-KEY-2', type: 'apiKey' },
+          OAuth2: { type: 'oauth2' }
+        }
+      }
+    };
+    const securityHandlers = {
+      ApiKey: vi.fn(async () => ({ data: 'ApiKey data', scopes: [] })),
+      ApiKey2: vi.fn(async () => ({ data: 'ApiKey2 data', scopes: [] })),
+      OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    await onRequest(request);
+
+    expect(securityHandlers.ApiKey).toHaveBeenCalledTimes(1);
+    expect(securityHandlers.ApiKey).toHaveBeenCalledWith('api key', request);
+    expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
+    expect(securityHandlers.OAuth2).toHaveBeenCalledWith('bearer token', request);
+    expect(securityHandlers.ApiKey2).not.toHaveBeenCalled();
+    expect(request[DECORATOR_NAME].security).toMatchObject({ ApiKey: 'ApiKey data', OAuth2: 'OAuth2 data' });
+    expect(request[DECORATOR_NAME].securityReport).toMatchInlineSnapshot(`
+      [
+        {
+          "ok": true,
+          "schemes": {
+            "ApiKey": {
+              "data": "ApiKey data",
+              "ok": true,
+            },
+            "OAuth2": {
+              "data": "OAuth2 data",
+              "ok": true,
+            },
+          },
+        },
+      ]
+    `);
+  });
+
+  it('should try second security block if the first one fails', 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 new Error('ApiKey error');
+      }),
+      OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    await onRequest(request);
+
+    expect(securityHandlers.ApiKey).toHaveBeenCalledTimes(1);
+    expect(securityHandlers.ApiKey).toHaveBeenCalledWith('api key', request);
+    expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
+    expect(securityHandlers.OAuth2).toHaveBeenCalledWith('bearer token', request);
+    expect(request[DECORATOR_NAME].security).toMatchObject({ OAuth2: 'OAuth2 data' });
+    expect(request[DECORATOR_NAME].securityReport).toMatchInlineSnapshot(`
+      [
+        {
+          "ok": false,
+          "schemes": {
+            "ApiKey": {
+              "error": [Error: ApiKey error],
+              "ok": false,
+            },
+          },
+        },
+        {
+          "ok": true,
+          "schemes": {
+            "OAuth2": {
+              "data": "OAuth2 data",
+              "ok": true,
+            },
+          },
+        },
+      ]
+    `);
+  });
+
+  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 new Error('ApiKey error');
+      }),
+      OAuth2: vi.fn(() => {
+        throw new Error('OAuth2 error');
+      })
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    expect.assertions(2);
+
+    try {
+      await onRequest(request);
+    } catch (err) {
+      expect(err).toBeInstanceOf(errors.UnauthorizedError);
+      expect(err.securityReport).toMatchInlineSnapshot(`
+        [
+          {
+            "ok": false,
+            "schemes": {
+              "ApiKey": {
+                "error": [Error: ApiKey error],
+                "ok": false,
+              },
+            },
+          },
+          {
+            "ok": false,
+            "schemes": {
+              "OAuth2": {
+                "error": [Error: OAuth2 error],
+                "ok": false,
+              },
+            },
+          },
+        ]
+      `);
+    }
+  });
+
+  it('should cache security handler calls', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        authorization: 'Bearer bearer token'
+      }
+    };
+    const operation = {
+      security: [{ OAuth2: ['read'] }, { OAuth2: ['write'] }]
+    };
+    const spec = {
+      components: {
+        securitySchemes: {
+          ApiKey: { in: 'header', name: 'X-API-KEY', type: 'apiKey' },
+          OAuth2: { type: 'oauth2' }
+        }
+      }
+    };
+    const securityHandlers = {
+      OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: ['write'] }))
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    await onRequest(request);
+
+    expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
+  });
+
+  it('should cache security handler calls, even if they throw', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        authorization: 'Bearer bearer token'
+      }
+    };
+    const operation = {
+      security: [{ OAuth2: ['read'] }, { OAuth2: ['write'] }]
+    };
+    const spec = {
+      components: {
+        securitySchemes: {
+          ApiKey: { in: 'header', name: 'X-API-KEY', type: 'apiKey' },
+          OAuth2: { type: 'oauth2' }
+        }
+      }
+    };
+    const securityHandlers = {
+      OAuth2: vi.fn(() => {
+        throw new Error('OAuth2 error');
+      })
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    expect.assertions(2);
+
+    try {
+      await onRequest(request);
+    } catch (err) {
+      expect(err).toBeInstanceOf(errors.UnauthorizedError);
+      expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
+    }
+  });
+
+  it('should skip security blocks that have at least one value missing', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        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(async () => ({ data: 'ApiKey data', scopes: [] })),
+      OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    expect.assertions(3);
+
+    await onRequest(request);
+
+    expect(securityHandlers.ApiKey).not.toHaveBeenCalled();
+    expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
+    expect(request[DECORATOR_NAME].securityReport).toMatchInlineSnapshot(`
+      [
+        {
+          "ok": false,
+          "schemes": {},
+        },
+        {
+          "ok": true,
+          "schemes": {
+            "OAuth2": {
+              "data": "OAuth2 data",
+              "ok": true,
+            },
+          },
+        },
+      ]
+    `);
+  });
+
+  it('should validate scopes', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        authorization: 'Bearer bearer token'
+      }
+    };
+    const operation = {
+      security: [{ OAuth2: ['write'] }]
+    };
+    const spec = {
+      components: {
+        securitySchemes: {
+          OAuth2: { type: 'oauth2' }
+        }
+      }
+    };
+    const securityHandlers = {
+      OAuth2: vi.fn(() => ({ data: 'OAuth2 data', scopes: ['read'] }))
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    expect.assertions(2);
+
+    try {
+      await onRequest(request);
+    } catch (err) {
+      expect(err).toBeInstanceOf(errors.UnauthorizedError);
+      expect(err.securityReport).toMatchInlineSnapshot(`
+        [
+          {
+            "ok": false,
+            "schemes": {
+              "OAuth2": {
+                "error": [FastifyError: Scopes do not match required scopes],
+                "ok": false,
+              },
+            },
+          },
+        ]
+      `);
+    }
+  });
+
+  it('should allow security handler to return undefined', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        authorization: 'Bearer bearer token'
+      }
+    };
+    const operation = {
+      security: [{ OAuth2: [] }]
+    };
+    const spec = {
+      components: {
+        securitySchemes: {
+          OAuth2: { type: 'oauth2' }
+        }
+      }
+    };
+    const securityHandlers = {
+      OAuth2: vi.fn(() => {})
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    await onRequest(request);
+
+    expect(request[DECORATOR_NAME].security).toMatchObject({ OAuth2: undefined });
+    expect(request[DECORATOR_NAME].securityReport).toMatchInlineSnapshot(`
+      [
+        {
+          "ok": true,
+          "schemes": {
+            "OAuth2": {
+              "data": undefined,
+              "ok": true,
+            },
+          },
+        },
+      ]
+    `);
+  });
+
+  it('should allow security handler to return undefined and still check scopes', async () => {
+    const request = {
+      [DECORATOR_NAME]: {},
+      headers: {
+        authorization: 'Bearer bearer token'
+      }
+    };
+    const operation = {
+      security: [{ OAuth2: ['read'] }]
+    };
+    const spec = {
+      components: {
+        securitySchemes: {
+          OAuth2: { type: 'oauth2' }
+        }
+      }
+    };
+    const securityHandlers = {
+      OAuth2: vi.fn(() => {})
+    };
+
+    const onRequest = parseSecurity(operation, spec, securityHandlers);
+
+    expect.assertions(2);
+
+    try {
+      await onRequest(request);
+    } catch (err) {
+      expect(err).toBeInstanceOf(errors.UnauthorizedError);
+      expect(err.securityReport).toMatchInlineSnapshot(`
+        [
+          {
+            "ok": false,
+            "schemes": {
+              "OAuth2": {
+                "error": [FastifyError: Scopes do not match required scopes],
+                "ok": false,
+              },
+            },
+          },
+        ]
+      `);
+    }
+  });
+});

package/src/parser/spec.js

@@ -0,0 +1,14 @@
+import OpenAPIParser from '@readme/openapi-parser';
+
+export const validateSpec = async options => {
+  const spec = await OpenAPIParser.validate(options.spec);
+
+  const version = spec.openapi ?? spec.swagger;
+  const majorVersion = Number(version?.split?.('.')[0]);
+
+  if (isNaN(majorVersion) || majorVersion < 3 || majorVersion >= 4) {
+    throw new TypeError(`Unsupported OpenAPI version: ${version ?? 'unknown'}`);
+  }
+
+  return spec;
+};

package/src/parser/spec.test.js

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { validateSpec } from './spec.js';
+
+describe('validateSpec()', () => {
+  it('should throw for invalid options', async () => {
+    await expect(validateSpec({})).rejects.toThrowError('Expected a file path, URL, or object.');
+    await expect(validateSpec({ spec: { foo: 'bar' } })).rejects.toThrowError(
+      'Supplied schema is not a valid OpenAPI definition.'
+    );
+  });
+
+  it('should throw an error on unsupported OpenAPI versions', async () => {
+    const specSwagger2 = {
+      info: {
+        title: 'Title',
+        version: '1'
+      },
+      paths: {},
+      swagger: '2.0'
+    };
+    const specOpenApi2 = {
+      info: {},
+      openapi: '2.0.0',
+      paths: {}
+    };
+    const specOpenApi4 = {
+      info: {},
+      openapi: '4.0.0',
+      paths: {}
+    };
+
+    await expect(validateSpec({ spec: specSwagger2 })).rejects.toThrowError(/Unsupported OpenAPI version: 2\.0/);
+    await expect(validateSpec({ spec: specOpenApi2 })).rejects.toThrowError(/Unsupported OpenAPI version: 2\.0\.0/);
+    await expect(validateSpec({ spec: specOpenApi4 })).rejects.toThrowError(/Unsupported OpenAPI version: 4\.0\.0/);
+  });
+
+  it('should return a parsed spec', async () => {
+    const spec = {
+      info: {
+        title: 'Title',
+        version: '1'
+      },
+      openapi: '3.1.0',
+      paths: {}
+    };
+
+    expect(await validateSpec({ spec })).toMatchObject(spec);
+  });
+
+  it("should resolve '$ref' in spec", async () => {
+    const Pet = {
+      type: 'object'
+    };
+    const spec = {
+      components: {
+        schemas: {
+          Pet
+        }
+      },
+      info: {
+        title: 'Title',
+        version: '1'
+      },
+      openapi: '3.1.0',
+      paths: {
+        '/pet': {
+          get: {
+            responses: {
+              200: {
+                content: {
+                  'application/json': {
+                    schema: {
+                      $ref: '#/components/schemas/Pet'
+                    }
+                  }
+                },
+                description: 'successful operation'
+              }
+            }
+          }
+        }
+      }
+    };
+
+    const parsedSpec = await validateSpec({ spec });
+    const { schema } = parsedSpec.paths['/pet'].get.responses['200'].content['application/json'];
+
+    expect(parsedSpec).toMatchObject(spec);
+    expect(schema).toMatchObject(Pet);
+  });
+});

package/src/parser/url.js

@@ -0,0 +1,4 @@
+export const parseUrl = url => {
+  // fastify looks for a format 'resource/:param' but OpenAPI describes routes as 'resource/{param}'.
+  return url.replace(/{(\w+)}/g, ':$1');
+};

package/src/parser/url.test.js

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+import { parseUrl } from './url.js';
+
+describe('parseUrl()', () => {
+  it('should transform OpenAPI path templates to Fastify patterns', () => {
+    expect(parseUrl('/path')).toBe('/path');
+    expect(parseUrl('/path/{id}')).toBe('/path/:id');
+    expect(parseUrl('/path/{id}/resource/{another_id}')).toBe('/path/:id/resource/:another_id');
+    expect(parseUrl('/path/{id}/{another_id}')).toBe('/path/:id/:another_id');
+  });
+});

package/src/plugin.js

@@ -0,0 +1,51 @@
+import { DECORATOR_NAME } from './utils/constants.js';
+import { errors } from './errors/index.js';
+import { parse } from './parser/index.js';
+
+const createRoute = (fastify, routes) => {
+  return ({ method, onRequest, operationId, schema, url, ...routeOptions }) => {
+    const route = routes[operationId];
+
+    // Throw an error if the operation is unknown.
+    if (!route) {
+      throw new TypeError(`Missing '${operationId}' in OpenAPI spec.`);
+    }
+
+    // Not allowed to override options inferred by the spec.
+    if (method || schema || url) {
+      throw new TypeError(`Not allowed to override 'method', 'schema' or 'url' for operation '${operationId}'.`);
+    }
+
+    // Check if there is a routeOptions.onRequest hook.
+    if (typeof onRequest === 'function') {
+      route.onRequest.push(onRequest);
+    }
+
+    // Register a new route.
+    fastify.route({
+      ...routes[operationId],
+      ...routeOptions
+    });
+  };
+};
+
+const plugin = async (fastify, options) => {
+  options = options ?? {};
+
+  const routes = await parse(options);
+
+  // Decorate fastify object.
+  fastify.decorate(DECORATOR_NAME, {
+    errors,
+    route: createRoute(fastify, routes)
+  });
+
+  // Decorate request.
+  fastify.decorateRequest(DECORATOR_NAME, {
+    operation: {},
+    security: {},
+    securityReport: []
+  });
+};
+
+export default plugin;

package/src/utils/constants.js

@@ -0,0 +1,3 @@
+export const PLUGIN_NAME = '@uphold/fastify-openapi-router';
+
+export const DECORATOR_NAME = 'oas';