ips/docs/ai/decisions/002-openidconnect-rest-authentication.md

# ADR-002: OpenID Connect Authentication for REST API

**Date:** 2026-02-25
**Status:** Accepted

## Context

The REST API (pkg6depotd) and REST client (RestBackend) currently have no authentication. The depot's `auth_check` handler is a stub that only checks for Bearer token presence. The legacy pkg5 used client certificates (x509), which is operationally expensive.

## Decision

Use OpenID Connect (OIDC) for authentication:

- **Depot server** validates JWT access tokens against an OIDC provider's JWKS endpoint
- **REST client** obtains tokens via OIDC flows (device code flow for CLI, authorization code flow for GUI)
- **Token refresh** handled transparently by the client credential manager

### Server Side (pkg6depotd)
- Configure OIDC issuer URL and required scopes in depot config
- Fetch JWKS from `{issuer}/.well-known/openid-configuration` -> `jwks_uri`
- Validate Bearer tokens on protected endpoints (publish, index rebuild)
- Read-only endpoints (catalog, manifest, file, search) remain unauthenticated by default
- Optional: per-publisher access control via JWT claims

### Client Side (libips RestBackend)
- Add `CredentialProvider` trait to RestBackend
- Implement OIDC device code flow for CLI (user opens browser, enters code)
- Token storage in image metadata directory (encrypted at rest)
- Automatic refresh before expiry

## Consequences

- Modern auth infrastructure, compatible with Keycloak/Dex/Auth0/etc.
- No client certificate management burden
- Publisher-level access control possible via scopes/claims
- Requires OIDC provider deployment for secured repos (optional — unsecured repos still work)
feat: Preserve manifest text through install pipeline, add architecture plans Manifest text is now carried through the solver's ResolvedPkg and written directly to disk during install, eliminating the redundant re-fetch from the repository that could silently fail. save_manifest() is now mandatory (fatal on error) since the .p5m file on disk is the authoritative record for pkg verify and pkg fix. Add ADRs for libips API layer (GUI sharing), OpenID Connect auth, and SQLite catalog as query engine (including normalized installed_actions table). Add phase plans for code hygiene, client completion, catalog expansion, and OIDC authentication. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-02-25 22:47:39 +01:00			`# ADR-002: OpenID Connect Authentication for REST API`

			`Date: 2026-02-25`
			`Status: Accepted`

			`## Context`

			The REST API (pkg6depotd) and REST client (RestBackend) currently have no authentication. The depot's `auth_check` handler is a stub that only checks for Bearer token presence. The legacy pkg5 used client certificates (x509), which is operationally expensive.

			`## Decision`

			`Use OpenID Connect (OIDC) for authentication:`

			`- Depot server validates JWT access tokens against an OIDC provider's JWKS endpoint`
			`- REST client obtains tokens via OIDC flows (device code flow for CLI, authorization code flow for GUI)`
			`- Token refresh handled transparently by the client credential manager`

			`### Server Side (pkg6depotd)`
			`- Configure OIDC issuer URL and required scopes in depot config`
			- Fetch JWKS from `{issuer}/.well-known/openid-configuration` -> `jwks_uri`
			`- Validate Bearer tokens on protected endpoints (publish, index rebuild)`
			`- Read-only endpoints (catalog, manifest, file, search) remain unauthenticated by default`
			`- Optional: per-publisher access control via JWT claims`

			`### Client Side (libips RestBackend)`
			- Add `CredentialProvider` trait to RestBackend
			`- Implement OIDC device code flow for CLI (user opens browser, enters code)`
			`- Token storage in image metadata directory (encrypted at rest)`
			`- Automatic refresh before expiry`

			`## Consequences`

			`- Modern auth infrastructure, compatible with Keycloak/Dex/Auth0/etc.`
			`- No client certificate management burden`
			`- Publisher-level access control possible via scopes/claims`
			`- Requires OIDC provider deployment for secured repos (optional — unsecured repos still work)`