feat(api): surface per-OIDC-instance status on /api/health #323

Merged

james merged 1 commit from 214-oidc-health into main 2026-06-28 18:46:27 +00:00

Conversation 1 Commits 1 Files changed 11 +732 -21

james commented 2026-06-28 18:19:06 +00:00

Owner

Copy link

Resolves the ADR-0017 deferred follow-up (#214): a misconfigured OIDC instance no longer fails silently (button missing, warning only in container logs).

• GET /api/health now returns a providers array — one entry per configured OIDC_<NAME>_ISSUER — as { id, status, lastError? } with status in ok | discovery_failed | override_invalid | disabled.
• OIDCEndpointError gains a kind discriminator + a secret-free publicDetail; a module-level snapshot keeps the unauthenticated probe cheap (no per-request discovery — failed discovery isn't otherwise memoized, so the snapshot is what stops a broken instance hitting the network on every probe).
• providers is informational only: it never changes the top-level status or the 200/503 (still DB-driven), so a bad sign-in button can't trip a container health probe. [] when no OIDC is configured.
• lastError is generic/secret-free (env-var names or fixed phrases) — never a client secret, raw env value, or IdP response body. Tests assert the secret and the doc's claimed issuer never appear in the response.
• OpenAPI: /api/health registered with HealthDto and removed from the coverage exclusion; openapi.json + api-client types regenerated.
• Docs: new Diagnostics section in docs/oidc-self-hoster-guide.md.

Status semantics

status	produced when
ok	resolveOIDCEndpoints succeeded
discovery_failed	discovery doc unreachable/malformed/issuer-mismatch/missing endpoint
override_invalid	an endpoint override isn't https://
disabled	parse-stage drop-out (bad name, built-in collision, empty issuer, missing client id/secret)

Verification

• pnpm -F @carol/api test — 817 pass / 175 skipped (new tests/auth/oidc-health.test.ts + tests/api/health.test.ts; Postgres legs skip locally — change touches no DB schema/queries, so it's engine-agnostic).
• openapi:check up-to-date, openapi:coverage 104 pairs.
• @carol/api-client + @carol/client typecheck — clean.

Closes #214

🤖 Generated with Claude Code

Resolves the ADR-0017 deferred follow-up (#214): a misconfigured OIDC instance no longer fails silently (button missing, warning only in container logs). - `GET /api/health` now returns a `providers` array — one entry per configured `OIDC_<NAME>_ISSUER` — as `{ id, status, lastError? }` with `status` in `ok | discovery_failed | override_invalid | disabled`. - `OIDCEndpointError` gains a `kind` discriminator + a secret-free `publicDetail`; a module-level snapshot keeps the unauthenticated probe cheap (no per-request discovery — failed discovery isn't otherwise memoized, so the snapshot is what stops a broken instance hitting the network on every probe). - `providers` is **informational only**: it never changes the top-level `status` or the 200/503 (still DB-driven), so a bad sign-in button can't trip a container health probe. `[]` when no OIDC is configured. - `lastError` is generic/secret-free (env-var names or fixed phrases) — never a client secret, raw env value, or IdP response body. Tests assert the secret and the doc's claimed issuer never appear in the response. - OpenAPI: `/api/health` registered with `HealthDto` and removed from the coverage exclusion; `openapi.json` + api-client types regenerated. - Docs: new **Diagnostics** section in `docs/oidc-self-hoster-guide.md`. ## Status semantics | status | produced when | |---|---| | `ok` | `resolveOIDCEndpoints` succeeded | | `discovery_failed` | discovery doc unreachable/malformed/issuer-mismatch/missing endpoint | | `override_invalid` | an endpoint override isn't `https://` | | `disabled` | parse-stage drop-out (bad name, built-in collision, empty issuer, missing client id/secret) | ## Verification - `pnpm -F @carol/api test` — **817 pass / 175 skipped** (new `tests/auth/oidc-health.test.ts` + `tests/api/health.test.ts`; Postgres legs skip locally — change touches no DB schema/queries, so it's engine-agnostic). - `openapi:check` up-to-date, `openapi:coverage` 104 pairs. - `@carol/api-client` + `@carol/client` typecheck — clean. Closes #214 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-28 18:19:06 +00:00

feat(api): surface per-OIDC-instance status on /api/health ... 0710cb087f

Resolves the ADR-0017 deferred follow-up (#214): a misconfigured OIDC
instance no longer fails silently (button missing, warning only in
container logs).

GET /api/health now returns a `providers` array — one entry per
configured OIDC_<NAME>_ISSUER — as { id, status, lastError? } with status
in ok | discovery_failed | override_invalid | disabled. OIDCEndpointError
gains a `kind` discriminator + a secret-free `publicDetail`; a
module-level snapshot keeps the unauthenticated probe cheap (no
per-request discovery; failed discovery isn't otherwise memoized).

providers is informational only: it never changes the top-level status or
the 200/503 (still DB-driven), so a bad sign-in button can't trip a
container health probe. lastError is generic/secret-free (env-var names
or fixed phrases) — never a client secret, raw env value, or IdP response
body.

OpenAPI: /api/health registered with HealthDto and removed from the
coverage exclusion; openapi.json + api-client types regenerated. Docs:
new Diagnostics section in docs/oidc-self-hoster-guide.md.

Closes #214

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

forgejo-actions commented 2026-06-28 18:23:19 +00:00

Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric	Value	Soft target
Lines	81.9% ✅	≥ 50%
Branches	73.3% ⚠️	≥ 75%
Functions	91.5%	informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 81.9% ✅ | ≥ 50% | | Branches | 73.3% ⚠️ | ≥ 75% | | Functions | 91.5% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

james merged commit d51af86e5e into main 2026-06-28 18:46:27 +00:00

james deleted branch 214-oidc-health 2026-06-28 18:46:27 +00:00

james referenced this pull request from a commit 2026-06-28 18:46:29 +00:00

Merge pull request 'feat(api): surface per-OIDC-instance status on /api/health' (#323) from 214-oidc-health into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!323

No description provided.