feat(actualbudget): configure oidc authentication

docs/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2026-09-06
+
+- **Configured OpenID Connect (OIDC) authentication for Actual Budget**:
+  - Configured `services.actual.settings` with `loginMethod = "openid"` and `openId` settings pointing to Pocket ID (`auth.masu.rs`), using client ID `92afe9f8-7ef6-42ab-8a06-701df3c7179d`.
+  - Added secret management for `actualbudget-oidc-secret.age` via `secrets.actualbudget-oidc-secret`, set with owner `actualbudget` and group `shared` (0440).
+  - Configured `systemd.services.actual` to order after the decrypted secret service and granted the dynamic unit access via `SupplementaryGroups = [ "shared" ]` and `PrivateUsers = false`.
+  - Updated `docs/oidc-services.md` with the verified callback URI (`https://money.masu.rs/openid/callback`) and NixOS configuration snippet.
+
 ## 2026-08-29 (root cause found and fixed)
 
 - **Root-caused and fixed the recurring post-TUI typing lag** (fish + Zellij + Ghostty) using a `lag-triage` capture from a live lagging shell plus a deterministic PTY reproduction (`presets/programs/lag-triage/upstream_repro.py`):
@@ -102,6 +110,11 @@
   to bind, the failure took down the entire terminal instead of erroring
   gracefully.
 
+## 2026-09-06
+
+- Configured Grafana OIDC authentication via Pocket ID in `platforms/nixos/modules/nmasur/presets/services/grafana/grafana.nix`.
+- Enabled `auth.oauth_allow_insecure_email_lookup = true` in Grafana settings to allow linking an incoming OAuth login to an existing Grafana user account with the same email.
+
 ## 2026-07-25
 
 - Added jjui config generation to `jujutsu.nix` in Home Manager to include custom GitHub ruleset bypass commands (`ctrl+b` and `ctrl+shift+b`).

docs/oidc-services.md

@@ -0,0 +1,245 @@
+# OIDC Service Analysis & Setup Requirements
+
+This document analyzes the services defined in this repository (specifically within `platforms/nixos/modules/nmasur/presets/services/` and related server profiles like `flame` and `swan`), evaluates their OpenID Connect (OIDC) compatibility, and details the requirements for configuring OIDC logins.
+
+---
+
+## Identity Provider Context: Pocket ID
+
+The configuration already includes a central self-hosted identity provider: **Pocket ID** (`platforms/nixos/modules/nmasur/presets/services/pocket-id/pocket-id.nix`), hosted on the communications server (`flame`) behind Caddy at **`https://auth.masu.rs`**.
+
+Pocket ID is an OpenID Connect (OIDC) provider with WebAuthn/Passkey support. It exposes the following standard OIDC endpoints:
+- **Issuer URL:** `https://auth.masu.rs`
+- **Discovery Endpoint:** `https://auth.masu.rs/.well-known/openid-configuration`
+- **Authorization Endpoint:** `https://auth.masu.rs/authorize`
+- **Token Endpoint:** `https://auth.masu.rs/api/oidc/token`
+- **Userinfo Endpoint:** `https://auth.masu.rs/api/oidc/userinfo`
+- **JWKS Endpoint:** `https://auth.masu.rs/.well-known/jwks.json`
+
+---
+
+## 1. Service Compatibility Breakdown
+
+### Tier 1: First-Class / Native OIDC Support
+
+These services support OpenID Connect natively without requiring external authentication proxies or custom code:
+
+| Service | Hostname | OIDC Support Level | Configuration Method |
+| :--- | :--- | :--- | :--- |
+| **Immich** | `photos.masu.rs` | Native core feature | NixOS config (`services.immich.settings.oauth`) |
+| **Gitea** | `git.masu.rs` | Native core feature | NixOS config / CLI or Web UI |
+| **Nextcloud** | `cloud.masu.rs` | Native (official `user_oidc` app) | Nextcloud app + `nextcloud-occ user_oidc:provider` |
+| **Grafana** | `metrics.masu.rs` | Native (Generic OAuth) | NixOS config (`services.grafana.settings."auth.generic_oauth"`) |
+| **Paperless-ngx** | `paper.masu.rs` | Native (`django-allauth`) | NixOS env vars (`PAPERLESS_SOCIALACCOUNT_PROVIDERS`) |
+| **Mealie** | `cooking.masu.rs` | Native core feature | NixOS env vars (`OIDC_AUTH_ENABLED`, etc.) |
+| **Karakeep / Hoarder** | `keep.masu.rs` | Native (NextAuth OIDC) | NixOS env vars (`OAUTH_WELLKNOWN_URL`, etc.) |
+| **Audiobookshelf** | `read.masu.rs` | Native core feature (v2.3+) | Web UI (Settings → Authentication) |
+| **Actual Budget** | `money.masu.rs` | Native core feature (v24.3+) | NixOS config (`services.actual.settings.openId`) |
+
+---
+
+### Tier 2: OIDC via Plugins or Reverse Proxy Header Auth
+
+These services do not have generic OIDC in their core web UI, but can support single sign-on through plugins or reverse proxy headers (`Remote-User` / `X-Forwarded-User`):
+
+| Service | Hostname | Strategy | Notes |
+| :--- | :--- | :--- | :--- |
+| **Jellyfin** | `stream.masu.rs` | `jellyfin-plugin-sso` | Web clients work well; TV and native apps typically rely on Quick Connect. |
+| **Calibre-Web** | `books.masu.rs` | Reverse proxy header auth | Set `services.calibre-web.options.reverseProxyAuth.enable = true` behind an authenticating reverse proxy. |
+| **File Browser** | `files.masu.rs` | Reverse proxy header auth | Set `auth.method = "proxy"` and `auth.header = "X-Forwarded-User"` behind an authenticating reverse proxy. |
+| **Navidrome** | `music.masu.rs` | Reverse proxy header auth | Supports `ReverseProxyUserHeader` for web UI; Subsonic API clients (Feishin, etc.) still require native user passwords. |
+| **Stalwart** | `contacts.masu.rs` | OIDC Directory / SASL OAuth | Stalwart supports OIDC directories, but CardDAV/CalDAV clients usually require HTTP Basic Auth or application passwords. |
+
+---
+
+### Tier 3: Incompatible or No Native OIDC Support
+
+- **Vaultwarden (`vault.masu.rs`):** Incompatible for vault decryption. Vaultwarden uses client-side zero-knowledge encryption where vault keys are derived from the user's master password. Bitwarden Enterprise SSO relies on a proprietary Key Connector that Vaultwarden does not implement.
+- **n8n (`n8n.masu.rs`):** SAML/OIDC SSO is an **Enterprise / commercial-only feature**; it is disabled in the free self-hosted Community edition.
+- **The Arr Stack (`download.masu.rs`):** Radarr, Sonarr, Lidarr, Readarr, Prowlarr, Bazarr, and Sabnzbd only support API keys, Basic Auth, or Forms.
+- **Transmission (`transmission.masu.rs`):** BitTorrent daemon; supports only HTTP Basic Auth / RPC whitelist.
+- **Uptime Kuma (`status.masu.rs`), ntfy (`ntfy.masu.rs`), The Lounge (`irc.masu.rs`), Pgweb (`pg.masu.rs`), Mathesar (`mathesar.masu.rs`), Hister (`hister.masu.rs`):** No native generic OIDC login mechanism.
+- **Infrastructure / Daemon Services:** PostgreSQL, InfluxDB, bind, avahi, cloudflared, wireguard, litestream (no user web UI).
+
+---
+
+## 2. General Setup Requirements
+
+Configuring OIDC requires setup across four layers:
+
+### A. Pocket ID Setup
+For each service, an OIDC client application must be registered in the Pocket ID admin interface:
+1. **Client ID:** A unique identifier slug (e.g. `gitea`, `immich`, `paperless`).
+2. **Client Secret:** A cryptographically secure random token.
+3. **Redirect URIs / Callback URLs:** The exact target URLs the service exposes for authorization code callbacks.
+4. **Scopes:** Usually `openid`, `profile`, and `email`.
+
+### B. Secrets Management (agenix)
+All client secrets should be encrypted with `agenix` under the respective service directory:
+- Example: `platforms/nixos/modules/nmasur/presets/services/<service>/<service>-oidc.age`
+- Defined in NixOS under `config.secrets.<service>-oidc` with appropriate owner/group permissions.
+
+### C. Network & Reverse Proxy (Caddy)
+1. **Back-Channel Connectivity:** When a user logs in, the service backend makes a server-to-server HTTPS call to `https://auth.masu.rs/api/oidc/token` to exchange the authorization code for tokens. Services hosted on `swan` (NAS) must be able to resolve and reach `auth.masu.rs` over HTTPS.
+2. **Proxy Headers:** Caddy's `reverse_proxy` handles `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-For` by default. Services should have reverse proxy trust enabled (e.g., `trusted_proxies = ["127.0.0.1"]`) so generated redirect URIs preserve the `https://` scheme.
+
+---
+
+## 3. Detailed Setup Requirements for Tier 1 Services
+
+### 1. Immich (`photos.masu.rs`)
+- **Pocket ID Redirect URIs:**
+  - Web: `https://photos.masu.rs/auth/login`
+  - Mobile: `app.immich:///oauth-callback`
+- **NixOS Configuration (`immich.nix`):**
+  ```nix
+  services.immich.settings.oauth = {
+    enabled = true;
+    issuerUrl = "https://auth.masu.rs";
+    clientId = "immich";
+    clientSecret = "..."; # or IMMICH_OAUTH_CLIENT_SECRET via environment file
+    scope = "openid profile email";
+    autoRegister = true;
+    buttonText = "Login with Pocket ID";
+  };
+  ```
+
+### 2. Gitea (`git.masu.rs`)
+- **Pocket ID Redirect URI:** `https://git.masu.rs/user/oauth2/pocket-id/callback`
+- **Setup in Gitea:**
+  Can be configured in the Web UI under **Site Administration → Authentication Sources** or via CLI:
+  ```bash
+  gitea admin auth add-oauth \
+    --name "Pocket ID" \
+    --provider openidConnect \
+    --key "<client_id>" \
+    --secret "<client_secret>" \
+    --auto-discover-url "https://auth.masu.rs/.well-known/openid-configuration"
+  ```
+  - Optional: Enable automatic account linking by matching email.
+
+### 3. Nextcloud (`cloud.masu.rs`)
+- **Pocket ID Redirect URI:** `https://cloud.masu.rs/apps/user_oidc/code`
+- **Setup in `nextcloud/nextcloud.nix`:**
+  1. Add `user_oidc` to `services.nextcloud.extraApps`.
+  2. Configure the provider via `nextcloud-occ`:
+     ```bash
+     nextcloud-occ user_oidc:provider pocket-id \
+       --clientid="<client_id>" \
+       --clientsecret="<client_secret>" \
+       --discoveryuri="https://auth.masu.rs/.well-known/openid-configuration" \
+       --scope="openid profile email"
+     ```
+
+### 4. Grafana (`metrics.masu.rs`)
+- **Pocket ID Redirect URI:** `https://metrics.masu.rs/login/generic_oauth`
+- **Setup in `grafana/grafana.nix`:**
+  ```nix
+  services.grafana.settings = {
+    auth.oauth_allow_insecure_email_lookup = true;
+    "auth.generic_oauth" = {
+      enabled = true;
+      name = "Pocket ID";
+      allow_sign_up = true;
+      client_id = "85d879ed-1a86-4984-b33d-43806500ef98";
+      client_secret = "$__file{${config.secrets.grafana-oidc-secret.dest}}";
+      scopes = "openid profile email";
+      auth_url = "https://${hostnames.auth}/authorize";
+      token_url = "https://${hostnames.auth}/api/oidc/token";
+      api_url = "https://${hostnames.auth}/api/oidc/userinfo";
+      login_attribute_path = "preferred_username";
+      skip_org_role_sync = true;
+    };
+  };
+  ```
+
+### 5. Paperless-ngx (`paper.masu.rs`)
+- **Pocket ID Redirect URI:** `https://paper.masu.rs/accounts/oidc/pocket-id/login/callback/`
+- **Setup in `paperless/paperless.nix`:**
+  ```nix
+  services.paperless.settings = {
+    PAPERLESS_APPS = "allauth.socialaccount.providers.openid_connect";
+    PAPERLESS_SOCIALACCOUNT_PROVIDERS = builtins.toJSON {
+      openid_connect = {
+        SERVERS = [
+          {
+            id = "pocket-id";
+            name = "Pocket ID";
+            server_url = "https://auth.masu.rs";
+            token_auth_method = "client_secret_basic";
+            APP = {
+              client_id = "paperless";
+              secret = "..."; # or via environmentFile
+            };
+          }
+        ];
+      };
+    };
+    PAPERLESS_REDIRECT_LOGIN_TO_SSO = "true"; # Optional: bypass local login
+  };
+  ```
+
+### 6. Mealie (`cooking.masu.rs`)
+- **Pocket ID Redirect URI:** `https://cooking.masu.rs/login`
+- **Setup in `mealie.nix`:**
+  ```nix
+  systemd.services.mealie.environment = {
+    OIDC_AUTH_ENABLED = "true";
+    OIDC_SIGNUP_ENABLED = "true";
+    OIDC_CONFIGURATION_URL = "https://auth.masu.rs/.well-known/openid-configuration";
+    OIDC_CLIENT_ID = "mealie";
+    OIDC_CLIENT_SECRET = "...";
+    OIDC_PROVIDER_NAME = "Pocket ID";
+    OIDC_USER_CLAIM = "email";
+  };
+  ```
+
+### 7. Karakeep / Hoarder (`keep.masu.rs`)
+- **Pocket ID Redirect URI:** `https://keep.masu.rs/api/auth/callback/custom`
+- **Setup in `karakeep.nix`:**
+  ```nix
+  services.karakeep.extraEnvironment = {
+    OAUTH_WELLKNOWN_URL = "https://auth.masu.rs/.well-known/openid-configuration";
+    OAUTH_CLIENT_ID = "hoarder";
+    OAUTH_CLIENT_SECRET = "...";
+    OAUTH_PROVIDER_NAME = "Pocket ID";
+    OAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING = "true";
+  };
+  ```
+
+### 8. Audiobookshelf (`read.masu.rs`)
+- **Pocket ID Redirect URIs:**
+  - Web: `https://read.masu.rs/auth/openid/callback`
+  - Mobile: `audiobookshelf://oauth`
+- **Setup in Audiobookshelf:**
+  Configured in the Web UI (**Settings → Authentication → OpenID Connect**):
+  - Issuer URL: `https://auth.masu.rs`
+  - Client ID & Client Secret
+  - Match user by email or username
+
+### 9. Actual Budget (`money.masu.rs`)
+- **Pocket ID Redirect URI:** `https://money.masu.rs/openid/callback`
+- **Setup in `actualbudget/actualbudget.nix`:**
+  ```nix
+  services.actual.settings = {
+    loginMethod = "openid";
+    openId = {
+      discoveryURL = "https://${hostnames.auth}/.well-known/openid-configuration";
+      client_id = "92afe9f8-7ef6-42ab-8a06-701df3c7179d";
+      client_secret._secret = config.secrets.actualbudget-oidc-secret.dest;
+      server_hostname = "https://${hostnames.budget}";
+      authMethod = "openid";
+    };
+  };
+  ```
+  *Note:* The optional end-to-end budget encryption password remains separate from the server authentication.
+
+---
+
+## 4. Forward Auth Architecture for Remaining Services
+
+For services without native OIDC support (such as Calibre-Web, File Browser, Uptime Kuma, and the Arr stack), you can implement **Forward Auth via Caddy**:
+
+1. Deploy an authenticating proxy (such as **OAuth2-Proxy** or **Authelia**) configured with Pocket ID as its OIDC provider.
+2. Configure Caddy routes using the `forward_auth` directive to verify user sessions with the proxy before forwarding requests to the target service.
+3. For services supporting reverse proxy authentication (Calibre-Web and File Browser), Caddy injects identity headers (e.g. `Remote-User: noah` or `X-Forwarded-User: noah`), enabling seamless single sign-on without requiring separate logins.

platforms/nixos/modules/nmasur/presets/services/actualbudget/actualbudget-oidc-secret.age

@@ -0,0 +1,17 @@
+-----BEGIN AGE ENCRYPTED FILE-----
+YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNzaC1lZDI1NTE5IE1nSGFPdyBycCtF
+S1ErMkNoME1ZNzYramZ6cFJGL1VLbU1sSnVBaTA2Y3B2M1FUYTM0Cnl1a0dmdEpt
+U3puRS9RUEUyVVBDelRRRGlGQXdWQzc4cHprZGNRb2RuYmcKLT4gc3NoLWVkMjU1
+MTkgWXlTVU1RIDJ1M1dmTnB4Vzg3WDZ3QzZDZ1phYTU4YUk0U1VmV2M5cHZ2bENE
+eEE5aDQKODFrOWJBWjE0WFJKRTVrb2dlTmVHdEVHeVc4MU9GRHhTY1l5Mzh1YnZo
+dwotPiBzc2gtZWQyNTUxOSBuanZYNUEgM2JNTmVuTCtiSnNOS2UybE5qQXptcW92
+QngyaGh5Y0VqOGZEaWpkazYzawpjZmExWmF5MjV0NE05ZXVzenhYVXpRaGg4R25x
+QkpFa080S3haTXpTUi80Ci0+IHNzaC1lZDI1NTE5IENxSU9VQSBQcjgrV0c3S21I
+RXY5WnlSdWRML1g4ZmtvNWVmTGNwb3owZUFWN0s0ckhZCm1PbGtKY1hOanBGU0V6
+MzRrd3lPSUIrUVY3ZW5VTzFrWnJjblNvZmVIYk0KLT4gc3NoLWVkMjU1MTkgejFP
+Y1p3IGdoRHVhbG52OE5wUEFwWjlvb0xZSUpOS0loNm1QOWZ0N2RGZ2xMcW5RQXcK
+UUpNdDh1aUN0cHM2N0M3bGMvcjIwT2YrV01sdjdBQThkM3BxQ1hXY1A3bwotLS0g
+K21sZndObVJLdkNBR3IvWHZ3c0RjSEJQajFUV2tFUmNXWDQ3RU1DNzJKcwon7wF2
+i2V9/fXS9QBfTvUJGP9MQ1gCe+UxstI3IPv+ODudHLeCGT0JoxkN6DZtayxKYYJn
+iKghS8tUNdzshOBqpA==
+-----END AGE ENCRYPTED FILE-----

platforms/nixos/modules/nmasur/presets/services/actualbudget/actualbudget.nix

@@ -32,6 +32,22 @@ in
       enable = true;
       settings = {
         port = cfg.port;
+        loginMethod = "openid";
+        openId = {
+          discoveryURL = "https://${hostnames.auth}/.well-known/openid-configuration";
+          client_id = "92afe9f8-7ef6-42ab-8a06-701df3c7179d";
+          client_secret._secret = config.secrets.actualbudget-oidc-secret.dest;
+          server_hostname = "https://${hostnames.budget}";
+          authMethod = "openid";
+        };
+      };
+    };
+
+    systemd.services.actual = {
+      after = [ "actualbudget-oidc-secret-secret.service" ];
+      serviceConfig = {
+        PrivateUsers = lib.mkForce false;
+        SupplementaryGroups = [ "shared" ];
       };
     };
 
@@ -107,6 +123,17 @@ in
       owner = builtins.toString config.users.users.actualbudget.uid;
       group = builtins.toString config.users.users.actualbudget.uid;
     };
+    secrets.actualbudget-oidc-secret = {
+      source = ./actualbudget-oidc-secret.age;
+      dest = "${config.secretsDirectory}/actualbudget-oidc-secret";
+      owner = config.users.users.actualbudget.name;
+      group = config.users.groups.shared.name;
+      permissions = "0440";
+    };
+    systemd.services.actualbudget-oidc-secret-secret = {
+      requiredBy = [ "actual.service" ];
+      before = [ "actual.service" ];
+    };
 
     # Allow web traffic to Caddy
     nmasur.presets.services.caddy.routes = lib.mkAfter [

platforms/nixos/modules/nmasur/presets/services/grafana/grafana-oidc-secret.age

@@ -0,0 +1,17 @@
+-----BEGIN AGE ENCRYPTED FILE-----
+YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNzaC1lZDI1NTE5IE1nSGFPdyBmRTZ2
+Q0pxZ2ZOZ21HcG9EWHJOR0FZbU5UeWFTQXZwRCtKK2hXWDZsQVJzCjh1MURnU0dr
+MERUWGVETHFZZjhiZnJsMVlqTDdSNnZwbDNQNFRCRDZuQ3MKLT4gc3NoLWVkMjU1
+MTkgWXlTVU1RIFl0V3Jac3IydVJDOVI3c3lscWZiQzU4TG1tYlNZSWZHbmtSakRl
+bGhVbk0KNzNFZDFXM3FhWkNWbUliRG00dGN3WjNxZktCT2RPd2FUbi9nS1NobEtQ
+cwotPiBzc2gtZWQyNTUxOSBuanZYNUEga29CZkplcC9yN25JU0lNakQxSW92UFBz
+bCtHQUNPd0FBdzVMaEhRVjJoWQpmV2xsWFcwU0o0SlljbjEzY2dPT0VlazVhZ3h3
+bDEwNzRGUWdJM0Y3UDhvCi0+IHNzaC1lZDI1NTE5IENxSU9VQSBzVWhPT01tSmZh
+UlpDb0ltZGdiRXRkVTFEQW45Tk5PMDVqdFczRTBlQ0hVCm1OOEJDNEN4K1lFZU1r
+cU1ENVRqM3BLV3lVTzRpOUhjbVFCU0t4Q0owR28KLT4gc3NoLWVkMjU1MTkgejFP
+Y1p3IFRTU1FBa2d2ZGRCc0JuanRpbEE2OU53M1htOGhJT1hoM0s5R2Rqbk1FMXcK
+SE1qbjFid1ZnUmljUDBlMU4yTlU0bWlOenhFN3Bkd3BSS3NIYStQNHFHYwotLS0g
+c2ZwZjNGaTQxVVBKUC9keTZhOGtxRHA0MkpmRkNwUGFjMlFXVnM0Y0VTWQpi8R/5
+BRFSxYiEYeB54XjyVXRcyct94jH4wentMOYUFcZP+kd3dwKnXdtrqZDlCk3eM9sy
+xzOoHpd8BhmmRK9hgw==
+-----END AGE ENCRYPTED FILE-----

platforms/nixos/modules/nmasur/presets/services/grafana/grafana.nix

@@ -40,15 +40,31 @@ in
       before = [ "grafana.service" ];
     };
 
+    secrets.grafana-oidc-secret = {
+      source = ./grafana-oidc-secret.age;
+      dest = "${config.secretsDirectory}/grafana-oidc-secret";
+      owner = "grafana";
+      group = "grafana";
+      permissions = "0440";
+    };
+    systemd.services.grafana-oidc-secret-secret = {
+      requiredBy = [ "grafana.service" ];
+      before = [ "grafana.service" ];
+    };
+
     services.grafana = {
       enable = true;
       settings = {
         security.secret_key = "$__file{${config.secrets.grafana-secret-key.dest}}";
+        auth = {
+          oauth_allow_insecure_email_lookup = true;
+        };
         server = {
           domain = hostnames.metrics;
           http_addr = "127.0.0.1";
           http_port = 3000;
           protocol = "http";
+          root_url = "https://${hostnames.metrics}/";
         };
         smtp = rec {
           enabled = true;
@@ -58,6 +74,19 @@ in
           from_name = "Grafana";
           from_address = user;
         };
+        "auth.generic_oauth" = {
+          enabled = true;
+          name = "Pocket ID";
+          allow_sign_up = true;
+          client_id = "85d879ed-1a86-4984-b33d-43806500ef98";
+          client_secret = "$__file{${config.secrets.grafana-oidc-secret.dest}}";
+          scopes = "openid profile email";
+          auth_url = "https://${hostnames.auth}/authorize";
+          token_url = "https://${hostnames.auth}/api/oidc/token";
+          api_url = "https://${hostnames.auth}/api/oidc/userinfo";
+          login_attribute_path = "preferred_username";
+          skip_org_role_sync = true;
+        };
       };
       provision = {
         enable = true;