grantr 0.1.0

grantr is the identity and access package for artifactr, reflexr and portalr: tenants, their members, groups, roles and service principals, and the grants that bind them to tenants, workspaces, threads, artifacts and rules. The libraries ask it, through their own hooks, before every command and read. It imports neither library, and neither imports it.

Status: v0.1's scope is built: the model, built-in and custom roles, groups, service principals and keys, checks, the libraries' hooks, restricted threads and artifacts, the audit log, in-memory and SQL storage with row-level security (the sql, sqlite and postgres extras), the admin router (the fastapi extra) and telemetry. stackr's template wires it in by default, so each library asks it before every command and read.

Why

Before grantr, any user of a tenant could do anything in every workspace of that tenant. The libraries' authorize hook was asked when a workspace was opened, and never heard what the actor was about to do, so a viewer couldn't be kept from editing. A user had exactly one tenant, set in their token, and nothing stored members, groups or roles. lattice RFC-0001 designs access once, for every surface, and grantr is where its model is built.

What it does

• Check every command and read. The libraries' hook hears the action, such as artifactr:edit_artifact, and asks grantr before each command and read, on every surface (ADR-0001).
• Grant down to threads and artifacts, and hide a restricted one from everyone without a role on it (ADR-0002, ADR-0003).
• Act for a user. An agent's turn is checked as the person whose message started it (ADR-0004).
• Own membership. A user's tenants come from grantr, and each request names its tenant (ADR-0005).
• Built-in and custom roles, groups and service principals, with keys shown once, and checks that deny by default (ADR-0006).
• An append-only audit log of every change to access (ADR-0007).
• Its own model, with OpenFGA-shaped ports, in memory or in SQL (ADR-0008), and a deployment-wide operator role (ADR-0009).
• Row-level security under the libraries' scoping, with PostgreSQL keeping each tenant's rows to that tenant (ADR-0026).

Quick start

from artifactr.workspace import ACTIONS as ARTIFACTR
from grantr import Grants, InMemoryStorage, Resource, User

grants = Grants(InMemoryStorage(), catalogs=[ARTIFACTR])
await grants.first_operator("root")
await grants.create_tenant("acme", owner="alice", by=User(id="root"))
await grants.add_member("acme", User(id="bob"), by=User(id="alice"))
main = Resource(kind="workspace", workspace="main")
await grants.grant("acme", "editor", on=main, to=User(id="bob"), by=User(id="alice"))
assert await grants.check("acme", User(id="bob"), "artifactr:edit_artifact", main)

Getting started goes on to the libraries' hooks, SQL storage and the admin API.

Documentation

grantr's documentation is its section of lattice's site, at https://lattice.alexnodeland.com/grantr/, built from docs/grantr/.

• Getting started, and the guides: roles and grants, restricted threads and artifacts, service principals and keys, row-level security, and the permission matrix.
• Architecture: the model, the checks, the commands and the storage port.
• Architecture decision records: why each part is the way it is.
• RFCs: the v0.1 plan, its phases and what each waits on.
• Identity and access, lattice's RFC-0001: the design grantr builds.
• Brand: the mark and its colours.

Contributing

See CONTRIBUTING.md for setup, the trunk-based workflow, and the RFC and ADR process.

License

MIT