Payjoin-Mailroom Key rotation / Client caching mechanism

[zealsham]

OHTTP Key Rotation and Cache Control

Problem

OHTTP (Oblivious HTTP, RFC 9458) is the privacy layer in payjoin v2. Clients
encrypt requests using the gateway's public key. If a directory operator loses
their key material or needs to rotate keys, every client holding the old key is
broken with no standard signal to refresh.

Previously, the gateway served keys with no Cache-Control header and returned
HTTP 400 on decapsulation failure. Clients had no way to distinguish a stale key
from a malformed request, and operators had no mechanism to control how long
clients cached keys or to rotate them automatically.

#445

#1035 this attempd to implement keys-catching, but would be retired for the solution below

Solution

#1449

A single configuration value, ohttp_keys_max_age, controls both client caching
and server-side key rotation. When set, it defines:

1. The Cache-Control: public, max-age=<seconds> header on the key endpoint,
   telling clients and intermediaries how long to cache the key.
2. The interval at which the server automatically generates a new key.
3. The overlap window during which the previous key remains valid for
   decapsulation, so clients with cached old keys continue to work.

When unset (the default), keys are served without cache headers and no rotation
occurs, preserving the previous behavior.

How It Works

Configuration

# Rotate keys every 7 days. Clients cache for the same duration.
ohttp_keys_max_age = 604800

Or via environment variable: PJ_OHTTP_KEYS_MAX_AGE=604800

Key Lifecycle

Each OHTTP key has a key_id (a single byte, 0–255) embedded in the first byte
of every encrypted message. The server uses this to dispatch decapsulation to the
correct key.

When rotation is enabled, the server manages keys through three phases:

Active phase. The key is served to new clients on
GET /.well-known/ohttp-gateway with a Cache-Control header. All incoming
requests encrypted with this key are decapsulated normally.

Overlap phase. A new key has been generated and is now being served to
clients. The old key is no longer advertised but still accepted for
decapsulation. This phase lasts ohttp_keys_max_age seconds — long enough for
all well-behaved caches to expire.

Retired. The old key is removed from memory and its .ikm file is deleted
from disk. Any request using this key now receives HTTP 422 with an
application/problem+json body of type ohttp-key, signaling the client to
fetch a fresh key.

Timeline Example (7-day rotation)

Day  1: key_id=1 generated, served to clients with max-age=604800
Day  8: key_id=2 generated, now served. key_id=1 enters overlap.
Day 15: key_id=1 retired. key_id=3 generated, key_id=2 enters overlap.
Day 22: key_id=2 retired. And so on.

At any point, at most two keys are active simultaneously.

Client Perspective

A client that respects Cache-Control re-fetches the key when its cache expires,
naturally picking up the new key before the old one is retired. No disruption.

A client using a stale key (e.g. from an old BIP21 URI with an embedded OH1
fragment) sees:

1. POST to the gateway fails with 422 Unprocessable Entity and a problem+json
   body: {"type":"https://iana.org/assignments/http-problem-types#ohttp-key", "title": "key identifier unknown"}.
2. Client fetches fresh keys from GET /.well-known/ohttp-gateway.
3. Client retries with the new key.

For payjoin-cli my intended caching approach is

1. Store the fetched key alongside the time it was fetched and the max-age value from the response header
2. Before each operation, check whether now - fetch_time > max_age
3. If the cache is still fresh, use the stored key without a network request
   I4. if expired, re-fetch from the directory before proceeding

The 422 status code is mandated by RFC 9458 (sections 5.2, 6.4) for requests the
server cannot decapsulate due to an unknown key identifier.

Operator Guidance

Goal	Configuration
No rotation (static key)	Omit ohttp_keys_max_age
Weekly rotation	ohttp_keys_max_age = 604800
Daily rotation	ohttp_keys_max_age = 86400
paranoid (hourly)	ohttp_keys_max_age = 3600

Shorter intervals mean clients must refresh keys more frequently but reduce the
window of exposure if key material is compromised. The overlap window always
equals the configured max-age, so there is no disruption for clients that honor
the cache headers.