# Genie Connector OAuth Broker Service

## PURPOSE
In the demo, Genie reaches beyond the data lake into **external systems** — searching Gmail for field notes, then Google Drive for the Germany risk report — through connectors the admin has provisioned and the user has authorized with **their own credentials via an OAuth prompt**. Crucially, that design ensures "everything that you do access in your conversation with Genie is data that you actually have access to." This project is the service that makes that guarantee real: a broker that stores per-user, per-connector grants, mints scoped access tokens, proxies search calls over httpx, and writes an audit record of every external lookup.

## WHY THIS MATTERS
The trust lesson of the video has two halves: answers are grounded in sources, and those sources are only those the user is allowed to see. Identity-aware connectors are what stop an analytics assistant from becoming a data-leak. Students learn that "the agent found it in Drive" is really "an OAuth token with narrow scopes fetched it on the user's behalf, and we logged it."

## HOW TO BUILD
1. `pip install -r requirements.txt`; run with `uvicorn`.
2. Define SQLAlchemy models `User`, `Connector`, and `Grant(user_id, connector_id, scopes, token_ref, expires_at)` plus an append-only `AuditLog`.
3. Endpoints: `GET /connectors` (list available + authorized), `POST /authorize` (deterministic OAuth stub returning a fake token), `POST /search` (checks the grant, then `httpx` GETs the upstream search API), `GET /audit`.
4. Enforce scope checks before any outbound call; 403 when the grant is missing or expired.
5. Keep the OAuth exchange as a deterministic stub so tests never hit the network.

```python
@app.post("/search")
def search(req: SearchRequest, db: Session = Depends(get_db)):
    grant = db.query(Grant).filter_by(user_id=req.user_id,
                                      connector_id=req.connector_id).first()
    if not grant or grant.expires_at < now() or req.scope not in grant.scopes:
        raise HTTPException(403, "no valid grant for this connector")
    resp = httpx.get(UPSTREAM[req.connector_id], params={"q": req.query},
                     headers={"Authorization": f"Bearer {token_for(grant)}"})
    log(db, req)
    return resp.json()
```

## WHEN TO USE IN PRODUCTION
Use it whenever an assistant must reach SaaS systems (Drive, Gmail, SharePoint, Confluence, MCP servers) on a user's behalf with least-privilege scopes and an audit trail. Ideal for governed enterprise deployments. Do **not** use it for public, anonymous data, for machine-to-machine jobs that should use service accounts instead, or as a place to store raw long-lived passwords — store refresh tokens in a vault and reference them.

## HOW IT HELPS STUDENTS
They practise SQLAlchemy schema design, FastAPI dependency injection, httpx client patterns, OAuth/scope reasoning, and the audit-as-a-feature mindset. This is the security layer every agentic integration eventually needs.

## STARTER CODE
`starter/main.py` is a runnable FastAPI + SQLAlchemy + httpx skeleton with models, the four endpoints, a deterministic OAuth stub, and `# TODO` markers for token refresh and MCP transport.
