🛡 Blitz Guard
Tags: blitz, javascript, monolith, serverless
Published: 2021-02-10 13:33:09

This article was originally posted on [Monolith Bias_](https://monolith-bias.com/posts/blitz-guard) the technical blog of the [Ingenious](https://www.ingenious.agency) development team.

---

As great as Blitz is for developing full-stack applications, I still miss the batteries included feeling Ruby on Rails has. I know I can't compare a mature framework like Rails to Blitz that barely has a year old, but I certainly miss the "there must be a gem for that" feeling.

One of the things I miss the most when working on a web app is a centralized place to manage authorization. Authorization is the most common requirement a web app may have. While Blitz itself tries to address this issue with the `$authorize` method that's built-in on the session, it falls short when the authorization is dependent on data attributes; technically called [attributes-based access control](https://en.wikipedia.org/wiki/Attribute-based_access_control).

The good news is that [Nico Torres](https://twitter.com/ntgussoni), a friend and former Ingenious employee, created [Blitz Guard](https://ntgussoni.github.io/blitz-guard/docs), the API is close to [RoR cancancan gem](https://github.com/CanCanCommunity/cancancan) but adapted to work with Blitz.

# Installation
With Blitz Guard latest release, you can execute the following:

```bash
$ blitz install ntgussoni/blitz-guard-recipe
```

This line uses the Blitz Guard recipe to install the library. [Recipes](https://blitzjs.com/docs/using-recipes) are an excellent, guided way to install new software in your app. It lets library developers update your codebase without breaking it.

# What's inside
Once installeed you'll end up with several new files. The most important one is `app/guard/ability.ts`. This file is the core of your authorization logic, and it will serve as a single source of truth, whether a user can or cannot do things in your app.

```tsx
import db from "db"
import { GuardBuilder, PrismaModelsType } from "@blitz-guard/core"
import { GetShoppingCartInput } from "app/shoppingCarts/queries/getShoppingCart"

type ExtendedResourceTypes = PrismaModelsType<typeof db>

type ExtendedAbilityTypes = ""

const Guard = GuardBuilder<ExtendedResourceTypes, ExtendedAbilityTypes>(
  async (ctx, { can, cannot }) => {
    cannot("manage", "all")
    if (ctx.session.$isAuthorized()) {
      can("read", "shoppingCart", async ({ where }: GetShoppingCartInput) => {
        return where.userId === ctx.session.userId
      })
    }
  }
)

export default Guard
```

The `ability` file creates a `Guard` using the `GuardBuilder` function. The resulting guard will be executed on every authorized query or mutation.

For example, if we want to deny access to a shopping cart based on who's the owner. We can do something like this:

```tsx
// app/guard/ability.ts

import { GetShoppingCartInput } from "app/shoppingCart/queries/getShoppingCart"
// ...

if (ctx.session.$isAuthorized()) {
  can("read", "shoppingCart", async ( { where }: GetShoppingCartInput ) => {
    return where.userId === ctx.session.userId;
  })
}
```
<small class="text-right">Notice GetShoppingCartInput is the same TS type that we use in the getShoppingCart query</small>

The `can` (and `cannot`) methods have three parameters. The first is the action to be performed (either create, read, update, delete, or manage), the second is which Prisma schema object this guard applies to (it doesn't need to be Prisma dependent, you can extend it using the `ExtendedResourceTypes`), and the third is an async function that should resolve to a boolean. 

On this third argument you can implement any logic you want -like querying the DB- to assert whether the logged-in user has permissions to perform the action on the specified resource. A more interesting example could be the following:

```ts
//...
if (ctx.session.$isAuthorized()) {
  can("read", "shoppingCart", async ( { where }: GetShoppingCartInput ) => {
    if(where.userId === ctx.session.userId) return true
    const count = await db.shoppingCartShare.count({ where: { userId: ctx.session.userId, shoppingCartId: where.id } })
    return count > 0
  })
}
```

<small>☝️ Here we assert that the user is the shopping cart owner or that the cart has been shared with this user previously.</small>

# Authorizing functions
So far, so good, but changing the ability file will do nothing if we don't authorize our functions. Blitz Guard will intercept your functions call and execute the guard only if we wrap queries and mutations with the `authorize` method.

```ts
import { Ctx, NotFoundError } from "blitz"
import db, { Prisma } from "db"
import Guard from "app/guard/ability"

export type GetShoppingCartInput = Pick<Prisma.ShoppingCartFindFirstArgs, "where">

async function getShoppingCart({ where }: GetShoppingCartInput, ctx: Ctx) {
 ctx.session.$authorize()

 const cart = await db.shoppingCart.findFirst({ where })

 if (!cart) throw new NotFoundError()

 return cart
}

export default Guard.authorize("read", "shoppingCart", getShoppingCart)
```

The first two arguments of this function should look familiar because they are the same arguments `can` and `cannot` functions receive. The third argument is the function we want to wrap, and that will only be called if the guard criteria are met. *Otherwise, you'll get a 403*.

This step is easy to forget, more so when the Blitz generator default exports the generated function. To aid this, Blitz Guard installs a middleware that warns you (in development) about queries and mutations not wrapped by the `Guard.authorize` function.

# Final words
Blitz Guard is still under heavy development, but I don't think the API will change a lot. It's a great option if you plan to develop an ambitious Blitz app by moving scattered business logic into a single place.