@authzed/authzed-node

Authzed NodeJS Client

This repository houses the NodeJS client library for Authzed.

Authzed is a database and service that stores, computes, and validates your application's permissions.

Developers create a schema that models their permissions requirements and use a client library, such as this one, to apply the schema to the database, insert data into the database, and query the data to efficiently check permissions in their applications.

Supported client API versions:

• v1

You can find more info on each API on the Authzed API reference documentation. Additionally, Protobuf API documentation can be found on the Buf Registry Authzed API repository.

See CONTRIBUTING.md for instructions on how to contribute and perform common tasks like building the project and running tests.

Getting Started

We highly recommend following the Protecting Your First App guide to learn the latest best practice to integrate an application with Authzed.

If you're interested in examples of a specific version of the API, they can be found in their respective folders in the examples directory.

Basic Usage

Installation

The project is packaged and distributed via NPM.

If you are using the typical npm toolchain, the command to install the library is:

npm i @authzed/authzed-node

Initializing a client

Everything required to connect and make API calls is located in a module respective to API version.

You will have to provide a your own API Token from the [Authzed dashboard] in place of t_your_token_here_1234567deadbeef in the following example:

import { v1 } from '@authzed/authzed-node';
// if your endpoint is localhost
// const client = v1.NewClient('t_your_token_here_1234567deadbeef', 'localhost:50051', v1.ClientSecurity.INSECURE_LOCALHOST_ALLOWED);
const client = v1.NewClient('t_your_token_here_1234567deadbeef');

Or to use a custom certificate authority, load the CA certificate and pass the file reference to NewClientWithCustomCert.

import { v1 } from '@authzed/authzed-node';
import fs from 'fs';

const endpoint = 'localhost:50051';
const cert = fs.readFileSync('path/to/cert.pem');
const client = v1.NewClientWithCustomCert('t_your_token_here_1234567deadbeef', endpoint, cert);

Performing an API call

Because of the verbosity of these types, we recommend writing your own functions/methods to create these types from your existing application's models.

The create method on generated classes takes attributes as input and defaults unspecified attributes to their empty value. This allows you to create request messages, for example, by specifying only relevant fields and leaves optional fields empty.

import { v1 } from '@authzed/authzed-node';

const client = v1.NewClient('token')

// Create the relationship between the resource and the user.
const firstPost = v1.ObjectReference.create({
    objectType: "blog/post",
    objectId: "1",
});

// Create the user reference.
const emilia = v1.ObjectReference.create({
    objectType: "blog/user",
    objectId: "emilia",
});

// Create the subject reference using the user reference
const subject = v1.SubjectReference.create({
    object: emilia,
});

const checkPermissionRequest = v1.CheckPermissionRequest.create({
    resource: firstPost,
    permission: "read",
    subject,
});

client.checkPermission(checkPermissionRequest, (err, response) => {
    console.log(response);
    console.log(err);
});

Promises (async/await) support

Each method available in the client has an associated promise-style method in place of callbacks, that can be accessed at the .promises property on the client.

import { v1 } from '@authzed/authzed-node';

const client = v1.NewClient('token');
const { promises: promiseClient } = client; // access client.promises

const checkPermissionRequest = /** from above **/;

const result = await promiseClient.checkPermission(checkPermissionRequest);

For stream-returning methods, including client.readRelationships(), client.lookupResources() and client.lookupSubjects(), the promise-style method will result in an array of response objects once the stream has been closed.

import { v1 } from '@authzed/authzed-node';

const client = v1.NewClient('token');
const { promises: promiseClient } = client; // access client.promises

const results = await promiseClient.readRelationships(/** req **/);
console.log(results[0]); // first ReadRelationship result

Writing Caveats

When writing caveat context to a relation, we've observed that you need to use the Struct object bundled with authzed-node, rather than importing it from the google-protobuf package. If you don't use the authzed-node version, writing context will fail silently and the relations won't reflect the context.

An example:

import { protobuf } from '@authzed/authzed-node';
const { Struct } = protobuf;

const writeRequest = WriteRelationshipsRequest.create({
updates: [
  RelationshipUpdate.create({
    relationship: Relationship.create({
      resource: resource,
      relation: "caveated_viewer",
      subject: SubjectReference.create({
        object: testUser,
      }),
      optionalCaveat: ContextualizedCaveat.create({
        caveatName: "has_special_attribute",
        context: Struct.fromJson({
          special: true,
        }),
      }),
    }),
    operation: RelationshipUpdate_Operation.CREATE,
  }),
],
});

const response = await client.writeRelationships(writeRequest);

Requirements

Supported Node.js versions: 18, 20, 22

Minimum TypeScript version 3.8