README.md

fastify-oso

A plugin for implementing Oso authorization in fastify applications.

Install

npm i @autotelic/fastify-oso

Usage

import { fastifyOso } from '@autotelic/fastify-oso'
import fastify from 'fastify'

const app = fastify()

const PORT = process.env.PORT || 3000

async function setupOso (oso) {
  const osoPolicy = `
    # Anyone may access the '/public' endpoint
    allow_request(_, request) if
      request.url.startsWith("/public");

    # Admin users can access everything
    allow(user, _, _) if
      user.role = "admin";
  `
  // Setup the oso instance here.
  // All side effects must occur before returning the oso instance.
  await oso.loadStr(osoPolicy)
  return oso
}

// Register the plugin
app.register(fastifyOso, { setupOso })

// Authorize access to your routes as an onRequest hook
const osoAuthorizeRequest = async (request, reply) => {
  try {
    await app.oso.authorizeRequest({}, request)
  } catch (error) {
    reply.status(403).send('Access Denied')
  }
}

// Anyone is able to access this route.
app.get('/public', { onRequest: [osoAuthorizeRequest] }, (request, response) => {
  return 'public information'
})


// Only "admin" users may access this route.
app.get('/private', async (request, reply) => {
  const user = {
    // Role and other identifying information could come from
    // JWTs or other data sources.
    role: request.headers.role || 'anonymous'
  }
  try {
    await app.oso.authorize(user)
  } catch (error) {
    reply.status(403).send('Access Denied')
  }
  return 'super secret'
})

app.listen(PORT, (_, address) => {console.log(`Listening at: ${address}`)})

Examples

We provide the following usage examples and recipes:

• basic
• onRequest hook

API

Plugin

Options

The configuration object accepts the following fields":

- setupOso: async (Oso) => Oso

A function that receives the oso instance, applies some configuration to that instance and then returns the configured oso class.

Decorators

The oso instance is exposed as a decorator inside the oso namespace. For a list of the exposed oso methods refer to the Oso API documentation

requestDecorators

- authorizeRequest: (Actor, Request) => Promise

Exposes the oso authorizeRequest method on the Request object.

This is useful for handling authorization within request lifecycle hooks.

Triggering a Release

Prerequisite: Update the repository access for the shared NPM_PUBLISH_TOKEN secret.

Trigger the release workflow via a tag

git checkout main && git pull
npm version { minor | major | path }
git push --follow-tags

License

This project is covered under the MIT license.