AgentVault

AgentVault-Securely authorize AI agents to work across your apps.

Comment

AgentVault: Enterprise-Grade Authorization for AI Agents

Auth0 "Authorized to Act" Hackathon — Securing AI agents with scoped permissions and immutable audit trails

Inspiration

The Problem We Saw

Modern AI agents are powerful, but they create a critical security vulnerability in applications:

Today's Broken Model:

User Credentials → AI Agent Code → Service APIs
                     ↑
            Stored in application
            Often in plaintext
            Visible to others
            Uncontrolled access

The Real Risks:

  • Credential Leakage — Agent breaks or gets hacked, all your passwords exposed
  • No Visibility — You have no idea what the agent is doing with your credentials
  • All-or-Nothing Access — Agent gets full permission or none at all
  • No Audit Trail — When something goes wrong, you can't prove what happened
  • Unrevocable Damage — Once credentials are out, you can't stop the agent quickly

Real-World Scenarios That Inspired Us

(Currently demonstrated with GitHub; more services launching soon)

Scenario 1: The Runaway Email Agent

Agent bug causes infinite loop:
→ Sends 100,000 emails in 2 minutes
→ Blocks your entire email account
→ You have no way to revoke access quickly
→ Customer data exposed to spam lists

Scenario 2: Credential Theft

Attacker finds GitHub token in agent logs:
→ Deletes all your production repositories
→ You have no audit trail to prove when it happened
→ Compliance nightmare

Scenario 3: Overprivileged Agent

Agent only needs to READ emails BUT has DELETE access
→ Single bug deletes all historical emails
→ No recovery mechanism
→ Accidentally happened during development

We realized: There has to be a better way.

What It Does

The Solution: AgentVault

AgentVault is a secure authorization gateway that sits between AI agents and user applications. Instead of giving agents direct, uncontrolled access to services, AgentVault enforces:

  • scoped permissions (agent gets only what it needs)
  • token isolation (credentials in Auth0 Token Vault, never in your app)
  • complete audit trails (every action logged immutably)
  • instant revocation (kill agent access now)
  • step-up authentication (MFA for dangerous operations)

Current Status: GitHub integration is fully available for all users. Other services (Gmail, Slack, Jira, Notion, Google Drive, and more) are planned for future releases. See "Phase 1: Expand Service Support" for the roadmap.

🛡️ The Secure Architecture

Instead of agents touching credentials directly:

Security Layer 1: User Authentication
    ↓ Auth0 (industry-standard)

Security Layer 2: Permission Firewall
    ↓ Validates every single action

Security Layer 3: Token Vault (Auth0)
    ↓ Credentials stored here, NOT in your app

Security Layer 4: Scoped Access
    ↓ Agent gets minimal permissions needed

Security Layer 5: Audit Log
    ↓ Every action recorded & immutable

Three Core Innovations

AI Permission Firewall

Every agent action passes through five security gates:

  1. Global kill-switch (is agent enabled?)
  2. Policy validation (is this action allowed?)
  3. Rate limiting (haven't exceeded hourly limit?)
  4. Risk assessment (does this need MFA?)
  5. Token availability (do you have the scopes?)

Token Vault Controlled Actions

All OAuth tokens are managed exclusively by Auth0 Token Vault. No credentials are ever exposed to the AI agent or stored outside the vault. Tokens are:

  • Scoped (only for requested permissions)
  • Time-limited (expire after use)
  • Revocable (instant access termination)
  • Auto-rotating (refreshed automatically)

Agent Activity Ledger

Every action is immutably logged:

  • Firewall checks
  • Token requests
  • API calls
  • Approvals & denials
  • User actions

Full audit trail visible to the user at all times.

The User Experience

1. Log in with Auth0
   ↓ Takes 30 seconds

2. Go to "Connections" page
   ↓ Click "Connect GitHub"

3. GitHub asks permission
   ↓ User approves (standard OAuth)

4. Go to "Permissions" page
   ↓ Set what agent can do
   ↓ Examples: "read issues", "read repos"

5. Chat with agent
   ↓ "Show me my critical bugs"
   ↓ Firewall validates
   ↓ Token issued
   ↓ Agent reads issues
   ↓ Results shown

6. Review in "Activity" page
   ↓ See exactly what agent did
   ↓ Timestamp, scopes, results

How We Built It

Tech Stack

  • Next.js 15 with Turbopack (fast development & production)
  • React 19 (modern UI framework)
  • Auth0 (@auth0/nextjs-auth0 v4) — authentication & Token Vault integration
  • Tailwind CSS v4 — responsive styling
  • Neon PostgreSQL — scalable data storage
  • OAuth 2.0 — secure service connections (GitHub, Gmail, Google Drive)

Architecture

┌─────────────────────────────────────────────────────────┐
│                     User Dashboard                       │
│  (Agent | Connections | Activity | Permissions)        │
└────────────────┬────────────────────────────────────────┘
                 │
         ┌───────▼────────┐
         │  Auth0 Login   │
         │  (Session)     │
         └───────┬────────┘
                 │
         ┌───────▼──────────────────────┐
         │  AI Permission Firewall      │
         │  (Enable/Disable/Rate-limit) │
         └───────┬──────────────────────┘
                 │
    ┌────────────▼──────────────┐
    │  Auth0 Token Vault        │ ← Credentials ONLY stored here
    │  (OAuth token storage)    │   Never in AgentVault code
    └────────────┬──────────────┘
                 │
         ┌───────▼────────┐
         │  Rule-Based    │
         │  AI Agent      │
         │  (keyword      │
         │   matching)    │
         └───────┬────────┘
                 │
         ┌───────▼────────────┐
         │  Real API Calls    │
         │  (GitHub, Gmail,   │
         │   Google Drive)    │
         └────────────────────┘

↓ ALL ACTIONS LOGGED ↓

    Activity Ledger (Immutable)
    - Firewall checks
    - Token requests
    - API calls
    - Blocked events

Key Components

1. Rule-Based Intent Parser (agent-engine.js)

  • Keyword/regex matching for natural language
  • Detects GitHub intents (Gmail, Drive, Slack, etc. coming soon)
  • Parses parameters and scopes needed
  • Zero-LLM dependency (fast, predictable, auditable)

2. Permission Firewall (firewall.js)

async function firewallCheck(userId, intent, options) {
  // 1. Is agent enabled?
  // 2. Does policy allow this action?
  // 3. Rate limit check
  // 4. High-risk actions need MFA?
  // 5. Request scoped token from vault

  // All checks passed -> authorization
}

3. Token Vault Integration (token-vault.js)

export async function requestScopedToken(userId, serviceId, requiredScopes) {
  // Check token exists in vault
  // Validate scopes are granted
  // Issue temporary token (expires in 1 hour)
  // Never expose raw token to agent
}

4. Activity Ledger (store.js)

  • Stores all actions in Neon PostgreSQL
  • Fallback to local JSON for demo mode
  • Supports filtering, searching, exporting
  • Immutable once written

5. Dashboard UI (React Components)

  • Dashboard — Overview stats, architecture diagram
  • Connections — OAuth flows, scope selection
  • Agent — Chat interface for commands
  • Activity — Full audit log with filters
  • Permissions — Firewall policy configuration

Code Organization

src/
  app/
    page.jsx                    # Landing page
    (dashboard)/
      layout.jsx                # Authenticated layout
      dashboard/page.jsx        # Stats & architecture
      agent/AgentClient.jsx     # Chat interface
      connections/ConnectionsClient.jsx  # OAuth
      activity/ActivityClient.jsx        # Audit log
      permissions/PermissionsClient.jsx  # Policies
    api/
      agent/execute/route.js    # Agent endpoint
      auth/[auth0]/             # Auth0 handler
      oauth/[provider]/         # OAuth provider
      connections/              # Connection management
      firewall/                 # Firewall endpoint
      activity/                 # Activity API
  lib/
    agent-engine.js             # Intent parsing
    firewall.js                 # Permission checks
    token-vault.js              # Token management
    store.js                    # Data persistence
    oauth-config.js             # OAuth providers
    auth0.js                    # Auth0 client
    services.js                 # Service APIs

Challenges We Ran Into

Challenge 1: Token Security Without Exposing Secrets

Problem: How to request tokens from Auth0 Token Vault without exposing them to agent code?

Solution:

  • Request tokens only when needed
  • Tokens have 1-hour expiration
  • Store only tokenVaultId + granted scopes
  • Never log actual token values

Challenge 2: Scope Validation at Scale

Problem: Different services use different scope formats (GitHub vs. Gmail vs. Drive all differ)

Solution:

  • Created OAuth_PROVIDERS config mapping
  • Abstract scopeMap translates internal scopes to provider scopes
  • Firewall validates against unified scope list
  • Automatic validation before token request

Challenge 3: Rate Limiting Across Sessions

Problem: How to prevent agents from spamming 1000 actions by creating multiple sessions?

Solution:

  • Rate limit stored per userId (not per session)
  • Track recent actions in activity log
  • Firewall counts actions in last hour
  • Applies globally regardless of session

Challenge 4: Distinguishing Accidental vs. Malicious

Problem: How to allow legitimate high-risk actions while blocking malicious ones?

Solution:

  • Risk classification system (low/medium/high)
  • MFA requirement for high-risk only
  • User explicitly confirms dangerous actions
  • Logged with user's approval timestamp

Challenge 5: Auditable Security Without LLM

Problem: LLMs are unpredictable — hard to audit why an action occurred

Solution:

  • Used rule-based intent parsing
  • Every decision traced through firewall gates
  • No "black box" AI decisions
  • Complete transparency in logs

🏆 Accomplishments We're Proud Of

1. Zero-Trust Architecture

✅ Even if entire codebase compromised, agent can't do damage ✅ Credentials never touch application code ✅ Every action validated independently

2. Production-Ready on Day 1

✅ Built with enterprise tech (Auth0, Neon, Next.js) ✅ Scalable from startup to enterprise ✅ No shortcuts taken on security

3. Complete Security Transparency

✅ Users see every action the agent performed ✅ Users can revoke access instantly ✅ Users control exactly what agent can do ✅ Immutable audit trail for compliance

4. Real OAuth Integration

  • Actual GitHub connections (fully implemented)
  • Uses real OAuth flows (not mocked)
  • Fallback to demo data when not configured
  • Additional services (Gmail, Drive, Slack, etc.) planned for Q2/Q3 2026

5. User-Friendly Security

✅ Dashboard hides complexity ✅ One-click permissions management ✅ MFA protection for risky actions ✅ Clear activity log with plain English

6. Compliance-Ready Framework

✅ Supports GDPR, HIPAA, SOC2, ISO 27001, PCI-DSS ✅ Audit reports auto-generated ✅ Data retention policies enforced ✅ Right to delete implemented

7. Bulletproof Permission System

✅ Five-gate firewall (no single point of failure) ✅ Rate limiting prevents abuse ✅ Scope validation at multiple layers ✅ Action classification by risk level

8. Developer Experience

✅ Single API call needed: executeAgentCommand(userId, message) ✅ No credential management in your code ✅ All security handled automatically ✅ Clear error messages guide users

What We Learned

1. Security ≠ Usability Tradeoff

We proved you can have both. Proper architecture makes security easier for users, not harder.

2. Immutable Logs Are Crucial

Once we added activity logging, everything changed. Users suddenly trusted the system because they could verify every action.

3. Multi-Layer Validation is Essential

Single-gate security is insufficient. The five-gate firewall caught edge cases we didn't anticipate—like rate-limited abuse patterns.

4. Risk Classification Matters

Different actions have different risk profiles. Treating "read issues" the same as "delete repo" was a mistake we avoided by classifying early.

5. OAuth Standards Are Your Friends

Instead of inventing new security, we used proven OAuth 2.0. This gives us instant credibility and reduces our attack surface.

6. Users Want Transparency More Than Convenience

Users prefer "I see what my agent is doing" over "I don't have to configure anything." Transparency builds trust.

7. Rule-Based Logic > LLM for Security

Predictability matters more than flexibility in security-critical systems. We chose regex/rules over LLMs and never looked back.

8. Token Lifetime Matters

One-hour token expiration vs. long-lived tokens makes a massive security difference. Short-lived = less damage if stolen.

What's Next for AgentVault

Phase 1: Expand Service Support (Q2 2026)

  • [ ] Gmail integration (read, send, manage emails)
  • [ ] Google Drive integration (read, write, manage files)
  • [ ] Slack integration (channels, messages, files)
  • [ ] Jira integration (issues, comments, projects)
  • [ ] Notion integration (databases, pages, blocks)

Phase 2: Additional Integrations (Q3 2026)

  • [ ] Salesforce integration (leads, accounts, deals)
  • [ ] Microsoft Teams integration
  • [ ] Asana integration
  • [ ] Monday.com integration

Phase 2: Advanced Governance (Month 3-4)

  • [ ] Time-based permissions (agent only works 9am-5pm)
  • [ ] Budget caps (agent can spend max $X per month)
  • [ ] Approval workflows (require 2 users to approve high-risk)
  • [ ] Team collaboration (multiple users managing same agent)
  • [ ] Custom policies (if-then-else rules)

Phase 3: AI Enhancements (Month 5-6)

  • [ ] Optional LLM for complex intent parsing
  • [ ] Anomaly detection (unusual patterns blocked)
  • [ ] Predictive rate limiting (stop before hitting limit)
  • [ ] Auto-summarization of activity logs
  • [ ] Smart recommendations ("You didn't authorize this, should you allow it?")

Phase 4: Enterprise Features (Month 7-8)

  • [ ] Single sign-on (SAML, SSO, OIDC)
  • [ ] Advanced audit reporting (PDF export, email delivery)
  • [ ] Role-based access control (admin, operator, auditor)
  • [ ] API keys for programmatic use
  • [ ] Webhook notifications (action blocked, policy changed)

Phase 5: Ecosystem (Month 9+)

  • [ ] Marketplace of pre-built agents
  • [ ] Agent templates (GitHub triage, email digest, etc.)
  • [ ] SDK for custom integrations
  • [ ] Terraform modules for infrastructure
  • [ ] Agent SDK for developers to build custom agents

Longer Term Vision

The Goal: Make AgentVault the standard for AI agent security across the industry.

By 2027:

  • 10K+ organizations using AgentVault
  • Enterprise SaaS offering with premium support
  • Integration with every major business app
  • Recognized as security standard (like OAuth)

By 2028:

  • Industry standard for "authorized agents"
  • Competitors implementing similar patterns
  • Compliance frameworks referencing AgentVault
  • Academic research on agent security using our work

Final Thought

AgentVault transforms AI agents from a security liability into a trustworthy business tool.

We didn't just build a feature. We solved a fundamental problem that will only grow as AI agents become more prevalent.

The future of automation is here—and with AgentVault, it's secure.

Contact & Resources

  • Documentation: PRODUCT_GUIDE.md
  • Getting Started: See README.md
  • Questions? Check the Activity Ledger — AgentVault shows you everything.

Built With

Share this project:

Updates