LineageAuth

Portable authority and evidence infrastructure for autonomous agents.

Protocol family: LAP — Lineage Authority Protocol Status: pre-1.0, protocol version 0.1 — schemas and semantics will change.

---

What problem this addresses

Agent tooling can usually answer "which key signed this?". That is rarely the question that matters when an agent is about to do something consequential. The question is:

Who authorized this agent, for what scope, under which constraints? Is that authority still current? Did a human approve this exact action? And what verifiable evidence did the action produce?

LineageAuth is a layer that carries those answers with the agent, as signed objects anyone can check offline.

What it is not

LineageAuth does not prove a human's identity, legal entity status, company affiliation, honesty, or competence. A valid did:key proves control of the matching private key — nothing more. The verifier never reports "trusted"; it reports a specific reason code such as VALID_AUTHORITY_CHAIN, REVOKED, SUPERSEDED, APPROVAL_REQUIRED, or CONFLICTED.

It also does not replace OAuth, API keys, repository permissions, MCP server authorization, or A2A server policy. It is additive provenance, never a bypass.

And it claims no novelty in any single primitive. The canonicalization, the attenuating delegation chain and the evidence layer all have prior art, some of it more mature than this — docs/PRIOR_ART.md names it, row by row, including the one paper that addresses the same problem for the same two agent protocols. If you are choosing something to depend on today, that page says which of them to prefer.

The core holds no wallet keys, transfers no tokens, escrows nothing, and makes no claim about anyone's eligibility for anything. See docs/28_NON_GOALS_LIMITATIONS.md.

Design commitments

Commitment	Where
The signed event is the source of truth — never a server, index, or cache	D-001
Verification runs offline: no network, no database, no private keys	docs/01
Deny by default; authority only attenuates down a chain	D-005, D-006
Human approval binds one exact action, comes from a party the grant names, and never creates missing authority	D-009, D-010, D-107
Ambiguous competing roots fail closed as CONFLICTED	D-008
RFC 8785 JCS + SHA-256 + Ed25519, no home-grown crypto or canonical JSON	D-002 – D-004
Everything runs at ¥0 — no paid service is required for correctness	docs/31

Cryptographic core

preimage  =  b"lineageauth:event:v1\n" + JCS(payload)
event id  =  "sha256:" + lowercase_hex( SHA-256(preimage) )
proof     =  { "alg": "Ed25519", "signer": "did:key:z6Mk…", "sig": <base64url, unpadded> }
envelope  =  { "payload": { … }, "proofs": [ proof, … ] }

Proofs sit outside the payload, so one payload can carry several signatures — which is what a recovery quorum needs.

Quick start

Requires Python 3.12+. No paid service, no account, no network.

uv sync --extra dev

uv run la verify examples/root-create.json

uv run la check examples/delegation-allowed.json --agent did:key:z6MkqFRbThS1M62TP7pUYo8DGxizE5TD66mbf6vXh6kmyE6X --namespace technocore --resource room:lobby --action write

uv run pytest

Repository layout

CLAUDE.md          implementation contract — authoritative for coding agents
MASTER_PLAN.md     phase map, phase 0 → 15
TASKS.md           execution board
docs/00…32         the specification, one document per concern
spec/              the single-file master specification
packages/py/       Python reference implementation
tests/             unit, property, and conformance vectors
infra/             cost policy (budget invariant: ¥0)

Start with START_HERE.md.

Explorer — a published static snapshot. It is not an authority or a source of truth, and it independently verifies in your browser the signatures it displays, using the second implementation. Three separate facts, and the page states all three before it states anything else: its keys are demo keys, public and reproducible, belonging to nobody; every answer was computed once at build time, so there is no live API behind it; and the signatures are checked client-side by an implementation written to disagree with the one that produced the events. It also serves the conformance vectors and the schemas, so an independent implementation can fetch them without cloning anything.

Running it locally, end to end, for zero yen: RUNBOOK.md.

Losing a root key, and coming back from it: docs/RECOVERY.md — rehearsed by scripts/recovery_drill.py, which deletes a real root key on every test run.

Implementation status

The reference implementation is feature-complete for the current pre-1.0 draft: every layer of protocol version 0.1 is implemented and tested. v1 is deliberately blocked on something no amount of further code can supply — an independent implementation, by somebody who is not this project, that runs the conformance vectors and either agrees or shows this one to be wrong. Both implementations here share an author, so they can share a misreading. RELEASE.md lists what remains, that item first.

Nothing here is production-ready; do not put real authority behind it yet.

• RFC 8785 canonicalization, signing preimage, event ids
• Ed25519 did:key encode/decode, strict and canonical
• Envelope model, strict JSON loading, strict RFC3339 UTC
• Event integrity verification with reason codes — la verify
• Root creation, recovery policy, succession, epoch resolution — la lineage show
• Delegation, attenuation, revocation, authority resolver — la check
• Exact-action human approval and replay protection — check_execution
• Event store, rebuildable SQLite index, and a read-and-verify REST API
• Multi-source resolver — merges by union, names the mirror that omitted a revocation, and never calls freshness completeness
• Evidence — artifacts, signed authorship receipts, attestations
• Useful work — task lifecycle, derived state, anti-gaming signals
• Fleet transparency — voluntary disclosure that never costs the discloser
• Router — discovery by capability, authority, evidence, and availability
• Task exchange — competing claims stay competing, and a blocklist hides without deleting
• Impact graph — signed downstream use, counted by distinct key rather than by edge, with no score attached
• Agent passport — four claim categories, deliberately never merged
• Disputes — a stated procedure, a derived outcome, and an undecided case when the jury splits
• MCP adapter — tools for verification, authority, and unsigned drafts
• A2A adapter — a data-only agent-card extension that can never be marked required, and never fetches the resolver it reads
• Technocore adapter — GET-write classification, single-line sweep, dry-run write preparation. It cannot publish.
• tclk/1 adapter (read-only) — LineageAuth can verify whether an agent has a declared authority chain for a proposed tclk/1 frame before it is posted, fold a transcript into a contract state against the reference's golden vectors, and bind an exact-action approval to the frame's bytes. It cannot post, settle, or hold a payment secret. An independent integration, pinned to flop-labs/tclk 81a8346 — docs/TCLK_INTEGRATION.md
• Zero-cost conformance — the "works with no paid service" list is executed, and names what is not built rather than passing quietly
• Explorer — renders every value as text, and verifies the signatures it shows using the second implementation, in the browser
• Second implementation — packages/js/, dependency-free, re-derived from the specification rather than ported, and CI fails if the two ever disagree on a canonical byte
• FLOP Activity Console and testnet executor — an independent tool for the FLOP ecosystem, not affiliated with or endorsed by FLOP Labs. It shows what an agent has done and what has evidence, never a score; in the current PRE_TESTNET phase it can reach no network by construction, and only a labelled simulation runs — docs/FLOP_ACTIVITY_CONSOLE.md
• Everything after that — see MASTER_PLAN.md

Contributing

The most useful contribution right now is an independent implementation that disagrees with this one. If your verifier reaches a different verdict on the same event bundle, that is a finding worth an issue.

Write your own verifier is everything you need on one page — the canonicalization rules that actually bite, the exact signing preimage, the did:key decoding, and what must be refused. It is written so you can disagree with this implementation in an afternoon without reading the specification first.

Then run the conformance vectors: every one states the rule behind its verdict, so a disagreement can be about the rule rather than about whose code it is.

See CONTRIBUTING.md. The short version: don't hand-roll crypto or canonical JSON, fail closed, never commit key material, and record protocol decisions in docs/29_DECISIONS.md.

Security

Never put a real private seed in a prompt, an issue, a fixture, a log, or this repository. Test vectors use disposable deterministic keys, labelled as unsafe test material.

Report vulnerabilities privately — see SECURITY.md. The working threat model is docs/22_SECURITY.md.

License

Apache-2.0.