Themis
English · Português (Brasil)
An authorization library for Rust. A validated permission catalog and a decision engine that combines RBAC, ABAC and ReBAC over the same grants, with governance and auditing of changes, and real-time propagation of those changes all the way to the client.
The core does no IO, does not depend on an async runtime and compiles to WebAssembly. Real time, transports and bindings live in separate crates, each one optional.
Status: pre-1.0. The API can still change between minor versions. Releases are published as
themis-authon crates.io and on npm. The library keeps the namethemis:use themis::....
Crates
| Crate | What it is for | Notable dependencies |
|---|---|---|
themis-auth |
Catalog, decision engine, governance, auditing (audit feature, on by default), JSON spec |
serde, thiserror; sha2 and serde_json with audit |
themis-sync |
Change hub, Transport trait, framework-independent SSE/WebSocket sessions, capability cache |
tokio |
themis-redis |
Transport over Redis pub/sub |
redis |
themis-postgres |
Transport over Postgres LISTEN/NOTIFY, with the notice sent inside the transaction |
tokio-postgres |
themis-axum |
axum SSE and WebSocket routes over the themis-sync sessions |
axum |
themis-inspect |
Inspector: the trace of each decision, grant simulation, access matrix and audit trail reading. Optional gpui window (gui feature) and terminal commands |
gpui-pre, gpui-component |
themis-node |
JS bindings: native module (N-API) for Node and Bun, WebAssembly for the browser, real-time client and server in JS | napi or wasm-bindgen |
Depend on it from another crate:
[]
= { = "themis-auth", = "0.3" }
= "0.3"
Concepts
| Concept | Type | Role |
|---|---|---|
| Catalog | Catalog, PermissionDef |
Dotted keys (document.invoice.export), accepted targets, implied_by, free-form metadata (meta). Validated on construction: malformed key, duplicate, unregistered target, missing parent, cycle, and the application's own rules (CatalogRule). Exports and imports JSON. |
| Resource | Resource, Anchor |
Path from the most specific to the broadest (document:7 → doc_type:invoice → project:42 → org:9), with an implicit global at the end, plus attributes. |
| Subject | Subject |
Id, roles (optionally scoped), principals (authenticated, anonymous or your own), attributes. |
| Grant | Grant |
Subject (User, Role, Principal, Relation, Any), permission, target, effect, optional scope and condition. |
| Engine | Engine |
Overrides, collection of the applicable grants, combination by strategy. Returns a Decision with the reason, the matched grants and warnings. |
| Governance | Governance, Invariant |
Applies a grant change only if every invariant passes, and records the outcome in the audit trail. |
Usage
use *;
let catalog = builder
.target_kinds
.broad_target
.permission
.permission
.build?;
let engine = builder
.override_with
.build?;
let grants = vec!;
let dave = user.with_role_in;
let invoice = new
.within
.within
.within;
let decision = engine.decide;
assert!; // g2 sits on a more specific step than g1
The same configuration can come from JSON, TOML or YAML through EngineSpec (catalog, role inheritance, relations, strategy, overrides). EngineSpec::builder() returns the EngineBuilder so you can add in code what does not serialize, such as condition functions.
Examples: cargo run -p themis-auth --example documents (the three models together) and cargo run -p themis-axum --example server (real-time server).
How a decision is made
- Permission not in the catalog: deny (
Reason::UnknownPermission). - Overrides, in order. The first one that answers decides.
override_excepttakes permissions (and the ones they imply) out of an override's reach. - Collection: a grant is a candidate when its permission is the requested one or one that implies it, its scope is on the resource path, its target matches a step of the path, its subject matches and its condition is true.
- The strategy picks the deciding grant. With no candidate, deny.
A condition or relation that cannot be evaluated (missing attribute, engine without a TupleStore) never opens access: the allow is dropped and the deny is applied. The reason goes into Decision::warnings.
| Strategy | Rule |
|---|---|
MostSpecific (default) |
The most specific step with any grant decides; on that step, deny wins. |
DenyOverrides |
Any deny wins. |
PermitOverrides |
Any allow wins. |
FirstApplicable |
The first grant in source order decides. |
The three models
RBAC. RoleGraph::builder().inherit("maintainer", "member") gives maintainer the grants of member. Subject::with_role_in(role, anchor) limits the role to the resources under that step.
ABAC. Grant::when(condition) with a serializable Condition: eq, ne, lt, le, gt, ge, is_in, exists, all, any, not and call. Operands read subject.*, resource.* and env.*. Your own functions are added with ConditionRegistry::register and checked by Engine::validate_grant.
ReBAC. object#relation@subject tuples in a TupleStore and per-type rules in a RelationSchema (This, Computed, TupleToUserset, Union, Intersection, Exclusion), Zanzibar style. user:* stands for every user. A grant with SubjectMatcher::relation("editor") applies to whoever holds editor on the step matched by the target. The search has a maximum depth (max_relation_depth, 32 by default) and cuts cycles.
Governance
let governance = new
.with
.with
.with
.with
.with
.audited;
let next = governance.apply_with?;
// persist `next` only on Ok
Assigning or revoking a role goes through the same invariants and is audited as role_assign/role_revoke; the grant set comes back unchanged and the subject to persist comes from Mutation::subject_after.
let change = AssignRole ;
governance.apply_with?;
let bob = change.subject_after.expect; // persist bob's roles
Forbid applies to a role assignment only when it targets a user, and it ignores scope. The library does not stop an actor who holds the required permission from giving someone else a stronger role than their own; that rule belongs in an Invariant of your own.
Add your own rule by implementing Invariant. The list can also come from JSON (InvariantSpec).
Auditing
With the audit feature, every change that goes through governance becomes an AuditRecord, whether applied or refused. ReBAC tuples and role assignments are recorded with Auditor::tuple_change and Auditor::role_change. If the sink fails to write, governance refuses the change with the audit violation: no record, no change.
let auditor = new;
Built-in sinks: MemoryAuditLog and JsonLinesAudit (any io::Write). A database, queue or SIEM plugs in by implementing AuditSink.
Levels and storage
Each level includes everything from the previous one. Sizes come from the reference record (audit::reference_record): a grant with a scope and a two-clause condition, UUID ids, an actor with two roles and three request metadata entries. They are compact JSON bytes in JSON Lines, without compression or indexes. The estimates_match_reference_records test fails if the measured size drifts more than 10% from the documented one, and cargo run -p themis-auth --example audit_storage measures again.
| Level | What it keeps | Bytes per record | Per 1 million records |
|---|---|---|---|
minimal |
When, who, action, object id, outcome | 175 | 175 MB (167 MiB) |
standard |
Plus the grant summary (permission, subject, target, effect, scope, whether it has a condition) and the names of the invariants that refused | 388 | 388 MB (370 MiB) |
detailed |
Plus the whole grant with its condition, the full actor, the violation messages and the request metadata | 1,097 | 1.10 GB (1,046 MiB) |
forensic |
Plus the SHA-256 digest of the grant set before and after, and the hash chain between records | 1,415 | 1.42 GB (1,349 MiB) |
Access decisions can be audited too: Auditor::decide(&engine, &ctx, &request, &meta) decides and records, and at the forensic level it uses Engine::explain and keeps the full trace. Reference record: three grants in the source (one with a condition), a resource with three steps, UUID ids and three metadata entries (audit::reference_decision_record, test decision_estimates_match_reference_records).
| Level | What it keeps from a decision | Bytes per record | Per 1 million records |
|---|---|---|---|
minimal |
When, subject, permission@resource, allowed or denied |
285 | 285 MB (272 MiB) |
standard |
Plus the reason (override, deciding grant and step, or no grant) and the grants that matched | 669 | 669 MB (638 MiB) |
detailed |
Plus the full subject and resource, the warnings and the request metadata; enough to re-evaluate the decision later | 1,239 | 1.24 GB (1,182 MiB) |
forensic |
Plus the full trace (Explanation) and the hash chain |
3,582 | 3.58 GB (3,416 MiB) |
The forensic trace grows with the number of grants the source returns per decision. AuditLevel::estimate_decision_bytes(n) gives the projection in code.
AuditLevel::estimate_bytes(n) returns the same projection for changes. In a database, add the row overhead (in Postgres, about 28 bytes between the tuple header and the item pointer) and the indexes you create. Long conditions or large metadata grow detailed and forensic proportionally.
At the forensic level, each record carries the hash of the previous one. audit::verify_chain detects an edited or removed record. Auditor::resume_chain continues the chain after a restart.
Real time
grant change ──► Hub::publish ──► local sessions (SSE/WebSocket) and CapabilityCache
│
└─► Transport (Redis, Postgres, your own) ──► Hub on the other instances
The notice (Change) states the kind of change and the affected step, without the grants. Receivers reload from the source, so the notice fits any transport. A session watches scopes and, with a CapabilityProvider, pushes the capabilities of each affected scope back to the client. Changes that arrive together are recomputed once. When the transport drops and comes back, or a client falls behind, the hub emits Resync and everything is reloaded.
let hub = builder
.transport
.build;
let _relay = hub.spawn_relay;
let cache = new;
hub.on_change;
let provider = new.with_cache;
let realtime = new.with_provider;
// in the routes: realtime.sse(subject, scopes) or realtime.websocket(upgrade, subject, scopes)
Transports:
- Redis (
themis-redis): pub/sub, publishing with automatic reconnection. - Postgres (
themis-postgres):LISTEN/NOTIFY. Callingthemis_postgres::notify(&tx, channel, &change)inside the transaction that writes the grant makes the notice go out only on commit. TLS throughPgTransport::with_tls. - Your own: NATS, Kafka or any other broker implements
Transport(publishandsubscribe).
Client protocol (JSON, identical over SSE and WebSocket): the server sends hello, capabilities, change, resync, error and ping; the client sends watch, unwatch and refresh (WebSocket only). To use another HTTP framework, forward the stream from Session::open and write each message with ServerMessage::to_sse or to_json.
JavaScript: Node, Bun and the browser
Install with npm install themis-auth. The package lives in crates/themis-node/js. scripts/build.sh builds the native module (js/native/themis.<platform>-<arch>.node) and the WebAssembly (js/wasm/).
import from 'themis-auth';
const = await ; // native on Node/Bun, wasm in the browser
const engine = ; // the same EngineSpec as the server
const ctx = ;
engine.;
engine.;
On Node and Bun, load() tries the native module and falls back to wasm. THEMIS_BACKEND=native|wasm forces one of them.
Frontend. PermissionClient (/client) connects over SSE or WebSocket, keeps the capabilities of each scope and decides locally with the same engine. Client-side decisions are for the interface; the server still decides on every operation.
import from 'themis-auth/client';
const client = .;
client.;
client.;
JS backend (/server). Hub, openSession, sseResponse (Fetch API: Bun.serve, Hono, Deno), pipeSse (Node's http) and the redisTransport (node-redis and Bun's RedisClient), ioredisTransport and pgTransport (pg package) transports. Notices share the themis-sync format, so Rust and JS instances exchange changes over the same channel.
Binding limits: custom condition functions (call) and custom overrides exist only in Rust. The JSON spec covers the built-in overrides (resource_owner, permission_holder).
Inspector (themis-inspect)
An optional crate, outside the default-members: cargo build -p themis-inspect. The window uses gpui (gpui-pre =0.3.11 and gpui-component =0.9.0); without the gui feature (--no-default-features) you keep the library and the terminal commands.
The scenario is a JSON file with the policy (spec, the same EngineSpec), the data (grants, tuples, env) and the subjects and resources to examine, by name. There is an example in crates/themis-inspect/examples/scenario.json, with a forensic trail of six decisions in examples/audit.jsonl, generated by:
- Evaluation (
avaliacao): pick a subject, permission and resource and see the decision, the reason, the resource path with the deciding step, the effective roles, each override and the fate of each grant (candidate, unrelated permission, out of scope, target off the path, subject does not match, condition false or not evaluable), with the condition tree and the resolved values. It is built onEngine::explain, also available from Rust and JS. - Simulation: turn grants on and off (or add some with
--add) and see whether the set would allow the access. When the decision changes, the panel also shows the decision with the original grants. - Matrix (
matriz): every catalog permission for every subject on a resource, with the cells the simulation changed marked. Clicking a cell opens its trace. - Audit (
auditoria): reads the JSON Lines trail, checks the hash chain of theforensicrecords, shows the recorded trace and re-evaluatesdetailedorforensicdecisions against the current policy, pointing out the ones that would change.
Files are reloaded on their own when they change on disk. The window embeds the Noto Sans and JetBrains Mono fonts (OFL license, in crates/themis-inspect/assets/fonts) and its own icons, so it looks the same on any machine. The interface text is in Brazilian Portuguese.
Extension points
| Trait | For |
|---|---|
GrantSource |
Reading grants from a database, a cache or more than one source ((A, B) tuples chain). |
TupleStore |
Keeping ReBAC tuples outside memory. |
Override |
Owner, superadmin, suspended account, maintenance window. FnOverride takes a closure. |
Strategy |
Another combination rule. |
Invariant |
Another grant change rule. |
CatalogRule |
Your own catalog validation (RequireMeta, FnRule). |
AuditSink |
Where the audit trail goes. |
Transport |
The medium between instances for change notices. |
CapabilityProvider, GrantLoader |
How a session computes the capabilities it sends. |
ChangeSink |
A synchronous reaction to each change (cache, metric). |
Development
# transports against real servers (skipped without the variables)
THEMIS_REDIS_URL=redis://127.0.0.1:6379/ THEMIS_PG_URL=postgres://postgres:pw@127.0.0.1/postgres
# JS: build and tests on Node and Bun
&& && &&
The JS tests also accept THEMIS_RUST_SERVER (the URL of the themis-axum server example) to test the client against the Rust server.
The gpui window of themis-inspect needs the Wayland and X11 development libraries on Linux (for example libxkbcommon-dev, libwayland-dev, libxcb1-dev, libvulkan-dev).
Source comments and the inspector interface are in Brazilian Portuguese; issues and pull requests are welcome in English or Portuguese. See CONTRIBUTING.md.
License
MIT. The fonts embedded in themis-inspect are under the SIL Open Font License 1.1 (see crates/themis-inspect/assets/fonts).