Oso Library

https://www.osohq.com/docs/oss/
Admin
The Oso Library is a batteries-included framework for building authorization in applications,...
Tokens:430,622
Snippets:5,121
Trust Score:9.8
Update:10 months ago
Show doc for...
Tokens:
Raw
### Clone and Install Node.js Dependencies

Source: https://www.osohq.com/docs/oss/node/getting-started/quickstart

Clones the Oso Node.js quickstart repository and installs its dependencies using npm. This is the initial setup step for the Node.js quickstart.

```shell
git clone https://github.com/osohq/oso-nodejs-quickstart.git
cd oso-nodejs-quickstart
npm install
```

--------------------------------

### Clone Ruby Quickstart Repo and Install Dependencies

Source: https://www.osohq.com/docs/oss/ruby/getting-started/quickstart

Clones the Oso Ruby quickstart repository and installs necessary project dependencies using Bundler. This sets up the environment for running the Oso authorization examples.

```bash
git clone https://github.com/osohq/oso-ruby-quickstart.git
cd oso-ruby-quickstart
bundle install

```

--------------------------------

### Clone and Install Java Quickstart Dependencies

Source: https://www.osohq.com/docs/oss/java/getting-started/quickstart

This snippet shows how to clone the Oso Java quickstart repository and install its dependencies using Maven. Ensure Maven is installed on your system before running these commands.

```bash
git clone https://github.com/osohq/oso-java-quickstart.git
cd oso-java-quickstart
mvn install # requires maven to be installed!

```

--------------------------------

### Starting Go REPL from Oso Instance Example

Source: https://www.osohq.com/docs/oss/node/project/changelogs/2021-02-17

An example demonstrating how to use the `oso.go` file as a starting point for initializing a Go REPL within your Oso instance.

```go
import (
	"github.com/osohq/go-oso/cmd/oso"
)

func main() {
	// Example of how to start a Go REPL from your Oso instance
	// oso.RunREPL()
}
```

--------------------------------

### Clone Python Quickstart Repo and Install Dependencies

Source: https://www.osohq.com/docs/oss/getting-started/quickstart

This snippet clones the Oso Python quickstart repository and installs the necessary project dependencies using pip. Ensure you have Git and pip installed.

```bash
git clone https://github.com/osohq/oso-python-quickstart.git
cd oso-python-quickstart
pip install -r requirements.txt
```

--------------------------------

### Run Node.js Development Server

Source: https://www.osohq.com/docs/oss/node/getting-started/quickstart

Starts the Node.js development server using npm. This command is used after dependencies are installed to run the application.

```shell
npm run dev
```

--------------------------------

### Run the Go Quickstart Server

Source: https://www.osohq.com/docs/oss/go/getting-started/quickstart

This command executes the Go application, starting a local web server. The server is configured to listen on port 5000 and will handle authorization requests using the Oso policy defined in `main.polar`.

```bash
go run .
```

--------------------------------

### Setup and Seed Django Example Data

Source: https://www.osohq.com/docs/oss/reference/frameworks/data_filtering/django

Instructions for setting up the Django example project, including installing dependencies and seeding the database with users and posts. This prepares the environment for testing authorization policies.

```bash
make setup
python example/manage.py runserver
```

--------------------------------

### Run Ruby Quickstart Server

Source: https://www.osohq.com/docs/oss/ruby/getting-started/quickstart

Starts the Ruby on Rails server for the Oso quickstart project. Once running, you can access the application via a web browser to test authorization rules.

```bash
bundle exec ruby server.rb

```

--------------------------------

### Add Oso Go Dependency

Source: https://www.osohq.com/docs/oss/go/reference/installation

Adds the Oso Go library as a dependency to your Go project using the go get command. Ensure you have Go version 1.14 or higher installed. This command fetches the specified version of the library.

```bash
go get github.com/osohq/go-oso@v0.27.3
```

--------------------------------

### Installation Guide

Source: https://www.osohq.com/docs/oss/ruby/reference/api/index

Instructions on how to install the oso-oso gem for your Ruby application.

```APIDOC
## Installation

### Description
Add the `oso-oso` gem to your application's Gemfile and run `bundle install`, or install it directly using `gem install oso-oso`.

### Method
Gem Installation

### Endpoint
N/A

### Parameters
N/A

### Request Example
**Gemfile:**
```ruby
gem 'oso-oso'
```

**Command Line:**
```bash
gem install oso-oso
```

### Response
N/A
```

--------------------------------

### Install Oso Python Library

Source: https://www.osohq.com/docs/oss/getting-started/application/model

Installs the Oso Python library using pip. This is the primary method for getting started with Oso in a Python application.

```bash
$ pip install oso
```

--------------------------------

### Setup and Run Tests for oso-oso

Source: https://www.osohq.com/docs/oss/ruby/reference/api/index

Instructions for setting up the development environment for the 'oso-oso' gem, including installing dependencies, running tests, and interacting with the project.

```bash
$ bundle install
$ bundle exec rake spec

```

--------------------------------

### Install Oso Go Library

Source: https://www.osohq.com/docs/oss/go/getting-started/application/model

Installs the Oso Go library using the go get command. This is the first step to integrating Oso into a Go application for policy evaluation.

```bash
go get github.com/osohq/go-oso

```

--------------------------------

### Run Python Flask Development Server

Source: https://www.osohq.com/docs/oss/getting-started/quickstart

This command starts the Flask development server for the Python quickstart project. It assumes the Flask app is named 'app.server'. The server will typically run on port 5000.

```bash
FLASK_APP=app.server python -m flask run
```

--------------------------------

### Full Example: Main Policy with Rules and Declarations

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

An extensive example demonstrating a main policy that includes a top-level 'allow' rule, a 'has_role' implementation, actor and resource definitions ('User', 'Organization', 'Repository'), and detailed role, permission, and relation declarations within the 'Repository' resource block.

```polar
allow(actor, action, resource) if
  has_permission(actor, action, resource);

has_role(user: User, name: String, resource: Resource) if
  role in user.Roles and
  role.Name = name and
  role.Resource = resource;

actor User {}

resource Organization {
  roles = [ "owner" ];
}

resource Repository {
  permissions = [ "read", "push" ];
  roles = [ "contributor", "maintainer" ];
  relations = { parent: Organization };

  # An actor has the "read" permission if they have the "contributor" role.
  "read" if "contributor";
  # An actor has the "push" permission if they have the "maintainer" role.
  "push" if "maintainer";

  # An actor has the "contributor" role if they have the "maintainer" role.
  "contributor" if "maintainer";

  # An actor has the "maintainer" role if they have the "owner" role on the "parent" Organization.
  "maintainer" if "owner" on "parent";
}

has_relation(organization: Organization, "parent", repository: Repository) if
  organization = repository.Organization;
```

--------------------------------

### Clone Go Quickstart Repo and Download Dependencies

Source: https://www.osohq.com/docs/oss/go/getting-started/quickstart

This snippet shows the commands to clone the Oso Go quickstart repository from GitHub and download its project dependencies using Go modules. It's the initial step for setting up the local development environment.

```bash
git clone https://github.com/osohq/oso-go-quickstart.git
cd oso-go-quickstart
go mod download
```

--------------------------------

### Flask Server Implementation for Oso Integration (Python)

Source: https://www.osohq.com/docs/oss/rust/getting-started/quickstart

This Python code sets up a Flask application that integrates with the Oso authorization library. It initializes Oso, registers data models, loads policy files, and defines a route to authorize user access to repositories.

```python
from flask import Flask
from oso import Oso, NotFoundError
from .models import User, Repository

# Initialize the Oso object. This object is usually used globally throughout
# an application.
oso = Oso()

# Tell Oso about the data you will authorize. These types can be referenced
# in the policy.
oso.register_class(User)
oso.register_class(Repository)

# Load your policy files.
oso.load_files(["app/main.polar"])

app = Flask(__name__)


@app.route("/repo/<name>")
def repo_show(name):
    repo = Repository.get_by_name(name)

    try:
        oso.authorize(User.get_current_user(), "read", repo)
        return f"<h1>A Repo</h1><p>Welcome to repo {repo.name}</p>", 200
    except NotFoundError:
        return f"<h1>Whoops!</h1><p>Repo named {name} was not found</p>", 404
```

--------------------------------

### Using Go REPL within Oso Instance

Source: https://www.osohq.com/docs/oss/project/changelogs/2021-02-17

An example demonstrating how to integrate and start a Go REPL from an existing Oso instance within a Go application.

```go
package main

import (
	"fmt"
	"os.Stdin"
	"os.Stdout"

	"github.com/osohq/go-oso"
)

func main() {
	oso, err := oso.New(
		oso.With políticas("*.polar"),
	)
	if err != nil {
		panic(err)
	}

	repl := oso.NewREPL(os.Stdin, os.Stdout)
	fmt.Println("Welcome to the Oso Go REPL!")
	repl.Run()
}

```

--------------------------------

### Import Oso Go Library

Source: https://www.osohq.com/docs/oss/go/reference/installation

Imports the Oso Go library into your Go source files after it has been added as a dependency. This allows you to use Oso's functionality within your application. Requires a Go environment with the Oso dependency correctly installed.

```go
import "github.com/osohq/go-oso"
```

--------------------------------

### Run the Java Quickstart Server

Source: https://www.osohq.com/docs/oss/java/getting-started/quickstart

Instructions to compile and run the Java quickstart server using Maven. This command will build the project and execute the main server class, making it accessible on port 5000.

```bash
mvn clean package exec:java -Dexec.mainClass="quickstart.Server"

```

--------------------------------

### Shorthand Rule with Relations Example

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Demonstrates shorthand rules that leverage declared relations. This example shows how roles on a parent resource can be used to grant roles on the current resource, particularly useful for hierarchical access control.

```polar
resource Repository {
  roles = ["contributor", "maintainer"];
  relations = { parent: Organization };

  "admin" if "owner" on "parent"  # "owner" role on parent Organization grants the "admin" role
  "contributor" if "member" on "parent"  # "member" role on parent Organization grants "contributor" role
}
```

--------------------------------

### Flask Integration Test Client Setup (Python)

Source: https://www.osohq.com/docs/oss/go/guides/more/testing

Sets up a test client for a Flask application within a pytest fixture. This allows for end-to-end testing of application routes and authorization logic.

```python
@pytest.fixture
def client():
    with app.test_client() as client:
        yield client

```

--------------------------------

### Launch REPL using NPM script

Source: https://www.osohq.com/docs/oss/node/reference/tooling/repl

This code snippet demonstrates how to add a script to your project's package.json file to launch the Oso REPL using NPM. This is useful when Oso is installed as a project dependency. After adding the script, you can start the REPL by running 'npm run oso'.

```json
{
"scripts": {
    "oso": "oso"
}
}
```

--------------------------------

### Install oso-oso Gem

Source: https://www.osohq.com/docs/oss/ruby/reference/api/index

This snippet shows how to add the 'oso-oso' gem to your application's Gemfile for installation via Bundler, or how to install it directly using the gem command.

```ruby
gem 'oso-oso'

```

```bash
$ bundle install

```

```bash
$ gem install oso-oso

```

--------------------------------

### Complete Resource Block with Logic

Source: https://www.osohq.com/docs/oss/node/reference/polar/polar-syntax

An example of a comprehensive 'Repository' resource block. It declares permissions ('read', 'push'), roles ('contributor', 'maintainer'), and relations ('parent'). It also includes shorthand rules to define how actors gain these roles and permissions based on other roles or relations.

```polar
resource Repository {
  permissions = ["read", "push"];
  roles = ["contributor", "maintainer"];
  relations = { parent: Organization };

  # An actor has the "read" permission if they have the "contributor" role.
  "read" if "contributor";
  # An actor has the "push" permission if they have the "maintainer" role.
  "push" if "maintainer";

  # An actor has the "contributor" role if they have the "maintainer" role.
  "contributor" if "maintainer";

  # An actor has the "maintainer" role if they have the "owner" role on the "parent" Organization.
  "maintainer" if "owner" on "parent";
}

```

--------------------------------

### Polar Policy Syntax Example

Source: https://www.osohq.com/docs/oss/go/project

Illustrates the syntax of a policy rule written in the Polar language. This example defines an 'allow' rule for viewing posts based on access level or creator.

```polar
allow(user, "view", post) if
    post.access_level = "public"
or
    post.creator = user;

```

--------------------------------

### Install Local oso-oso Gem

Source: https://www.osohq.com/docs/oss/ruby/reference/api/index

Command to install the 'oso-oso' gem onto your local machine after checking out the repository and installing dependencies.

```bash
$ bundle exec rake install

```

--------------------------------

### Install Oso REPL using Cargo (Rust)

Source: https://www.osohq.com/docs/oss/rust/reference/tooling/repl

Provides instructions for installing the Oso REPL executable using the Rust package manager, Cargo. This is a prerequisite for using the REPL.

```bash
cargo install --features=cli oso
```

--------------------------------

### Start Oso REPL with Application Code (Java)

Source: https://www.osohq.com/docs/oss/java/reference/tooling/repl

Starts the Oso REPL after registering application classes and loading policy files programmatically. This allows interaction with application objects and defined policies.

```java
import com.example.Expense;
import com.example.User;

import com.osohq.oso.*;

public class AppRepl {
    public static void main(String[] args) throws OsoException, IOException {
        Oso oso = new Oso();
        oso.registerClass(Expense.class);
        oso.registerClass(User.class);
        oso.loadFiles(["alice.polar"]);
        oso.repl(args)
    }
}
```

--------------------------------

### Complete Oso Policy Example

Source: https://www.osohq.com/docs/oss/go/getting-started/application/model

A comprehensive Oso policy defining actors, resources, permissions, roles, and the `has_role` and `allow` rules. This serves as a full example for authorization logic.

```polar
actor User {}

resource Repository {
    permissions = ["read", "push", "delete"];
    roles = ["contributor", "maintainer", "admin"];

    "read" if "contributor";
    "push" if "maintainer";
    "delete" if "admin";

    "maintainer" if "admin";
    "contributor" if "maintainer";
}

has_role(actor: User, role_name: String, repository: Repository) if
    role in actor.roles and
    role_name = role.name and
    repository = role.repository;

allow(actor, action, resource) if
    has_permission(actor, action, resource);

```

--------------------------------

### Polar Negation (not) Operator Example

Source: https://www.osohq.com/docs/oss/ruby/reference/polar/polar-syntax

Shows how the 'not' operator in Polar is used to succeed when its argument fails. Examples include negating a comparison and negating rule calls.

```Polar
non_zero(x) if not x == 0;

positive(x) if
    non_zero(x) and
    not negative(x);

negative(x) if x < 0;

positive(x) if
    not (x == 0 or negative(x));
```

--------------------------------

### Go Server Implementation with Oso Integration

Source: https://www.osohq.com/docs/oss/go/getting-started/quickstart

This Go code sets up a Fiber web server that integrates with the Oso authorization library. It defines routes, registers data models with Oso, loads the policy file, and uses `oso.Authorize` to enforce access control for repository access.

```go
package main

import (
	"fmt"
	"reflect"

	"github.com/gofiber/fiber/v2"
	"github.com/osohq/go-oso"
)

func main() {
	app := fiber.New()
	oso, err := oso.NewOso()
	if err != nil {
		fmt.Printf("Failed to set up Oso: %v", err)
		return
	}

	oso.RegisterClass(reflect.TypeOf(Repository{}), nil)
	oso.RegisterClass(reflect.TypeOf(User{}), nil)
	if err := oso.LoadFiles([]string{"main.polar"}); err != nil {
		fmt.Printf("Failed to start: %s", err)
		return
	}

	app.Get("/repo/:repoName", func(c *fiber.Ctx) error {
		c.Set(fiber.HeaderContentType, fiber.MIMETextHTML)
		repoName := c.Params("repoName")
		repository := GetRepositoryByName(repoName)
		err := oso.Authorize(GetCurrentUser(), "read", repository)
		if err == nil {
			return c.Status(200).SendString(fmt.Sprintf("<h1>A Repo</h1><p>Welcome to repo %s</p>\n", repository.Name))
		} else {
			return c.Status(404).SendString(fmt.Sprintf("<h1>Whoops!</h1><p>Repo named %s was not found</p>\n", repoName))
		}
	})
	if err := app.Listen(":5000"); err != nil {
		fmt.Printf("Failed to start: %s", err)
	}
}

```

--------------------------------

### Development Guide

Source: https://www.osohq.com/docs/oss/ruby/reference/api/index

Steps for setting up the development environment for the Oso OSS project.

```APIDOC
## Development

### Description
Follow these steps to set up the development environment: install dependencies with `bundle install`, run tests with `bundle exec rake spec`, or experiment in the REPL with `bundle exec oso`. To install the gem locally, use `bundle exec rake install`. Releases are managed via GitHub Actions.
```

--------------------------------

### Polar Unification Operator Example

Source: https://www.osohq.com/docs/oss/ruby/reference/polar/polar-syntax

Shows the explicit use of the unification operator '=' in Polar to check for equality or variable binding. Examples include literal equality and variable assignment.

```Polar
1 = 1
"a" = "a"
x = 1
```

--------------------------------

### Polar Rule Definition Example

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Shows a basic example of a Polar rule, defining a `person` fact based on a `bear` fact. It illustrates the `HEAD if BODY;` structure where the `HEAD` is true if the `BODY` terms are true.

```Polar
person("yogi", "bear") if bear("yogi", "bear");
```

--------------------------------

### Java Server Implementation with Oso Integration (Server.java)

Source: https://www.osohq.com/docs/oss/java/getting-started/quickstart

The main server class for the Java quickstart project. It uses Javalin for web requests and integrates Oso for authorization checks. The server registers User and Repository classes with Oso and loads the policy file.

```java
package quickstart;

import java.io.IOException;
import io.javalin.Javalin;
import com.osohq.oso.Oso;
import com.osohq.oso.Exceptions.NotFoundException;
import quickstart.Models.Repository;
import quickstart.Models.User;

public class Server {
    public static void main(String[] args) throws IOException {
        Javalin app = Javalin.create();
        Oso oso = new Oso();
        oso.registerClass(User.class, "User");
        oso.registerClass(Repository.class, "Repository");
        oso.loadFile("src/main/java/quickstart/main.polar");
        app.get("/repo/{name}", ctx -> {
            ctx.contentType("text/html");
            String name = ctx.pathParam("name");
            Repository repo = Repository.byName(name);
            User user = User.getCurrentUser();

            try {
                oso.authorize(user, "read", repo);
                ctx.result(String.format("<h1>A Repo</h1><p>Welcome to repo %s</p>", repo.name));
            } catch (NotFoundException e) {
                ctx.status(404);
                ctx.result(String.format("<h1>Whoops!</h1><p>Repo named %s was not found</p>", name));
            }
        });
        app.start(5000);
    }
}

```

--------------------------------

### Ruby Server Implementation with Oso Integration

Source: https://www.osohq.com/docs/oss/ruby/getting-started/quickstart

Implements a Sinatra web server in Ruby that integrates with the Oso authorization library. It defines routes, registers Oso classes, loads policies, and uses OSO.authorize to protect repository access.

```ruby
# frozen_string_literal: true

require 'oso'
require 'sinatra'

require_relative 'models'

OSO = Oso.new

OSO.register_class(User)
OSO.register_class(Repository)

OSO.load_files(["main.polar"])

get '/repo/:name' do
  repo = Repository.get_by_name(params['name'])

  begin
    OSO.authorize(User.get_current_user, "read", repo)
    "<h1>A Repo</h1><p>Welcome to repo #{repo.name}</p>"
  rescue Oso::NotFoundError
    status 404
    "<h1>Whoops!</h1><p>Repo named #{params['name']} was not found</p>"
  end
end

set :port, 5000


```

--------------------------------

### Unification Operator Example

Source: https://www.osohq.com/docs/oss/java/reference/polar/polar-syntax

Shows the explicit use of the unification operator (`=`) in Polar. This operator checks if two values are equal or can be made equal through variable bindings. Examples include unifying literals, and unifying a variable with a literal.

```Polar
1 = 1
"a" = "a"
x = 1

```

--------------------------------

### Example Polar rule for route authorization

Source: https://www.osohq.com/docs/oss/reference/frameworks/django

An example Polar policy rule that allows any user to access the root path ('/') with a GET request. It demonstrates using request attributes like 'path' in authorization rules.

```polar
# Allow any actor to make a GET request to "/".
allow(_user: User, "GET", http_request: HttpRequest) if
    http_request.path = "/";
```

--------------------------------

### Python Flask Server with Oso Authorization Logic

Source: https://www.osohq.com/docs/oss/getting-started/quickstart

This Python code sets up a Flask web application that uses the Oso library for authorization. It initializes Oso, registers data models (User, Repository), loads the policy, and defines a route '/repo/<name>' that checks if the current user can 'read' the specified repository.

```python
from flask import Flask
from oso import Oso, NotFoundError
from .models import User, Repository

# Initialize the Oso object. This object is usually used globally throughout
# an application.
oso = Oso()

# Tell Oso about the data you will authorize. These types can be referenced
# in the policy.
oso.register_class(User)
oso.register_class(Repository)

# Load your policy files.
oso.load_files(["app/main.polar"])

app = Flask(__name__)


@app.route("/repo/<name>")
def repo_show(name):
    repo = Repository.get_by_name(name)

    try:
        oso.authorize(User.get_current_user(), "read", repo)
        return f"<h1>A Repo</h1><p>Welcome to repo {repo.name}</p>", 200
    except NotFoundError:
        return f"<h1>Whoops!</h1><p>Repo named {name} was not found</p>", 404

```

--------------------------------

### Implement has_relation Hook Rule

Source: https://www.osohq.com/docs/oss/java/reference/polar/polar-syntax

Shows an example implementation for the `has_relation` rule, which is required when declaring relations. This rule is responsible for querying the application's data to ascertain if a specified relationship exists between two entities. The example demonstrates fetching the parent organization for a repository.

```rego
# Relation hook - required when using relations
has_relation(parent_org: Organization, "parent", repo: Repository) if
  # Look up parent-child relation from application, e.g.
  parent_org = repo.organization;
```

--------------------------------

### Oso Initialization

Source: https://www.osohq.com/docs/oss/java/reference/api/com/osohq/oso/Oso

Demonstrates how to create an instance of the Oso client.

```APIDOC
## Oso Constructor

### Description
Initializes a new instance of the Oso authorization client.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
None

### Request Example
```java
Oso oso = new Oso();
```

### Response
N/A
```

--------------------------------

### Negation (not) Operator Example

Source: https://www.osohq.com/docs/oss/java/reference/polar/polar-syntax

Shows how the `not` operator is used in Polar to succeed when its argument fails. This is useful for expressing conditions like 'not equal to' or when negating the results of another rule. The example demonstrates `not x == 0` and negating a rule call `not negative(x)`.

```Polar
non_zero(x) if not x == 0;

positive(x) if
    non_zero(x) and
    not negative(x);

negative(x) if x < 0;

```

--------------------------------

### Node.js Server Implementation with Oso

Source: https://www.osohq.com/docs/oss/node/getting-started/quickstart

Implements an Express.js server in Node.js that uses the Oso library for authorization. It registers User and Repository classes, loads a Polar policy file, and defines a route to authorize 'read' access to repositories.

```javascript
const { Oso, NotFoundError } = require("oso");
const { User, Repository } = require("./models");
const express = require("express");

async function start() {
  const oso = new Oso();
  oso.registerClass(User);
  oso.registerClass(Repository);
  await oso.loadFiles(["main.polar"]);

  const app = express();

  app.get("/repo/:name", async (req, res) => {
    const name = req.params.name;
    const repo = Repository.getByName(name);
    const user = User.getCurrentUser();

    try {
      await oso.authorize(user, "read", repo);
      res.send(`<h1>A Repo</h1><p>Welcome to repo ${repo.name}</p>`);
    } catch (e) {
      if (e instanceof NotFoundError) {
        res.status(404);
        res.send(`<h1>Whoops!</h1><p>Repo named ${name} was not found</p>`);
      } else {
        throw e;
      }
    }
  });
  app.listen(5000, () => console.log("Server running on port 5000"));
}

start();

```

--------------------------------

### Define Shorthand Rules Without Relations

Source: https://www.osohq.com/docs/oss/node/reference/polar/polar-syntax

This example shows shorthand rules defined without using relations. It maps roles directly to permissions and other roles within the same resource block. For example, the 'contributor' role grants the 'read' permission, and the 'maintainer' role grants the 'contributor' role.

```polar
resource Repository {
  permissions = ["read", "push"];
  roles = ["contributor", "maintainer"];

  "read" if "contributor";  // "contributor" role grants "read" permission
  "push" if "maintainer";  // "maintainer" role grants "push" permission
  "contributor" if "maintainer";  // "maintainer" role grants "contributor" role
}
```

--------------------------------

### SQLAlchemy-Oso Resource Predicate Configuration Example

Source: https://www.osohq.com/docs/oss/node/project/changelogs/2021-06-09

Illustrates the updated syntax for the `resource` predicate in `sqlalchemy-oso`, demonstrating the renaming of `perms` to `permissions` and the addition of namespaces to role names. This example shows how to configure actions, roles, and cross-resource role implications.

```rego
resource(_type: Organization, "org", actions, roles) if
    actions = ["invite", "list_repos"] and
    roles = {
        member: {
            # `perms` renamed to `permissions`
            permissions: ["invite"]
        },
        owner: {
            permissions: ["list_repos"],
            # Roles from a different resource are now referenced by namespace
            implies: ["member", "repo:reader"]
        }
    };

```

--------------------------------

### Start REPL with Application Code (JavaScript)

Source: https://www.osohq.com/docs/oss/node/reference/tooling/repl

This JavaScript code snippet shows how to start the Oso REPL while also loading application code and registering classes. It imports necessary modules, initializes Oso, registers application classes (Expense, User), loads policy files, and then invokes the REPL using `Oso.repl()`.

```javascript
const { Expense, User } = require('./models');
const { Oso } = require('oso');

const oso = new Oso();
oso.registerClass(Expense);
oso.registerClass(User);
await oso.loadFiles(["alice.polar"])
await oso.repl();

```

--------------------------------

### Combine base and conditional rules in Polar

Source: https://www.osohq.com/docs/oss/learn/polar-foundations

Shows a practical example combining several 'father' rules with a conditional 'grandfather' rule. This setup allows for querying complex relationships.

```Polar
father("Artemis", "Zeus");
father("Apollo", "Zeus");
father("Asclepius", "Apollo");
grandfather(a, b) if father(a, anyPerson) and father(anyPerson, b);
```

--------------------------------

### Integrate Application Code with Go REPL

Source: https://www.osohq.com/docs/oss/go/reference/tooling/repl

A Go code snippet showing how to initialize Oso, register custom classes (like Expense and User), load policy files, and start the REPL using `Oso.repl()`.

```go
import "github.com/osohq/go-oso"
import "reflect"

func main() {
    // error handling not shown
    osoInstance, err := oso.NewOso()
    osoInstance.RegisterClass(reflect.TypeOf(Expense{}), nil)
    osoInstance.RegisterClass(reflect.TypeOf(User{}), nil)
    osoInstance.LoadFile("policy.polar")
    osoInstance.Repl()
}
```

--------------------------------

### Oso Query Execution Example (Python)

Source: https://www.osohq.com/docs/oss/go/project

Demonstrates how to execute an authorization query using the Oso library in Python. It involves creating an Oso instance, registering application classes, and querying for an authorization decision.

```python
import oso

# Initialize Oso
polar = oso.Oso()

# Register application classes (example)
polar.register_class(User)
polar.register_class(Expense)

# Load policy file
polar.load_file("policy.polar")

# Example user and expense objects
user = User(id=1, name="Alice")
expense = Expense(id=101, amount=50.0, creator=user)

# Execute a query
query_result = polar.query_rule("allow", user, "view", expense)

# Process the result
if query_result:
    print("Authorization granted.")
else:
    print("Authorization denied.")
```

--------------------------------

### Polar Conjunction (and) Operator Example

Source: https://www.osohq.com/docs/oss/ruby/reference/polar/polar-syntax

Illustrates the use of the 'and' operator in Polar to ensure that multiple conditions in a rule's body must all be true for the rule to be satisfied.

```Polar
oso_user(first, last) if
    user(first, last) and
    employee("Oso", first, last);
```

--------------------------------

### Polar Assignment Operator Example

Source: https://www.osohq.com/docs/oss/ruby/reference/polar/polar-syntax

Demonstrates the assignment operator ':=' in Polar, which assigns a value to an unbound variable. It highlights that this operator will fail if the left-hand side is not an unbound variable.

```Polar
foo := 1
```

--------------------------------

### Negation Operator Example

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Demonstrates the `not` operator in Polar, which succeeds when its argument fails. This is useful for negating conditions or rule calls. Parentheses can be used to group multiple expressions for negation.

```polar
non_zero(x) if not x == 0;

positive(x) if
    non_zero(x) and
    not negative(x);

negative(x) if x < 0;

positive(x) if
    not (x == 0 or negative(x));

```

--------------------------------

### Simplify SQLAlchemy Oso Initialization with SQLAlchemyOso

Source: https://www.osohq.com/docs/oss/go/project/changelogs/2021-05-12

This code demonstrates the simplified initialization of Oso for SQLAlchemy using the new `SQLAlchemyOso` object. It replaces the previous method of initializing `Oso` and `OsoRoles` separately. The `SQLAlchemyOso` object wraps both, providing a unified interface and streamlining the setup process.

```python
from oso import Oso
from sqlalchemy_oso import register_models
from sqlalchemy_oso.roles2 import OsoRoles
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()
oso = Oso()
register_models(oso, Base)
oso_roles = OsoRoles(oso, Base, User, sessionmaker)

```

```python
from sqlalchemy_oso import SQLAlchemyOso
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()
oso = SQLAlchemyOso(Base)
oso.enable_roles(User, sessionmaker)

```

--------------------------------

### Oso Policy Definition for Repository Access (Polar)

Source: https://www.osohq.com/docs/oss/go/getting-started/quickstart

This is a policy file written in Polar, Oso's policy language. It defines access control rules for `Repository` resources, including permissions, roles, and specific conditions for granting 'read' access based on repository public status. It also includes helper rules for fetching user roles.

```polar
actor User {}

resource Repository {
  permissions = ["read", "push", "delete"];
  roles = ["contributor", "maintainer", "admin"];

  "read" if "contributor";
  "push" if "maintainer";
  "delete" if "admin";

  "maintainer" if "admin";
  "contributor" if "maintainer";
}

# This rule tells Oso how to fetch roles for a repository
has_role(user: User, roleName: String, repository: Repository) if
  role in user.Roles and
  role.Role = roleName and
  role.RepoId = repository.Id;

has_permission(_actor: User, "read", repository: Repository) if
  repository.IsPublic;

allow(actor, action, resource) if
  has_permission(actor, action, resource);
```

--------------------------------

### Example Polar Policy Rule

Source: https://www.osohq.com/docs/oss/rust/reference/tooling/repl

A simple 'allow' rule written in Polar, defining authorization logic for a 'GET' request on an expense. This rule can be loaded into the Oso REPL.

```polar
allow("alice@example.com", "GET", expense: Dictionary) if
    expense.id == 1;
```

--------------------------------

### Polar Singleton Variable Warning Example

Source: https://www.osohq.com/docs/oss/ruby/reference/polar/polar-syntax

Demonstrates how Polar flags unused singleton variables in rules, indicating potential logical errors. It shows the warning message and the problematic rule.

```Polar
user(first, last) if person("George", last);
```

--------------------------------

### Polar Rule with Variables

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Illustrates how to use variables in Polar rules to create more dynamic and general statements. This example defines that any bear is also a person by using `first` and `last` variables.

```Polar
person(first, last) if bear(first, last);
```

--------------------------------

### Start oso REPL

Source: https://www.osohq.com/docs/oss/ruby/reference/api/index

Command to launch an interactive Read-Eval-Print Loop (REPL) for the 'oso' tool, allowing for experimentation and exploration of its features.

```bash
$ bundle exec oso

```

--------------------------------

### Initialize Oso Client

Source: https://www.osohq.com/docs/oss/java/reference/api/com/osohq/oso/Oso

Creates a new instance of the Oso client. This is the starting point for all interactions with the Oso authorization library.

```java
Oso oso = new Oso();
```

--------------------------------

### Polar List Literals

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Illustrates the syntax for defining lists as sequences of values using brackets. It provides examples of simple lists and nested lists, and mentions the `in` operator for list membership.

```Polar
["polar", "lang", "oso"]
["oso", ["polar", "lang"]]
```

--------------------------------

### Define 'father' rules and a conditional 'grandfather' rule in Polar

Source: https://www.osohq.com/docs/oss/ruby/learn/polar-foundations

This example combines multiple 'father' rule definitions with a conditional 'grandfather' rule. This setup allows for more complex relationship inference within the Polar system.

```polar
father("Artemis", "Zeus");
father("Apollo", "Zeus");
father("Asclepius", "Apollo");
grandfather(a, b) if father(a, anyPerson) and father(anyPerson, b);

```

--------------------------------

### Declare Relations for a Resource

Source: https://www.osohq.com/docs/oss/node/reference/polar/polar-syntax

Illustrates declaring relations between resource/actor types. This example defines a 'parent' relation for 'Repository' pointing to an 'Organization'. Related object types must also be declared in blocks.

```polar
resource Repository {
  relations = { parent: Organization };
}

```

--------------------------------

### Ruby Example Execution: Data Filtering and Authorization

Source: https://www.osohq.com/docs/oss/ruby/guides

Executes the Oso data filtering example by initializing the database and Oso, creating sample data (organizations, repositories, users), and then demonstrating authorization checks. This function sets up the environment for testing the defined policies.

```ruby
def example
  init_db
  oso = init_oso

  osohq = Organization.create id: 'osohq'
  apple = Organization.create id: 'apple'

  ios = Repository.create id: 'ios', organization: apple
  oso_repo = Repository.create id: 'oso', organization: osohq
  demo_repo = Repository.create id: 'demo', organization: osohq

  leina = User.create id: 'leina'
  steve = User.create id: 'steve'

  OrgRo
```

--------------------------------

### Polar forall Operator Examples

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

The `forall` operator checks if an action succeeds for every alternative produced by a condition. It can be used with lists or application data. Bindings within `forall` are not accessible outside.

```polar
forall(x in [1, 2, 3], x = 1)

forall(x in [1, 1, 1], x = 1)

forall(role = user.roles(), role = "admin")
```

--------------------------------

### Ruby Database Initialization for Oso Example

Source: https://www.osohq.com/docs/oss/ruby/guides

Initializes an SQLite database and creates necessary tables for the Oso data filtering example. This includes tables for organizations, users, repositories, and roles. It uses ActiveRecord to establish a connection to the database file.

```ruby
def init_db
  File.delete DB_FILE if File.exist? DB_FILE
  db = SQLite3::Database.new(DB_FILE)
  db.execute <<-SQL
    create table organizations (
      id varchar(16) not null primary key
    );
  SQL
  db.execute <<-SQL
    create table users (
      id varchar(16) not null primary key
    );
  SQL
  db.execute <<-SQL
    create table repositories (
      id varchar(16) not null primary key,
      org_id varchar(16) not null
    );
  SQL
  db.execute <<-SQL
    create table repo_roles (
      id integer not null primary key autoincrement,
      name varchar(16) not null,
      repo_id varchar(16) not null,
      user_id varchar(16) not null
    );
  SQL
  db.execute <<-SQL
    create table org_roles (
      id integer not null primary key autoincrement,
      name varchar(16) not null,
      org_id varchar(16) not null,
      user_id varchar(16) not null
    );
  SQL

  ActiveRecord::Base.establish_connection(
    adapter: 'sqlite3',
    database: DB_FILE
  )
end

```

--------------------------------

### Conjunction Operator Example

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Shows the use of the `and` operator in Polar to combine multiple conditions in a rule body. Both conditions must be true for the rule to be satisfied. This is useful for ensuring that multiple criteria are met.

```polar
oso_user(first, last) if
    user(first, last) and
    employee("Oso", first, last);

```

--------------------------------

### Launch and Basic Usage of Oso REPL

Source: https://www.osohq.com/docs/oss/ruby/reference/tooling/repl

Demonstrates how to launch the Oso REPL from the terminal and interactively query using Polar expressions. The REPL responds with 'true', 'false', or sets of variable bindings that satisfy the query.

```shell
$ oso
query> 1 = 1
true
query> 1 = 2
false
query> x = 1 and y = 2
y => 2
x => 1
query> x = 1 or x = 2
x => 1
x => 2
query> x = 1 and x = 2
false
```

--------------------------------

### Build and Run Go REPL

Source: https://www.osohq.com/docs/oss/go/reference/tooling/repl

Instructions to build the Oso executable for the Go REPL and launch it from the terminal. This allows for interactive policy testing.

```bash
$ go build cmd/oso/oso.go
$ ./oso
query>
```

--------------------------------

### Shorthand Rule without Relations Example

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Illustrates shorthand rules within a resource block where permissions and roles are defined. It shows how a role can directly grant a permission or another role without involving relations.

```polar
resource Repository {
  permissions = ["read", "push"];
  roles = ["contributor", "maintainer"];

  "read" if "contributor";  # "contributor" role grants "read" permission
  "push" if "maintainer";  # "maintainer" role grants "push" permission
  "contributor" if "maintainer";  # "maintainer" role grants "contributor" role
}
```

--------------------------------

### Ffi Class Documentation

Source: https://www.osohq.com/docs/oss/java/reference/api/com/osohq/oso/Ffi

Provides an overview of the Ffi class, its constructors, and its nested classes. This class serves as the entry point for interacting with the Oso FFI.

```APIDOC
## Ffi Class

### Description
The `Ffi` class is the primary interface for interacting with the Oso policy engine via its Foreign Function Interface (FFI). It provides methods for initializing the Oso engine, managing resources, and accessing core functionalities.

### Nested Classes

- `Ffi.CResultPointer`: Represents a C-style result pointer.
- `Ffi.CResultVoid`: Represents a C-style void result.
- `Ffi.Polar`: Represents the main Oso policy engine object.
- `Ffi.PolarLib`: An interface for the Polar library.
- `Ffi.Query`: Represents a query within the Oso engine.

### Constructors

- `protected Ffi()`: Protected constructor for the Ffi class. Typically accessed via the `get()` static method.
```

--------------------------------

### Polar Pattern Matching Examples

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Polar supports pattern matching against primitive types, dictionary literals, instance literals, and type names. For dictionaries, the pattern must be a subset. Type matching considers subclasses.

```polar
{x: 1, y: 2} matches {x: 1}
{x: 1, y: 3} matches {y: 3}
{x: 1, y: 3} matches {x: 1, y: 3}
not {x: 1, y: 3} matches {x: 1, y: 4}

new Person() matches Person
new Person(x: 1, y: 2) matches Person{x: 1}
```

--------------------------------

### Create User and Check Resource Authorization (Python)

Source: https://www.osohq.com/docs/oss/ruby/guides

This snippet demonstrates creating a user, loading an Oso policy from a file, and checking if a user is authorized to perform a 'read' action on a 'Repository' resource. It expects the policy to return specific repositories if authorization is granted.

```python
leina, organization: osohq, name: 'owner'
oso.load_files(['policy_b.polar'])
results = oso.authorized_resources(leina, 'read', Repository)
raise unless results == [oso_repo, demo_repo]
```

--------------------------------

### Initialize Oso Instance

Source: https://www.osohq.com/docs/oss/ruby/reference/api/Oso/Oso

Creates and configures an Oso instance. Allows customization of error types for 'not found' and 'forbidden' scenarios, as well as the default 'read' action used for authorization checks.

```ruby
def initialize(not_found_error: NotFoundError, forbidden_error: ForbiddenError, read_action: 'read')
  super()
  @not_found_error = not_found_error
  @forbidden_error = forbidden_error
  @read_action = read_action
end
```

--------------------------------

### Polar Dictionary Literals

Source: https://www.osohq.com/docs/oss/go/reference/polar/polar-syntax

Explains how dictionaries (associative arrays) are defined in Polar using curly braces to express unordered relational data. It includes examples of standard dictionary syntax and the shorthand syntax for mapping variables to values.

```Polar
{first_name: "Yogi", last_name: "Bear"}
{ first_name, last_name }
{ first_name, last_name: "Bear" }
```

--------------------------------

### Basic Authorization Check with Oso Cloud (Conceptual)

Source: https://www.osohq.com/docs/oss/ruby/guides

This conceptual example shows the simplified syntax for checking authorization across services using Oso Cloud. It assumes `user`, `action`, and `resource` objects are defined elsewhere.

```plaintext
oso.authorize(user, action, resource)
```

--------------------------------

### Define has_relation Hook Rule

Source: https://www.osohq.com/docs/oss/node/reference/polar/polar-syntax

An example 'hook' rule for relations. The 'has_relation' rule fetches relationship data from the application, linking declared relations (like 'parent') to actual data structures. It must be defined for every declared relation.

```polar
# Relation hook - required when using relations
has_relation(parent_org: Organization, "parent", repo: Repository) if
  # Look up parent-child relation from application, e.g.
  parent_org = repo.organization;

```

--------------------------------

### Oso Policy for Repository Access Control (Polar)

Source: https://www.osohq.com/docs/oss/getting-started/quickstart

This is an Oso policy file written in Polar syntax. It defines resource permissions, roles, and rules for an 'actor' (User) interacting with 'Repository' resources, including conditions for 'read' access based on repository public status.

```polar
actor User {}

resource Repository {
  permissions = ["read", "push", "delete"];
  roles = ["contributor", "maintainer", "admin"];

  "read" if "contributor";
  "push" if "maintainer";
  "delete" if "admin";

  "maintainer" if "admin";
  "contributor" if "maintainer";
}

# This rule tells Oso how to fetch roles for a repository
has_role(actor: User, role_name: String, repository: Repository) if
  role in actor.roles and
  role_name = role.name and
  repository = role.repository;

has_permission(_actor: User, "read", repository: Repository) if
  repository.is_public;

allow(actor, action, resource) if
  has_permission(actor, action, resource);
```

--------------------------------

### Define has_role Hook Rule

Source: https://www.osohq.com/docs/oss/node/reference/polar/polar-syntax

An example 'hook' rule required when using roles. This rule, 'has_role', connects the declared roles in resource blocks to actual user-role assignments stored in the application. It must handle all declared role names.

```polar
# User-role assignment hook - required when using roles
has_role(user: User, name: String, repo: Repository) if
  # Look up user-role assignments from application, e.g.
  role in user.roles and
  role.repo_id = repo.id;

```

--------------------------------

### Define Repository Shorthand Rules With Relations (Polar)

Source: https://www.osohq.com/docs/oss/ruby/reference/polar/polar-syntax

This example illustrates defining shorthand rules for a 'Repository' resource that leverage relations. It shows how roles like 'admin' and 'contributor' can be granted based on roles on a related resource, specifically the 'parent' Organization.

```polar
resource Repository {
  roles = ["contributor", "maintainer"];
  relations = { parent: Organization };

  "admin" if "owner" on "parent"  # "owner" role on parent Organization grants the "admin" role
  "contributor" if "member" on "parent"  # "member" role on parent Organization grants "contributor" role
}

```

--------------------------------

### Integrate Application Code with Oso REPL

Source: https://www.osohq.com/docs/oss/reference/tooling/repl

This Python snippet shows how to integrate application code with the Oso REPL. It involves importing necessary classes, initializing the Oso instance, registering application classes using `oso.register_class()`, loading policy files, and then starting the REPL using `oso.repl()`.

```python
from app import Expense, User

from oso import Oso

oso = Oso()
oso.register_class(Expense)
oso.register_class(User)
oso.load_files(["alice.polar"])
oso.repl()
```

--------------------------------

### Oso Policy for Repository Access Control (main.polar)

Source: https://www.osohq.com/docs/oss/java/getting-started/quickstart

Defines the authorization rules for accessing repositories. This policy specifies permissions, roles, and the logic for determining if an actor has permission to perform an action on a repository, including checking for public repositories.

```polar
actor User {}

resource Repository {
  permissions = ["read", "push", "delete"];
  roles = ["contributor", "maintainer", "admin"];

  "read" if "contributor";
  "push" if "maintainer";
  "delete" if "admin";

  "maintainer" if "admin";
  "contributor" if "maintainer";
}

# This rule tells Oso how to fetch roles for a repository
has_role(actor: User, role_name: String, repository: Repository) if
  role in actor.roles and
  role_name = role.name and
  repository = role.repository;

has_permission(_actor: User, "read", repository: Repository) if
  repository.isPublic;

allow(actor, action, resource) if
  has_permission(actor, action, resource);

```

--------------------------------

### Oso Policy for Request Path Authorization

Source: https://www.osohq.com/docs/oss/reference/frameworks/flask

This code snippet shows an example Oso policy that allows any actor to make a GET request to the root path "/". It utilizes the `Request` object type to specify the path attribute for authorization checks.

```go
# Allow any actor to make a GET request to "/".
allow(_actor, "GET", _resource: Request{path: "/"});

```
Tokens:
Raw