gitwtfhub

wtf is warden?

geminimir/warden — explained in plain English

Analysis updated 2026-05-18

5PythonAudience · developerComplexity · 4/5Setup · moderate

TL;DR

A fail-closed authorization gateway that ensures AI agents only retrieve and cite documents a specific user is actually permitted to see, with per-turn revalidation.

Mindmap

mindmap
  root((warden))
    What it does
      Permission-aware retrieval
      Fail-closed authorization
      Per-turn revalidation
      Audit trail
    Tech stack
      Python
      FastAPI
      Postgres pgvector
      Redis
    Use cases
      Agentic RAG security
      Multi-tenant document access
      Prompt injection defense
    Architecture
      Gate 1 pre-filter
      Gate 2 authoritative check
      Gate 3 session revalidation

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Enforce per-user document permissions inside an AI agent's retrieval pipeline in a multi-tenant knowledge base.

REASON 2

Re-check every document reference before each model call so revoked access is removed mid-conversation.

REASON 3

Prevent prompt-injection attacks from leaking unauthorized documents by binding identity server-side, not to model input.

What's in the stack?

PythonFastAPIPostgrespgvectorRedis

How it stacks up

geminimir/warden1ncendium/aibusteraaronmayeux/ha-hurricane-tracker
Stars555
LanguagePythonPythonPython
Setup difficultymoderatemoderateeasy
Complexity4/53/52/5
Audiencedeveloperops devopsgeneral

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Requires Docker Compose to start Postgres with pgvector, Redis, and the seeded demo API.

License is not yet decided, the README lists it as TBD.

Wtf does this do

Warden is a security gateway designed to sit inside AI systems that retrieve documents to answer questions, a pattern often called RAG, short for retrieval-augmented generation. Its job is to make sure an AI agent only ever sees and cites documents that the specific person it is acting for is actually allowed to see, even as that agent pulls information from a shared, multi-tenant knowledge base. The project explains that the two common approaches to this problem both have flaws. Checking permissions after fetching results is fast but breaks down if the person is only authorized to see a tiny fraction of documents, since a normal search would then return almost nothing they are allowed to read. The opposite approach, listing every document a person can access ahead of time, stays accurate but becomes far too slow once someone is authorized on millions of documents. Warden's answer is to compress permissions into small labels that can be checked cheaply during the initial search, and then treat that as just a performance shortcut, backed by a separate, authoritative permission check on the smaller set of results before anything reaches the AI model. Beyond that initial check, Warden also re-verifies permissions before every single call to the AI model and again before a final answer is given, so that if someone's access to a document is revoked mid conversation, that document gets removed from what the AI can see and cite. Importantly, the identity of the person asking is tied to the session on the server side, never something the AI model itself can influence through its input, which is meant to close off a class of prompt injection attacks that try to trick the agent into revealing something it should not. It is built in Python using FastAPI, with Postgres and its pgvector extension for storing both the permission data and the document vectors together, plus Redis for caching, and it can also work alongside OpenFGA, an existing permission system some teams already use. The project explicitly says it is not production hardened yet and describes itself as still shipping in stages, with a license still to be decided.

Yoink these prompts

Prompt 1
Explain Warden's three-gate architecture and why Gate 2 is the actual security boundary, not Gate 1.
Prompt 2
Walk me through running Warden locally with docker-compose and the seeded demo corpus.
Prompt 3
Show me how capability labels compress a user's authorized documents into a fast pre-filter for pgvector search.
Prompt 4
Explain why stale grants are dangerous but stale revocations are safe in Warden's permission model.

Frequently asked questions

wtf is warden?

A fail-closed authorization gateway that ensures AI agents only retrieve and cite documents a specific user is actually permitted to see, with per-turn revalidation.

What language is warden written in?

Mainly Python. The stack also includes Python, FastAPI, Postgres.

What license does warden use?

License is not yet decided, the README lists it as TBD.

How hard is warden to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is warden for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.