rfid-database/README.md

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

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

# 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

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)

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):

docker compose exec rfid-database \
  npx tsx scripts/create-user.ts --email [email protected] --password 'secret' --name You

Stop / remove (keeps volume):

docker compose down

Plain docker

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.