fix(register): make client_id TTL configurable, default 7d (#28)

The sealed client_id minted by POST /register previously used
a hardcoded 24h TTL. Refresh tokens last 7 days, so any MCP
client running longer than 24h failed its first refresh-token
rotation with `invalid_client: client registration expired`,
even with a still-valid refresh token. Most MCP clients
(codex_rmcp_client, Claude Code, Cursor, …) treat DCR as
one-shot at startup and surface the error to the user
instead of re-registering.

Fix:

  - Default TTL bumped to 7 days, matching refreshTokenTTL so
    the sealed client_id always covers a full refresh-token
    cycle.

  - New CLIENT_REGISTRATION_TTL env var lets operators raise
    or lower the envelope. Go duration syntax; capped at 90d
    at startup (wider windows extend the residual-reuse threat
    of an exfiltrated client_id with no operational upside).

  - Register handler signature gains a clientTTL parameter.
    All call sites (main.go + tests) pass either the wired
    cfg.ClientRegistrationTTL or DefaultClientTTL.

  - Regression test (TestTokenRefresh_ClientLifecycleAroundTTL)
    covers three boundary points: 48h-old (the bug repro),
    6d23h-old (just inside the 7d envelope), and 1m past
    expiry (must reject).

  - 5 config tests for the env var: default, custom, non-
    positive reject, above-cap reject, bad-format reject (the
    "7d" case — time.ParseDuration doesn't accept the d
    suffix; documented).

Rolling-deploy note: the TTL is sealed into each client_id at
registration time. Bumping the env var only affects newly-
issued client_ids; existing registrations stay on whatever
TTL was in effect when they were minted. Documented in the
new docs/runbooks/client-registration-expired.md.

Author: babs

README.md

@@ -140,6 +140,7 @@ All configuration via **environment variables**. Bold = required.
 | `REDIS_REQUIRED` | `true` | Fail startup when `REDIS_URL` is unset. Set `false` only for dev / single-replica; stateless mode leaves codes/refresh replayable within TTL |
 | `REDIS_KEY_PREFIX` | `mcp-auth-proxy:` | Key prefix for shared Redis; set to empty to opt out of namespacing |
 | `REFRESH_RACE_GRACE_SEC` | `2` | Grace window in seconds during which a refresh-rotation collision is treated as a benign concurrent submit (parallel-tab refresh, slow-network double-submit) and returns 429 `refresh_concurrent_submit` without revoking the family. Outside the window every collision still revokes. Range `[0, 10]`; `0` disables (every collision = reuse). The 10s ceiling is a security cap — wider windows are statistically attacker-shaped |
+| `CLIENT_REGISTRATION_TTL` | `168h` (7d) | Lifetime of a sealed `client_id` minted by `POST /register`. Default matches the 7-day refresh-token TTL so a client holding a still-valid refresh can always exchange it; a shorter value silently kills long-running MCP clients (which treat DCR as one-shot at startup) the moment their access token first expires. Go duration syntax (`168h`, `720h`, …); capped at 90d. **Rolling-deploy note:** the TTL is sealed into each `client_id` at registration time, so bumping this env var only affects newly-issued client_ids — existing registrations stay on whatever TTL was in effect when they were minted. See [`docs/runbooks/client-registration-expired.md`](./docs/runbooks/client-registration-expired.md) |
 | `IDP_EXCHANGE_RATE_PER_SEC` | _(empty / disabled)_ | Cap on outbound proxy → IdP token-endpoint requests at `/callback`. Defense in depth: a flood of `/callback` hits that slips past the per-IP limiter (distributed sources, permissive XFF trust matrix) is bounded by this token bucket before reaching the IdP. Denied requests get 503 `temporarily_unavailable` + `error_code=idp_exchange_throttled` + `Retry-After: 1`. Set to a positive number (e.g. `20`) to enable |
 | `IDP_EXCHANGE_BURST` | `50` | Burst size for the IdP-exchange limiter when `IDP_EXCHANGE_RATE_PER_SEC > 0`. Higher burst absorbs a short spike (e.g. a deploy-time reconnect storm) without 503s; lower burst keeps the ceiling tighter. Ignored when `IDP_EXCHANGE_RATE_PER_SEC` is unset/zero (limiter is not constructed) |
 | `RATE_LIMIT_ENABLED` | `true` | Per-IP rate limiting on pre-auth endpoints and on the authenticated MCP route. Disable only behind a WAF that already enforces it |
@@ -173,7 +174,7 @@ payloads alone remain replayable within their TTL.
 
 | Flow state | Encrypted into | TTL |
 |---|---|---|
-| Client registration | `client_id` | 24h |
+| Client registration | `client_id` | 7d (configurable via `CLIENT_REGISTRATION_TTL`) |
 | Authorize session | IdP `state` parameter | 10min |
 | Authorization code | `code` parameter | 60s |
 | Access token | Opaque bearer | 1h |

config/config.go

@@ -72,6 +72,15 @@ type Config struct {
 	// IdPExchangeBurst is the burst size for the IdP-exchange limiter
 	// when IdPExchangeRatePerSec > 0. env: IDP_EXCHANGE_BURST.
 	IdPExchangeBurst int
+	// ClientRegistrationTTL is the lifetime of a sealed client_id
+	// minted by POST /register. Defaults to 7 days so the envelope
+	// always covers a full refresh-token cycle — a shorter value
+	// would silently kill long-running MCP clients (which treat DCR
+	// as one-shot at startup) the moment their access token first
+	// expired. env: CLIENT_REGISTRATION_TTL (Go duration: 168h, 7d-
+	// equivalent values like 168h0m0s, etc.; "d" suffix not supported
+	// by time.ParseDuration).
+	ClientRegistrationTTL time.Duration
 	// CompatAllowStateless keeps the legacy Cursor/MCP Inspector behavior of
 	// accepting /authorize requests without a client-supplied state. Default
 	// false — strict mode refuses stateless requests so the client cannot
@@ -352,6 +361,27 @@ func Load() (*Config, error) {
 		c.IdPExchangeBurst = n
 	}
 
+	// CLIENT_REGISTRATION_TTL: how long a sealed client_id stays
+	// openable. Default 7d so a client holding a still-valid
+	// refresh token (refreshTokenTTL = 7d) can always exchange it.
+	// Hard cap at 90d — a longer envelope materially extends the
+	// window an exfiltrated client_id (which is unauthenticated
+	// metadata) can be reused.
+	c.ClientRegistrationTTL = 7 * 24 * time.Hour
+	if raw := os.Getenv("CLIENT_REGISTRATION_TTL"); raw != "" {
+		d, err := time.ParseDuration(raw)
+		if err != nil {
+			return nil, fmt.Errorf("CLIENT_REGISTRATION_TTL must be a Go duration (e.g. 168h, 24h, 720h): %w", err)
+		}
+		if d <= 0 {
+			return nil, fmt.Errorf("CLIENT_REGISTRATION_TTL must be positive, got %s", d)
+		}
+		if d > 90*24*time.Hour {
+			return nil, fmt.Errorf("CLIENT_REGISTRATION_TTL exceeds 90d cap, got %s", d)
+		}
+		c.ClientRegistrationTTL = d
+	}
+
 	if ag := os.Getenv("ALLOWED_GROUPS"); ag != "" {
 		for _, g := range strings.Split(ag, ",") {
 			if g = strings.TrimSpace(g); g != "" {

config/config_test.go

@@ -361,6 +361,56 @@ func TestLoad_IdPExchangeBurst_RejectsZero(t *testing.T) {
 	}
 }
 
+func TestLoad_ClientRegistrationTTL_Default(t *testing.T) {
+	setAllRequired(t)
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if cfg.ClientRegistrationTTL != 7*24*time.Hour {
+		t.Errorf("ClientRegistrationTTL default = %v, want 168h (7d)", cfg.ClientRegistrationTTL)
+	}
+}
+
+func TestLoad_ClientRegistrationTTL_Custom(t *testing.T) {
+	setAllRequired(t)
+	t.Setenv("CLIENT_REGISTRATION_TTL", "720h")
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if cfg.ClientRegistrationTTL != 720*time.Hour {
+		t.Errorf("ClientRegistrationTTL = %v, want 720h", cfg.ClientRegistrationTTL)
+	}
+}
+
+func TestLoad_ClientRegistrationTTL_RejectsNonPositive(t *testing.T) {
+	setAllRequired(t)
+	t.Setenv("CLIENT_REGISTRATION_TTL", "0s")
+	_, err := Load()
+	if err == nil || !strings.Contains(err.Error(), "positive") {
+		t.Fatalf("want positive rejection, got %v", err)
+	}
+}
+
+func TestLoad_ClientRegistrationTTL_RejectsAboveCap(t *testing.T) {
+	setAllRequired(t)
+	t.Setenv("CLIENT_REGISTRATION_TTL", "2400h") // 100 days, > 90d cap
+	_, err := Load()
+	if err == nil || !strings.Contains(err.Error(), "90d cap") {
+		t.Fatalf("want 90d-cap rejection, got %v", err)
+	}
+}
+
+func TestLoad_ClientRegistrationTTL_RejectsBadFormat(t *testing.T) {
+	setAllRequired(t)
+	t.Setenv("CLIENT_REGISTRATION_TTL", "7d") // time.ParseDuration doesn't accept "d"
+	_, err := Load()
+	if err == nil || !strings.Contains(err.Error(), "Go duration") {
+		t.Fatalf("want format-error, got %v", err)
+	}
+}
+
 func TestLoad_PKCERequired_Default(t *testing.T) {
 	setAllRequired(t)
 	cfg, err := Load()

docs/runbooks/client-registration-expired.md

@@ -0,0 +1,102 @@
+# Runbook — `invalid_client: client registration expired`
+
+When an MCP client (Claude Code, codex_rmcp_client, Cursor, …)
+fails with:
+
+```
+OAuth token refresh failed: Server returned error response:
+invalid_client: client registration expired
+```
+
+it has been alive longer than the sealed `client_id`'s TTL.
+DCR is one-shot for most MCP clients, so they don't auto-
+re-register and the user sees the error directly.
+
+## Signals
+
+- Per-client log line: `client_registration_expired`
+  (`handlers/helpers.go`, fired by `openAndValidateClient`).
+- Counter: `mcp_auth_access_denied_total{reason="invalid_client"}`
+  with `error_description="client registration expired"` in the
+  log line that accompanies it.
+- User report: "MCP server stopped working after a few days of
+  uptime, restart fixes it."
+
+## Why it happens
+
+The sealed `client_id` returned by `POST /register` has a
+lifetime baked into its encrypted payload (`ExpiresAt`). After
+that timestamp, every endpoint that re-validates the
+`client_id` (`/authorize`, `/token` for both grant types)
+rejects with `invalid_client: client registration expired`.
+
+The lifetime is the `CLIENT_REGISTRATION_TTL` env var, default
+**7 days** (matches `refreshTokenTTL` so a client holding a
+still-valid refresh can always exchange it). Cap is 90 days.
+
+## Response
+
+### Client side
+
+The MCP client must re-register: re-run DCR (`POST /register`)
+to obtain a fresh `client_id` + retry the OAuth flow from
+`/authorize`. Most MCP clients do this on a fresh connection,
+so a restart of the client is the simplest fix.
+
+### Operator side
+
+If users are hitting this faster than `CLIENT_REGISTRATION_TTL`
+suggests they should:
+
+1. **Verify `CLIENT_REGISTRATION_TTL` is what you think.**
+   `kubectl exec ... -- env | grep CLIENT_REGISTRATION_TTL`.
+2. **Check `REVOKE_BEFORE`.** `REVOKE_BEFORE` rejects access
+   tokens whose `iat` predates the cutoff, but does NOT shorten
+   `client_id` lifetime. If both fire on the same flow, the
+   user sees `invalid_client` (client_id check runs first); the
+   actual cause may be the token cutoff. Logs disambiguate.
+3. **Lengthen the TTL** for long-running deployments by setting
+   `CLIENT_REGISTRATION_TTL=720h` (30d) or up to the 90d cap.
+4. **Consider Option 4** (auto-extend `client_id` on each
+   `/token` use) — see `misc/next-steps.md`. Not yet
+   implemented as of this writing.
+
+## Rolling-deploy transient
+
+Bumping `CLIENT_REGISTRATION_TTL` does **NOT** retroactively
+extend already-issued `client_id`s. The TTL is sealed into the
+encrypted payload at registration time. Existing clients
+running on the old TTL keep that TTL until they re-register,
+no matter what the env var says now. Plan accordingly:
+- A deploy that raises the TTL takes effect immediately for
+  newly-registered clients.
+- Already-affected users won't be unblocked until their MCP
+  client re-registers (manual restart, or running long enough
+  to hit any other re-registration trigger).
+
+## What NOT to do
+
+- **Don't disable `CLIENT_REGISTRATION_TTL` checks.** The TTL
+  bounds the residual reach of an exfiltrated `client_id`
+  (which is unauthenticated metadata sent in the clear on
+  `/authorize`). A 0 or near-infinite value silently extends
+  that window.
+- **Don't try to extend an existing `client_id` server-side.**
+  The sealed payload is immutable. The only way to extend is
+  re-issuing a fresh `client_id`.
+- **Don't increase past 90d** (capped at startup). Wider
+  windows add no operational value once the auto-extend design
+  ships, and increase the residual-reuse threat in the
+  meantime.
+
+## Prevention
+
+- **Default `CLIENT_REGISTRATION_TTL` matches refresh-token
+  lifetime (7d).** A client that successfully refreshes its
+  access token at least every 7d cycles its session before
+  the `client_id` envelope lapses. Long-idle clients are
+  the failure mode this runbook catches.
+- **Document re-registration in the MCP client's own UX.**
+  Out of scope for the proxy; in scope for the client author
+  if the client expects long-lived sessions without
+  intervention.

e2e_test.go

@@ -205,7 +205,7 @@ func buildTestProxy(t *testing.T, oidcProvider *mockOIDCProvider, mcpServer *moc
 
 	r := chi.NewRouter()
 	registerDiscoveryRoutes(r, proxyBaseURL, "/mcp", "", nil)
-	r.Post("/register", handlers.Register(tm, zap.NewNop(), proxyBaseURL))
+	r.Post("/register", handlers.Register(tm, zap.NewNop(), proxyBaseURL, handlers.DefaultClientTTL))
 	r.Get("/authorize", handlers.Authorize(tm, zap.NewNop(), proxyBaseURL, oauth2Cfg, handlers.AuthorizeConfig{
 		PKCERequired:      true,
 		CanonicalResource: proxyBaseURL + "/mcp",