Reference
Client SDK
Node.js

Node.js Client API

ℹ️

These are the docs for the v2 release. For v1, see the docs and the migration guide.

First, install the oso-cloud package on NPM:


npm install oso-cloud

Before going through this guide, make sure you follow the Oso Cloud Quickstart to get your Oso Cloud API Key properly set in your environment.

The minimum supported Node.js version is 16.

Instantiating an Oso Cloud client

The Oso Cloud client provides an Oso class that takes your Oso Cloud URL and API key:


const { Oso } = require("oso-cloud");
const oso = new Oso("https://cloud.osohq.com", YOUR_API_KEY);
// Later, in an async function:
await oso.tell("has_role", user, role, resource);
// Wherever authorization needs to be performed
if (await oso.authorize(user, action, resource)) {
// Action is allowed
}

ℹ️

You should instantiate one client and share it across your application. Under the hood, it reuses connections to avoid paying the cost of negotiating a new connection on every request.

Generating TypeScript types from your policy

Version 2.0.0 of the Node.js SDK introduced much better TypeScript types across the entire API surface. However, the default types are agnostic to your authorization policy. If, for example, your authorization policy declares a "read" permission and you add an oso.authorize() call for "reda", the default types won't catch that typo at compile time.

To catch these errors at compile time, you can generate TypeScript types from your policy file(s) using the oso-cloud CLI. The generated types infer the set of possible facts that you can send to Oso Cloud and the set of possible queries you can make, so you know at compile time if your API call is valid.

Generate types

Requires >= v0.16.0 of the oso-cloud CLI.

Generate types from your Polar policy file(s):


$ oso-cloud generate-types typescript path/to/policy.polar > path/to/polarTypes.d.ts

To ensure these types remain up-to-date with your policy, add a CI check that generates types and diffs the output against the checked-in version:


$ oso-cloud generate-types typescript path/to/policy.polar | diff path/to/polarTypes.d.ts -

Using the generated types

Requires >= v2.0.0 of the Node.js SDK.

Import the generated types and pass them to the Oso constructor as a type parameter:


import type { PolarTypes } from "./polarTypes";
const oso = new Oso<PolarTypes>(...);

Specifying an Oso Fallback host

If you have deployed Oso Fallback nodes to your infrastructure, you may specify the host when instantiating the Oso Cloud client.


// Assumes Oso Fallback is hosted at http://localhost:8080
const oso = new Oso("https://cloud.osohq.com", YOUR_API_KEY, {
fallbackUrl: "http://localhost:8080",
});

Passing application entities into the client

Under the hood, Oso Cloud represents an entity in your application as a combination of a type and an ID, which together uniquely identify the entity. The Node client represents these entities as objects with both type and id properties. For example:


const alice = { type: "User", id: "alice" };
const anvilsRepository = { type: "Repository", id: "anvils" };

You will pass objects like these into nearly every function call you make to the Node client.

Management API

Add fact: oso.insert([name, ...args])

Adds a fact named name with the provided arguments. Example:


await oso.insert([
"has_role",
{ type: "User", id: "bob" },
"owner",
{
type: "Organization",
id: "acme",
},
]);

Delete fact: oso.delete([name, ...args])

Deletes a fact, if possible. Does not throw an error if the given fact is not found. Example:


await oso.delete([
"has_role",
{ type: "User", id: "bob" },
"maintainer",
{
type: "Repository",
id: "anvils",
},
]);

When deleting facts, you can use null as a wildcard to delete many facts at once.


// remove all of bob's roles across all resources
await oso.delete(["has_role", { type: "User", id: "bob" }, null, null]);

Transactionally delete and add facts: oso.batch((tx) => { })

ℹ️

For Oso Cloud developer accounts, batch calls are limited to 20 facts. If you attempt to send more than 20 facts, these functions will throw an error.

Allows deleting and inserting many facts in one atomic transaction. Deletions and insertions are run in the order they appear in the callback. Example:


const bob = { type: "User", id: "bob" };
await oso.batch((tx) => {
tx.insert(["has_role", bob, "owner", { type: "Organization", id: "acme" }]);
tx.delete([
"has_role",
bob,
"maintainer",
{ type: "Repository", id: "anvils" },
]);
});

Get facts: oso.get([name, ...args])

ℹ️

For Oso Cloud developer accounts, Get calls are limited to 1000 results. If you have more than 1000 facts, the function will throw an error.

Get facts that are stored in Oso Cloud. Can be used to check the existence of a particular fact, or used to fetch all facts that have a particular argument:


// Get one fact:
await oso.get([
"has_role",
{ type: "User", id: "bob" },
"admin",
{
type: "Repository",
id: "anvils",
},
]);
// => [
// [
// "has_role",
// {type: "User", id: "bob"},
// {type: "String", id: "admin"},
// {type: "Repository", id: "anvils"}
// ]
// ]
// List all role-related facts on the `anvils` repo
await oso.get(["has_role", null, null, { type: "Repository", id: "anvils" }]);
// => [
// [
// "has_role",
// {type: "User", id: "bob"},
// {type: "String", id: "admin"},
// {type: "Repository", id: "anvils"}
// ],
// //...other has_role facts
// ]

Note that null behaves like a wildcard for get calls: passing null, null, anvils means "find all facts where anvils is the third argument, regardless of other arguments".

oso.get() only returns facts you've explicitly added. If you want to return a list of authorized resources, use the Check API. For example, to answer "on which resources can a given user perform a given action", use oso.list(). If you want to query for arbitrary information that can be derived from your facts and policy, use the Query Builder API.

Check API

ℹ️

For Oso Cloud developer accounts, * the number of context facts per request is limited to 20; and * the number of records returned is limited to 1000.

Context facts

You may provide an array of context facts as an optional argument to any of the Check API methods. When Oso Cloud performs a check, it will consider these context facts in addition to any other facts you've previously added. Context facts are only used in the API call in which they're provided— they do not persist across requests. Learn more about context facts.

Check a permission: oso.authorize(actor, action, resource)

Determines whether or not an action is allowed, based on a combination of authorization data and policy logic. Example:


const alice = { type: "User", id: "alice" };
const anvilsRepository = { type: "Repository", id: "anvils" };
const authorized = await oso.authorize(alice, "read", anvilsRepository);
if (!authorized) {
throw new Error("Action is not allowed");
}

You may provide an array of context facts as an optional fourth argument to this method. Example:


const issue = { type: "Issue", id: "anvils-1" };
const authorized = await oso.authorize(alice, "read", issue, [
["has_relation", issue, "parent", anvilsRepository], // a context fact
]);

List authorized resources: oso.list(actor, action, resourceType)

Fetches a list of resource IDs on which an actor can perform a particular action. Example:


const alice = { type: "User", id: "alice" };
const repositoryIds = await oso.list(alice, "read", "Repository");
// => ["acme"]

You may provide an array of context facts as an optional fourth argument to this method. Example:


const anvilsRepository = { type: "Repository", id: "anvils" };
const acmeRepository = { type: "Repository", id: "acme" };
const issueOnAcmeRepository = { type: "Issue", id: "acme-1" };
const issueOnAnvilsRepository = { type: "Issue", id: "anvils-2" };
const repositoryIds = await oso.list(alice, "read", "Issue", [
// context facts
["has_relation", issueOnAnvilsRepository, "parent", anvilsRepository][
("has_relation", issueOnAcmeRepository, "parent", acmeRepository)
],
]);
// => ["acme-1"]

List authorized actions: oso.actions(actor, resource)

Fetches a list of actions which an actor can perform on a particular resource. Example:


const alice = { type: "User", id: "alice" };
const acmeRepository = { type: "Repository", id: "acme" };
await oso.actions(user, acmeRepository);
// => ["read"]

You may provide an array of context facts as an optional third argument to this method. Example:


const issueOnAcmeRepository = { type: "Issue", id: "acme-1" };
await oso.actions(alice, issueOnAcmeRepository, [
["has_relation", issueOnAcmeRepository, "parent", acmeRepository], // a context fact
]);
// => ["read"]

Query for any rule: oso.buildQuery([predicate, ...args])

Query Oso Cloud for any predicate and any combination of concrete and wildcard arguments. Unlike oso.get, which only lists facts you've added, you can use oso.buildQuery to list derived information about any rule in your policy. Example:


const actor = { type: "User", id: "bob" };
const repository = typedVar("Repository");
// Query for all the repos `User:bob` can `read`
await oso.buildQuery(["allow", actor, "read", repository]).evaluate(repository);
// => [ "acme", "anvils" ]

Query Builder API

The oso.buildQuery() API is a builder-style API where you chain methods to construct a query and then execute it.

oso.buildQuery([predicate, ...args])

The oso.buildQuery() function takes the name of the rule you want to query and a list of arguments. The arguments can be concrete values (e.g., "read" or { type: "User", id: "bob" }) or type-constrained variables constructed via the typedVar function:


const actor = { type: "User", id: "bob" };
const repository = typedVar("Repository");
// Query for all the repositories bob can read
oso.buildQuery(["allow", actor, "read", repository]);
// => QueryBuilder { ... }

Note: once you've finished building up your query, you must call evaluate to run it and get the results.

QueryBuilder.and([predicate, ...args])

This function adds another condition that must be true of the query results.

For example:


const actor = { type: "User", id: "bob" };
const repository = typedVar("Repository");
const folder = { type: "Folder", id: "folder-1" };
// Query for all the repositories this user can read...
oso
.buildQuery(["allow", actor, "read", repository])
//... and require the repositories to belong to the given folder.
.and(["has_relation", repository, "folder", folder]);
// => QueryBuilder { ... }

Note: once you've finished building up your query, you must call evaluate to run it and get the results.

QueryBuilder.in(variable, values)

This function requires a given typedVar query variable to be included in a given set of values. You can only call in once per variable per query. Calling in a second time with the same variable on the same query builder will throw an error.

For example:


const actor = { type: "User", id: "bob" };
const repositories = ["acme", "anvil"];
const action = typedVar("String");
const repository = typedVar("Repository");
// Query for all the actions this user can perform on any repository...
oso
.buildQuery(["allow", actor, action, repository])
// ...given that the repository's ID is in the given list of IDs.
.in(repository, repositories);
// => QueryBuilder { ... }

Note: once you've finished building up your query, you must call evaluate to run it and get the results.

QueryBuilder.withContextFacts(contextFacts)

This function adds the given context facts to the query. For example:


const actor = { type: "User", id: "bob" };
const repository = typedVar("Repository");
// Query for all the repositories bob can read...
oso
.buildQuery(["allow", actor, "read", repository])
// ...while including the fact that bob owns acme
.withContextFacts([
["has_role", actor, "owner", { type: "Repository", id: "acme" }],
]);
// => QueryBuilder { ... }

For more information on context facts, see this section.

Note: once you've finished building up your query, you must call evaluate to run it and get the results.

QueryBuilder.evaluate()

This function evaluates the built query, fetching the results from Oso.

The return type of this function varies based on the arguments you pass in.

  • If you pass no arguments, this function returns a boolean. For example:

    const allowed = await oso
    .buildQuery(["allow", actor, action, resource])
    .evaluate();
    // => true if the given actor can perform the given action on the given resource

  • If you pass a single typedVar query variable, this function returns a list of values for that variable. For example:

    const action = typedVar("String");
    const actions = await oso
    .buildQuery(["allow", actor, action, resource])
    .evaluate(action);
    // => all the actions the actor can perform on the given resource- eg. ["read", "write"]

  • If you pass a tuple of typedVar query variables, this function returns a list of tuples of values for those variables. For example:

    const action = typedVar("String");
    const repository = typedVar("Repository");
    const pairs = await oso
    .buildQuery(["allow", actor, action, repository])
    .evaluate([action, repository]);
    // => an array of pairs of allowed actions and repo IDs-
    // eg. [["read", "acme"], ["read", "anvil"], ["write", "anvil"]]

  • If you pass an object with a typedVar query variable as a key and another typedVar as its value, returns a Map grouping unique values of that variable. For example:

    const action = typedVar("String");
    const repository = typedVar("Repository");
    const map = await oso
    .buildQuery(["allow", actor, action, repository])
    .evaluate({ [repository]: action });
    // => a map of repo IDs to allowed actions-
    // eg. new Map(Object.entries({ "acme": ["read"], "anvil": ["read", "write"]}))

Some queries have unconstrained results. For instance, maybe users with the admin role can read all Repository entities in your application. In this case, rather than returning an array containing the ID of every repository, evaluate will return an array containing the string "*". For example:


const repos = typedVar("Repository");
await oso
.buildQuery(["allow", { type: "User", id: "admin" }, "read", repos])
.evaluate(repos); // Return just the IDs of the repos admin can read
// => ["*"] // admin can read anything

Query Builder Examples

Field-level access control

const actor = { type: "User", id: "alice" };
const resource = { type: "Repository", id: "anvil" };
const field = typedVar("Field");
const results = await oso
.buildQuery(["allow_field", actor, "read", resource, field])
.evaluate(field);
// => Returns a list of the fields alice can read on the given repo- eg.
// ["name", "stars"]

Checking a global permission

const actor = { type: "User", id: "alice" };
const result = await oso
.buildQuery(["has_permission", actor, "create_repository"])
.evaluate();
// => true if alice has the global "create_repository" permission

Fetching authorized actions for a collection of resources

const repos = ["anvil", "acme"];
const actor = { type: "User", id: "alice" };
const action = typedVar("String");
const repo = typedVar("Repository");
const results = await oso
.buildQuery(["allow", actor, action, repo])
.in(repo, repos)
.evaluate({ [repo]: action });
// => Returns a map of the given repos to the actions alice can perform on those repos- eg.
// new Map(Object.entries({ "anvil": ["read"], "acme": ["read", "write"] }))

Filtering out unauthorized resources from a collection

const repos = ["anvil", "acme"];
const actor = { type: "User", id: "bob" };
const repo = typedVar("Repository");
const results = await oso
.buildQuery(["allow", actor, "read", repo])
.in(repo, repos)
.evaluate(repo);
// => Returns the subset of `repos` that bob can read- eg.
// ["anvil"]

Filtering an authorize() query based on a relation

const actor = { type: "User", id: "bob" };
const repo = typedVar("Repository");
const org = { type: "Org", id: "coolguys" };
const results = await oso
.buildQuery(["allow", actor, "read", repo])
.and(["has_relation", repo, "parent", org])
.evaluate(repo);
// => Returns the IDs of the repos in the coolguys org that bob can read- eg.
// ["acme", "anvil"]

Learn more about how to query Oso Cloud.

Distributed Check API

The distributed check API allows you to perform authorization using data that's distributed across Oso Cloud and your own database. When you instantiate the Oso Cloud client, provide the path to the YAML file that specifies how to resolve facts in your database.


const oso = new Oso(..., {
dataBindings: "path/to/data_bindings.yaml"
});

For more information, see the guide on filtering lists with decentralized data.

List authorized resources with distributed data: oso.listLocal(actor, action, resource_type, column)

Fetches a filter that can be applied to a database query to return just the resources on which an actor can perform an action. Example with Kysely (opens in a new tab):


const alice = { type: "User", id: "alice" };
const authorized_issues = await db
.selectFrom("issues")
.where(sql.raw<boolean>(await oso.listLocal(alice, "read", "Issue", "id")))
.selectAll()
.execute();

You may use the Kysely query builder (opens in a new tab) to combine this authorization filter with other things such as ordering and pagination.

Check a permission with distributed data: oso.authorizeLocal(actor, action, resource)

Fetches a query that can be run against your database to determine whether an actor can perform an action on a resource. Example with Kysely (opens in a new tab):


const alice = { type: "User", id: "alice" };
const swage_issue = { type: "Issue", id: "swage" };
const query = await oso.authorizeLocal(alice, "read", swage_issue);
const { allowed } = (await sql.raw<AuthorizeResult>(query).execute(db)).rows[0];
if (!allowed) {
throw new Error("Action is not allowed");
}

List authorized actions with distributed data: oso.actionsLocal(actor, resource)

Fetches a query that can be run against your database to fetch the actions an actor can perform on a resource. Example with Kysely (opens in a new tab):


const alice = { type: "User", id: "alice" };
const swage_issue = { type: "Issue", id: "swage" };
const query = await oso.actionsLocal(alice, swage_issue);
const result = await sql.raw<{ actions: string }>(query).execute(db);
const actions = result.rows.map(({ actions }) => actions);

Policy API

Update the active policy: oso.policy(policy)

Updates the policy in Oso Cloud. The string passed into this method should be written in Polar. Example:


await oso.policy("actor User {}");

This command will run any tests defined in your policy. If one or more of these tests fail, your policy will not be updated.

Get policy metadata: oso.getPolicyMetadata()

Returns metadata about the currently active policy. Example:


metadata = await oso.getPolicyMetadata();

returns:


resources: {
Organization: {
roles: ["admin", "member"],
permissions: [
"add_member",
"read",
"repository.create",
"repository.delete",
"repository.read",
],
relations: {},
},
User: {
roles: [],
permissions: [],
relations: {},
},
global: {
roles: [],
permissions: [],
relations: {},
},
}

See the Policy Metadata guide for more information on use cases.

Debugging

Request logs can be found in the Oso Cloud dashboard, but sometimes it's useful to print timings from the client so you can diagnose network problems. There are two configuration parameters you can set


var oso = new Oso(url, apiKey, { debug: { print: true } });

will print debug messages to stdout.


var oso = new Oso(url, apiKey, { debug: { file: "oso_debug.txt" } });

will append debug messages to the file you specify.

In both cases the messages will look like this. They show the route, the response code, the total request time and how much time was spent in Oso Cloud processing the request vs. network transport.


[oso] /facts 200 total: 4ms, server: 3ms network: 1ms
[oso] /policy 200 total: 9ms, server: 3ms network: 6ms
...

Talk to an Oso Engineer

If you'd like to learn more about using Oso Cloud in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer. We're happy to help.

Get started with Oso Cloud →

Migrating to v2