# Consent Vault

Consent Vault is authorization middleware for AI agents using private data. It
combines Aleo private consent records, independent subject and agent accounts,
encrypted vault binding, a real local model, MCP integration, persistent policy
storage, expiry, and revocation.

## Links

- Repository: https://github.com/SU-AN-coder/private-ai-consent-vault
- Live demo: https://private-ai-consent-vault.vercel.app

## Current proof

### Stateful Aleo testnet

The primary program is `consent_state_0725b.aleo`, deployed in accepted
transaction
`at1sq0hacrpuc34meyj3lw7fvgvquek87ya6wsxp3gygtgstpxsncxq86k9gu`.
It stores canonical consent status, expiry, approved request nullifiers, and
revocation hashes in Aleo mappings.

The current independent subject/agent stateful chain includes:

- `create_consent`:
  `at14hcnrudnw28evqr4aa9qfdzlwq85x6lt7pn0d5qvv7rpll659cxq0gyhmj`
- `approve_request`:
  `at14tj8c7kl63j2q3smeq4f943qmzatf5e6s8q89ergpvl5g4jf2y8q9dg6sv`
- separate revoked consent `create_consent`:
  `at1ld9e7uysmjpyp446p242qmhggr48f8cu6zlkx3qm9unjp8wg2y8qymlnjw`
- `revoke_with_notice`:
  `at1hpzqtw6zyhqee4h4jc5mue83t0lkjv7kaf22gy6n9ef5ng0ngqqspqzfre`

The six accepted mapping checks prove active status and expiry, a consumed
request nullifier, revoked status and expiry, and the exact revocation hash. The
independent agent decrypts and validates the agent-owned `AccessGrant`; MCP then
checks the live mappings before vault decryption. An additional agent-signed,
subject-fee-sponsored
`prove_grant_live` transaction is opt-in with
`CONSENT_RUN_SPONSORED_GRANT_PROOF=true` because it is not required for the
mapping authorization path.

Run or resume the full active plus revoked mapping lifecycle:

```powershell
npm run testnet:consent:stateful-chain
npm run testnet:verify-stateful-evidence
```

The earlier private-record chain on `consent_vault_0709.aleo` remains accepted
legacy evidence:

- `create_consent`:
  `at12l7a7atfjs8c3n06h479pquvdn74723ylv62e4alklcg6c70esgslh5j67`
- `approve_request`:
  `at15j705he025urctszcnf9zaux9ry8w8vfrykspfw3eg3h6ap2cvyswphejd`
- `revoke_with_notice`:
  `at15pq9pq22dz5vq4xf4332a2sqw6e3ywljypzkzekgqfqyykql0gzqfn4w04`
- `publish_revocation`:
  `at1wrywa0zgxprc2zutx583l5pcqwm5ccszq6rqsjr65ppl2tff858ssqxv8d`

The independent agent decrypted its own `AccessGrant` and verified its owner,
subject, agent, receipt commitment, and request hash.

### Local private inference

- Real model: `onnx-community/Qwen2.5-0.5B-Instruct`
- Pinned revision: `cc5cc01a65cc3ff17bdb73a7de33d879f62599b0`
- Runtime: Transformers.js, CPU, q8
- Remote model loading disabled
- Local files only
- Fetch guard installed before model loading
- Observed network calls during inference: `0`
- Raw context forwarded externally: `false`
- Three-scenario quality gate: `3/3` passed
- Average inference: `2201 ms`; maximum: `2390 ms`
- Model role: rationale only; deterministic payment control owns severity and
  action
- Off-topic or unsafe model text is retried once, then withheld

### MCP and persistent security

- Stable `@modelcontextprotocol/sdk` over real stdio client/server
- Tools: `consent_vault_policy_status` and
  `consent_vault_local_risk_assessment`
- Live Aleo create, approve, status, expiry, and request-nullifier checks before
  vault decryption
- Local Poseidon8 consent-id and Poseidon4 request-nullifier recomputation binds
  the signed audit bundle to the exact on-chain authorization
- Stable `sql.js` WASM SQLite registry with atomic snapshot persistence and
  append-only hash-chain audit
- Cross-platform system keyring through `@napi-rs/keyring`: Windows Credential
  Manager, macOS Keychain, or Linux Secret Service
- Explicit scrypt passphrase backend for headless deployments
- One-time migration of legacy Windows DPAPI envelopes into the system keyring
- AES-256-GCM encryption for vault passphrases
- Policy and secret recovery verified after two MCP server processes
- Wrong-passphrase, ciphertext, audit tamper, and legacy migration tests pass
- No `node:sqlite` runtime or experimental warning

## Commands

From this repository root:

```powershell
npm install
npm run model:prepare
npm run model:quality:verify
npm run keyring:verify
npm test
npm run build
npm run mcp:serve
```

Run the MCP server directly after configuring its database, protected-key, and
model-cache paths:

```powershell
npm run mcp:serve
```

The external provider path remains available only for an explicitly approved
disclosure workflow:

```powershell
npm run agent:authorized
```

It is not the primary private-inference claim.

## Evidence

- `docs/evidence/independent-subject-agent-testnet-chain.json`
- `docs/evidence/stateful-consent-deployment.json`
- `docs/evidence/stateful-consent-testnet-chain.json`
- `docs/evidence/local-private-inference.json`
- `docs/evidence/local-model-quality.json`
- `docs/evidence/mcp-local-private-inference.json`
- `docs/evidence/system-keyring.json`
- `docs/evidence/deepseek-authorized-context.json`

No evidence file contains private keys, vault passphrases, vault ciphertexts,
private record plaintext, or private input context.

## Security boundary

The completed proof uses Aleo testnet, a local CPU model, stable SQLite, and an
OS keyring. The current machine verifies Windows Credential Manager; the native
keyring library also implements macOS Keychain and Linux Secret Service.
Mainnet deployment, secure-enclave inference, cloud KMS/HSM integration,
organization-wide policy administration, and hosted enterprise vaults are not
claimed.