feat: add confidential OAuth client support for longer-lived sessions (#578)

* feat: add confidential OAuth client support for longer-lived sessions

adds support for ATProto OAuth confidential clients using private_key_jwt
authentication. when OAUTH_JWK is configured, the client authenticates
with a cryptographic key, earning 180-day refresh tokens (vs 2-week for
public clients).

changes:
- add OAUTH_JWK setting to AtprotoSettings for ES256 private key
- update OAuthClient to pass client_secret_key when configured
- add /.well-known/jwks.json endpoint for public key discovery
- update /oauth-client-metadata.json to include confidential client fields
- add scripts/gen_oauth_jwk.py utility to generate keys
- add tests for is_confidential_client() and get_public_jwks()

to enable:
1. run: uv run python scripts/gen_oauth_jwk.py
2. add output to .env as OAUTH_JWK='...'

closes #577

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

* address review comments: remove deferred imports, add type annotations

- move imports to top level in main.py (is_confidential_client, get_public_jwks, HTTPException)
- add type annotation to metadata variable: dict[str, Any]
- update return types to dict[str, Any]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

* docs: add OAuth confidential client documentation

explains what confidential clients are, why they matter for plyr.fm,
and how the implementation works. includes sources and key rotation
guidance.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

* docs: add token refresh mechanism and migration notes

- explain how token refresh works (trigger, detection, refresh, retry)
- document what gets refreshed (access vs refresh tokens)
- add observability notes (logfire log messages)
- document migration impact for existing sessions
- clarify that existing tokens can't be upgraded (2-week refresh limit)
- note that only 3 internal dev tokens affected in production

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

---------

Co-authored-by: Claude Opus 4.5 <[e-mail]>

backend/src/backend/_internal/auth.py

···
 import secrets
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
-from typing import Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any
 
 from atproto_oauth import OAuthClient
 from atproto_oauth.stores.memory import MemorySessionStore
 from cryptography.fernet import Fernet
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.serialization import load_pem_private_key
 from fastapi import Cookie, Header, HTTPException
+from jose import jwk
 from sqlalchemy import select
 
 from backend._internal.oauth_stores import PostgresStateStore
 from backend.config import settings
 from backend.models import ExchangeToken, PendingDevToken, UserPreferences, UserSession
 from backend.utilities.database import db_session
+
+if TYPE_CHECKING:
+    from cryptography.hazmat.primitives.asymmetric.ec import EllipticCurvePrivateKey
 
 logger = logging.getLogger(__name__)
 
···
 _state_store = PostgresStateStore()
 _session_store = MemorySessionStore()
 
+# confidential client key (loaded lazily)
+_client_secret_key: "EllipticCurvePrivateKey | None" = None
+_client_secret_key_loaded = False
+
+
+def _load_client_secret_key() -> "EllipticCurvePrivateKey | None":
+    """load EC private key from OAUTH_JWK setting for confidential client.
+
+    the key is expected to be a JSON-serialized JWK with ES256 (P-256) key.
+    returns None if OAUTH_JWK is not configured (public client mode).
+    """
+    global _client_secret_key, _client_secret_key_loaded
+
+    if _client_secret_key_loaded:
+        return _client_secret_key
+
+    _client_secret_key_loaded = True
+
+    if not settings.atproto.oauth_jwk:
+        logger.info("OAUTH_JWK not configured, using public OAuth client")
+        return None
+
+    try:
+        # parse JWK JSON
+        jwk_data = json.loads(settings.atproto.oauth_jwk)
+
+        # convert JWK to PEM format using python-jose
+        key_obj = jwk.construct(jwk_data, algorithm="ES256")
+        pem_bytes = key_obj.to_pem()
+
+        # load as cryptography key
+        _client_secret_key = load_pem_private_key(pem_bytes, password=None)
+
+        if not isinstance(_client_secret_key, ec.EllipticCurvePrivateKey):
+            raise ValueError("OAUTH_JWK must be an EC key (ES256)")
+
+        logger.info("loaded confidential OAuth client key from OAUTH_JWK")
+        return _client_secret_key
+
+    except Exception as e:
+        logger.error(f"failed to load OAUTH_JWK: {e}")
+        raise RuntimeError(f"invalid OAUTH_JWK configuration: {e}") from e
+
+
+def get_public_jwks() -> dict | None:
+    """get public JWKS for the /.well-known/jwks.json endpoint.
+
+    returns None if confidential client is not configured.
+    """
+    if not settings.atproto.oauth_jwk:
+        return None
+
+    try:
+        # parse private JWK
+        jwk_data = json.loads(settings.atproto.oauth_jwk)
+
+        # construct key and extract public components
+        key_obj = jwk.construct(jwk_data, algorithm="ES256")
+        public_jwk = key_obj.to_dict()
+
+        # remove private key components, keep only public
+        public_jwk.pop("d", None)  # private key scalar
+
+        # ensure required fields for public key
+        public_jwk["use"] = "sig"
+        public_jwk["alg"] = "ES256"
+
+        return {"keys": [public_jwk]}
+
+    except Exception as e:
+        logger.error(f"failed to generate public JWKS: {e}")
+        return None
+
+
+def is_confidential_client() -> bool:
+    """check if confidential OAuth client is configured."""
+    return bool(settings.atproto.oauth_jwk)
+
 
 def get_oauth_client(include_teal: bool = False) -> OAuthClient:
     """create an OAuth client with the appropriate scopes.
 
     at ~17 OAuth flows/day, instantiation cost is negligible.
     this eliminates the need for pre-instantiated bifurcated clients.
+
+    if OAUTH_JWK is configured, creates a confidential client with
+    private_key_jwt authentication (180-day refresh tokens).
+    otherwise creates a public client (2-week refresh tokens).
     """
     scope = (
         settings.atproto.resolved_scope_with_teal(
···
         if include_teal
         else settings.atproto.resolved_scope
     )
+
+    # load confidential client key if configured
+    client_secret_key = _load_client_secret_key()
+
     return OAuthClient(
         client_id=settings.atproto.client_id,
         redirect_uri=settings.atproto.redirect_uri,
         scope=scope,
         state_store=_state_store,
         session_store=_session_store,
+        client_secret_key=client_secret_key,
     )
 
 

backend/src/backend/config.py

···
         validation_alias="OAUTH_ENCRYPTION_KEY",
         description="Fernet encryption key for OAuth data at rest",
     )
+    oauth_jwk: str = Field(
+        default="",
+        validation_alias="OAUTH_JWK",
+        description="JSON-serialized ES256 private key for confidential OAuth client. Generate with: uv run python scripts/gen_oauth_jwk.py",
+    )
 
     @computed_field
     @property

backend/src/backend/main.py

···
 from contextlib import asynccontextmanager
 from typing import Any
 
-from fastapi import FastAPI, Request, WebSocket
+from fastapi import FastAPI, HTTPException, Request, WebSocket
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import ORJSONResponse
 from slowapi import _rate_limit_exceeded_handler
···
 )
 
 from backend._internal import notification_service, queue_service
+from backend._internal.auth import get_public_jwks, is_confidential_client
 from backend._internal.background import background_worker_lifespan
 from backend.api import (
     account_router,
···
 
 
 @app.get("/oauth-client-metadata.json")
-async def client_metadata() -> dict:
-    """serve OAuth client metadata."""
-    # Extract base URL from client_id for client_uri
+async def client_metadata() -> dict[str, Any]:
+    """serve OAuth client metadata.
+
+    returns metadata for public or confidential client depending on
+    whether OAUTH_JWK is configured.
+    """
+    # extract base URL from client_id for client_uri
     client_uri = settings.atproto.client_id.replace("/oauth-client-metadata.json", "")
 
-    return {
+    metadata: dict[str, Any] = {
         "client_id": settings.atproto.client_id,
         "client_name": settings.app.name,
         "client_uri": client_uri,
···
         ),
         "grant_types": ["authorization_code", "refresh_token"],
         "response_types": ["code"],
-        "token_endpoint_auth_method": "none",
         "application_type": "web",
         "dpop_bound_access_tokens": True,
     }
+
+    if is_confidential_client():
+        # confidential client: use private_key_jwt authentication
+        # this gives us 180-day refresh tokens instead of 2-week
+        metadata["token_endpoint_auth_method"] = "private_key_jwt"
+        metadata["token_endpoint_auth_signing_alg"] = "ES256"
+        metadata["jwks_uri"] = f"{client_uri}/.well-known/jwks.json"
+    else:
+        # public client: no authentication
+        metadata["token_endpoint_auth_method"] = "none"
+
+    return metadata
+
+
[e-mail]("/.well-known/jwks.json")
+async def jwks_endpoint() -> dict[str, Any]:
+    """serve public JWKS for confidential client authentication.
+
+    returns 404 if confidential client is not configured.
+    """
+    jwks = get_public_jwks()
+    if jwks is None:
+        raise HTTPException(
+            status_code=404,
+            detail="JWKS not available - confidential client not configured",
+        )
+
+    return jwks

backend/tests/test_auth.py

···
 
 import json
 from datetime import UTC, datetime, timedelta
+from unittest.mock import patch
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
···
     create_exchange_token,
     create_session,
     delete_session,
+    get_public_jwks,
     get_session,
+    is_confidential_client,
     update_session_tokens,
 )
 from backend.models import ExchangeToken, UserSession
···
     actual_expiry = db_session_record.expires_at.replace(tzinfo=UTC)
     diff = abs((expected_expiry - actual_expiry).total_seconds())
     assert diff < 60  # within 1 minute
+
+
+# confidential client tests
+
+
+def test_is_confidential_client_false_by_default():
+    """verify is_confidential_client returns False when OAUTH_JWK not set."""
+    # tests run without OAUTH_JWK configured
+    assert is_confidential_client() is False
+
+
+def test_is_confidential_client_true_when_configured():
+    """verify is_confidential_client returns True when OAUTH_JWK is set."""
+    test_jwk = '{"kty":"EC","crv":"P-256","x":"test","y":"test","d":"test"}'
+
+    with patch("backend._internal.auth.settings.atproto.oauth_jwk", test_jwk):
+        assert is_confidential_client() is True
+
+
+def test_get_public_jwks_returns_none_without_config():
+    """verify get_public_jwks returns None when OAUTH_JWK not configured."""
+    # tests run without OAUTH_JWK configured
+    assert get_public_jwks() is None
+
+
+def test_get_public_jwks_returns_public_key():
+    """verify get_public_jwks returns JWKS with public key only."""
+    # generate a test JWK
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec
+    from jose import jwk as jose_jwk
+
+    # generate test key
+    private_key = ec.generate_private_key(ec.SECP256R1())
+    pem_bytes = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    key_obj = jose_jwk.construct(pem_bytes, algorithm="ES256")
+    test_jwk = json.dumps(key_obj.to_dict())
+
+    with patch("backend._internal.auth.settings.atproto.oauth_jwk", test_jwk):
+        jwks = get_public_jwks()
+
+        assert jwks is not None
+        assert "keys" in jwks
+        assert len(jwks["keys"]) == 1
+
+        public_key = jwks["keys"][0]
+        # should NOT have private key component
+        assert "d" not in public_key
+        # should have public key components
+        assert "x" in public_key
+        assert "y" in public_key
+        assert public_key["kty"] == "EC"
+        assert public_key["alg"] == "ES256"
+        assert public_key["use"] == "sig"

docs/authentication.md

···
 - token names help identify which token is used where
 - tokens require explicit OAuth consent at your PDS
 
+## OAuth client types: public vs confidential
+
+ATProto OAuth distinguishes between two types of clients based on their ability to authenticate themselves to the authorization server.
+
+### what is a confidential client?
+
+a **confidential client** is an OAuth client that can prove its identity to the authorization server using cryptographic keys. the term "confidential" means the client can keep a secret - specifically, an ES256 private key that never leaves the server.
+
+**public client** (default):
+- cannot authenticate itself (uses `token_endpoint_auth_method: "none"`)
+- anyone could impersonate your client_id
+- authorization server issues **2-week refresh tokens**
+
+**confidential client** (with `OAUTH_JWK`):
+- authenticates using `private_key_jwt` - signs a JWT with its private key
+- authorization server verifies signature against your `/.well-known/jwks.json`
+- proves the request actually came from your server
+- authorization server issues **180-day refresh tokens**
+
+### why this matters for plyr.fm
+
+with public clients, the underlying ATProto refresh token expires after 2 weeks regardless of what we store in our database. users would need to re-authenticate with their PDS every 2 weeks.
+
+with confidential clients:
+- **developer tokens actually work long-term** - not limited to 2 weeks
+- **users don't get randomly kicked out** after 2 weeks of inactivity
+- **sessions last effectively forever** as long as tokens are refreshed within 180 days
+
+### how it works
+
+1. **key generation**: generate an ES256 (P-256) keypair
+   ```bash
+   uv run python scripts/gen_oauth_jwk.py
+   ```
+
+2. **configuration**: set `OAUTH_JWK` env var with the private key JSON
+
+3. **JWKS endpoint**: backend serves public key at `/.well-known/jwks.json`
+   - authorization server fetches this to verify our signatures
+
+4. **client metadata**: `/oauth-client-metadata.json` advertises:
+   ```json
+   {
+     "token_endpoint_auth_method": "private_key_jwt",
+     "token_endpoint_auth_signing_alg": "ES256",
+     "jwks_uri": "https://plyr.fm/.well-known/jwks.json"
+   }
+   ```
+
+5. **token requests**: on every token request (initial AND refresh), the library:
+   - creates a short-lived JWT (`client_assertion`) signed with our private key
+   - includes `client_assertion_type` and `client_assertion` in the request
+   - PDS verifies signature → issues long-lived tokens
+
+### implementation details
+
+the confidential client support lives in our `atproto` fork (`zzstoatzz/atproto`):
+
+```python
+# packages/atproto_oauth/client.py
+client = OAuthClient(
+    client_id='https://plyr.fm/oauth-client-metadata.json',
+    redirect_uri='https://plyr.fm/auth/callback',
+    scope='atproto ...',
+    state_store=state_store,
+    session_store=session_store,
+    client_secret_key=ec_private_key,  # enables confidential client
+)
+```
+
+when `client_secret_key` is set, `_make_token_request()` automatically adds client assertions to all token endpoint calls (initial exchange, refresh, revoke).
+
+### key rotation
+
+for key rotation:
+1. generate new key with different `kid` (key ID)
+2. add both keys to JWKS (old and new)
+3. deploy - new tokens use new key, old tokens still verify
+4. after 180 days, remove old key from JWKS
+
+### token refresh mechanism
+
+plyr.fm automatically refreshes ATProto tokens when they expire. here's how it works:
+
+1. **trigger**: user makes a PDS request (upload, create record, etc.)
+2. **detection**: PDS returns `401 Unauthorized` with `"exp"` in error message (access token expired)
+3. **refresh**: `_refresh_session_tokens()` in `_internal/atproto/client.py`:
+   - acquires per-session lock (prevents race conditions)
+   - calls `OAuthClient.refresh_session()` with the refresh token
+   - for confidential clients: signs a client assertion JWT
+   - PDS verifies assertion → issues new tokens
+   - saves new tokens to database
+4. **retry**: original request retries with fresh tokens
+
+**what gets refreshed**:
+- **access token**: short-lived (~minutes), refreshed frequently
+- **refresh token**: long-lived (2 weeks public, 180 days confidential), rotated on each use
+
+**observability**: look for these log messages in logfire:
+- `"access token expired for did:plc:..., attempting refresh"`
+- `"refreshing access token for did:plc:..."`
+- `"successfully refreshed access token for did:plc:..."`
+
+### migration: deploying confidential client
+
+when deploying confidential client support, **existing sessions continue to work** but have limitations:
+
+| aspect | existing sessions | new sessions (post-deploy) |
+|--------|-------------------|---------------------------|
+| plyr.fm session | unchanged | unchanged |
+| ATProto refresh token | 2-week lifetime (public client) | 180-day lifetime (confidential) |
+| behavior at 2 weeks | refresh fails → re-auth needed | continues working |
+
+**what happens to existing tokens**:
+1. existing sessions were created as "public client" - the PDS issued 2-week refresh tokens
+2. those refresh tokens cannot be upgraded - they have a fixed expiration
+3. when the refresh token expires, the next PDS request will fail
+4. users will need to re-authenticate to get new sessions with 180-day refresh tokens
+
+**timeline example**:
+- dec 8: user creates dev token (public client, 2-week refresh)
+- dec 22: ATProto refresh token expires
+- user tries to upload → refresh fails → 401 error
+- user creates new dev token → now gets 180-day refresh
+
+**production impact** (as of deployment):
+- most browser sessions expire within 14 days anyway (cookie `max_age`)
+- developer tokens are affected most - they have 90+ day session expiry but 2-week refresh
+- only 3 long-lived dev tokens in production (internal accounts)
+- new sessions will automatically get 180-day refresh tokens
+
+### sources
+
+- [ATProto OAuth spec - tokens and session lifetime](https://atproto.com/specs/oauth#tokens-and-session-lifetime)
+- [RFC 7523 - JWT Bearer Client Authentication](https://datatracker.ietf.org/doc/html/rfc7523)
+- [bailey's ATProto SvelteKit template](https://tangled.org/baileytownsend.dev/atproto-sveltekit-template) - TypeScript reference implementation
+- PR #578: confidential OAuth client support
+
 ## references
 
 - [MDN: HttpOnly cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#security)

scripts/gen_oauth_jwk.py

···
+#!/usr/bin/env python3
+"""generate ES256 JWK for OAuth confidential client.
+
+outputs a JSON string suitable for the OAUTH_JWK environment variable.
+
+usage:
+    uv run python scripts/gen_oauth_jwk.py
+
+then add to your .env:
+    OAUTH_JWK='{"kty":"EC","crv":"P-256",...}'
+"""
+
+import json
+import time
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from jose import jwk
+
+
+def generate_jwk() -> str:
+    """generate ES256 (P-256) JWK for OAuth client authentication."""
+    # generate P-256 (secp256r1) key pair
+    private_key = ec.generate_private_key(ec.SECP256R1())
+
+    # serialize to PEM
+    pem_bytes = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+    # convert to JWK using python-jose
+    key_obj = jwk.construct(pem_bytes, algorithm="ES256")
+    jwk_dict = key_obj.to_dict()
+
+    # add key ID based on timestamp (for key rotation)
+    jwk_dict["kid"] = str(int(time.time()))
+    jwk_dict["use"] = "sig"
+    jwk_dict["alg"] = "ES256"
+
+    return json.dumps(jwk_dict)
+
+
+if __name__ == "__main__":
+    jwk_json = generate_jwk()
+    print("generated ES256 JWK for OAuth confidential client:\n")
+    print(jwk_json)
+    print("\nadd to your .env file as:")
+    print(f"OAUTH_JWK='{jwk_json}'")