A message arrives with a valid signature. Somewhere downstream, that gets treated as “this is allowed” instead of what it actually says — “this is from someone.” Software does this constantly, quietly, by default. signedwrite is a small Python package built so that gap between identity and permission is a structural fact, not something a developer has to remember to enforce under pressure.
It comes out of a piece of infrastructure doctrine I wrote after watching two agent systems share a router and let one system’s restart quietly become an outage for the other: “you can’t guard a boundary you won’t admit exists.” A signature check that lets “I can prove who I am” become “therefore I may do this” is the same shape of failure, one layer down.
Four laws, four modules
The whole package is built so that identity and authorization are never one module’s problem.
A signature identifies. It never authorizes. verify_write tells you exactly one thing — which registered identity produced this exact content. That’s identity.py and writes.py’s entire job. Neither has an opinion about permission. Asking one is a type error, not bad practice.
Permission is a separate object, minted only by the Owner. A Capability is signed by a declared Owner, for one (writer, action_class, expiry) triple. There’s no authorize_on_behalf_of anywhere — not hidden, not deprecated, never implemented. If a design needs delegated permission, that need gets solved outside this trust model, on purpose.
A relayed write carries no permission. relay() forwards a write’s identity — the signature still verifies — and strips everything that looked like permission, marking provenance="relayed" so the log refuses it with a precise reason:
shaurya@sps ~ % python
>>> forwarded = relay(irreversible)
>>> log.append(forwarded)
AuthorizationError: provenance='relayed' — a relay proves who first said
something. It has never been able to say what they were allowed to do.
Nothing is ever deleted. AppendOnlyLog has no delete. retract() appends a new write pointing at the one it supersedes. history() shows everything, retractions included. head() resolves retractions at read time. The audit trail grows; it never edits itself.
Three tiers of “how much permission”
Every Write declares an ActionClass, and the log holds a different bar for each. Class A — free, reversible — needs only a valid signature. Class B — needs review — needs a live, non-expired Capability naming this exact handle and class; a "reviewed": true field sitting in the payload is never treated as one. Class C — irreversible — needs a LiveOwnerSignature: the Owner, present, signing this exact write’s content hash, inside a window measured in seconds, consumed exactly once. A Capability is never accepted at Class C, however fresh — the whole safety property there is “an Owner looked at this just now,” not “an Owner once handed out a token a replay could spend later.”
shaurya@sps ~ % python examples/task_board.py
runs three simulated sessions through all three classes, including the refused forwarded Class-C request with its exact reason printed, and prints the full audit trail at the end.
The crypto backend picks the best available Ed25519 implementation at import time — cryptography preferred, then PyNaCl, then a vendored pure-Python fallback so the package still runs with neither compiled library present. All three produce the same key and signature shapes, so a keypair signed under one verifies under another.
What it can’t do yet
- No capability revocation. A
Capabilityonly ever ends by expiry. If an Owner mints a 30-minute one and changes their mind at minute five, there’s norevoke()— this prototype can’t shorten that window early. - Wall-clock trust. Class B expiry and Class C’s live-signature window both trust the process’s local clock. No monotonic-clock hardening, no NTP skew handling. Fine on one trusted machine; not fine across an adversarial network.
- The identity registry is in-memory only. Prefix-freedom and the active-handle set live in a plain Python object, not persisted like the log is. A real deployment needs that durable too.
- Single-writer-process SQLite. The storage layer hasn’t been exercised under concurrent multi-process writers — no WAL tuning, no busy-timeout configuration. Fine for tests and the demo; needs real concurrency work before production.
- The pure-Python Ed25519 fallback isn’t constant-time. It exists so the package installs everywhere, not as a substitute for a real crypto library’s side-channel hardening.
- Retraction authority is coarse. Only a write’s original author or a declared Owner can retract it. No finer delegation of who may retract what, and no special handling for retracting a retraction beyond appending another one.
Fifty-nine tests pin down the signature-versus-authorization separation, every action-class boundary — including the reviewed-flag trap and Class C’s single-use window — relay stripping, and retraction resolution. None of the limitations above are hidden. They’re exactly what the fourth law exists to make impossible to quietly paper over: written down here, in the README’s own audit-trail sense, not the payload’s.
— Shaurya