feat(httpauth): add HTTP Basic auth and capabilities to /v1/me

Introduce username/password authentication via `Authorization: Basic`
as a first-class credential class alongside static bearer tokens, mTLS
certs, and OIDC JWTs. The resolve chain is now: bearer → Basic → mTLS
→ OIDC.

Changes:

- pkg/httpauth/policy.go: new `BasicIdentity` struct (bcrypt-hashed
  passwords); `resolveBasic` resolver with fail-closed TLS posture
  (`AllowBasicWithoutTLS` defaults to false); `Capabilities()` on
  `Identity` derives stable `cache.<scope>` strings from scopes.

- pkg/httpauth/loader.go: new `users:` YAML block in `fileSchema`;
  `AllowBasicWithoutTLS` config flag; boot-time `Validate()` rejects
  malformed bcrypt hashes and empty usernames loudly.

- cmd/hypercache-server/main.go + openapi.yaml: `meResponse` and
  `IdentityResponse` gain a required `capabilities` field populated
  from `Identity.Capabilities()`; OpenAPI description updated to
  reflect all four auth modes.

- __examples/distributed-oidc-client/: new runnable OIDC
  client-credentials demo (PUT/GET/DELETE/batch surface) with full
  README covering env-var setup, scope mapping patterns across
  Keycloak/Auth0/Okta, and production caveats.

- docs/rfcs/0003-client-sdk-and-redis-style-affordances.md: new RFC
  proposing a Go client SDK with multi-endpoint HA, username/password
  auth, and structured typed errors; design options enumerated with
  recommended path.

- Tests: Basic auth happy path, wrong-password/user, malformed header,
  and plaintext-refused-by-default cases in `policy_test.go`; YAML
  round-trip and boot-guard tests in `loader_test.go`; `me_test.go`
  updated for the new `capabilities` field.

- go.mod: promote `golang.org/x/crypto` from indirect to direct; bump
  ewrap v1.5.0 → v1.5.1, sectools v1.2.5 → v1.2.6.

Author: hyp3rd

CHANGELOG.md

@@ -8,6 +8,30 @@ All notable changes to HyperCache are recorded here. The format follows
 
 ### Added
 
+- **HTTP Basic auth as a first-class credential class (Redis-style `AUTH user pass`).** New top-level
+  `users:` block in `HYPERCACHE_AUTH_CONFIG` accepts bcrypt-hashed passwords. Each user resolves to the
+  same `Identity{ID, Scopes}` shape as every other auth mode, so all four mechanisms (static bearer →
+  Basic → mTLS → OIDC) coexist in one cluster with consistent downstream behavior. Fail-closed posture:
+  Basic over plaintext is refused by default; operators opt into dev-only plaintext via
+  `allow_basic_without_tls: true`. Implementation in
+  [`pkg/httpauth/policy.go`](pkg/httpauth/policy.go) with bcrypt verification via
+  `golang.org/x/crypto/bcrypt`. Threat note: bcrypt-per-request is CPU-bound; rate-limiting is left to a
+  fronting LB (see [RFC 0003](docs/rfcs/0003-client-sdk-and-redis-style-affordances.md) open question 3).
+- **`/v1/me` now returns a `capabilities` field.** Stable capability strings derived 1:1 from scopes
+  (`read` → `cache.read`, etc.). Clients should prefer `capabilities` over `scopes` for
+  forward-compatibility: if a scope is later split into multiple capabilities, scope-keyed clients
+  break but capability-keyed clients keep working. OpenAPI spec
+  ([`cmd/hypercache-server/openapi.yaml`](cmd/hypercache-server/openapi.yaml)) updated to reflect the
+  new required field; the binary's embedded spec is the contract.
+- **Tests pinning the new auth contract.**
+  [`pkg/httpauth/policy_test.go`](pkg/httpauth/policy_test.go) covers Basic resolves on correct
+  credentials, rejects on wrong passwords/users/malformed headers, refuses plaintext by default, and
+  documents the bearer-wins-over-Basic chain order via a Locals-introspection test.
+  [`pkg/httpauth/loader_test.go`](pkg/httpauth/loader_test.go) covers the YAML round-trip plus the
+  fail-loud-at-boot guards for malformed bcrypt hashes and empty usernames.
+- **Operator runbook updates.**
+  [`docs/oncall.md`](docs/oncall.md) Auth failures section gains a Basic-auth debugging row covering
+  the `curl -u user:pass /v1/me` canary and the plaintext-refused failure mode.
 - **Migration-source observability for the hint queue.** Hints produced by rebalance migrations are now
   tagged at queue time and tracked in a dedicated set of counters alongside the existing aggregate
   metrics. Five new OTel metrics: `dist.migration.queued`, `dist.migration.replayed`,

__examples/README.md

@@ -23,3 +23,5 @@ All the code in this directory is for demonstration purposes only.
 1. [`Size`](./size/size.go) - An example of using the HyperCache package to store a list of items and limit the cache based on size.
 
 1. [`Observability (OpenTelemetry)`](./observability/otel.go) - Demonstrates wrapping the service with tracing and metrics middleware using OpenTelemetry.
+
+1. [`Distributed OIDC client`](./distributed-oidc-client/) - End-to-end demo of a backend service authenticating to a `hypercache-server` cluster via OIDC client credentials, then exercising the PUT/GET/DELETE/batch surface. See the example's [README](./distributed-oidc-client/README.md) for env-var setup and IdP integration patterns.

__examples/distributed-oidc-client/README.md

@@ -0,0 +1,140 @@
+# Distributed cache client with OIDC auth
+
+A runnable example showing a backend service connecting to a `hypercache-server` cluster, authenticating via
+OIDC client credentials, and exercising the full client API.
+
+This is a **service-to-service** flow (no browser, no user redirect). The application proves its identity to
+the IdP with a client ID and secret, gets back a short-lived JWT, and presents that JWT to the cache. The
+cache validates the JWT against the same IdP and resolves the caller's identity + scopes. The same model fits
+Keycloak, Auth0, Okta, Entra ID, Google, and any RFC 6749 §4.4 compliant IdP.
+
+## What the example does
+
+1. Discovers the IdP's token endpoint from `$OIDC_ISSUER/.well-known/openid-configuration`.
+1. Uses `golang.org/x/oauth2/clientcredentials` to exchange the client ID + secret for an access token. The
+   library caches the token in memory and transparently refreshes it before expiry — every cache call below is
+   a plain `http.Client.Do` with no header bookkeeping.
+1. Hits `GET /v1/me` to verify the bound identity + scopes (canary: "is my token actually valid against this
+   cluster?").
+1. Exercises `PUT /v1/cache/:key`, `GET` with raw bytes, `GET` with the JSON envelope (metadata view),
+   `DELETE`, and `POST /v1/cache/batch/put`.
+
+## Requirements
+
+- Go 1.26+ (see [`go.mod`](../../go.mod))
+- A reachable `hypercache-server` running with OIDC enabled (i.e. `HYPERCACHE_OIDC_ISSUER` and
+  `HYPERCACHE_OIDC_AUDIENCE` set on the server). See
+  [`cmd/hypercache-server/README.md`](../../cmd/hypercache-server/README.md).
+- An OIDC client registered in your IdP with -. The **client_credentials** grant type enabled. -. A scope (or
+  audience claim mapper) that produces the scopes the cache expects — see [Scope mapping](#scope-mapping)
+  below.
+
+## Environment variables
+
+| Variable              | Required | Default                 | Description                                                              |
+| --------------------- | -------- | ----------------------- | ------------------------------------------------------------------------ |
+| `HYPERCACHE_ENDPOINT` | no       | `http://localhost:8080` | Cache server base URL (client API port).                                 |
+| `OIDC_ISSUER`         | **yes**  | —                       | IdP base URL (no trailing `/.well-known`).                               |
+| `OIDC_AUDIENCE`       | **yes**  | —                       | Must match the server's `HYPERCACHE_OIDC_AUDIENCE`.                      |
+| `OIDC_CLIENT_ID`      | **yes**  | —                       | OAuth2 client ID registered for this service in the IdP.                 |
+| `OIDC_CLIENT_SECRET`  | **yes**  | —                       | OAuth2 client secret. Treat as a secret — never commit.                  |
+| `OIDC_SCOPES`         | no       | `openid`                | Space-separated scope list. See [Scope mapping](#scope-mapping).         |
+| `OIDC_TOKEN_INSECURE` | no       | `0`                     | Set to `1` to skip TLS verification on the token endpoint. **Dev only.** |
+
+## Run
+
+```sh
+export HYPERCACHE_ENDPOINT=https://cache.example.com:8080
+export OIDC_ISSUER=https://keycloak.example.com/realms/cache
+export OIDC_AUDIENCE=hypercache-cluster
+export OIDC_CLIENT_ID=my-service
+export OIDC_CLIENT_SECRET=...
+export OIDC_SCOPES="openid cache:read cache:write"
+
+go run ./__examples/distributed-oidc-client/
+```
+
+Expected output:
+
+```text
+== /v1/me (verify bound identity) ==
+  resolved identity: my-service
+  granted scopes:    [read write]
+
+== PUT /v1/cache/example-key (5 min TTL) ==
+  stored
+
+== GET /v1/cache/example-key (raw bytes) ==
+  value: "hello from oidc client"
+
+== GET /v1/cache/example-key (JSON envelope) ==
+  key:      example-key
+  version:  1
+  owners:   [cache-0 cache-1 cache-2]
+  encoding: base64
+
+== DELETE /v1/cache/example-key ==
+  deleted
+
+== batch PUT /v1/cache/batch/put (3 keys) ==
+  stored 3 keys
+```
+
+## Scope mapping
+
+The cache treats scopes as a closed set: `read`, `write`, `admin`. Your IdP's scope/claim values must map to
+those three strings for the cache to grant access.
+
+Two configuration knobs on the server control this mapping:
+
+- `HYPERCACHE_OIDC_SCOPE_CLAIM` (default `scope`) — which JWT claim to read. Standard OAuth2 uses `scope`
+  (space-separated string); some IdPs use a custom array claim like `cache_scopes`.
+- The values inside that claim must be exactly `read`, `write`, or `admin`. Anything else is dropped silently.
+
+**Pattern 1: OAuth2 standard scopes.** Register scopes `read` and `write` in your IdP, grant them to the
+service client, and request them via `OIDC_SCOPES="openid read write"`. The cache reads them from the standard
+`scope` claim.
+
+**Pattern 2: Mapped scopes** (when your IdP namespaces scopes, e.g. `cache:read`). Use the IdP's claim-mapper
+feature to project the `cache:read` scope into a custom claim, then set
+`HYPERCACHE_OIDC_SCOPE_CLAIM=cache_scopes` server-side. Map `cache:read` → `read`, `cache:write` → `write` at
+the mapper level.
+
+**Pattern 3: Role-based.** Map IdP roles (e.g. Keycloak realm roles `cache-reader`, `cache-writer`) into the
+custom claim. Same shape as Pattern 2.
+
+## Coexistence with static bearer tokens
+
+A cluster can run with both OIDC verification and static bearer tokens configured at the same time. The auth
+chain resolves in this order:
+
+1. `Authorization: Bearer <token>` matched against `HYPERCACHE_AUTH_CONFIG`'s `tokens` list → static identity.
+1. If no static match, the OIDC verifier runs → OIDC identity.
+1. If neither matches and `AllowAnonymous: true`, request runs as anonymous. Otherwise 401.
+
+This means a single deployment can have humans signing in via OIDC (through the monitor's redirect flow) and
+machine integrations using long-lived static bearers — both succeed against the same cache. See
+[`pkg/httpauth/policy.go`](../../pkg/httpauth/policy.go) for the implementation.
+
+## Production caveats
+
+This example is intentionally minimal. For real services:
+
+- **Pool HTTP connections.** `oauth2.NewClient` returns a fresh `http.Client`; in production you want a
+  configured `Transport` with `MaxIdleConnsPerHost`, keepalives, and connection-level timeouts.
+- **Retry policy.** This example does no retries; transient 5xx or network errors surface as failures. Wrap
+  the cache calls in a bounded exponential-backoff retry for production.
+- **Observability.** The cache emits OpenTelemetry traces if the server is configured with a tracer provider;
+  propagate the trace context by setting `traceparent` headers on your requests.
+- **Token caching across processes.** `clientcredentials` caches tokens per-process. If your service spawns
+  many short-lived workers, consider a shared cache (e.g. Redis-backed) to avoid re-hitting the IdP on every
+  process start.
+
+## See also
+
+- [`docs/auth.md`](../../docs/auth.md) — server-side auth surface (when present; otherwise
+  [`cmd/hypercache-server/README.md`](../../cmd/hypercache-server/README.md) is the current source of truth).
+- [`docs/oncall.md`](../../docs/oncall.md#auth-failures) — debugging 401/403s when the client surface is
+  misbehaving.
+- [`cmd/hypercache-server/oidc.go`](../../cmd/hypercache-server/oidc.go) — the cache's OIDC verifier closure,
+  for reference on what's enforced server-side.