ADR-0001: Shared JWT for Devices (Defers Per-Device Tokens)

Status: Accepted (temporary)
Date: 2025-12-18
Authors: Dave Emmanuel Magno
Supersedes: None
Superseded by: None

Context

Devices must be able to authenticate and operate offline for days.
Opaque bearer tokens require an online introspection call for every verification, which breaks offline operation and introduces latency and coupling to the auth service.

JWTs verified against a published JWKS allow: - Offline verification with only public keys on the device. - Standard libraries and tooling. - Low-latency checks without network calls.

Per-device tokens would provide better isolation and revocation, but: - They require non-trivial provisioning flows (per-device identity, enrollment, storage). - They add operational overhead we are not ready to absorb yet.

Decision

  • Issue a single shared “fleet” JWT for all devices:
  • Key type: Ed25519
  • alg=EdDSA
  • Includes a stable kid for key lookup.
  • JWT claims:
  • iss: auth service issuer
  • sub: client / client_id representing the fleet
  • aud="devices"
  • scope: least-privilege set of device capabilities
  • jti: unique token identifier
  • iat, nbf: standard issuance / not-before
  • exp: 14–30 days (tunable, but short enough to limit risk)
  • Publish public keys at /.well-known/jwks.json with appropriate cache headers so devices can:
  • Fetch the JWKS when online.
  • Cache it locally for offline verification.
  • Keep /api/v1/introspect active for:
  • Opaque tokens (non-device clients, admin flows, migration).
  • Transitional use while moving more clients to JWT.

Trade-offs

Pros

  • Simple rollout: only one “fleet” token to issue and manage initially.
  • Full offline verification via JWT + JWKS; no dependency on live introspection.
  • Standard, fast verification using widely supported JWT libraries.

Cons

  • Larger blast radius: if the fleet token leaks, all devices are effectively compromised.
  • No per-device revoke or isolation; we cannot disable a single device’s access.

Mitigations

  • Use shorter exp (14–30 days) to bound the lifetime of a leaked token.
  • Implement and practice rapid key rotation for the Ed25519 keys.
  • Strictly protect the private key material (HSM, access controls, auditing).
  • Issue tokens with minimal scopes required for device behavior.
  • Audit token issuance and usage patterns for anomalies.

Consequences

  • All devices share one fleet JWT for now; device-level isolation is intentionally deferred.
  • Devices can verify tokens locally using the cached JWKS, including during multi-day offline periods.
  • Auth service must maintain both JWKS (/.well-known/jwks.json) and introspection (/api/v1/introspect) endpoints.
  • Security posture is acceptable only with strong operational controls (rotation, key protection, monitoring).

Tech Debt (Postponed)

  • Introduce per-device JWTs with aud=device_id (or similar) for:
  • Least-privilege access.
  • Per-device revocation and isolation.
  • Build automation for:
  • Device provisioning and identity assignment.
  • Secure token delivery and refresh to devices.
  • Migrate device flows from the shared fleet token to per-device tokens once the above is stable.