mirror of
https://github.com/Chewbaccalakis/rfid-database.git
synced 2026-09-09 16:01:56 -07:00
Cursor Agent
924b889f76
The previous merge commit accidentally retained <<<<<<< markers in Dockerfile, README, and .env.example, which broke docker compose build.
132 lines
3.9 KiB
Markdown
132 lines
3.9 KiB
Markdown
# 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
|
|
|
|
### docker compose (recommended)
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# set AUTH_SECRET to a long random string
|
|
|
|
# optional first user on boot:
|
|
# echo '[email protected]' >> .env
|
|
# echo 'CREATE_USER_PASSWORD=changeme' >> .env
|
|
|
|
docker compose up -d --build
|
|
```
|
|
|
|
App: http://localhost:3000 — SQLite persists in the `rfid-data` volume.
|
|
|
|
Create a user later (if you skipped bootstrap):
|
|
|
|
```bash
|
|
docker compose exec rfid-database \
|
|
npx tsx scripts/create-user.ts --email [email protected] --password 'secret' --name You
|
|
```
|
|
|
|
Stop / remove (keeps volume):
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
### Plain docker
|
|
|
|
```bash
|
|
docker build -t rfid-database .
|
|
docker run --rm -p 3000:3000 \
|
|
-e AUTH_SECRET=your-long-secret \
|
|
-e CREATE_USER_EMAIL=[email protected] \
|
|
-e CREATE_USER_PASSWORD=changeme \
|
|
-v rfid-data:/data \
|
|
rfid-database
|
|
```
|
|
|
|
## 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.
|