---
category: reference
tags: [spike, atproto, oauth, auth]
last_updated: 2026-03-15
confidence: high
---

# VS-1: ATProto OAuth Spike

## Status: COMPLETE — ready for manual deployment and testing

## What was built

A throwaway spike adapting the [Bluesky cookbook Flask OAuth demo](https://github.com/bluesky-social/cookbook/tree/main/python-oauth-web-app) (CC-0) for robot.wtf identity-only authentication.

**Branch:** `feat/vs-1-atproto-spike` in the robot.wtf repo
**Location:** `spike/atproto-oauth/`

## Key adaptations from cookbook demo

1. **Scope changed to `"atproto"`** — identity-only, no PDS write access. The ATProto spec explicitly supports this for "Login with atproto" use cases.
2. **Fixed client_id** at `https://robot.wtf/auth/client-metadata.json` (cookbook dynamically computes it from request host)
3. **All routes under `/auth/`** prefix to match Caddy routing
4. **JWK loaded from file** (`/srv/data/client_jwk.json`) instead of environment variable
5. **Inline JWKS** in client metadata instead of separate `jwks_uri` endpoint (simpler for spike)
6. **Profile page** displays DID, handle, and display name (fetched from public Bluesky API)
7. **Removed** Bluesky posting feature, `atproto_util.py`, `bsky_util.py`
8. **Removed** `regex` dependency — using stdlib `re` (no Unicode handle validation needed for spike)

## Files

| File | Lines | Source |
|------|-------|--------|
| `app.py` | ~280 | Heavily adapted from cookbook `app.py` |
| `atproto_oauth.py` | ~230 | Cookbook, removed `pds_authed_req` |
| `atproto_identity.py` | ~100 | Cookbook, unchanged |
| `atproto_security.py` | ~40 | Cookbook, unchanged |
| `schema.sql` | ~20 | Cookbook, unchanged |
| `templates/` | 4 files | New (simpler than cookbook) |
| `requirements.txt` | 6 deps | Subset of cookbook |

## Smoke test results

- Flask app starts and initializes SQLite database
- `/auth/client-metadata.json` serves correct JSON with all required ATProto OAuth fields
- `/auth/login` renders login form
- `/auth/` redirects to `/auth/login` when not authenticated
- Public key in JWKS contains no private material (`d` field absent)

## Dependencies

```
Flask>=3.0
authlib>=1.3
dnspython>=2.6
requests>=2.32
requests-hardened>=1.0.0b3
cryptography>=41.0
```

## Deployment steps

1. Copy `spike/atproto-oauth/` to VPS at `/srv/app/atproto-spike/`
2. Install deps in `/srv/app/venv`
3. Set `FLASK_SECRET_KEY` env var
4. Run `flask --app app run --host 127.0.0.1 --port 8003`
5. Test at `https://robot.wtf/auth/login`

## What to watch for during manual testing

- **DPoP nonce errors**: The spike preserves the cookbook's retry-on-nonce-error pattern. If the first PAR request fails with `use_dpop_nonce`, it retries with the server-provided nonce. Watch logs for `"retrying with new auth server DPoP nonce"`.
- **Client metadata fetch**: The PDS fetches `https://robot.wtf/auth/client-metadata.json` during PAR. If Caddy isn't routing correctly or the response is malformed, PAR will fail with a 400.
- **Scope verification**: The callback asserts `tokens["scope"] == "atproto"`. If the AS returns a different scope string, the assertion will fail. This is the most likely breakage point.
- **Session cookie**: Requires `FLASK_SECRET_KEY`. Without it, Flask will error on any session operation.

## Findings for V3 production implementation

1. The cookbook code is well-structured and directly usable. The `atproto_oauth.py` and `atproto_identity.py` modules can transfer to production with minimal changes.
2. Identity-only scope (`"atproto"`) is confirmed supported by the spec. The `sub` field in the token response contains the DID.
3. `requests-hardened` upgraded to 1.2.0 (stable, no longer beta). SSRF mitigations work.
4. The `authlib.jose` module handles all JWT/JWK operations (no `joserfc` needed).
5. For production: replace SQLite session store with the platform's user/session tables, mint platform JWT on successful auth, add error handling beyond bare `assert` statements.