ADR-001: RS256 over HS256 for M2M Tokens

Status: Accepted Date: 2026-03 Deciders: Platform team (platform-0040)

Context

Arbitex issues OAuth 2.0 client credentials tokens for Machine-to-Machine (M2M) API access. These tokens must be verifiable by the Hybrid Outpost without requiring a round-trip to the platform on every request. Two signing schemes were considered:

HS256 (HMAC-SHA256): A symmetric scheme where the same secret key is used to both sign and verify tokens. This requires the verifying party (the outpost) to hold the secret, which means the secret must be distributed to every outpost deployment. If any outpost is compromised, the shared secret must be rotated across all outposts simultaneously.

RS256 (RSA-SHA256): An asymmetric scheme where the platform signs tokens with a private RSA key, and verifiers hold only the corresponding public key. The public key can be distributed freely — possession of it does not allow token forgery.

Decision

We use RS256 for all OAuth 2.0 M2M JWT tokens issued by the Arbitex Platform.

The JWKS endpoint (/.well-known/jwks.json) publishes the current RSA public key. Outposts fetch and cache the public key (configurable TTL, default 300 seconds) and validate incoming Bearer tokens locally using RS256 signature verification.

Consequences

Positive:

Outposts can verify tokens offline — no platform call required per request, reducing latency and eliminating a dependency on platform availability for token validation.
Compromising an outpost exposes only the public key (already public) — no signing capability is leaked.
Key rotation is operationally simpler: rotate the private key on the platform, publish new JWKS, and outposts pick up the new key on their next cache refresh cycle.
Aligns with industry-standard OAuth 2.0 deployment patterns (RFC 7517, RFC 7518).

Negative / trade-offs:

RS256 verification is computationally heavier than HS256 (~10×), though negligible for the request volumes handled by a single outpost.
Requires RSA key management infrastructure on the platform (key generation, rotation scheduling, JWKS endpoint).
JWKS cache introduces a propagation delay on key rotation (up to OAUTH_JWKS_CACHE_TTL seconds).

Configuration:

Outpost: OAUTH_JWKS_URL — JWKS endpoint URL; OAUTH_JWKS_CACHE_TTL — cache TTL in seconds (default 300).
Platform: RSA key pair managed by the secrets backend; public key published at /.well-known/jwks.json.