Node.js Client API

First, install the oso-cloud package on NPM:

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:

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):

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:

To output resource block declarations as an exported constant, pass in the --include resources flag, and output to a .ts module:

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:

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.

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:

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

Primitive value conversion

Additionally, for fields with primitive values you may pass an instance of the corresponding type directly instead of a full object:

Centralized Authorization Data API

Oso Cloud clients provide an API to manage authorization data stored directly in Oso Cloud.

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:

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

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

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

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

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:

Check API

Context facts

The Check AP lets you provide context facts with each request. When Oso Cloud performs a check, it considers the request's context facts in addition to any other centralized authorization data. Context facts are only used in the API call in which they're provided-- they do not persist across requests.

For more details, see 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:

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

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

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

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

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

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

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

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:

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:

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:

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:

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:

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 a Map mapping one typedVar query variable (call it K) to another (call it V), returns a Map grouping unique values of K to unique values of V for each value of K. For example:
  
  

  const action = typedVar("String");

  const repository = typedVar("Repository");

  const map = await oso

  .buildQuery(["allow", actor, action, repository])

  .evaluate(new Map([[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:

Query Builder examples

Field-level access control

Checking a global permission

Fetching authorized actions for a collection of resources

Filtering out unauthorized resources from a collection

Filtering an authorize() query based on a relation

Learn more about how to query Oso Cloud.

Local Check API

The local check API lets you perform authorization using data that's distributed across Oso Cloud and your own database.

After creating your Local Authorization configuration, provide the path to the YAML file that specifies how to resolve facts in your database.

For more information, see Local Authorization.

List authorized resources with local 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):

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.

You may provide a list of context facts as an optional final argument to this method.

Check a permission with local 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):

You may provide a list of context facts as an optional final argument to this method.

List authorized actions with local 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):

You may provide a list of context facts as an optional final argument to this method.

Query for any rule with local data: QueryBuilder

You can use the Query Builder to construct SQL queries that you can run against your database to answer arbitrary questions about authorization.

See the Query Builder API documentation for information on how to construct queries. Once you've built your query, instead of calling evaluate (which would evaluate your query exclusively against data stored in Oso Cloud), call either evaluateLocalSelect or evaluateLocalFilter to construct a SQL query which you can run against your database.

Local Query API

QueryBuilder.evaluateLocalSelect(columnNamesToQueryVars)

Fetches a complete SQL query representing the given Query Builder query. (See the Query Builder API documentation for information on how to construct queries.)

The argument to this function is an object that maps the column names that will appear in the SELECT clause of the SQL query to the Query Builder variables whose values should be selected. For example, query.evaluateLocalSelect({user_id: userVar}) will select all the authorized values of userVar (that is, all the values of userVar that satisfy the Query Builder query) into a column called "user_id".

If you pass in an empty object or omit this argument entirely, the SQL query will return a single row selecting a boolean column called result. This column will be true when there's some combination of data in your database that can satisfy the given Query Builder query and false otherwise.

Note that each query variable can appear at most once in the columnNamesToQueryVars mapping. For example, query.evaluateLocalSelect({user_id: userVar, another_user_id: userVar}) will throw a TypeError, because userVar appears twice in the mapping parameter.

Note that column names will be double-quoted and are thus case-sensitive.

Limitations

evaluateLocalSelect has the following limitations:

• Queries that would return a wildcard for one of the selected query variables are currently unsupported.

  Example:

  policy.polar

  
  

  has_permission(user: User, "read", _: Repo) if is_global_admin(user);

  
  
  
  

  // alice is a global admin, and can read *any* repo

  await oso.insert(["is_global_admin", { type: "User", id: "alice" }]);

  // UNSUPPORTED: Attempt to query for each authorized user / repo pair

  const userVar = typedVar("User");

  const repoVar = typedVar("Repo");

  const sql = await oso

  .buildQuery(["allow", userVar, "read", repoVar])

  .evaluateLocalSelect({ user_id: userVar, repo_id: repoVar });

  // => throws `Error`, because alice can read any repo, so this query would return

  // a wildcard for the repos alice can read

  
  

QueryBuilder.evaluateLocalFilter(columnName, queryVar)

Fetches a SQL fragment representing the given Query Builder query that you can embed in the WHERE clause of some other SQL query. Use this to filter out unauthorized results from your SQL query.

(See the Query Builder API documentation for information on how to construct queries.)

columnName is the name of the column you want to filter in your SQL query, and queryVar is the query variable to filter against. For example, query.evaluateLocalFilter("user_id", userVar) will return a SQL fragment of the form "user_id" IN (...), constraining the column "user_id" to the authorized values of userVar.

Note that the column name will be double-quoted and is thus case-sensitive.

Local query examples

These examples all use Kysely (opens in a new tab) to execute the returned SQL queries, but you can use any database client you prefer.

Field-level access control

Checking a global permission

Fetching authorized actions for a paginated collection of resources

Filtering an authorize() query based on a relation

Filtering on users who can read a certain resource

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:

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:

returns:

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 three configuration parameters you can set

will print debug messages to stdout.

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.

Custom Logger

The third option is logger which allows you to route Oso's debug timings to your own logger such as winston. The function signature is:

Example:

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 →