README.md
1# Oso
2
3[![Development][badge-ci]][badge-ci-link]
4[![GitHub release (latest SemVer)][badge-release]][badge-release-link]
5[![Go version][badge-go]][badge-go-link]
6[![Maven version][badge-java]][badge-java-link]
7[![NPM version][badge-nodejs]][badge-nodejs-link]
8[![PyPI version][badge-python]][badge-python-link]
9[![RubyGems version][badge-ruby]][badge-ruby-link]
10[![Crates.io version][badge-rust]][badge-rust-link]
11[![Slack][badge-slack]][badge-slack-link]
12
13## What is Oso?
14
15Oso is a batteries-included library for building authorization in your application.
16
17Oso gives you a mental model and an authorization system – a set of APIs built on top of a declarative policy language called Polar, plus a debugger and REPL – to define who can do what in your application. You can express common concepts from “users can see their own data” and role-based access control, to others like multi-tenancy, organizations and teams, hierarchies and relationships.
18
19Oso lets you offload the thinking of how to design authorization and build features fast, while keeping the flexibility to extend and customize as you see fit.
20
21Developers can typically write a working Oso policy in <5 minutes, add Oso to an app in <30 minutes, and use Oso to solve real authorization problems within a few hours. To get started, you add the library to your application, create a new Oso instance and load an Oso policy. You can mix and match any of Oso’s authorization APIs to implement features like roles with custom policies that you write to suit your application.
22
23Oso is ideal for building permissions into user-facing applications, but you
24can check out [Use Cases][use-cases] to learn about other applications for Oso.
25
26Oso currently offers libraries for [Node.js][badge-nodejs-link], [Python][badge-python-link], [Go][badge-go-link],
27[Rust][badge-rust-link], [Ruby][badge-ruby-link], and [Java][badge-java-link].
28
29## Getting started
30
31To get up and running with Oso, check out the [Getting Started
32guides](https://docs.osohq.com/getting-started/quickstart.html) in the [Oso
33documentation][docs].
34
35If you have questions, need help getting started, or want to discuss anything about the product, your use case, or authorization more generally, [join us on Slack][badge-slack-link].
36
37## Development
38
39### Core
40
41Oso's Rust [core][core] is developed against [Rust's latest stable
42release][rust].
43
44### Language libraries
45
46Oso's language libraries can be developed without touching the Rust core, but
47you will still need the Rust stable toolchain installed in order to build the
48core.
49
50To build the WebAssembly core for the Node.js library, you will need to have
51[`wasm-pack`][wasm-pack] installed and available on your system PATH.
52
53#### Language requirements
54
55To work on a language library, you will need to meet the following version
56requirements:
57
58- Java: 10+
59 - Maven: 3.6+
60- Node.js: 10.14.2+
61 - Yarn 1.22+
62- Python: 3.6+
63- Ruby: 2.4+
64 - Bundler 2.1.4+
65- Rust: 1.46+
66- Go: 1.12+
67
68## Contributing
69
70See: [CONTRIBUTING.md][contributing].
71
72## License
73
74See: [LICENSE][license].
75
76[badge-ci]: https://github.com/osohq/oso/workflows/Development/badge.svg
77[badge-ci-link]: https://github.com/osohq/oso/actions?query=branch%3Amain+workflow%3ADevelopment
78[badge-release]: https://img.shields.io/github/v/release/osohq/oso?color=005b96&logo=github&sort=semver
79[badge-release-link]: https://github.com/osohq/oso/releases
80[badge-slack]: https://img.shields.io/badge/slack-oso--oss-orange
81[badge-slack-link]: https://join-slack.osohq.com/
82[badge-go]: https://img.shields.io/github/v/tag/osohq/go-oso?color=7fd5ea&label=go.dev
83[badge-go-link]: https://pkg.go.dev/github.com/osohq/go-oso
84[badge-java]: https://img.shields.io/maven-central/v/com.osohq/oso
85[badge-java-link]: https://search.maven.org/artifact/com.osohq/oso
86[badge-nodejs]: https://badge.fury.io/js/oso.svg
87[badge-nodejs-link]: https://www.npmjs.com/package/oso
88[badge-python]: https://badge.fury.io/py/oso.svg
89[badge-python-link]: https://pypi.org/project/oso/
90[badge-ruby]: https://badge.fury.io/rb/oso-oso.svg
91[badge-ruby-link]: https://rubygems.org/gems/oso-oso
92[badge-rust]: https://img.shields.io/crates/v/oso
93[badge-rust-link]: https://crates.io/crates/oso
94[go-link]: https://pkg.go.dev/github.com/osohq/go-oso
95[contributing]: https://github.com/osohq/oso/blob/main/CONTRIBUTING.md
96[core]: https://github.com/osohq/oso/tree/main/polar-core
97[docs]: https://docs.osohq.com
98[license]: https://github.com/osohq/oso/blob/main/LICENSE
99[rust]: https://www.rust-lang.org/tools/install
100[use-cases]: https://docs.osohq.com/more/use-cases.html
101[wasm-pack]: https://rustwasm.github.io/wasm-pack/installer/
102
103## Share your story
104
105We'd love to hear about your use case and experience with Oso. Share your story on [Twitter](https://twitter.com/osoHQ) or fill out [this form](https://osohq.typeform.com/to/mIFfkN05) for some Oso swag.
106
