TL;DR: ConsentVault is a single-file, dependency-free interactive demo of U-PERM — the universal permission layer from the U-STACK architecture. The premise: user-owned data, apps as guests, capabilities instead of ambient authority. You play a clinic owner whose AI receptionist agent needs data access. You issue scoped, time-bound capability tokens, watch the agent's access attempts get allowed or denied live, and then hit REVOKE ALL to kill every grant instantly. One index.html (525 lines, ~23 KB), zero dependencies, works over file://. github.com/Shivay00001/consent-vault.
The problem: AI agents get the keys to the kingdom
The default way we grant AI agents access today is ambient authority: connect your inbox, your calendar, your CRM — all of it, indefinitely, revocable only by digging through settings pages. An agent that needs to read today's appointments gets the same standing access as one that could read every patient record ever. When a token leaks, a prompt gets injected, or an agent simply misbehaves, there is no kill switch, no scoped boundary, and no receipt of what was touched.
ConsentVault demonstrates the alternative the industry is converging on: capability-based security. Instead of identity-based access ("this agent may access the clinic system"), the agent holds unforgeable, narrowly-scoped capability tokens ("this token permits read access to the appointments calendar for the next 10 minutes, for the purpose of handling appointment bookings"). No token, no access — default-deny. Tokens attenuate (a read-appointments token can never authorize a write-billing action). Tokens expire. And every grant can be revoked instantly, with an audit trail to prove it.
The five invariants, demonstrated live
ConsentVault is organized around five U-PERM invariants, each one made visible in the demo rather than merely documented:
| Invariant | Meaning | How the demo shows it |
|---|---|---|
| P1 — Default-deny | No grant, no access | On load, zero grants exist — every agent attempt renders red DENIED ("no grants issued — default-deny"). The onboarding hint reads: "Issue a grant to let the agent work." |
| P2 — Attenuation | Grants can't exceed their scope | Grants are minted per-resource with explicit read/write toggles. A grant for read appointments does not authorize write billing — out-of-scope attempts are denied with "attenuation holds". |
| P3 — Time-bounded | Every grant expires | Each grant carries an expiry with a live countdown on its token card. Issue a 60-second grant and watch it die: subsequent attempts flip to DENIED and the audit log records "grant expired". |
| P4 — Total revocation | One action kills all access | The big red REVOKE ALL button: red screen flash, banner "All access revoked — agent is now blind", token cards flip to REVOKED, the feed goes all-DENIED. Per-grant Revoke buttons do the same for a single token. |
| P5 — Legible purpose | Every grant states why it exists | Each grant carries a plain-language purpose (default "Handle appointment bookings"), printed on the token card and in the audit log. |
Inside the demo: three panes
Left — Grant builder. Resource checkboxes for three clinic data stores (Appointments calendar, Patient records, Billing ledger), each with per-resource read/write pills, an expiry selector, a purpose field, and an "Issue grant" button. Every issued grant becomes a capability token card showing issuer → holder, resource/action chips, a live expiry countdown, and its own Revoke button.
Middle — Agent activity. A simulated receptionist agent (agent 'recep-01', your principal) attempts an action roughly every 2.5 seconds — read/write across the three resources. Each attempt is checked against the live grant set and renders green ALLOWED (citing the authorizing grant) or red DENIED (citing the reason: no grant, out of scope, expired, revoked). A Start/Pause button controls the simulation.
Right — Audit log. An append-only record of everything: grants issued, access allowed/denied, grants expired, grants revoked — each with a timestamp and a "Copy audit log" button for exporting the receipt trail.
Implementation notes
The whole thing is one HTML file with inline CSS and vanilla JavaScript — no build step, no framework, no network calls. The script contains roughly 27 functions, and the architecture is legible enough to read in one sitting:
issueGrant()mints a token from the builder form state;grantCard()renders it;renderGrants()keeps the token list in sync.liveGrants()andgrantById()are the authorization check path — every simulated agent attempt runs through them, which is exactly where a real policy-enforcement point would sit.- A
setInterval-driven loop ticks the expiry countdowns and drives the agent's ~2.5 s attempt cadence. - Small utilities do the unglamorous work properly:
esc()for HTML escaping,stamp()for timestamps,fmtLeft()for countdown formatting,resLabel()for resource names.
That last point matters more than it looks: the demo's structure mirrors how a production system would be built. The grant-issuance path, the check path, and the audit path are separate functions — swap the simulated agent for a real one and the simulated check for a real token verifier, and the shape of the code barely changes.
How to run it
No build, no dependencies, no network. Two options:
# Option 1: just double-click index.html (works over file://)
# Option 2: serve it
cd consent-vault
python3 -m http.server 8000
# open http://localhost:8000The 5-step demo script (from the README — worth doing in order):
- Watch the blind agent. On load, zero grants exist — every feed row is red DENIED (P1).
- Grant narrow access. Check Appointments calendar → read only, 10-minute expiry, purpose "Handle appointment bookings", Issue grant. Appointment reads flip green; billing writes stay red (P2).
- Watch a grant die. Issue a 60-second grant for Billing ledger read. The card counts down live; at zero, billing attempts flip back to DENIED and the audit log records the expiry (P3).
- Check the audit log. Every event timestamped and append-only.
- REVOKE ALL. The money moment — red flash, banner, REVOKED cards, all-DENIED feed (P4).
Honest status and roadmap
Status: working interactive prototype — fully simulated. The README and the page's own footer say this plainly: "Interactive simulation of the U-STACK U-PERM specification · No real data." The agent is simulated, the authorization checks are simulated, the grants are in-memory objects, and nothing persists beyond the page session. That is the correct scope for what this is: a legible, hands-on explanation of a security architecture, not a security product. Anyone evaluating it as cryptography would be missing the point; anyone evaluating it as a teaching tool will find it does its job in about three minutes.
Roadmap (the path from demo to system):
- Real capability-token format — macaroons or biscuits, with cryptographic attenuation instead of in-memory flags.
- A server-side policy-enforcement point so checks can't be bypassed client-side.
- Multi-agent scenarios: delegation chains (agent A grants a narrowed token to agent B).
- Signed, exportable audit log — tamper-evident receipts, not just a text area.
- Integration with the EnterChat / YOU.PDF agent stack, where U-PERM originated as a research concept.
Who should look at this repo
- AI agent builders who need to explain scoped permissions to stakeholders — this demo does in 3 minutes what a whitepaper does in 30 pages.
- Security-minded engineers interested in capability-based access control applied to the agent era.
- Founders in healthtech, fintech, or any regulated vertical where "the AI can see everything" is not an acceptable architecture.
Why capabilities beat scopes
It's worth pausing on why the capability model ConsentVault demonstrates is structurally better than the OAuth scopes most agent platforms use today. Scopes are ambient: once granted, they apply to every request the agent makes, indefinitely, and they're coarse ("read your email" means all of it). Capabilities are object-bound: the token itself names the resource, the permitted actions, the expiry, and the purpose. Three properties follow that scopes can't easily provide:
- Least privilege by construction. You can't accidentally over-grant, because the grant UI forces you to pick resources, actions, and an expiry for every token. The demo's per-resource read/write pills make this tactile.
- Revocation that actually works. Revoking an OAuth token often leaves derived sessions alive; revoking a capability token kills the exact permission the agent holds, immediately, with the denial visible in the feed.
- Auditable purpose. Every token carries a human-readable purpose, so the audit log answers not just what was accessed but why it was allowed — the question regulators and customers actually ask.
ConsentVault doesn't implement the cryptography — but it makes the mental model click, which is the prerequisite for building it right.
Frequently asked questions
Is ConsentVault real authorization?
No — it is an interactive simulation of the U-PERM specification. The agent, the grants, and the checks are all simulated client-side. Its purpose is to make the architecture legible, not to enforce it.
Why a single HTML file with no dependencies?
So anyone can open it in seconds, read the whole implementation in one sitting, and embed or fork it freely. The idea is the product here, and a zero-dependency file is the most legible possible packaging for an idea.
What are U-PERM and U-STACK?
U-PERM is the universal permission layer concept — user-owned data, apps as guests, capabilities instead of ambient authority — from the U-STACK architecture research. ConsentVault is its interactive demonstration.
Can I embed the demo in my own site or presentation?
Yes — it is one self-contained HTML file with no network calls. Open it, serve it, or iframe it.
The bottom line
ConsentVault's thesis is simple and, frankly, correct: in the agent era, "connect everything and hope" is not a permission model. Scoped, time-bound, revocable capability tokens with an audit trail are. This repo won't enforce that for you — but in one dependency-free file, it will make you feel why it matters the moment you hit REVOKE ALL and watch the agent go blind. That's what a good demo is for.