Implement RFID tag dump PWA with REST API, auth, and CI (#1)

Add Next.js app with SQLite/Drizzle storage for sites and LF/HF tag
dumps, multi-user Auth.js (credentials + optional OIDC), personal API
tokens in Settings, versioned /api/v1 for UI and future CLI use,
MCT/Proxmark/JSON import-export, PWA offline shell, Vitest tests, and
GitHub Actions CI.

Co-authored-by: Cursor Agent <[email protected]>

README.md

@@ -1 +1,101 @@
-# rfid-database
+# RFID Database
+
+PWA + REST API for storing LF/HF RFID tag dumps organized by site. Use the web UI in the field, or call `/api/v1` from scripts (and a future Proxmark CLI).
+
+## Features
+
+- Sites (A, B, C, …) with tag records (UID, protocol, keys, full dump)
+- Multi-user auth (shared workspace, no RBAC yet) — local password + optional OIDC
+- Personal API tokens (Settings UI) for Bearer auth
+- Export: JSON, Proxmark, MCT, hex
+- Import dumps + full JSON backup
+- Installable PWA with offline read of cached pages
+- Vitest unit/integration tests + GitHub Actions CI
+
+## Quick start
+
+```bash
+cp .env.example .env
+# set AUTH_SECRET to a long random string
+
+npm install
+npm run create-user -- --email [email protected] --password 'changeme' --name You
+npm run dev
+```
+
+Open http://localhost:3000 and sign in.
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AUTH_SECRET` | yes | NextAuth secret |
+| `RFID_DB_PATH` | no | SQLite path (default `./data/rfid.db`) |
+| `AUTH_OIDC_ISSUER` | no | OIDC issuer URL |
+| `AUTH_OIDC_CLIENT_ID` | no | OIDC client id |
+| `AUTH_OIDC_CLIENT_SECRET` | no | OIDC client secret |
+| `AUTH_OIDC_NAME` | no | Button label (default `SSO`) |
+| `NEXT_PUBLIC_AUTH_OIDC_ENABLED` | no | Set `1` to show SSO button |
+| `NEXT_PUBLIC_AUTH_OIDC_NAME` | no | Public SSO button label |
+
+## REST API (`/api/v1`)
+
+Authenticate with a session cookie **or** `Authorization: Bearer rfid_…` (create tokens under **Settings → API tokens**).
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET/POST | `/api/v1/sites` | List / create sites |
+| GET/PATCH/DELETE | `/api/v1/sites/{id}` | Site detail |
+| GET/POST | `/api/v1/tags` | List / create tags |
+| GET/PATCH/DELETE | `/api/v1/tags/{id}` | Tag detail |
+| PUT | `/api/v1/tags/by-uid/{uid}?siteId=` | Upsert by UID |
+| GET | `/api/v1/tags/{id}/export?format=` | `json` \| `proxmark` \| `mct` \| `hex` |
+| POST | `/api/v1/tags/import` | Parse dump → create tag |
+| GET | `/api/v1/search?q=` | Cross-site search |
+| GET/POST | `/api/v1/backup` | Full backup export / import |
+| GET/POST | `/api/v1/tokens` | List / create PATs |
+| DELETE | `/api/v1/tokens/{id}` | Revoke PAT |
+| GET | `/api/v1/me` | Current user |
+
+### curl examples
+
+```bash
+# Create a token in the UI first, then:
+export TOKEN=rfid_…
+export HOST=http://localhost:3000
+
+curl -sH "Authorization: Bearer $TOKEN" "$HOST/api/v1/sites"
+
+curl -sH "Authorization: Bearer $TOKEN" \
+  "$HOST/api/v1/tags/$ID/export?format=proxmark" -o dump.json
+
+curl -sH "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -X PUT "$HOST/api/v1/tags/by-uid/04A1B2C3?siteId=$SITE" \
+  -d '{"label":"Dock fob","frequency":"HF","protocol":"MIFARE_CLASSIC_1K","uid":"04A1B2C3","dumpData":{"size":"1K","sectors":[]},"keys":{"A":["FFFFFFFFFFFF"]}}'
+```
+
+## Tests & CI
+
+```bash
+npm test
+npm run lint
+npm run typecheck
+```
+
+GitHub Actions runs lint, typecheck, and tests on every pull request and push to `main`.
+
+## Docker
+
+```bash
+docker build -t rfid-database .
+docker run --rm -p 3000:3000 \
+  -e AUTH_SECRET=your-long-secret \
+  -v rfid-data:/data \
+  rfid-database
+```
+
+Create the first user against the mounted DB (exec into the container or run `create-user` with `RFID_DB_PATH` pointed at the volume).
+
+## Security
+
+Tag dumps often include sector keys. Keep the app behind HTTPS, do not expose it publicly without auth, and treat `data/rfid.db` as sensitive.