📘 IntentShield — Zero-Trust Intent Security Framework

IntentShield is a Zero-Trust Intent Security API system that classifies, scores, and enforces policies on user intents before execution using FastAPI + Open Policy Agent (OPA).

It acts as a security layer for AI-driven and API-driven systems, ensuring that every request is evaluated for intent, risk, and policy compliance.

---

🚀 Live Demo Architecture (Current Setup)

Frontend (Lovable UI)
        ↓
Cloudflare Tunnel (Public HTTPS URL)
        ↓
Local Machine (FastAPI + Docker)
        ↓
OPA Policy Engine + Risk Scoring + Intent Classification

---

⚠️ Important: System Availability

❗ This system runs on a LOCAL machine

Because the backend is running locally and exposed via Cloudflare Tunnel:

✔ It works ONLY when:

• Your laptop is ON
• Docker container is running
• Cloudflare tunnel is active

---

❌ It will STOP when:

• You shut down your system
• You disconnect internet
• You stop Cloudflare tunnel process

---

🔄 How to START the system again

Whenever you want to run IntentShield again:

1. Start backend (Docker)

docker build -t intentshield .
docker run -p 8000:8000 intentshield

OR if already built:

docker restart intentshield

---

2. Start Cloudflare Tunnel

cloudflared tunnel --url http://localhost:8000

---

3. Copy new URL

You will get a new URL like:

https://random-name.trycloudflare.com

---

4. Update frontend (IMPORTANT)

Update Lovable frontend with new backend URL:

Change in environment variable:

VITE_API_BASE_URL=https://new-cloudflare-url.trycloudflare.com

OR update API base URL in frontend config.

---

🔗 API Usage

Base URL

https://your-cloudflare-url.trycloudflare.com

---

Health Check

GET /health

Response:

{
  "status": "ok"
}

---

Intent Analysis (Core API)

POST /intent

Headers:

Content-Type: application/json
X-API-Key: admin-key-123
X-Correlation-ID: demo-001

Body:

{
  "intent": "transfer_funds"
}

---

Response:

{
  "intent_token": "ITX-xxxx",
  "category": "financial_action",
  "risk_score": 85,
  "decision": "deny"
}

---

🔐 Authentication

Built-in development API keys:

User	Role	API Key
Admin	admin	admin-key-123
User	user	user-key-456

For frontend demos, use:

admin-key-123

---

💻 Frontend (Lovable Integration)

The frontend is built using Lovable and connects directly to the backend API.

Required config in frontend:

VITE_API_BASE_URL = <your-cloudflare-url>

---

⚠️ Important Frontend Note

Since Cloudflare Tunnel URLs are temporary:

Every restart will generate a NEW URL.

So you must:

• Update frontend config manually
• Or re-run Lovable prompt with new URL

---

🧠 Recommended Lovable instruction for updates

When backend URL changes, tell Lovable:

Update backend API base URL to:

https://NEW-CLOUDFLARE-URL.trycloudflare.com

Replace all previous API endpoints.
Do not modify UI or logic.

---

🌍 Future Production Plan

Currently, Cloudflare Tunnel is used for zero-cost deployment testing.

Future upgrade plan:

We will migrate to:

• Custom domain (e.g. api.intentshield.io)
• Stable backend hosting (Oracle Cloud / Render / AWS)
• CI/CD pipeline from GitHub

This will remove the need to update URLs manually.

---

📌 Key Features

• Intent classification engine
• Risk scoring system
• OPA policy enforcement
• API key authentication
• Correlation ID tracing
• Security decision engine (ALLOW / DENY)
• SOC-style frontend dashboard (Lovable)

---

🧪 Example Use Cases

Try sending intents like:

• transfer_funds
• delete_all_users
• access_admin_panel
• read_user_data

System will:

classify → score → enforce policy → return decision

---

🛡️ Security Model

IntentShield ensures:

• Authentication (who is calling)
• Intent classification (what is being done)
• Risk scoring (how dangerous it is)
• Policy enforcement (should it be allowed)

---

⚠️ Known Limitations (Current Phase)

• Backend runs locally (not cloud hosted)
• Cloudflare URL changes on restart
• Manual frontend update required after restart
• No persistent domain yet (cost constraint)

---

🧭 Next Improvements (Planned)

• Stable cloud deployment (no URL changes)
• Custom domain setup
• Advanced SOC dashboard UI upgrades
• Attack simulation and audit logs
• Multi-tenant RBAC system

---

👨‍💻 Author

Built by Sathvik Shetty IntentShield — Zero-Trust Intent Security Framework

---

✅ Summary

This system demonstrates:

A real-world Zero Trust API security architecture with live policy enforcement and frontend visualization.

---