Initial commit (history squashed)

docs/dev/32_AUTH_CLIENT_GUIDE.md

@@ -0,0 +1,91 @@
+# StellaOps Auth Client — Integration Guide
+
+> **Status:** Drafted 2025-10-10 as part of LIB5. Consumer teams (Feedser, CLI, Agent) should review before wiring the new options into their configuration surfaces.
+
+The `StellaOps.Auth.Client` library provides a resilient OpenID Connect client for services and tools that talk to **StellaOps Authority**. LIB5 introduced configurable HTTP retry/backoff policies and an offline-fallback window so downstream components stay deterministic even when Authority is briefly unavailable.
+
+This guide explains how to consume the new settings, when to toggle them, and how to test your integration.
+
+## 1. Registering the client
+
+```csharp
+services.AddStellaOpsAuthClient(options =>
+{
+    options.Authority = configuration["StellaOps:Authority:Url"]!;
+    options.ClientId = configuration["StellaOps:Authority:ClientId"]!;
+    options.ClientSecret = configuration["StellaOps:Authority:ClientSecret"];
+    options.DefaultScopes.Add("feedser.jobs.trigger");
+
+    options.EnableRetries = true;
+    options.RetryDelays.Clear();
+    options.RetryDelays.Add(TimeSpan.FromMilliseconds(500));
+    options.RetryDelays.Add(TimeSpan.FromSeconds(2));
+
+    options.AllowOfflineCacheFallback = true;
+    options.OfflineCacheTolerance = TimeSpan.FromMinutes(5);
+});
+```
+
+> **Reminder:** `AddStellaOpsAuthClient` binds the options via `IOptionsMonitor<T>` so changes picked up from configuration reloads will be applied to future HTTP calls without restarting the host.
+
+## 2. Resilience options
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `EnableRetries` | `true` | When disabled, the shared Polly policy is a no-op and HTTP calls will fail fast. |
+| `RetryDelays` | `1s, 2s, 5s` | Edit in ascending order; zero/negative entries are ignored. Clearing the list and leaving it empty keeps the defaults. |
+| `AllowOfflineCacheFallback` | `true` | When `true`, stale discovery/JWKS responses are reused within the tolerance window if Authority is unreachable. |
+| `OfflineCacheTolerance` | `00:10:00` | Added to the normal cache lifetime. E.g. a 10 minute JWKS cache plus 5 minute tolerance keeps keys for 15 minutes if Authority is offline. |
+
+The HTTP retry policy handles:
+
+- 5xx responses
+- 429 responses
+- Transient transport failures (`HttpRequestException`, timeouts, aborted sockets)
+
+Retries emit warnings via the `StellaOps.Auth.Client.HttpRetry` logger. Tune the delay values to honour your deployment’s SLOs.
+
+## 3. Configuration mapping
+
+Suggested configuration keys (coordinate with consuming teams before finalising):
+
+```yaml
+StellaOps:
+  Authority:
+    Url: "https://authority.stella-ops.local"
+    ClientId: "feedser"
+    ClientSecret: "change-me"
+    AuthClient:
+      EnableRetries: true
+      RetryDelays:
+        - "00:00:01"
+        - "00:00:02"
+        - "00:00:05"
+      AllowOfflineCacheFallback: true
+      OfflineCacheTolerance: "00:10:00"
+```
+
+Environment variable binding follows the usual double-underscore rules, e.g.
+
+```
+STELLAOPS__AUTHORITY__AUTHCLIENT__RETRYDELAYS__0=00:00:02
+STELLAOPS__AUTHORITY__AUTHCLIENT__OFFLINECACHETOLERANCE=00:05:00
+```
+
+CLI and Feedser teams should expose these knobs once they adopt the auth client.
+
+## 4. Testing recommendations
+
+1. **Unit tests:** assert option binding by configuring `StellaOpsAuthClientOptions` via a `ConfigurationBuilder` and ensuring `Validate()` normalises the retry delays and scope list.
+2. **Offline fallback:** simulate an unreachable Authority by swapping `HttpMessageHandler` to throw `HttpRequestException` after priming the discovery/JWKS caches. Verify that tokens are still issued until the tolerance expires.
+3. **Observability:** watch for `StellaOps.Auth.Client.HttpRetry` warnings in your logs. Excessive retries mean the upstream Authority cluster needs attention.
+4. **Determinism:** keep retry delays deterministic. Avoid random jitter—operators can introduce jitter at the infrastructure layer if desired.
+
+## 5. Rollout checklist
+
+- [ ] Update consuming service/CLI configuration schema to include the new settings.
+- [ ] Document recommended defaults for offline (air-gapped) versus connected deployments.
+- [ ] Extend smoke tests to cover Authority outage scenarios.
+- [ ] Coordinate with Docs Guild so user-facing quickstarts reference the new knobs.
+
+Once Feedser and CLI integrate these changes, we can mark LIB5 **DONE**; further packaging work is deferred until the backlog reintroduces it.