Refresh an issuer value when the issuer orders it

[czpython]

What changes

• POST /refresh/{host_id}/{service} on the exchange. An issuer that ends a value before its expiry, as an OAuth provider does when it revokes the previous token at a refresh, orders a refresh. The exchange forgets the held value, fetches now, and on a provider that holds the value pushes at once.
• Secrets.refresh replaces the entry's RefreshableSecret with a fresh one and runs the existing push or refresh on it, so the retry wait and the push bookkeeping stay the code they are. It raises IssuerUnavailableError when nothing valid came back.
• Answers: 200 after the refresh and the push. 503 with Retry-After: 5 when the issuer gave nothing usable or the push failed, and the entry then waits as after any failed fetch. 404 for an unknown host or service. 409 for a static entry. The route logs the host and the service, never a value.
• Tests: a proxy entry serves the new value on the next /authorize with no wait, an sbx entry gets the new value pushed at once and the timer finds it fresh afterwards, a failed fetch answers 503 and the next request waits out the retry delay, a failed push answers 503 and logs no value, an unknown host or service, and a static entry.
• docs/api.md lists the exchange's endpoints. docs/security.md states the order's trust: no value, no token, one fetch at most. docs/architecture.md describes the flow.

Where this differs from the ticket

• Nothing. Secrets.current and the push timer are unchanged.

Names

Secrets.refresh, beside current and push. The route is refresh, the word the exchange already uses for the act.

Gates

uv run ruff check, uv run ruff format --check, uv run pyright, and uv run pytest are green, 680 tests.

Review

Pending.

🤖 Generated with Claude Code