@uphold/fastify-openapi-router-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Uphold
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+# @uphold/fastify-openapi-router-plugin
+
+[![Tests](https://github.com/uphold/fastify-openapi-router-plugin/actions/workflows/tests.yaml/badge.svg)](https://github.com/uphold/fastify-openapi-router-plugin/actions/workflows/tests.yaml)
+
+A plugin for [Fastify](https://fastify.dev) to connect routes with a OpenAPI 3.x specification. It does so by:
+
+- Providing a way to register routes using the `operationId` defined in your specification instead of having to manually call `fastify.route` with the correct URL, method, and schema.
+- Handling `securitySchemes` and `security` keywords defined in your specification, simplifying the implementation of authentication and authorization middleware.
+
+## Installation
+
+```bash
+npm install @uphold/fastify-openapi-router-plugin
+```
+
+This plugin is written and exported in ESM only. If you are using CommonJS, consider making a pull-request and we will happily review it.
+
+## Usage
+
+```js
+import Fastify from 'fastify';
+import openApiRouterPlugin from '@uphold/fastify-openapi-router-plugin';
+
+const fastify = Fastify();
+
+// Register the OpenAPI Router plugin.
+await fastify.register(openApiRouterPlugin, {
+  spec: './petstore.json'
+});
+
+// Register a route using the 'operationId'.
+fastify.oas.route({
+  operationId: 'getPetById',
+  handler: async (request, reply) => {
+    const { petId } = request.params;
+
+    const pet = await retrievePetFromDB(petId);
+
+    return pet;
+  }
+});
+```
+
+### Options
+
+You can pass the following options during the plugin registration:
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: './petstore.json',
+  securityHandlers: {
+    APIAuth: (value, request) => {}
+  }
+});
+```
+
+| Option | Type | Description |
+| ------ | ---- | ----------  |
+| `spec` | `string` or `object` | **REQUIRED**. A file path or object of your OpenAPI specification. |
+| `securityHandlers` | `object` | An object containing the security handlers that match [Security Schemes](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object) described in your OpenAPI specification. |
+
+#### `spec`
+
+If you don't provide a valid OpenAPI specification, the plugin will throw an error telling you what's wrong.
+
+**Sample using a file path**
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: './petstore.json' // or spec: './petstore.yaml'
+});
+```
+
+**Sample using an object**
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: {
+    openapi: '3.1.0',
+    ...
+  }
+});
+```
+
+#### `securityHandlers`
+
+If you haven't defined any [Security Schemes](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object) in your OpenAPI specification, this option won't be required. Otherwise, plugin will try to resolve every `securityHandlers.<name>` as an async function that matches `securitySchemes.<name>` in your OpenAPI specification.
+
+Security handlers are executed as a `onRequest` hook for every API operation if plugin founds a [Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-requirement-object) defined on the root level or operation level of your OpenAPI specification. According to [Fastify Lifecycle](https://fastify.dev/docs/latest/Reference/Lifecycle/), it is the most secure way to implement an authentication layer because it avoids parsing the body for unauthorized accesses.
+
+If your operation's `security` use repeated security schemes, the plugin will call the associated security handler only once per request and cache its result. Furthermore, the plugin is smart enough to skip `security` blocks that have missing values from the request. For example, if you have a `security` block with `APIKey` and `OAuth2` and the request contains the API key but no bearer token, the plugin will automatically skip the block altogether without calling any security handler.
+
+The security handler should either throw an error or return an object with `{ data, scopes }` where `data` becomes available as `request.oas.security.<name>` in your route handler and `scopes` is array of strings that will be used to verify if the scopes defined in the API operation are satisfied.
+
+**Sample using OAuth 2.0**
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: {
+    openapi: '3.1.0',
+    ...
+    paths: {
+      '/pet/{petId}': {
+        get: {
+          operationId: 'getPetById',
+          ...
+          security: [
+            { OAuth2: ['pets:read'] }
+          ]
+        }
+      }
+    }
+    components: {
+      securitySchemes: {
+        OAuth2: {
+          type: 'oauth2',
+          flows: {
+            ...
+          }
+        }
+      }
+    }
+  },
+  securityHandlers: {
+    OAuth2: async (token, request) => {
+      // Validate and decode token.
+      const { userId } = verifyToken(token);
+
+      return {
+        data: { userId },
+        scopes: tokenData.scopes
+      };
+    }
+  }
+});
+```
+
+> [!TIP]
+> The `scopes` returned by the security handler can contain **wildcards**. For example, if the security handler returns `{ scopes: ['pets:*'] }`, the route will be authorized for any security scope that starts with `pets:`.
+
+> [!IMPORTANT]
+> If your specification uses `http` security schemes with `in: cookie`, you must register [@fastify/cookie](https://github.com/fastify/fastify-cookie) before this plugin.
+
+### Decorators
+
+#### `fastify.oas.route(options)`
+
+This method is used to register a new route by translating the given `operationId` to a compliant Fastify route.
+
+`options` must be an object containing at least the `operationId` and `handler(request, reply)`. All the available [routes options](https://fastify.dev/docs/latest/Reference/Routes/#routes-options) can be used except `method`, `url` and `schema` because those are loaded from your OpenAPI specification.
+
+**Example**
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: './petstore.json'
+});
+
+fastify.oas.route({
+  operationId: 'getPetById',
+  handler: (request, reply) => {}
+});
+```
+
+#### `fastify.oas.errors`
+
+This object contains all error classes that can be thrown by the plugin:
+
+- `UnauthorizedError`: Thrown when all security schemes verification failed.
+
+#### `request.oas`
+
+For your convenience, the object `request.oas` is populated with data related to the request being made. This is an object containing `{ operation, security, securityReport }`, where:
+
+- `operation` is the raw API operation that activated the Fastify route.
+- `security` is an object where keys are security scheme names and values the returned `data` field from security handlers.
+- `securityReport`: A detailed report of the security verification process. Check the [Error handler](#error-handler) section for more information.
+
+**Example**
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: './petstore.json',
+  securityHandlers: {
+    OAuth2: async (request, reply) => {
+      // Validate and decode token.
+      const { userId, scopes } = verifyToken(token);
+
+      return {
+        data: { userId },
+        scopes,
+      };
+    }
+  }
+});
+
+fastify.oas.route({
+  operationId: 'getPetById',
+  handler: (request, reply) => {
+    const { petId } = request.params;
+    const { userId } = request.oas.security.PetStoreAuth;
+
+    return getPetById(petId, userId);
+  }
+});
+```
+
+### Error handler
+
+The plugin will throw an `UnauthorizedError` when none of the `security` blocks succeed. By default, this error originates a `401` reply with `{ code: 'FST_OAS_UNAUTHORIZED', 'message': 'Unauthorized' }` as the payload. You can override this behavior by registering a fastify error handler:
+
+```js
+fastify.setErrorHandler((error, request, reply) => {
+  if (error instanceof fastify.oas.errors.UnauthorizedError) {
+    // Do something with `error.securityReport` and call `reply` accordingly.
+  }
+
+  // ...
+});
+```
+
+The `securityReport` property contains an array of objects with the following structure:
+
+```js
+[
+  {
+    ok: false,
+    // Schemes can be an empty object if the security block was skipped due to missing values.
+    schemes: {
+      OAuth2: {
+        ok: false,
+        // Error thrown by the security handler or fastify.oas.errors.ScopesMismatchError if the scopes were not satisfied.
+        error: new Error(),
+      }
+    }
+  }
+]
+```
+
+## License
+
+[MIT](./LICENSE)
+
+## Contributing
+
+### Development
+
+Install dependencies:
+
+```bash
+npm i
+```
+
+Run tests:
+
+```bash
+npm run test
+```
+
+Run tests and update snapshots:
+
+```bash
+npm run test -- -u
+```
+
+### Cutting a release
+
+The release process is automated via the [release](https://github.com/uphold/fastify-openapi-router-plugin/actions/workflows/release.yaml) GitHub workflow. Run it by clicking the "Run workflow" button.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@uphold/fastify-openapi-router-plugin",
+  "version": "0.1.0",
+  "description": "A plugin for Fastify to connect routes with a OpenAPI 3.x specification",
+  "main": "./src/index.js",
+  "types": "types/index.d.ts",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "release": "release-it",
+    "start": "node --watch ./examples/petstore/app.js",
+    "lint": "eslint .",
+    "test": "vitest --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uphold/fastify-openapi-router-plugin"
+  },
+  "keywords": [
+    "fastify",
+    "openapi"
+  ],
+  "author": "Uphold",
+  "license": "MIT",
+  "homepage": "https://github.com/uphold/fastify-openapi-router-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/uphold/fastify-openapi-router-plugin/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.6.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "eslint": "^9.6.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "eslint-plugin-sort-destructure-keys": "^2.0.0",
+    "eslint-plugin-sort-imports-requires": "^1.0.2",
+    "eslint-plugin-sort-keys-fix": "^1.1.2",
+    "fastify": "^4.28.1",
+    "globals": "^15.7.0",
+    "prettier": "^3.3.3",
+    "release-it": "^17.6.0",
+    "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "@readme/openapi-parser": "^2.6.0",
+    "fastify-plugin": "^4.5.1",
+    "lodash-es": "^4.17.21",
+    "openapi-types": "^12.1.3",
+    "p-props": "^6.0.0"
+  }
+}

package/src/errors/index.js

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

package/src/errors/scopes-mismatch-error.js

@@ -0,0 +1,17 @@
+import createError from '@fastify/error';
+
+const ScopesMismatchError = createError('FST_OAS_SCOPES_MISMATCH', 'Scopes do not match required scopes', 403);
+
+const createScopesMismatchError = (providedScopes, requiredScopes, missingScopes) => {
+  const err = new ScopesMismatchError();
+
+  err.scopes = {
+    missing: missingScopes,
+    provided: providedScopes,
+    required: requiredScopes
+  };
+
+  return err;
+};
+
+export { ScopesMismatchError, createScopesMismatchError };

package/src/errors/unauthorized-error.js

@@ -0,0 +1,16 @@
+import createError from '@fastify/error';
+
+const UnauthorizedError = createError('FST_OAS_UNAUTHORIZED', 'Unauthorized', 401);
+
+const createUnauthorizedError = securityReport => {
+  const err = new UnauthorizedError();
+
+  Object.defineProperty(err, 'securityReport', {
+    enumerable: false,
+    value: securityReport
+  });
+
+  return err;
+};
+
+export { UnauthorizedError, createUnauthorizedError };

package/src/index.js

@@ -0,0 +1,8 @@
+import { PLUGIN_NAME } from './utils/constants.js';
+import fp from 'fastify-plugin';
+import plugin from './plugin.js';
+
+export default fp(plugin, {
+  fastify: '4.x',
+  name: PLUGIN_NAME
+});

package/src/index.test.js

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import OpenAPIRouter from './index.js';
+import fastify from 'fastify';
+
+describe('Fastify plugin', () => {
+  let spec;
+
+  beforeEach(() => {
+    spec = {
+      info: { title: 'Title', version: '1' },
+      openapi: '3.1.0',
+      paths: {
+        '/pets': {
+          get: {
+            operationId: 'getPets'
+          }
+        }
+      }
+    };
+  });
+
+  it('should default export', () => {
+    expect(OpenAPIRouter).toBeTypeOf('function');
+  });
+
+  it('should expose plugin methods', async () => {
+    const app = fastify({ logger: false });
+
+    await app.register(OpenAPIRouter, { spec });
+
+    expect(app.oas).toBeTypeOf('object');
+    expect(app.oas).toMatchObject({
+      route: expect.any(Function)
+    });
+
+    app.oas.route({
+      handler: request => request.oas,
+      operationId: 'getPets'
+    });
+
+    const result = await app.inject({ url: '/pets' });
+
+    expect(result.json()).toMatchObject({
+      operation: { operationId: 'getPets' },
+      security: {}
+    });
+  });
+
+  it('should throw registering a route if `operationId` is not in spec', async () => {
+    const app = fastify({ logger: false });
+
+    await app.register(OpenAPIRouter, { spec });
+
+    expect(() =>
+      app.oas.route({
+        handler: () => {},
+        operationId: 'getUnknown'
+      })
+    ).toThrowError(`Missing 'getUnknown' in OpenAPI spec.`);
+  });
+
+  it('should set a route-level onRequest hook', async () => {
+    const app = fastify({ logger: false });
+    const onRequest = vi.fn(async () => {});
+
+    await app.register(OpenAPIRouter, { spec });
+
+    app.oas.route({
+      handler: async () => {},
+      onRequest,
+      operationId: 'getPets'
+    });
+
+    await app.inject({ url: '/pets' });
+
+    expect(onRequest).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not override internal route options', async () => {
+    const app = fastify({ logger: false });
+
+    await app.register(OpenAPIRouter, { spec });
+
+    expect(() =>
+      app.oas.route({
+        handler: async () => {},
+        method: 'PUT',
+        operationId: 'getPets',
+        url: '/pets/:id'
+      })
+    ).toThrowError(`Not allowed to override 'method', 'schema' or 'url' for operation 'getPets'.`);
+  });
+});

package/src/parser/body.js

@@ -0,0 +1,19 @@
+import { addPropertyToSchema, removeAttributesFromSchema } from '../utils/schema.js';
+
+export const parseBody = (route, operation) => {
+  if (!operation.requestBody?.content) {
+    return;
+  }
+
+  // Pick the first body type because fastify only supports one per route.
+  const [[contentType, { schema }]] = Object.entries(operation.requestBody.content);
+
+  // Enforce the correct Content-Type.
+  addPropertyToSchema(route.schema.headers, { 'content-type': { const: contentType } }, true);
+
+  // Sanitize schema.
+  removeAttributesFromSchema(schema, ['xml', 'example']);
+
+  // Add request body schema.
+  route.schema.body = schema;
+};

package/src/parser/body.test.js

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { parseBody } from './body.js';
+
+describe('parseBody()', () => {
+  let route;
+
+  beforeEach(() => {
+    route = {
+      schema: { body: {}, headers: { properties: {}, required: [] } }
+    };
+  });
+
+  it('should do nothing if operation does not contain a response body', () => {
+    parseBody(route, {});
+    parseBody(route, { requestBody: {} });
+
+    expect(route.schema.body).toStrictEqual({});
+    expect(route.schema.headers).toStrictEqual({
+      properties: {},
+      required: []
+    });
+  });
+
+  it('should parse a valid OpenAPI requestBody object', () => {
+    const requestBody = {
+      content: {
+        'application/json': {
+          schema: {
+            foo: { type: 'string' },
+            required: ['foo']
+          }
+        }
+      }
+    };
+
+    parseBody(route, { requestBody });
+
+    expect(route.schema.body).toStrictEqual({
+      foo: { type: 'string' },
+      required: ['foo']
+    });
+    expect(route.schema.headers).toStrictEqual({
+      properties: { 'content-type': { const: 'application/json' } },
+      required: ['content-type']
+    });
+  });
+
+  it('should pick the first content-type if requestBody object has more than one', () => {
+    const schema = {
+      foo: { type: 'string' },
+      required: ['foo']
+    };
+    const requestBody = {
+      content: {
+        'application/json': { schema },
+        'application/xml': { schema }
+      }
+    };
+
+    parseBody(route, { requestBody });
+
+    expect(route.schema.body).toStrictEqual({
+      foo: { type: 'string' },
+      required: ['foo']
+    });
+    expect(route.schema.headers).toStrictEqual({
+      properties: { 'content-type': { const: 'application/json' } },
+      required: ['content-type']
+    });
+  });
+
+  it('should sanitize body schema', () => {
+    const schema = {
+      foo: { example: 'baz', type: 'string', xml: { name: 'foo' } },
+      required: ['foo'],
+      xml: { name: 'Bar' }
+    };
+    const requestBody = {
+      content: {
+        'application/json': { schema }
+      }
+    };
+
+    parseBody(route, { requestBody });
+
+    expect(route.schema.body).toStrictEqual({
+      foo: { type: 'string' },
+      required: ['foo']
+    });
+    expect(route.schema.headers).toStrictEqual({
+      properties: { 'content-type': { const: 'application/json' } },
+      required: ['content-type']
+    });
+  });
+});

package/src/parser/index.js

@@ -0,0 +1,54 @@
+import { DECORATOR_NAME } from '../utils/constants.js';
+import { parseBody } from './body.js';
+import { parseParams } from './params.js';
+import { parseResponse } from './response.js';
+import { parseSecurity, validateSecurity } from './security.js';
+import { parseUrl } from './url.js';
+import { validateSpec } from './spec.js';
+
+export const parse = async options => {
+  const routes = {};
+
+  const spec = await validateSpec(options);
+
+  await validateSecurity(spec, options);
+
+  // Parse all existing paths.
+  for (const path in spec.paths) {
+    const methods = spec.paths[path];
+
+    // Parse each path method.
+    for (const method in methods) {
+      const operation = methods[method];
+
+      // Build fastify route.
+      const route = {
+        method: method.toUpperCase(),
+        onRequest: [
+          async function (request) {
+            request[DECORATOR_NAME].operation = operation;
+          },
+          parseSecurity(operation, spec, options.securityHandlers)
+        ].filter(Boolean),
+        schema: {
+          headers: parseParams(operation.parameters, 'header'),
+          params: parseParams(operation.parameters, 'path'),
+          query: parseParams(operation.parameters, 'query'),
+          response: {}
+        },
+        url: parseUrl(path)
+      };
+
+      // Parse body and apply its schema to fastify route.
+      parseBody(route, operation);
+
+      // Parse responses.
+      parseResponse(route, operation);
+
+      // Finally, add route to global routes object.
+      routes[operation.operationId] = route;
+    }
+  }
+
+  return routes;
+};

package/src/parser/params.js

@@ -0,0 +1,24 @@
+import { addPropertyToSchema } from '../utils/schema.js';
+
+export const parseParams = (parameters, location) => {
+  const schema = {
+    properties: {},
+    required: [],
+    type: 'object'
+  };
+
+  // Parameters is always an array in OpenAPI and we need a 'location' to proceed.
+  if (!Array.isArray(parameters) || !location) {
+    return schema;
+  }
+
+  // Filter params by location.
+  const params = parameters.filter(param => param.in === location);
+
+  // Add params to schema.
+  for (const param of params) {
+    addPropertyToSchema(schema, { [param.name]: param.schema }, param.required);
+  }
+
+  return schema;
+};