Skip to content

UC-010: Admin Manages NFC Keys and Access Rules

Actor: Admin (board member) Priority: Must Status: Draft (backend API implemented, signing workflow manual)

Summary

An admin registers new NFC keys, assigns them to members or guests, configures access rules via the backend API, then signs the updated allow-list offline with a sub-key and uploads it.

Preconditions

  • Admin has API key for the backend
  • Admin has access to an air-gapped signing device (or a machine with the sub-key)
  • Backend is running and database is accessible

Main Flow: Register a new member + key

  1. Admin creates a member: POST /api/v1/admin/members with name, email, role
  2. Admin registers the member's NFC card: POST /api/v1/admin/members/{id}/keys with UID (hex), label, access_type, time_slots, valid_from/until
  3. Admin downloads the unsigned allow-list: GET /api/v1/admin/allowlist/unsigned
  4. Admin signs the payload offline using the sub-key (Ed25519, air-gapped)
  5. Admin uploads the signed allow-list: PUT /api/v1/admin/allowlist/signed
  6. Backend verifies the signature against the master public key (defense-in-depth) and stores the payload
  7. ESP32 picks up the new allow-list at next sync (within 5 minutes)

Alternative Flows

A1: Revoke a key

  1. Admin deactivates a key: DELETE /api/v1/admin/keys/{key_id} or sets is_active to false
  2. Admin repeats steps 3–6 (download unsigned → sign → upload signed)
  3. ESP32 syncs — revoked key no longer grants access

A2: Modify access schedule

  1. Admin updates a key: PUT /api/v1/admin/keys/{key_id} with new time_slots or access_type
  2. Admin repeats steps 3–6
  3. Change takes effect at next sync

A3: Temporary guest key

  1. Admin creates a member with role "guest" (0x10)
  2. Registers a SCHEDULED key with valid_from and valid_until
  3. Signs and uploads the new allow-list
  4. After event: key expires automatically (valid_until passed), or admin deactivates it and re-signs

A4: Apply an access template

  1. Admin creates a key with template_id referencing a saved AccessTemplate
  2. Template pre-fills access_type, time_slots, grace_minutes, and notify_flags
  3. Admin can override any pre-filled field before saving

Error Flows

E1: Duplicate UID

  1. Admin tries to register a UID that's already registered to another key
  2. Backend returns 409 Conflict
  3. Admin must resolve the conflict (deactivate old key or use a different card)

E2: Invalid time slot

  1. Admin submits a key with invalid time (e.g., start_hour > 23 or more than 4 time slots)
  2. Backend returns 422 Validation Error with details

E3: Signature verification fails

  1. Admin uploads a signed payload with an invalid or mismatched signature
  2. Backend rejects with 400 Bad Request — payload not stored
  3. Admin must re-sign with the correct sub-key (one certified by the master key)

Postconditions

  • Member, key, and optional TOTP entry are stored in the database
  • A new signed allow-list is stored in the database
  • Change propagates to the ESP32 within 5 minutes

Access Rule

  • N/A (admin operation, not a door access event)

Notes

  • No signing keys on the backend: The master key and sub-keys never touch the server. The backend only holds the master public key for verification (see ADR-007).
  • The frontend/admin UI is planned for Phase 5. Until then, admins use the REST API directly (curl/httpie) and a local signing tool.
  • Audit log records all admin actions with timestamps and admin identity.
  • Revocation latency is at most 5 minutes (the sync interval). For immediate revocation, a future "push invalidation" mechanism could be added.