Repository navigation
decern 0.3.1: caller authentication, workload binding, and everything since 0.2.0 #136
anivar
announced in
Announcements
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
0.3.1 is out. Since it lands on crates.io alongside 0.3.0's work, which was tagged here but never reached the registry, this covers everything since 0.2.0: 56 commits across 91 files, 8–17 August.
The short version is that 0.2.0 could decide and record, but it could not tell you who was asking. Its server was two source files,
main.rsandchallenge.rs, and it had no notion of a caller at all — not even--trust-proxy, which did not exist yet. The kernel was proven and the ledger was tamper-evident, and anyone who could reach the port could ask anything about anyone. That is the gap this work closes.The server establishes its own callers
decern-servenow refuses to start unless it is told how callers are established, and naming a second one is also a startup failure rather than a precedence rule.--bearer-issuerat+jwtaccess token, EdDSA, issuer matched exactly, audience per RFC 8707--signed-agent-keycnfclaim--spiffe-trust-domain--trust-proxyEvery credential posture verifies against keys configured at startup. Nothing is fetched, so a decision never waits on a third party being reachable and the default build still carries no outbound TLS stack.
A warning is what a startup script discards. A refusal makes the operator write their posture down.
The server is split by layer now, one seam per file.
caller.rsholds theCallerAuthtrait and the single guard over the protected routes, and each posture implements that trait in its own module knowing nothing of the others. That arrangement is the reason a posture added later cannot skip a step by being wired in differently, and it is what stopped--trust-proxyfrom quietly bypassing checks the credential postures make.Proof of possession
Under
--signed-agent-keya leaked token is not enough on its own. The caller has to sign this request, now, with the key the token'scnfclaim binds it to. The covered components are@method,@authority,@pathandsignature-key; a POST addscontent-digest(RFC 9530).examples/signed-request/asserts each refusal end to end. The one to read is the replay with a wrong key: the token there is byte-identical to the one that just succeeded — samesub, sameaud, samecnf, unexpired. Only the signature differs, because the caller holds the token but not the private key it confirms. A bearer credential would accept that request.SPIFFE, and what it refuses
spiffe.rsverifies JWT-SVIDs against bundles read once at startup. The refusals are the interesting part:example.org.evilcannot present asexample.org.jkunaming an attacker-controlled key source is refused rather than ignored.kidis optional in the spec. With one bundle key that is unambiguous; with several the spec gives no rule, so the code refuses rather than guessing.nbfis gated, including a fractional value, and a non-numeric one is refused rather than skipped.sub. JWT-SVID mandates noiss, and a caller cannot name its own.ES256 only.
RS*andPS*need thersacrate, which carries RUSTSEC-2023-0071 — a timing side-channel that recovers the private key, with no patched version — and the supply-chain gate runs with no advisory exceptions. A SPIRE deployment issuing RSA SVIDs will not work here (#117).A workload may only speak for itself
Under a workload posture, an authenticated caller may only name itself as AuthZEN subject, mission approver, stored approver on terminate, and directory principal. A mismatch is
403 caller_mismatch.This closed something demonstrable rather than theoretical. Before it, a workload authenticating as
agent-1— an identity not present in the authority graph at all — could callPOST /mission/v1/approvenamingcorpas approver and mint itself a live grant formove_money. Attenuation held the whole time; the grant never exceeded whatcorpactually holds.corpsimply never asked for it. The ledger recorded the discrepancy faithfully and stopped nothing, which is the difference between an audit log and a control.Bearer and
--trust-proxyare deliberately exempt, because they authenticate a gateway, and a gateway asking about other parties is what AuthZEN is for. The corollary is the part people miss: a bearer token issued to a workload is a gateway credential and carries no bind at all. If your caller is a workload, give it a workload posture.--pepnames the workloads that really are gateways.Security
Most of these had a working exploit before they had a fix.
The signature did not cover the request body. Every guarded POST shares method, host and path, so one captured signature authorized any body at that endpoint inside the freshness window. A signature captured over a
Readwas replayed with aMoveMoneybody and reached the kernel. It was denied there, by the Mission requirement — a separate control that happened to catch it. The signature contributed nothing.A Mission was standing in for the data subject's consent. A live Mission covering
AccessPIIsetcontext.consent = true. But a Mission is an approver's grant ofpii:read, and consent is a claim about the resource owner. On a model isolating the gate:True ['P-pii']before,False ['F-consent']after. An agent could read another person's data on the strength of a grant that person never gave.MoveMoney could be approved by request body.
context.human_approved: truemoved money whenever--require-missionwas off. It now requires a live Mission unconditionally. Deployments that gated money by asserting that flag from their own PEP need to approve a Mission and name it incontext.missioninstead — this is the one change in this range that will break a working setup.The ledger and the signing key were world-readable. Both were created at the process umask, commonly
0644. The ledger holds decision subjects and the pseudonymous handles the open subject-audit route is keyed by. The key is now created at0600and refused if it is group- or other-readable; the ledger is created at0600and tightened when next opened, rather than refused, since failing an existing deployment's next append would be worse. Sealed segments moved from0444to0400.Also: Agent Badges used cofactorless
verifyon the one path that admits a principal into the authority graph, and now useverify_strictlike everything else. A remotely triggerable panic, where the403refusal echoed an attacker-chosen principal id bounded by bytes so a multi-byte character straddling the cut downed the request. And the documented Envoyext_authzsnippet forwarded a client-supplied subject header — the exact bypass its own README warns about.These are listed plainly rather than folded into "hardening" because the project's claim is that it is checkable, and a security section that reads as routine maintenance would be the first place to start lying.
Accountability on the record
Every decision under a credential posture now carries
asserted_by: the caller's subject, client and issuer exactly as the server verified them. A hardened deployment's log reads "the gateway asked about alice" rather than only "alice". It is absent under--trust-proxy, because an assertion the server did not verify itself does not belong on a permanent record, and it is never a decision input — the kernel does not see it. Mission approve and terminate records carry it too.A forged
context.asserted_byin a request body is stripped before recording, on every endpoint. There is a test that calls the mission path directly with one, even though no live route reaches it today, so a future change that makes it reachable does not silently lose the guarantee.Integrations
The worked examples are runnable and CI-tested, and none is published as a crate.
examples/mcp/is a Model Context Protocol server (revision 2026-07-28, no SDK) that validates its client's token and consults the PDP before every tool call, with the exact arguments digest-bound onto the record. A deny a fresh grant could satisfy is a403 insufficient_scopewhose challenge actually works on retry; a deny no re-authorization can fix is a tool result withisError, where the model can read it and stop. The client's token is never forwarded to decern, which MCP forbids. The authorization check is deliberately not itself a tool: a check the checked party can decline to call is not a check.examples/ext_authz_adapter/, contributed by @sameer-kireap, is a forward-auth shim for NGINXauth_request, TraefikforwardAuthand Envoyext_authz. It fails closed on deny, on an incomplete forward, and on an unreachable PDP.examples/signed-request/andexamples/spiffe/each run a workload posture end to end, minting their own credentials with fixed public keys — every reader holds the private keys, which is the loudest available way to say these prove nothing outside the example.SDKs
The Go, Python and TypeScript clients can present a bearer token, sent on every request when set and absent entirely when not. Failed calls carry the HTTP status and response body, capped at 64 KiB with truncation reported, so a denial is distinguishable from a misconfigured endpoint. Each carries source, homepage and issue tracker metadata; npm publishes with provenance. TypeScript requires Node 24, the active LTS and the only line tested. The Mission lifecycle is not exposed in any SDK yet (#64).
Documentation
Two files described the default binaries as carrying zero compiled-C-FFI dependencies.
cargo treedisagrees:cedar-policy→stacker→psmcompiles a small assembly routine viaccin every build, the default included. The claim that holds is no TLS stack, no OpenSSL and nocmake, which is what the README andDEPENDENCIES.mdalready said. An audit that foundpsmafter being told otherwise would be right to distrust everything else in the document.In the same pass: a sample record on the website carried no
asserted_bydirectly beneath a sentence claiming every record has one — it had been captured under--trust-proxy, which records none by design. The README's record showed"reasons":["F-money"]for an input that returns an emptyreasons. Both are now reproduced from live runs.--require-mission's help text claimed server-derived consent, which it never provided.AGENTS.mdgained the rules the gates cannot check: theCallerAuthseam a new posture must implement rather than route around, the context fields that must never reach the kernel, record-before-serve, and that a claim in the documentation is part of the product.What 0.3.1 adds on its own
The crates now publish to crates.io by OIDC, the same way the PyPI and npm packages already did. The registry mints a credential for the run and the job revokes it; trust is pinned per crate to this repository, the workflow filename and the
crates-ioenvironment. The 0.2.0 release stopped mid-publish on a token scopedpublish-new, which does not cover new versions of crates that already exist — valid enough to look configured, wrong enough to stop a release. A minted credential cannot drift out of scope because it does not outlive the run.Otherwise 0.3.1 is the documentation pass above. It alters no decision, ledger or caller-authentication behaviour.
Known limits
Unchanged from 0.3.0, and none of them a regression:
--require-mission, on-behalf-of access to personal data fails closed rather than becoming server-derived.decern verify --anchor, against a tree head published somewhere you do not control, is what detects a dropped tail; the append path loads no commitment, and--anchoris not available for--sharded.--trust-proxyis a complete PDP to anyone who can reach the port. It is a statement about your topology, not a mode. The quickstart uses it; the quickstart is not a production posture.typrequirement, nocritrefusal, nonbfgate, open header set. They cannot change a decision, but a forged one can write a false challenge answer onto the record.ReevaluateWithSubjectContextis a label, not a re-evaluation.entities.json, the clock, the HTTP layer, the Mission lifecycle, or caller binding.Open and known, beyond that list: a workload caller can still name mission reads and
decision_subjectfreely (#124); some caller-binding decisions shipped without explicit rationale, including that a workload cannot terminate its own Mission (#116); and there is no importer for an existing directory, so every deployment hand-authorsentities.json(#101).There are still no known production deployments. That is written down in
ADOPTERS.mdso the claim stays checkable rather than inferred from silence.Install
Clients:
uv add decern,npm install decern,go get github.com/anivar/decern/sdks/go.Release notes · CHANGELOG · Commands
Open work is labelled
help wanted, and ARCHITECTURE.md maps each area to the crate that owns it. Agent-written pull requests are welcome on the same terms as anyone else's, with a human sponsoring the DCO sign-off.Thanks to @sameer-kireap for the ext_authz adapter,
asserted_byon the Mission lifecycle records, and the adapter's supply-chain gate.All reactions