🛡️ Shekara

Security-first AI agent framework with risk-scored authorization, multi-agent scope isolation, and full audit transparency.

Built on Auth0 Token Vault for the Authorized to Act Hackathon.

---

What is Shekara?

Shekara is an AI agent that interacts with your Google Calendar, Gmail, and GitHub — but every action is classified by risk before execution. Instead of giving AI unlimited access to your accounts, Shekara enforces a 4-tier authorization model where high-risk actions require explicit user consent, step-up authentication, or even async approval.

The name "Shekara" (шекара) means "boundary" — because AI agents need them.

Risk Model

Every tool call is scored using a two-dimensional formula:

Risk Score = Action Severity (1-5) × Context Multiplier (1.0-2.5)

Tier	Score Range	Auth Flow	Example
🟢 C	1.0 – 2.0	Silent (no interruption)	List calendar events
🟡 B	2.5 – 4.0	Inline consent + intent preview	Send email, create issue
🟠 A	4.5 – 8.0	Step-up authentication	Merge PR, bulk send
🟣 S	8.5+	CIBA async approval	Delete repo

Context multipliers escalate risk when:

• Sensitive data detected (PII in params): ×1.5
• Cross-service chain (reading email → creating GitHub issue): ×2.0
• Bulk operations detected: ×2.5

Architecture

┌──────────────────────────────────────────────────┐
│                    Frontend (Next.js)              │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │ ChatUI   │  │ Audit    │  │ Permission       │ │
│  │ +RiskBadge│  │ Trail    │  │ Dashboard        │ │
│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘ │
│       │              │                  │           │
│       └──────────────┴──────────────────┘           │
│                      │                              │
│              Auth0 Middleware (v4)                   │
└──────────────────────┬──────────────────────────────┘
                       │ HTTPS + refresh_token
┌──────────────────────┴──────────────────────────────┐
│                 Backend (FastAPI + LangGraph)         │
│  ┌─────────────┐  ┌────────────┐  ┌──────────────┐  │
│  │ Risk Engine  │  │ Sanitizer  │  │ Audit Logger │  │
│  │ (2D scoring) │  │ (anti-PI)  │  │ (PII redact) │  │
│  └──────┬──────┘  └─────┬──────┘  └──────┬───────┘  │
│         │               │                │           │
│  ┌──────┴───────────────┴────────────────┴─────────┐ │
│  │            LangGraph ReAct Agent                 │ │
│  │  ┌─────────┐ ┌────────┐ ┌──────────────────────┐│ │
│  │  │Calendar │ │ Gmail  │ │ GitHub               ││ │
│  │  │list/create│ │search/ │ │repos/issues/PRs     ││ │
│  │  │         │ │read/send│ │create issue          ││ │
│  │  └────┬────┘ └───┬────┘ └──────┬───────────────┘│ │
│  └───────┴──────────┴─────────────┴────────────────┘ │
│                      │                                │
│          Auth0 Token Vault (scope isolation)           │
│    ┌─────────────┐ ┌───────────┐ ┌─────────────────┐ │
│    │calendar.read│ │gmail.send │ │github (app perms)│ │
│    │calendar.write│ │gmail.read │ │                  │ │
│    └─────────────┘ └───────────┘ └─────────────────┘ │
└───────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• Auth0 account (free plan works)
• Google OAuth 2.0 Client
• GitHub OAuth App

1. Clone and install

git clone https://github.com/YOUR_USERNAME/shekara.git
cd shekara

# Backend
cd backend
pip install -r requirements.txt  # or: pip install fastapi uvicorn auth0-ai-langchain langgraph langchain-openai google-api-python-client python-dotenv google-auth httpx
cp .env.example .env
# Edit .env with your credentials

# Frontend
cd ../frontend
npm install
cp .env.local.example .env.local
# Edit .env.local with your credentials

2. Configure Auth0

1. Create a Regular Web Application in Auth0 Dashboard
2. Enable Refresh Token and Token Vault grant types
3. Set up Google social connection with Connected Accounts for Token Vault
4. Enable calendar.readonly, calendar.events, gmail.readonly, gmail.send scopes
5. Set up GitHub social connection with Token Vault

3. Run

# Terminal 1 — Backend
cd backend
python -m uvicorn app.main:app --port 54367 --reload

# Terminal 2 — Frontend
cd frontend
npm run dev

Visit http://localhost:3000 → Login → Start chatting!

Tech Stack

Layer	Technology	Why
Frontend	Next.js 16, React 19, Tailwind CSS	Modern SSR + dark theme
Auth	Auth0 v4, Token Vault	Scoped token exchange
Backend	FastAPI, LangGraph	Async agent orchestration
LLM	OpenAI GPT-4o-mini	Fast, cheap, structured output
Google APIs	Calendar v3, Gmail v1	Calendar + email access
GitHub API	REST v3	Repo/issue management

OWASP LLM Top 10 Mitigations

#	Risk	Mitigation
LLM01	Prompt Injection	sanitizer.py strips injection patterns from tool outputs
LLM02	Data Disclosure	Token Vault: each tool gets only the scopes it needs
LLM06	Excessive Agency	4-tier risk classification with user consent gates
LLM07	System Prompt Leak	Prompt stored server-side only, agent refuses to reveal
LLM08	Supply Chain	No dynamic package loading, deps pinned
LLM09	Overreliance	Intent preview cards show exactly what agent will do

Pages

• / — Chat with Shekara (login required)
• /audit — Real-time audit trail with risk badges
• /dashboard — Connected accounts + permission scopes

License

Apache 2.0