When the user object is empty, a "default" user object will be created with the defaultRole (e.g. { role: opts.defaultRole }).

Error code thrown when an unauthenticated user is not allowed to access a resource.

Error code thrown when an authenticated user is not allowed to access a resource.

When you use .diffInputFromResource(), the resource and the inputItem are compared and a diff (an object containing the changes) is fed to your access control checker.

Since the diff is produced as a plain object, we need to cast it to the appropriate model class again so that you can access that model's methods and model-specific fields.

However, in some cases (such as when you're doing some bespoke field/value remapping in Model.$parseJson()), casting the object to the model class isn't "safe" to do, and the resulting model instance might contain different values from the raw diff object.

If you want to disable it, just set opts.castDiffToModelClass to false and the raw diff object will be fed to the access control functions.

When you automatically modify/include some fields (e.g. automatic timestamps) in your Objection models, as objection-authorize is typically the "last" hook to run before execution, the policies will check for those fields as well.

These allow you to ignore those fields in authorization decisions. Note that you can specify the fields in dot notation as well (e.g. timestamp.updatedAt).

Normally, the item is used as "resource" since that's what the user is acting on.

However, for relation queries (e.g. add Book to a Library), the user is really acting on the Book, not the Library. For cases like this, you can set this option to true in order to use the inputItem (Book) as "resource" instead of item (Library) ONLY during relation queries.

This is the bread and butter of this library. You can chain .authorize() to any Objection Model query (i.e. Model.query().authorize()) to authorize that specific ORM call/HTTP request.

First, an explanation of the parameters:

The user should be an object representation of the user; typically, you can just plug in req.user (express) or ctx.user (koa) directly, even if the user is not signed in (aka req.user === undefined)!

The resource object is an optional parameter, and for most queries, you won't need to manually specify the resource.

The opts can be used to override any of the default options that you passed during initialization of this plugin (i.e. you don't have to pass the whole options object in; only the parts you want to override for this specific query).

So, what are we actually checking here with this function?

When you chain .authorize() to the ORM query, the query is (typically) doing one of four things: create, read, update, or delete (CRUD) - which is the action they're trying to take. These correspond to the HTTP verbs: GET/POST/PUT/PATCH/DELETE (if you're not familiar with how this is the case, please read up on REST API design).

In addition, the query already provides the following contexts: the resource/item(s) that the user is acting on (e.g. read a user's email, or create a post), the body/inputItem(s) that the user is supplying. This is typically the req.body that you pass to the .insert()/.update()/.delete() query methods, aka how you want to change the resource.

So, given this information, we can just rely on the ACL (see below for how to define it) to check whether the user is allowed to take the specified action on resource/items with the given body/inputItems! Specifically, the authorization check involves the following functionalities:

1. Check if the user is allowed to apply the specified action on the items, and if not, throw an httpError with the appropriate HTTP error code
2. If there's inputItems, check if the user is allowed to modify/add the specific fields in inputItems. If a user tries to set/modify a property they're not allowed to, error is thrown again.

That's it!

The nuances of this plugin comes with how it's able to drastically simplify said ACL calls & context fetching. For example, while figuring out the inputItems might be simple, how does the plugin know which items the action applies to?

The plugin looks at the following places to fetch the appropriate resource(s):

1. If the resource parameter is specified in the .authorize() call, it takes precedence and is set as the only item(s) that we check against.
2. If the resource parameter is not specified, then it looks at the model instance (if you're calling .$query() or .$relatedQuery())
3. If you call .fetchContextFromDB(), then the plugin executes a pre-emptive SQL SELECT call to fetch the rows that the query would affect.

And once the plugin figures out items and inputItems, it simply iterates along both arrays and checks the ACL whether the user can take action on items[i] with input inputItems[j].

That's it.

TIP: the .authorize() call can happen anywhere within the query chain!

Rather than using the "default" actions (create/read/update/delete), you can override the action per query.

This is useful when you have custom actions in your ACL (such as promote) for a specific endpoint/query. Just chain a .action(customAction) somewhere in the query (in this case, the customAction would be "promote").

For methods that don't support passing inputItem(s) (e.g. .delete()) but you still want to set the input item/resource, you can call this method to manually override the value of the resource used by the ACL.

Sometimes, you need to know the values of the resource(s) you're trying to access before you can make an authorization decision. So instead of loading the model instance(s) yourself and running .$query() on them, you can chain .fetchResourceContextFromDB() to your query and automatically populate the inputs/resources that would've been affected by the query.

e.g.

await Person.query()
  .authorize(user)
  .where('lastName', 'george')
  .update({ lastName: 'George' }) // input item
  .fetchResourceContextFromDB() // Loads all people that would be affected by the update,
// and runs authorization check on *all* of those individuals against the input item.

This method is particularly useful for UPDATE requests, where the client is sending the entire object (rather than just the changes, like PATCH). Obviously, if you put the whole object through the AuthZ check, it will trip up (for example, the client may include the object's id as part of an UPDATE request, and you don't want the ACL to think that the client is trying to change the id)!

Therefore, call this method anywhere along the query chain, and the plugin will automatically diff the input object(s) with whatever the resource is! The beauty of this method is that it also works for nested fields, so even if your table includes a JSON field, only the exact diff - all the way down to the nested subfields - will be passed along to the ACL.

e.g.

Model.query()
  .authorize(user, { id: 1, foo: { bar: 'baz', a: 0 } })
  .updateById(id, { id: 1, foo: { bar: 'baz', b: 0 } })
  .diffInputFromResource() // the diff will be { foo: { b: 0 } }

NOTE: the plugin is ONLY able to detect changes to an existing field's value or an addition of a new field, NOT the deletion of an existing field (see above how the implicit deletion of foo.a is not included in the diff).

Therefore, care must be taken during UPDATE queries where fields (especially nested fields) may be added/removed dynamically. Having JSON subfields doesn't mean you throw out schema Mongo-style; so if you need to monitor for deletion of a field (rather than mutation or addition), I would recommend assigning all of the possible fields' value with null, rather than leaving it out entirely, so that deletions would show up as mutations.

e.g. in the above case, if you wanted to check whether field foo.a was deleted or not:

resource = { id: 1, foo: { bar: 'baz', a: 0, b: null } }
input = { id: 1, foo: { bar: 'baz', a: null, b: 0 } }

Prior to objection-authorize v4, the plugin "automatically" filtered any resulting model instances against a user's read access, but it didn't work consistently and I found it to be too hacky, so from v4 and on, you will need to manually call the .authorizeRead() on your model instance to filter it according to the user's read access (which can be overridden with the action parameter).

This call is synchronous and will return the filtered model instance directly. Note that the result is a plain object, not an instance of the model class anymore, since this call is meant to be for "finalizing" the model instance for returning to the user as a raw JSON.