decern decern

Authorization kernel · Rust


decern

Authorization you can prove and contest.

Software now decides, at machine speed, what agents and people are allowed to do: move this money, read this file, act for this account. decern is the decision point that answers those questions and proves it did so safely. It checks its safety rules hold for every possible request, keeps a tamper-evident record of every decision, and lets the party a decision was about see it and challenge it.

Read the code on GitHub Try it on your machine Where the work is

Protocol explorer


How decern establishes a caller, step by step.

decern will not start until the deployment names how its callers are established. The five postures differ in how the caller is proven, and that decides whom it may name and what the record says. From the kernel on, every request takes the same path: the solver-proven kernel, the recorded decision, the fail-closed serve. Pick a posture and step through it, or play it.

Choose how the caller is established

    All five, side by side

    Where each posture's traffic goes, without stepping through it.

    What the caller presents, where that credential came from, what decern checks it against, and what decern calls while it answers. From the kernel on, the path is the same for all five.

    The problem


    Writing permissions down is standardised. Guaranteeing they hold is not.

    Tokens and delegation formats settle how permission is described. Whether it holds is left to whoever builds the system: that passed-on authority can only get narrower, that a dropped record can be caught, that an answer stayed inside its mandate.

    decern is the guarantee. People, AI agents and services are one kind of principal here, answered by the same proven function.

    What it does


    What happens to a request, and what you can check afterwards.

    01 · The rules

    A solver checks every input the model allows

    An answer depends only on the request (who asks, for what, with what context), the authority graph, the policy and the time. Because it is that contained, cvc5 can search the model's symbolic input space for one that breaks a rule. The rules are checked this way, over the policy rather than the running server. A pass means it found none.


    decern-proof · runs in decern prove and CI only, never on the request path

    02 · The record

    A log you can check yourself

    Each answer is added to the end of the log, signed, and linked to the one before it. The signature shows a record is genuine and the links show the log holds together; whoever holds the key could still rewrite it, so a tree head kept out of the operator's reach is what shows nothing up to it was dropped or changed. A log torn by a crash repairs itself. You check the file yourself, offline.


    decern-ledger · Merkle · JCS canonicalisation · anchors

    03 · The caller

    It will not start until it knows how callers are established

    Before evaluating anything, decern-serve establishes who is asking — a bearer token, a signed request, a SPIFFE identity, an AAuth agent token, or a declared authenticated front taking responsibility for what it asserts. There is no default identity, and no way to start the server without naming one. The three workload postures go further: unless exempted, such a caller may only name itself. The verified caller is written onto the decision record itself, not inferred afterwards.


    decern-server · five caller postures · asserted_by under any credential posture

    Answerable by design


    Every decision is answerable to the party it lands on.

    Authored in the open standards bodies and implemented here, the three profiles below make a decision legible to the party it was about.

    Who it is about

    Decision subject

    The party a decision is taken upon, as a pseudonymous handle. Distinct from who asked and who answers, recorded and never deciding.


    draft-aravind-oauth-decision-subject ↗

    IETF OAuth

    How it is contested

    Subject-side challenge

    The party a decision was about can contest it, answered on the record, without touching the decision.


    S-ARAP ↗

    OpenID AuthZEN

    All three are being standardized now, in the IETF and the OpenID AuthZEN Working Group. decern implements them today.

    Where the work is


    The work is tracked in the open, issue by issue.

    None of the next line exists yet; every step of it is an open issue. The direction, in the roadmap's words: decern turns an authorization decision into a receipt. The decision is recorded before it is answered, the receipt comes back with the answer, and anyone who holds it can check it offline against the log's public key. A resource can refuse to act without one.

    A small proxy is to sit between an enforcement point and the decision point it already uses, speak AuthZEN on both sides, record each decision and return it with the receipt. It enforces nothing. Cedar stays built in.

    0 Spikes Each risky assumption is proven or broken before the format is written.
    1 Release Released from a tag whose release-candidate run passed.
    2 First slice On a clean machine, the proxy in front of an AuthZEN decision point returns a receipt that verifies offline, in under five minutes.
    3 Cedar on the new log The built-in model decides through the new crates and a receipt verifies in a browser.
    4 Facts and grants The new line holds no state outside the log, and the approval rule is proven.
    5 Proofs, replay, first use A recorded decision replays against its policy, and one outside party has run the quickstart.
    6 Remove the old line main holds the new crates only.

    Each row is a phase and the gate it has to pass, in order, with no dates. The steps of a later phase can change when an earlier gate teaches something. If no outside issue, pull request or adopter has appeared by the gate of phase 5, the work stops at the format, its test vectors and the drafts, and phase 6 does not run.

    How to contribute

    New contributors are welcome, and not only for code: a review, a doc fix, or running the quickstart and filing what broke all help. The roadmap is cut into milestone issues; pick one, or open a pull request straight away for a small, obvious fix. For anything that changes the design, open an issue first — a short conversation saves a wasted PR. People and agents contribute on the same terms: agents start at AGENTS.md, and a person signs off the DCO. A vulnerability is reported privately, as SECURITY.md asks, never as a public issue.

    The one gate

    build · test · cvc5 proofs
    clippy · fmt · cargo-deny
    standards guard


    Every change goes through ./scripts/verify.sh. Run it before you open a pull request.

    Rules


    Every rule is checked across the model's whole symbolic input space.

    Each line is the rule in brief; decern prove prints the exact statement, trusted base included.

    01 money-gate No MoveMoney allow unless the context carries human_approved.
    02 isolation No allow ever crosses a tenant boundary.
    03 decay No allow once authority has expired.
    04 attenuation-edge No access without ownership, a delegation ancestor, or an explicit grant.
    05 scope-gate Bounded actions require their named scope.
    06 revocation-gate A revoked principal is allowed nothing.
    07 residency-gate Residency-labelled resources need matching clearance.
    08 role-gate Role-required resources need the role.
    09 consent-gate Non-owned PII needs the context to carry consent.

    Negative controls

    Every rule also ships with its opposite: a test that takes the guarantee out of the policy and insists cvc5 does find a counterexample. If that test ever passed quietly, the proof was proving nothing.

    What it does not prove

    cvc5 proves the kernel's rules. It cannot tell whether your policy says what you meant, and it is never a claim that a deployment is secure — the deciding endpoints validate EdDSA-signed RFC 9068 bearer tokens, signed requests, SPIFFE identities or AAuth agent tokens when configured, or run behind a declared authenticating front; the server refuses to start with none stated. Where a rule leans on a derived value, that part is ordinary tested Rust and is written up as such. The full boundary lives in the repository, under known limits in this release ↗.

    One request, start to finish


    What a request goes through.

    The answer is handed back only after its record is safely written. If it cannot be recorded you get 503 — never a bare allow.

    01

    Ask

    A request arrives at decern-serve, and the caller is established first — bearer, signed request, SPIFFE, AAuth, or a declared front.

    02

    Evaluate

    The proven kernel answers, using the authority graph. The clock comes from the server, never the request.

    03

    Record

    The answer, plus who is accountable for it, is appended and signed.

    04

    Serve or 503

    Sent back only if that record was written. Otherwise refused.

    05

    Verify

    Anyone can re-check the links and signatures later, offline — and, with --anchor and a tree head kept out of the operator's reach, that nothing up to it was dropped.

    Who is answerable


    A record names an accountable owner: the top of the asker's delegation chain, worked out by the server from its own directory — never taken from the request. A stand-in's record names whoever is finally answerable for it; a top-level principal vouches for itself; a caller the directory does not know gets none.

    When the caller was established from a verified token, the record also names who asserted the request — the subject and client the server verified, and the issuer where it checked one's signature; a signed request's record names none. That is a separate field from the accountable owner above: one says who is answerable, the other says who spoke.

    Both are there for accountability, not as a gate. Neither ever changes the answer.

    The ledger


    What a tampered log looks like.

    Three decisions from one run of the built binaries. Alter record 1 to see what decern verify reports.

    /tmp/decern.jsonl
    Seq Decision Recorded Prev Chain
    0 allow corp · Read · claim1 0000…0000 intact
    1 deny corpB · Read · claim1 cc46…0efd intact
    1 allow corpB · Read · claim1 cc46…0efd mismatch
    2 deny corp · Read · claim2 d65c…38ed intact not reached

    $ decern verify --ledger /tmp/decern.jsonl --pubkey 09846b62…2cfe OK 3 entries root: e9bdceac…4d1e signatures: verified signer: 09846b62…2cfe from seq 0

    $ decern verify --ledger /tmp/decern.jsonl --pubkey 09846b62…2cfe error: TAMPER at seq 1: entry altered (hash mismatch) $ echo $? 1

    Drawn in the browser from one real run: three decisions under --trust-proxy, then the decision in record 1 edited by hand. Hashes are abbreviated; the output lines are what the binary printed. examples/quickstart.sh runs the whole loop: prove, serve, decide, verify, and tamper-is-rejected.

    An actual record seq 0 · Ed25519-signed · hash-chained · from the same run
    {
      "entry": {
        "seq": 0, "ts_ms": 1795054470000,
        "subject_type": "Principal", "subject_id": "corp",
        "action": "Read",
        "resource_type": "Resource", "resource_id": "claim1",
        "context": { "now": 1795054470 },
        "decision": true, "reasons": ["P-read"],
        "sponsor": { "kind": "Principal", "id": "corp" },
        "digests": {"authority": "9f445dc745481b5f486658a61ec1e9dd93fd0d3c78291616efa7aec812934170",
                    "parameters": "d75b260458777659c8c5cb33db67b4f5d60666d9c4772b499b8236f252157d85"}
      },
      "prev":    "0000000000000000000000000000000000000000000000000000000000000000",
      "hash":    "cc4675bc0b5fdd5ade53dbde53b0b39e6eac18d4dde2332bbc94a19984d20efd",
      "sig_b64": "lCU0FYd8ImEHTe0xq3rNMMgy4p/xZTUdzThNqKFfe8AFSPJXFo09NxDH8gosyPcN8wU68ovOOBf5od/Kb8FJBg==",
      "kid":     "09846b62c033010ececb3c8528fdce51d5bb207cbc765ee2f1e0b72852562cfe"
    }

    $ decern verify --ledger /tmp/decern.jsonl --pubkey 09846b62c033010ececb3c8528fdce51d5bb207cbc765ee2f1e0b72852562cfe OK 3 entries root: e9bdceac65499df53f4533f6472f1d1d9ca5300079f4a50559f40cb96ebf4d1e signatures: verified signer: 09846b62c033010ececb3c8528fdce51d5bb207cbc765ee2f1e0b72852562cfe from seq 0

    Subject-side


    The subject named in a record can ask what was decided about them, and each record comes with a proof that it is in the tree head signed with the answer: proof it was recorded, not that nothing about them was left out. GET /audit/v1/subject projects up to 256 decisions whose subject is the given handle straight from the ledger; GET /.well-known/decern-subject-side-disclosure states, in one document, what a subject can ask for and how. Neither route changes an answer — they make the record legible to the one it was about. The audit route asks for no credential and reads the whole ledger for every answer, and GET /anchor/v1/tree-head reads it each time it recomputes, so both cost more as the ledger grows: rate-limit them at whatever fronts the server. Under --sharded both answer 501.

    Missions


    An approver grants an agent named scopes and a deadline, never wider than the approver's own authority.

    A principal the model marks Human hands an agent a narrow slice of its authority: named scopes, a deadline. Ask for a scope the approver does not hold, a deadline past their own, an agent outside their tenant, an approver that is not marked Human or that is the agent itself, and the Mission is refused — with nothing recorded.

    Every accepted step is written to the same log before it is reported as done, and a Mission that has ended never comes back on the host that ended it. Its reference is derived from the approval itself, so re-approving an identical dead grant is refused — a new one has to differ in at least one field.

    Registry is durable and local — --missions <PATH>, default decern-missions.json beside the ledger. Consulted in-perimeter, no phone-home; under a multi-host ledger each host keeps its own.

    Mission lifecycle

    POST /mission/v1/approve
    {approver, agent, description, approved_tools, capabilities?, expiry}
    → {approver, s256, reference}
    GET /mission/v1/{s256}
    → {reference, state: active | terminated, expiry}
    POST /mission/v1/{s256}/terminate
    → {reference, state: terminated}

    What it is made of


    Built from small, auditable crates.

    The default build pulls no TLS stack, OpenSSL or cmake — though cedar's stacker/psm compiles one small assembly routine via cc. The Postgres head store adds a TLS provider, so it sits behind --features postgres, and is off by default.

    decern architecture: decern and decern-serve (five postures) over the kernel, identity, proof, ledger, store, and crypto crates
    Crate topology, as shipped in the repository.
    decern-kernel lib The deterministic decision function — Cedar authority graph, the directory, the check itself. The security core.
    decern-proof lib The SMT harness — compiles the Cedar model symbolically and discharges the nine invariants with cvc5, each with a negative control.
    decern-ledger lib The tamper-evident record — append-only, Ed25519-signed, hash-chained; Merkle, JCS canonicalisation, anchors, single-file and sharded.
    decern-store lib Persistence traits and reference implementations — the single-host file head store and the durable Mission registry.
    decern-store-postgres lib · opt Multi-host head store over Postgres advisory locks — the same trait, behind a feature flag the release binaries are built without.
    decern-identity lib The Mission core — approval-backed, fail-closed-attenuated authority.
    decern-crypto lib Ed25519 and SHA-256 primitives shared by the ledger and identity.
    decern-cli bin Builds the decern binary: prove · decide · explain · verify.
    decern-server bin Builds the decern-serve binary: the fail-closed PDP that evaluates, records and serves, plus the Mission lifecycle over decern-identity.

    HTTP surface

    POST /access/v1/evaluation
    POST /decide (alias)
    POST /access/v1/evaluations
    POST /access/v1/search/{subject,resource,action}
    GET  /.well-known/authzen-configuration
    POST /mission/v1/approve · GET · terminate
    GET  /anchor/v1/tree-head
    GET  /audit/v1/subject
    GET  /directory/v1/…/descendants
    GET  /.well-known/decern-subject-side-disclosure
    GET  /pubkey · /healthz

    Request {subject, action:{name}, resource, context}; response {decision}, with reasons or errors under context.

    Clients

    Go, Python and TypeScript SDKs ship in the repository, written against the AuthZEN surface. New SDKs and enforcement adapters are the easiest way in: mirror an existing client, or put a thin gateway in front of the server.


    crates/decern-kernel/model/ holds the Cedar policy, schema and entities the kernel loads.

    Start


    Try it on your machine.

    Two binaries: decern to prove and verify, decern-serve to answer requests. You only need cvc5 on PATH for the proofs — not to serve answers.

    Prebuilt binaries

    Prebuilt, signed binaries for Linux (x64/arm64), macOS (Apple Silicon) and Windows (x64) are on the releases page. Each one carries a Sigstore bundle; how to check a signature is in SECURITY.md. Name them decern and decern-serve and put them on your PATH.

    Releases ↗

    From source

    cargo install decern-cli decern-server

    Or clone and build with the pinned toolchain from rust-toolchain.toml.

    # 1 · prove every invariant over the model's input space (cvc5)
    decern prove
    # 2 · run the PDP (writes a tamper-evident ledger); this walkthrough is its own caller.
    #    --key keeps the signing key: without it a restart refuses the ledger it already wrote.
    decern-serve --ledger /tmp/decern.jsonl --key /tmp/decern.key --trust-proxy &
    # 3 · decide over HTTP (AuthZEN-shaped) — corp reads a claim it owns
    curl -s localhost:8080/access/v1/evaluation -H 'content-type: application/json' -d '{
      "subject":  {"type":"Principal","id":"corp"},
      "action":   {"name":"Read"},
      "resource": {"type":"Resource","id":"claim1"}
    }'
    # 4 · verify the ledger (hash chain + every signature)
    decern verify --ledger /tmp/decern.jsonl \
      --pubkey "$(curl -s localhost:8080/pubkey | jq -r .kid)"

    Sovereign · one process

    --ledger <PATH>

    One ledger file. Binds loopback by default; starting requires the caller posture to be named — bearer, signed request, SPIFFE, AAuth, or a declared front.

    Hosted · one host

    --sharded <DIR>

    Several server processes share one ledger, one hash chain per tenant, coordinated by a file lock.

    Hosted · many hosts

    --sharded postgres://…

    Advisory-lock head store for replicas across hosts. Build with --features postgres; a URL to another host must carry sslmode=require, and the URL is never logged.

    --ledger and --sharded are mutually exclusive, and --sharded requires --key, the key every replica signs with, a postgres:// URL also --missions-per-host, and --retired-key names each key it replaced. Audit a directory store with decern verify --sharded <dir> --pubkey <kid>, with --pubkey once per key GET /pubkey lists under keys — it checks every shard and exits non-zero if any fails; a Postgres head store has no decern verify path. A start, and that verify, read each shard's whole history under the shard's lock, so an append to it waits until the read ends.

    Integrations & clients

    Five worked examples ship in the repository, all runnable and CI-tested and none published as crates: examples/mcp consults decern before every tool call, examples/ext_authz_adapter puts it behind NGINX, Traefik or Envoy, and signed-request, spiffe and aauth each run a workload posture end to end. Thin AuthZEN 1.0 clients are published for applications: uv add decern (Python), npm install decern (TypeScript) and go get github.com/anivar/decern/sdks/go (Go).

    Who runs this


    Maintained in the open.

    What is next

    The next line returns a signed receipt with every decision: a record anyone holding it can check offline, from a recorder that sits in front of any AuthZEN decision point, with Cedar built in as the engine whose decisions can be replayed and proven. None of it exists yet; the roadmap is the plan. Enforcement, OAuth, vendor credentials and approval UX stay outside.

    ROADMAP.md

    Maintained by

    Anivar A. Aravind

    Anivar A. Aravind

    anivar.net ↗

    I maintain decern alone, in the open. If you read the code or the proofs and something is wrong, open an issue. A vulnerability is reported privately, through the repository's Security tab, as SECURITY.md asks; never as a public issue.

    Review and merge rules are written down in GOVERNANCE.md.

    Contributors

    Beyond the maintainer, code has come from: