rodmontiel/uai
Just a simple engineer thinking about Skynet :). Contribute to rodmontiel/uai development by creating an account on GitHub.
0 stars · 0 forks
README
Universal Agent Identity (UAI)
Every AI agent should be accountable. An identity and accountability layer for autonomous artificial intelligence — open protocol, reference implementation, and a path to a federated network of independently operated registries.
A real agent in a running stack, captured by make screenshots. Every value comes from the API — including UAI-AL0 — how strongly the identity was established, not how safe the agent is, which is the sentence this project exists to keep saying.
Mission Make every action taken by an autonomous agent attributable to a named, responsible party — and make that attribution checkable by anyone, without trusting the party that produced it. An AI agent sends an email, moves money, changes a firewall rule, reads a customer record. Today the trace it leaves is, at best, a line in somebody's log saying bot-27 — written by the same system that took the action. A receipt that signed itself. UAI replaces that with a chain of signed, independently verifiable evidence: this identity, this declared owner, these granted capabilities, this stated purpose, this exact version of the rulebook, this outcome — and the cryptographic material for a third party to check every link without running our code. Vision One registry is a product. A network of them is infrastructure. The internet does not have a central authority deciding who may route packets. It has roughly 75,000 independently operated Autonomous Systems, each with its own number, each peering with others bilaterally, each responsible for what it originates. That design is why the internet scales across jurisdictions, competitors and political boundaries. UAI is built toward the same shape for agent identity. An organization, a regulator, a cloud provider or a country runs its own registry — a UAI-AS — with its own number, its own key and its own operational policy. Registries peer with each other explicitly. Signed statements about identities travel between peers, always attributable to the registry that originated them. Nobody's database becomes anybody else's. The long-term goal is global auditability: an action taken by an agent registered in Buenos Aires can be verified by a counterparty in Frankfurt, against evidence neither of them had to take on trust.
Where this actually is today: the first three capabilities of that vision exist and run — a registry has its own identity, two registries peer explicitly, and one sends the other a signed statement about an identity it issued. Everything that makes it a network rather than a link — transit, path propagation, route selection, discovery — does not exist yet and is listed as such in Federation.
Long-term stretch goal: if Skynet ever does become self-aware and wake up 😂, at least the audit trail will say which owner registered it, under which policy version it acted, whether its passport had expired, and exactly which rule it fired on the way. We still will not have a kill switch — but the incident report is going to be immaculate. 🤖
What UAI claims — and what it does not This goes first, not last, because it is the part most easily oversold. UAI does not claim an agent is safe. No protocol can. It claims an action is attributable. UAI has no global kill switch, and says so in the specification, the API responses, the UI and the demo. Revoking an identity means participating organizations stop honoring its credentials — not that the program stops. Code on a disconnected machine keeps running. The demo demonstrates that limit on purpose rather than hiding it.
identified ≠ safe. Identity enables accountability. Accountability is what trust is built on.
The product, in four artifacts
Artifact What it answers What it is
UAI-ID Who is this? A globally unique, time-sortable identifier, 1:1 with a W3C DID
UAI Credential Who answers for it, and what may it do? A Verifiable Credential binding the identity to an owner, an organization and its capabilities
UAI Passport Where, and until when? A time-bounded authorization to act across jurisdictions — never a grant of new capability
UAI Action Attestation What did it do? A signed, hash-chained record of each action, naming the exact policy version that allowed it
The distinction between the last two is the one worth keeping:
The credential says "this agent may read customer records." That is the what, and only the owner grants it. The passport says "it may do so in Argentina and Germany, until 21 March." That is the where and until when.
A passport can never add a capability the owner did not grant. That is what makes it safe for an agent to request its own.
The screens Seven pages, one origin, a strict CSP, no build step and no external JavaScript. The image at the top of this page is captured from a running stack by make screenshots, not pasted by hand — a screenshot taken once goes stale silently, and a README showing a product that no longer exists is a small lie that compounds. The panels below are sketched from the real page code and real example documents in spec/schemas/examples/; where a panel is a document rather than a page in web/, it says so. 1 · Identification — who is this, and how sure are we? The card above is the answer to who is this. verify.html is the answer to and should I believe it — the only screen in the system you are not asked to trust. It does not render our verdict: the code that checks the signatures runs in your browser, has no dependencies, and can be read in a few hundred lines. The page keeps the two halves apart and says so: "this panel is the registry's answer. The checks below are performed in your browser." Two things on it are the whole product argument. The assurance level says why it is not higher. A bare UAI-AL0 is indistinguishable from a misconfiguration, so the registry reports the level and the dimension holding it down: Assurance UAI-AL0 — limited by runtime attestation no attested runtime; a binding the agent described itself is not attestation
The level is derived from evidence on every read — key protection, owner verification, runtime attestation — and it is the minimum of the three. It is never stored: a saved copy would be a cache with no invalidation path, and the evidence moves when a key rotates, a binding expires or an owner is verified. And the chain check refuses to conclude. An identity that has attested nothing gets not checked — no events yet rather than a green tick, and one whose history cannot be tied back to registration is reported as failed, not as passed-with-nothing-to-check. A verifier that reported success for a walk it did not perform would be worse than no verifier at all. 2 · The AI Passport — where it may act, and until when The passport is not a screen: it is a signed credential the holder can hand to a counterparty, who validates it without calling us. This is a real one from spec/schemas/examples/: { "type": ["VerifiableCredential", "AgentPassportCredential"], "id": "urn:uai:passport:01JY8RB1Q4X7N2M8V0K3T5S9WE", "validFrom": "2026-09-22T00:00:00Z", "validUntil": "2027-03-21T00:00:00Z", "credentialSubject": { "id": "did:uai:agent:01JY8R9ZAF392N7QX2T81JH6KM", "owner": "did:uai:owner:01JY8R9ZB00000000000000000", "allowedJurisdictions": ["AR", "BR", "DE", "ES"], "restrictedJurisdictions": ["KP", "IR"], "authorizedCapabilities": [ { "capability": "cloud.securitygroup.update", "minAssurance": "UAI-AL3", "constraints": { "max_actions_per_hour": 20 } }, { "capability": "crm.customer.read", "minAssurance": "UAI-AL2" } ], "assuranceLevel": "UAI-AL3", "policyVersion": "GASC-2027.4", "state": "VALID" }, "proof": { "type": "DataIntegrityProof", "domain": "UAI-v1:credential", "…": "…" } } Note the floors. cloud.securitygroup.update requires UAI-AL3; holding this passport changes nothing about whether the identity reaches it. If it does not, the guardrail refuses the action with assurance_below_floor and names the rule that fired. A document that authorized something the guardrail would deny is a document telling an operator they are covered when they are not. And validUntil is not decoration: a passport expires, and an expired one authorizes nothing. That is why it is safe for an agent to request its own — the worst case of a fraudulent passport is narrower scope, never wider. 3 · The event chain — what it did, in order, with no gaps Every action is a signed record naming the previous one. You cannot insert one, and you cannot remove one without the numbering failing to close. explorer.html walks that chain: Action explorer Identity uai:agent:01JY8R9ZAF392N7QX2T81JH6KM ● ACTIVE Genesis sha256:f2d8c41d…32718f
418 attested action(s) # ACTION OUTCOME LINKS TO EVENT ASSERTED AT ──────────────────────────────────────────────────────────────────────────────────────────── 418 infrastructure.modify SUCCESS aaaaaaaa…aa 3f91c02b…7d 14:02:04Z 417 crm.customer.read ABORTED_BY_POLICY 99c1e70b…13 aaaaaaaa…aa 13:58:41Z
An identity that has attested nothing gets a sentence rather than an empty table: "That is not evidence that it did nothing: an actor that never submits an event leaves no trace, which is a limit this system states rather than hides." Each row is a signed document. This is a real one from spec/schemas/examples/: { "event_id": "01JY8RA3C7K2V9M0QW4T6Z8XPD", "agent_did": "did:uai:agent:01JY8R9ZAF392N7QX2T81JH6KM", "runtime_identity": "spiffe://uai.world/agents/01JY8R9ZAF392N7QX2T81JH6KM/i/7f6a92", "action": { "type": "infrastructure.modify", "capability": "cloud.securitygroup.update", "resource": "urn:cloud:aws:eu-central-1:sg-0a1b2c3d", "risk_class": "CRITICAL" }, "purpose": "incident_remediation", "jurisdiction": { "origin": "AR", "targets": ["DE"], "cross_border": true, "basis": "resource_location" }, "policy": { "version": "GASC-2027.4", "decision": "ALLOW_WITH_MONITORING", "decision_id": "01JY8RA3C0…", "rules_fired": ["gasc.infra.cross_border_change"] }, "passport": { "required": true, "status_at_decision": "VALID", "credential_hash": "sha256:bb…" }, "input_commitment": "sha256:aaaa…", "output_commitment": "sha256:bbbb…", "outcome": "SUCCESS", "previous_event_hash": "sha256:aaaa…", "sequence": 418, "signature": { "domain": "UAI-v1:attestation", "…": "…" } } Three things this record does that a log line cannot: it names the exact policy version and the rules that fired, so the decision can be re-evaluated years later; it records the passport's state at decision time, so that survives the passport's later expiry; and inputs and outputs appear only as salted commitments — the text never leaves the agent, and the salts stay with its owner, who decides who may open them and when. Failures are attested too. FAILURE, PARTIAL and ABORTED_BY_POLICY are first-class outcomes, and the SDK attests a thrown exception before re-throwing it. An accountability record containing only successes is an advertisement. 4 · Governance — revoking an identity takes people, not an administrator Governance PROPOSAL SUBJECT KIND STATE THRESHOLD YES/NO COUNTRIES CLOSES ──────────────────────────────────────────────────────────────────────────────────────────────────────── 01JY8RC4D2… uai:agent:01JY8R9ZAF… REVOKE OPEN 4-of-5 4 / 1 4 in 19h
How a vote is cast Each vote is a WebAuthn assertion with user verification: a human, on a hardware key, present at that moment. The challenge the key signs IS the digest of the vote, so an automated process cannot cast one — it may hold the delegate's credential and still not produce a valid vote. The registry refuses it with UAI_VOTE_NOT_USER_VERIFIED.
COUNTRIES is not decoration: the quorum must be drawn from at least three jurisdictions, which is what stops a single government — or one operator holding several delegates — from revoking alone. Every vote is permanently attributed; there is no anonymous governance here. An administrator may submit a revocation. An administrator may never decide one: UAIRevocationRegistry.executeRevocation re-verifies the delegate signatures and reads the quorum from the policy registry, so a compromise of the application layer — or of the admin account itself — cannot produce a revocation the contract accepts.
Federation: the network this is built toward The idea BGP works because no one owns it. Each Autonomous System has a number, decides for itself who to peer with, and is accountable for the routes it originates. There is no global registry operator, and that is precisely why it spans jurisdictions that agree on very little else. Agent identity needs the same property. A single global registry of AI agents would be a single point of political failure, a single subpoena target and a single outage. What the world needs instead is many registries that can recognize each other's statements without merging their databases. In UAI, an installation with a number of its own is a UAI-AS:
BGP UAI
ASN — a number identifying an autonomous network UAI-ASN — a number identifying an autonomous registry
AS15169 did:uai-registry:1001
Peering session between two ASes Explicit, mutually configured peering between two registries
BGP OPEN Signed REGISTRY_HELLO
UPDATE announcing a prefix Signed IDENTITY_ANNOUNCEMENT about an identity
"I originate this prefix" "I issued this identity, and here is its state"
UAI-ASNs are independent of internet ASNs. An organization that already runs AS64500 does not inherit a UAI number, and never should: routing packets and vouching for an AI agent are different authorities. What exists today Running make federation-demo stands up two registries with separate databases and separate gateways — because a process talking to itself proves nothing about autonomy — and exercises the whole path: ==> step 1 — each registry says who it is A UAI-AS 1001 · OMniLeads-UAI · did:uai-registry:1001 · ACTIVE B UAI-AS 2001 · Partner-UAI · did:uai-registry:2001 · ACTIVE
==> step 3 — handshake A sent REGISTRY_HELLO from AS1001 · answered from AS2001 (Partner-UAI) ✓ PEER ACTIVE in both directions
==> step 5 — AS1001 announces an identity it issued A announced did:uai:1001:agent:01M3SGKV0D1MZV4C0DDWVESR45 → ACCEPTED
==> step 7 — what AS2001 now holds B AGENT DID ORIGIN STATUS SIGNATURE B did:uai:1001:agent:01M3SGKV0D… AS1001 REGISTERED VERIFIED B These belong to other registries. None of them is an agent of this one.
==> and what AS2001 refuses ✓ a replayed announcement: STALE_SEQUENCE ✓ AS2001 trying to revoke AS1001's identity: WRONG_AUTHORITY ✓ AS2001 has 0 local agents: a federated identity is not one
The rule the whole design rests on:
PEER TRUST ≠ AGENT TRUST Configuring a peer means "this registry may send me signed statements." It never means "I trust its agents." A federated identity is a claim by another registry, recorded as such, and it is never an identity of yours.
That is enforced in the schema, not in a comment: federated identities live in their own table with no foreign key to local agents, and a CHECK ties every DID to the ASN it was announced under. And a valid signature is not authority — a registry can perfectly well sign a statement about somebody else's agent, and it is refused with WRONG_AUTHORITY. An announcement has seven fields, none of them free-form, and the decoder rejects unknown members. That is how "announcements must never carry prompts or PII" stops being a rule in a document. What does not exist yet Named here so it cannot be mistaken for a roadmap that already shipped. None of the following is implemented:
REGISTRY_PATH and transit — an announcement travels one hop, between two directly configured peers. Nothing forwards it onward, and nothing records the path it took. BGP-style route selection, multi-path, and tie-breaking between competing statements. Automatic peer discovery — peering is manual and mutual, on purpose. Trust-on-first-use is offered for a lab and the tool says out loud that out-of-band is better. An RPKI equivalent — nothing outside the two registries certifies that a UAI-ASN belongs to who claims it. Confederations, route reflectors, trust communities, import/export policy engines. Propagation of revocation or quarantine between peers. Passport federation and cross-registry capability recognition. A looking glass, and federation consensus on a blockchain.
The interfaces were left extensible. Nothing above is scheduled, and nothing above is implied by what runs today. 📖 Step by step, with real output: docs/Ejemplo_Practico_federation_es.md ┌─ Federation — UAI ───────────────────────────────────────────────────────────┐ │ This registry │ │ UAI-AS 1001 │ │ Registry OMniLeads-UAI │ │ Registry DID did:uai-registry:1001 ● ACTIVE │ │ Federation endpoint https://uai.omnileads.example │ │ Protocol 0.1 │ │ │ │ Peers │ │ UAI-AS REGISTRY DID STATUS ENDPOINT LAST SEEN │ │ 2001 did:uai-registry:2001 ACTIVE https://partner.exam… 16:49Z │ │ │ │ Federated identities │ │ AGENT DID ORIGIN REMOTE STATUS SIGNATURE SEQ │ │ did:uai:2001:agent:01M3SGKV0D… AS2001 REGISTERED VERIFIED 1042 │ │ │ │ These belong to other registries. None of them is an agent of this one. │ └──────────────────────────────────────────────────────────────────────────────┘
Federation is opt-in and off by default. An installation nobody gave a number to answers 404 UAI_FEDERATION_NOT_CONFIGURED, which is the honest state for a registry that has not joined anything.
Run it ./deploy.sh up # four containers; open http://localhost:8081 ./deploy.sh status # what is running, and whether runtime attestation is on ./deploy.sh down # stop To watch the whole protocol exercised end to end instead: make demo # throwaway stack, the ACME scenario, # fails unless all 21 MVP criteria are demonstrated make federation-demo # two independent registries recognising each other Where to start reading
If you are Start here
Evaluating this as a product This page, then docs/Ejemplo_Practico_es.md — twelve steps, every output real
New to the concepts docs/MANUAL.md — the whole system, component by component. Also in Spanish: docs/MANUAL.es.md
Building a verifier docs/protocol/00-index.md — 26 sections, written so a third party can build a conformant verifier without running any code from this repository. The two files you must implement are identity and cryptography
Interested in federation docs/Ejemplo_Practico_federation_es.md
Assessing the risk docs/protocol/13-threat-model.md, and §20.5 in particular: the controls that do not exist yet, each with its consequence
Status Phase numbering follows the roadmap exactly. A phase is ✅ only when its own stated deliverable exists in this repository.
Phase Status What
0–1 Definition & architecture ✅ Protocol specification v0.1, 26 sections, Mermaid diagrams, t