# StellaOps Auth Client — Integration Guide

> **Status:** Drafted 2025-10-10 as part of LIB5. Consumer teams (Concelier, 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("concelier.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: "concelier"
    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 Concelier 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 Concelier and CLI integrate these changes, we can mark LIB5 **DONE**; further packaging work is deferred until the backlog reintroduces it.