Skip to content

harvest-invoicer: optional OIDC login and waitress for server deployments - #189

Merged
aldoborrero merged 1 commit into
mainfrom
feat/harvest-invoicer-oidc
Nov 2, 2026
Merged

aldoborrero merged 1 commit into
mainfrom
feat/harvest-invoicer-oidc

Conversation

@aldoborrero

Copy link
Copy Markdown
Member

harvest-invoicer serve has no authentication, so the README tells people never to expose it, which rules out running it on a server. This adds an optional OIDC login, plus a production server for that mode. Without an issuer, nothing changes: local serve (loopback, browser), --demo and generate behave as before.

OIDC login (opt-in: enabled when --oidc-issuer is set)

  • Authlib client: discovery, where the advertised issuer must match the configured one; S256 PKCE; state and nonce; iss/aud pinned explicitly, since Authlib's default would accept a foreign aud when azp matches.
  • Signing algorithms: limited to RS256/PS256/ES256/EdDSA, intersected with what discovery advertises.
  • Who gets in: allow-listed subjects, or allow-listed emails with email_verified. If the ID token lacks either claim (Zitadel's default), they are read from userinfo, whose sub must match the ID token's.
  • Fails closed: it refuses to start without an allow-list (unless --oidc-allow-any-user), without a session secret of at least 32 characters, or without --public-url. Redirect and post-logout URIs come only from the public URL, never from request headers.
  • Sessions:
    • absolute lifetime (--session-lifetime, 12 h by default);
    • cleared at login (no session fixation);
    • HttpOnly, SameSite=Lax, and Secure behind https;
    • rotating the session secret revokes them all.
  • Guard:
    • unauthenticated GET → /login?next=… (same-origin paths only);
    • other methods → 401;
    • htmx → HX-Redirect;
    • an authenticated but disallowed user → 403 page (no redirect loop).
  • Logout: a CSRF-guarded POST that also ends the provider session (end_session_endpoint).
  • Proxy: ProxyFix (--trusted-proxies, 1 by default with OIDC), and the public host is accepted by the existing CSRF guard.
  • /quit: disabled under OIDC.
  • Secrets: read from *_FILE or the environment, never logged; log lines escape provider-supplied text.

Server

In OIDC mode serve runs on waitress (--server auto|werkzeug|waitress, --threads):

  • Single process, because the editor state lives in memory.
  • Request limits: channel_timeout=60, connection_limit=100, header and body size caps.
  • Shutdown: clean on SIGTERM.
  • Proxy headers: waitress's own handling is left off so ProxyFix sees X-Forwarded-*.

Tests

  • Count: 415 passed and 1 skipped (the existing WeasyPrint skip), also inside nix build.
  • In-process OIDC provider: discovery, JWKS, a token endpoint that checks PKCE and single-use codes, userinfo, and real RS256 tokens. Login therefore goes through Authlib's real validation path.
  • Rejection tests: wrong signing key, alg: none, HS256-only provider, foreign aud, expired token, a token response without id_token, bad or replayed state, userinfo sub mismatch.
  • Redirects: open-redirect attempts.
  • Logs: log injection.
  • Unchanged modes: OIDC off, server selection and SIGTERM.

Checks

nix fmt is clean (ruff ALL, mypy strict) and nix flake check passes. Dependencies added: authlib, requests and waitress, in both pyproject.toml/uv.lock and the Nix package.

The README gains a Server deployment (OIDC) section listing every option and environment variable, with an example, and its Security section is updated.

…ents

The editor has no authentication, so it could only run on loopback. With an
issuer configured, `serve` now requires an OIDC login (Authlib: discovery,
S256 PKCE, state and nonce, pinned iss/aud, an RS256/PS256/ES256/EdDSA
allow-list) and only admits allow-listed subjects or verified emails. It
fails closed on an empty allow-list, a missing session secret or a missing
public URL. Sessions have an absolute lifetime (12 h by default) and logout
is a CSRF-guarded POST that also ends the provider session. ProxyFix makes
it work behind a reverse proxy, and redirect URIs come only from the
configured public URL.

In OIDC mode the app is served by waitress, a single-process multithreaded
server with request limits and a clean SIGTERM shutdown; `--server` forces
either one. Without an issuer nothing changes: local `serve`, `--demo` and
`generate` behave as before.
@aldoborrero
aldoborrero added this pull request to the merge queue Nov 2, 2026
Merged via the queue into main with commit 663667e Nov 2, 2026
3 checks passed
@aldoborrero
aldoborrero deleted the feat/harvest-invoicer-oidc branch November 2, 2026 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant