If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/osohq/oso shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 30+ active contributors
• Distributed ownership (top contributor 21% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live osohq/oso repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/osohq/oso.

What it runs against: a local clone of osohq/oso — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in osohq/oso | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 465 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of osohq/oso. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/osohq/oso.git
#   cd oso
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of osohq/oso and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "osohq/oso(\\.git)?\\b" \\
  && ok "origin remote is osohq/oso" \\
  || miss "origin remote is not osohq/oso (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".github/workflows/test.yml" \\
  && ok ".github/workflows/test.yml" \\
  || miss "missing critical file: .github/workflows/test.yml"
test -f "polar-core" \\
  && ok "polar-core" \\
  || miss "missing critical file: polar-core"
test -f "docs/content/any/getting-started/deprecation.md" \\
  && ok "docs/content/any/getting-started/deprecation.md" \\
  || miss "missing critical file: docs/content/any/getting-started/deprecation.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 465 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~435d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/osohq/oso"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Oso is a deprecated but maintained authorization framework that lets developers model, test, and enforce access control policies across applications. It provides a declarative policy language called Polar, multi-language SDKs (Rust, Python, Node.js, Go, Ruby, Java), and collection filtering capabilities beyond simple yes/no permission checks. The core engine is written in Rust and compiled to WebAssembly and C FFI bindings for language interoperability. Monorepo organized with polar-core (Rust core engine) and language-specific bindings: languages/rust/oso for Rust, languages/python for Python FFI, languages/go, languages/ruby, languages/java, languages/typescript (inferred from language stats). The Polar language compiler (Rust) sits in polar-core/, and language implementations wrap it via FFI. docs/ contains full Hugo site with content organized by use case (docs/content/any/examples/gitclub.md shows RBAC example).

Backend engineers and platform teams building authorization systems who want to centralize access control logic instead of scattering it across application code. Specifically: Python/Django developers, Node.js teams, Go microservice architects, and Ruby on Rails apps that need RBAC, relationship-based access control, and policy testing without writing custom ACL layers.

Actively maintained but officially deprecated as of the README notice—the project is stable and used in production but no longer receiving new features; critical bug fixes and support continue. Strong CI/CD setup visible (.github/workflows/ has 20+ automated workflows including test.yml, publish.yml, audit.yml), multi-language test coverage, and version-pinned releases (VERSION file present). This is production-ready legacy software, not experimental.

Deprecation status is the primary risk—the team has announced plans for a next-generation release (Oso Cloud), so migration may eventually be necessary for teams relying on new features. The monorepo spans 6 language ecosystems (Rust, Python, TypeScript, Go, Ruby, Java) increasing maintenance surface area; single breaking Cargo.lock and Cargo.toml suggest coordinated mono-version releases. No visible SLA guarantees in LICENSE or SECURITY.md for critical patch timelines.

No active feature development—repository is in maintenance mode. Recent activity appears focused on CI/CD reliability (.github/workflows/audit.yml suggests security scanning), documentation updates, and language library patch releases (publish-django-release.yml, publish-flask-release.yml, publish-sqlalchemy-release.yml workflows indicate ongoing library version bumps). The deprecation notice suggests the team is focused on Oso Cloud rather than this open-source version.

git clone https://github.com/osohq/oso.git
cd oso
cargo build --release  # Core Rust engine
cd languages/python && pip install -e .  # Or pick your language
make test  # Run test suite (Makefile present)

Daily commands:

# Build Rust core
cargo build --release

# Python example
cd languages/python && python -m pytest tests/

# TypeScript/Node.js example
cd languages/javascript && npm test

# Run docs locally (Hugo)
cd docs && hugo serve

• Cargo.toml — Workspace root defining all Rust members (polar-core, polar-c-api, polar-wasm-api) and build profiles; essential for understanding project structure and dependencies
• README.md — Declares this library as deprecated and links to the official deprecation notice; every contributor must understand Oso's maintenance status before making changes
• .github/workflows/test.yml — Primary CI/CD pipeline for running tests across all language bindings; defines what must pass before merging
• polar-core — Root Rust library implementing the core Polar authorization engine; the heart of the entire framework
• docs/content/any/getting-started/deprecation.md — Official documentation of deprecation rationale and migration guidance; required reading for all new contributors
• VERSION — Single source of truth for the library version across all language bindings and release automation
• .github/workflows/publish.yml — Release automation that publishes to PyPI, npm, RubyGems, crates.io, and Maven; critical for understanding versioning and deployment

Add a new language binding (e.g., C#, PHP)

1. Create a new directory in languages/ for your language (e.g., languages/csharp/) (languages)
2. Implement FFI layer using polar-c-api as the C interface (polar-c-api)
3. Add a new release workflow in .github/workflows/ following the pattern of publish-python-release.yml (.github/workflows/publish-python-release.yml)
4. Register your language in the main publish.yml workflow to orchestrate multi-language releases (.github/workflows/publish.yml)

Extend the Polar policy language (new built-in predicate)

1. Add the predicate implementation in polar-core/src/ (e.g., new built-in function) (polar-core)
2. Update the language documentation in docs/content/any/guides/ with examples and semantics (docs/content/any/guides/_index.md)
3. Add test cases in polar-core/tests/ to ensure backward compatibility (polar-core)
4. Update the language server (polar-language-server) to provide IDE autocomplete and hints (polar-language-server)

Add a new framework integration guide (e.g., FastAPI, Django ORM)

1. Create a new markdown file in docs/content/any/guides/enforcement/ with integration steps (docs/content/any/guides/enforcement/_index.md)
2. Include language-specific variants (.python.md, .node.md) if needed, following the pattern of enforcement/_index.python.md (docs/content/any/guides/enforcement/_index.python.md)
3. Add a complete runnable example in docs/content/any/examples/ and link from the integration guide (docs/content/any/examples/_index.md)

Release a new version of Oso

1. Update the version in VERSION file (e.g., from 0.26.0 to 0.27.0) (VERSION)
2. Push to the main branch, which triggers the publish.yml workflow automatically (.github/workflows/publish.yml)
3. The workflow publishes to PyPI, npm, RubyGems, Crates.io, and Maven in parallel (.github/workflows/publish.yml)
4. Monitor GitHub Actions logs to confirm all language-specific releases succeeded (.github/workflows)

• Rust (polar-core) — High performance, memory safety, and ability to compile to C (via polar-c-api), WebAssembly, and native binaries; critical for a security-sensitive authorization engine
• C FFI (polar-c-api) — Language-agnostic interface layer allowing bindings for Python, JavaScript, Ruby, Go, Java, and other languages without rewriting the core engine
• WebAssembly (polar-wasm-api) — Enables browser-side policy evaluation and offline decision-making without network round-trips to a server
• Hugo (documentation) — Static site generation reduces hosting costs and supports multi-language content variants (e.g., Python, Node.js, Java examples)
• GitHub Actions — Native CI/CD tightly integrated with repository; enables parallel testing and publishing across 6+ languages and multiple package registries

• Single Rust core with language bindings via C FFI rather than reimplementing Polar in each language

  • Why: Avoids duplicating complex authorization logic and security vulnerabilities across implementations; easier to maintain consistency
  • Consequence: Binding languages must support C FFI or be implemented by third parties; adds complexity to deployment (distributing compiled binaries)

• Deprecated project maintained in maintenance mode rather than sunset entirely

  • Why: Avoids breaking existing production users; allows community to use Oso without forced migration
  • Consequence: Must maintain backward compatibility; newer features and optimizations are lower priority; may deter new adoption

• Multi-language support (6+ bindings) in a single monorepo

  • Why: Ensures consistency, single version number, and coordinated releases across all ecosystems
  • Consequence: Large test matrix; slow CI; requires expertise in many languages; each PR touches more code than language-specific libraries

• Policy defined in Polar DSL rather than inline code

  • Why: Separates authorization logic from application logic; allows non-engineers to audit rules; enables IDE support and validation
  • Consequence: Users must learn a new language; adds a parsing/interpretation layer at runtime (mitigated by caching)

• Real-time policy updates without application restart (policies are typically loaded once at startup)
• Distributed or federated authorization decisions across multiple Oso instances
• Fine-grained attribute-based access control (ABAC) with dynamic attributes from external services (manual integration required)
• Authentication or user identity management (Oso is authorization-only; authentication is the caller's responsibility)
• Data encryption at rest or in transit (Oso does not store sensitive data; transport security is the application's responsibility)

Language-specific version skew: Each language SDK can have different patch versions despite shared core—check languages/{lang}/Cargo.toml or setup.py for independent version numbers. Cargo.lock is committed: Rust builds are pinned; run cargo update carefully across the workspace or all language bindings may break. FFI stability: Changes to polar-c-api/src/lib.rs require coordinated updates in all language bindings—no backward compatibility guarantee stated. Polar syntax reserved words: The policy language has keywords (e.g., allow, forbid) that may conflict with application domain models; check polar-core/src/parser.rs for current list. WebAssembly build requires wasm-pack: TypeScript/browser usage needs explicit wasm-pack toolchain setup not documented in top-level README.

• Logic Programming & Prolog-like Semantics — Polar is a logic language inspired by Prolog; understanding unification, backtracking, and rule resolution is essential to writing correct authorization policies and debugging why 'allow' rules fire (or don't).
• Foreign Function Interface (FFI) — All non-Rust SDKs communicate with polar-core via C FFI (ctypes in Python, WASM in JavaScript, cgo in Go); understanding FFI marshaling and lifetime management is critical for debugging cross-language failures.
• Attribute-Based Access Control (ABAC) — Oso's policy language supports ABAC patterns (allow if resource.owner == actor and resource.is_public); this is more expressive than pure RBAC and requires understanding attribute evaluation in authorization rules.
• Relationship-Based Access Control (ReBAC) — Oso supports modeling relationships between users, roles, and resources (e.g., 'user is member of org'); critical for multi-tenant systems and hierarchical authorization.
• WebAssembly (WASM) Compilation & Runtime — polar-wasm-api compiles the Rust core to WASM for browser/JavaScript use; understanding WASM module boundaries, memory, and async FFI calls helps debug JavaScript SDK issues.
• Query Filtering / Collection Authorization — Oso's unique capability is filtering collections (SQL queries, ORM filters) based on policies, not just yes/no checks—requires understanding how policies compile to data layer filters.
• Monorepo Workspace Management (Cargo) — Cargo workspace in root Cargo.toml coordinates polar-core, polar-c-api, and language bindings; understanding shared dependencies and version pinning prevents release conflicts.

• casbin/casbin — RBAC/ABAC authorization library for Go, similar scope but language-specific; comparison point for authorization patterns
• authzed/spicedb — Relationship-based access control (like Oso's relationship patterns) but designed as a separate service; modern alternative approach to authorization
• ory/keto — Dedicated authorization service using zanzibar-style relationship tuples; ecosystem alternative if moving away from policy-language approach
• osohq/oso-examples — Official example applications (likely separate repo) showing Oso integration with real frameworks; companion learning resource
• osohq/oso-cloud — Successor SaaS product; the future direction the Oso team is steering toward after deprecating open-source library

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI workflow for Python framework integrations (Django, Flask, SQLAlchemy)

The repo has separate release workflows for Django, Flask, and SQLAlchemy (publish-django-release.yml, publish-flask-release.yml, publish-sqlalchemy-release.yml) but no unified test workflow that validates all three frameworks together before release. This creates risk of integration regressions. A new workflow should run the test suite against all three frameworks in matrix form.

• [ ] Create .github/workflows/test-python-frameworks.yml with matrix strategy for Django, Flask, SQLAlchemy versions
• [ ] Reference existing test.yml structure but extend to isolate framework-specific test suites
• [ ] Ensure workflow runs on PR to catch regressions before release workflows are triggered
• [ ] Update CONTRIBUTING.md to document the new pre-release validation process

Add missing language-specific README files for SDK packages

The Cargo.toml workspace lists multiple language implementations (languages/rust/oso, languages/rust/oso-derive) and there are release workflows for Go, Java, Node.js, Python, and Ruby, but the file structure shows no README files for non-Rust language directories. Contributors need clear guidance on building/testing language-specific packages.

• [ ] Create README.md files in languages/go/, languages/java/, languages/nodejs/, languages/python/, languages/ruby/ directories (if they exist)
• [ ] Include setup instructions, build commands, test commands, and contribution guidelines specific to each language
• [ ] Cross-link to root CONTRIBUTING.md and point to language-specific CI workflows
• [ ] Verify directory structure by examining .gitmodules for submodule paths

Create documentation index for getting-started guides across content hierarchy

The docs/content structure shows deeply nested getting-started folders (docs/content/any/getting-started/application with multiple subdirectories for enforce, filter-data, model) but there's no visible index or navigation file tying these together. New users will struggle to understand the learning path.

• [ ] Add docs/content/any/getting-started/_index.md with a structured learning pathway that links to enforce, filter-data, and model subsections
• [ ] Add section headers in docs/config.toml (or equivalent Hugo configuration) to properly configure the menu structure for the getting-started hierarchy
• [ ] Add breadcrumb navigation hints in the archetypes/default.md template for consistent navigation across all tutorial pages
• [ ] Verify the generated docs site renders the hierarchy correctly by checking docs/README.md build instructions

• Add integration tests for polar-wasm-api (languages/typescript/src/wasm.ts) to verify that authorization policies work identically in WebAssembly vs. native FFI—no test parity visible in the repo.
• Write end-to-end examples for the three Django/Flask/SQLAlchemy integrations in docs/content/any/examples/ showing complete model definitions + policy files + test cases (currently only gitclub.md visible).
• Audit and document the C API stability guarantees in polar-c-api/src/lib.rs; add version-gating comments for breaking changes so language maintainers know which Oso core versions support their FFI calls.

The Oso codebase has a moderate security posture. The primary concern is that the project is deprecated, which may lead to slower security updates and reduced maintenance activity. The security disclosure policy is clearly documented with a responsible vulnerability reporting mechanism (security@osohq.com). No obvious hardcoded secrets, injection vulnerabilities, or critical misconfigurations were identified in the provided file structure and configuration. The multi-language support (Rust, Python, Java, Go, Node.js, Ruby) and active CI/CD pipelines indicate previous good security practices, but current maintenance levels should be verified before deploying in production environments requiring high security assurance.

• Medium · Deprecated Project with Ongoing Maintenance — README.md, docs/content/any/getting-started/deprecation.md. The repository is marked as deprecated in the README, indicating that this is legacy software. While the maintainers state they will provide support and critical bug fixes, being on a deprecated codebase increases security risk due to reduced development activity and potential for delayed security patches compared to actively maintained projects. Fix: Consider migrating to the next open source release when available. If continued use is necessary, establish a regular security audit schedule and monitor for critical updates from the maintainers.
• Low · Workspace Excluded Directories — Cargo.toml. The Cargo.toml file excludes 'docs/examples/quickstart/rust' from the workspace. While this is a common practice, excluded directories may not receive the same level of dependency management and security updates as the main workspace. Fix: Verify that excluded example directories do not contain production code or dependencies that need security updates. Document why exclusions are necessary.
• Low · Environment Configuration File Template Present — docs/.env.sample, .gitignore. A .env.sample file exists in the docs directory (docs/.env.sample). While this is a template file and should not contain secrets, it indicates that environment-based configuration is used. The actual .env file should be properly excluded from version control. Fix: Ensure .env, .env.local, and similar files are in .gitignore. Verify that no actual .env files with credentials are committed to the repository. Document required environment variables in .env.sample only.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.