Merge branch 'main' into docs/sdd-integration

docs/ARCHITECTURE.md

@@ -61,7 +61,7 @@ Members of the cross-cutting layer have no entity of their own, no user-facing C
 | `audit` | Append-only event store (`audit_log`) for all domain mutations. Feeds the activity feed and Family Pulse dashboard. | Consumed by 5+ domains; no user-facing CRUD of its own |
 | `config` | Infrastructure bean definitions: `MinioConfig`, `AsyncConfig`, `WebConfig` | Framework infra; no business logic |
 | `dashboard` | Stats aggregation for the admin dashboard and Family Pulse widget | Aggregates from 3+ domains; no owned entities |
-| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service. Adding a new `ErrorCode` requires matching updates in `frontend/src/lib/shared/errors.ts` and all three `messages/*.json` locale files. Current security-related codes: `CSRF_TOKEN_MISSING` (403 on mutating request without valid `X-XSRF-TOKEN` header), `TOO_MANY_LOGIN_ATTEMPTS` (429 when login rate limit exceeded). Journey/geschichte domain codes: `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG`. |
+| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service. Adding a new `ErrorCode` requires matching updates in `frontend/src/lib/shared/errors.ts` and all three `messages/*.json` locale files. Current security-related codes: `CSRF_TOKEN_MISSING` (403 on mutating request without valid `X-XSRF-TOKEN` header), `TOO_MANY_LOGIN_ATTEMPTS` (429 when login rate limit exceeded). Journey/geschichte domain codes: `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`, `GESCHICHTE_TITLE_TOO_LONG`, `GESCHICHTE_INTRO_TOO_LONG`. Timeline domain codes: `TIMELINE_EVENT_NOT_FOUND`, `TIMELINE_EVENT_CONFLICT`, `TIMELINE_TITLE_TOO_LONG`, plus a generic `CONFLICT` (409 optimistic-lock backstop). |
 | `filestorage` | `FileService` — MinIO/S3 upload, download, presigned-URL generation | Generic service; consumed by `document` and `ocr` |
 | `importing` | `CanonicalImportOrchestrator` — async canonical import running four idempotent loaders (`TagTreeImporter` → `PersonRegisterImporter` → `PersonTreeImporter` → `DocumentImporter`) over the normalizer's committed canonical artifacts (`canonical-*.xlsx` + `canonical-persons-tree.json`) | Orchestrates across `person`, `tag`, `document` |
 | `security` | `SecurityConfig`, `Permission` enum, `@RequirePermission` annotation, `PermissionAspect` (AOP) | Framework infra; enforced globally across all controllers |

docs/adr/041-renovate-runner-setup.md

@@ -0,0 +1,123 @@
+# ADR-041 — Renovate runner stand-up: two-token model, OSV surfacing, digest pinning
+
+**Date:** 2026-06-13  
+**Status:** Accepted  
+**Issue:** [#818](https://git.raddatz.cloud/marcel/familienarchiv/issues/818)
+
+---
+
+## Context
+
+Issue #817 (esbuild/cookie advisory) revealed that `main` had no early-warning
+mechanism for newly-published advisories. An advisory landed against already-pinned
+versions, turned the `npm audit --audit-level=high --omit=dev` gate red on `main`,
+and then ambushed the next unrelated PR (#774). The author who hit it did not cause
+it and had no warning.
+
+`renovate.json` existed but `renovatebot` had never actually run: there was no
+`.gitea/workflows/renovate.yml` and zero Renovate-authored PRs in the repo's entire
+history. The three `packageRules` (bucket4j / tiptap / privileged-digest) were
+silently inert.
+
+This ADR records the **negative space** — why specific design choices were made,
+so future maintainers do not "tidy up" toward a worse outcome.
+
+---
+
+## Decision
+
+### Why there is no auto-provided `GITEA_TOKEN`
+
+Self-hosted Gitea runners do not auto-inject a `GITEA_TOKEN` equivalent.
+`docs/infrastructure/ci-gitea.md` (and its current line ~251) explicitly states the
+token "must be created manually." No existing workflow in this repo references
+`GITEA_TOKEN` for API calls — only for container registry auth (`docker login`).
+Both `RENOVATE_TOKEN` and `NIGHTLY_AUDIT_TOKEN` must be manually provisioned as
+Gitea secrets by a repository admin.
+
+### Why two tokens, not one
+
+The two jobs have different blast radii on token compromise:
+
+| Token | Scopes | Used by |
+|-------|--------|---------|
+| `RENOVATE_TOKEN` | `contents` + `pull_request` + `issues` | Renovate — must read/write files and open PRs |
+| `NIGHTLY_AUDIT_TOKEN` | `issues` only | Nightly audit — only needs to file a tracking issue |
+
+The nightly job's token appears in step `env:` and is passed to `curl -H`. A leak via
+runner logs, process arguments, or a misconfigured step would expose the token.
+An `issues`-only token cannot push branches, open PRs, or read repository contents —
+the leaked token's blast radius is limited to creating/editing issues.
+
+A single broad token would give any leak path full `contents` + `pull_request` write
+access to the repository. That risk is asymmetric with the upside (one fewer secret).
+
+Both tokens belong to one dedicated bot account (consistent authorship; one identity
+to audit and rotate). **Branch protection on `main` must forbid the bot pushing
+directly**, because a `contents`-scoped token can push to any unprotected branch.
+
+### Why the Renovate action is digest-pinned
+
+`renovatebot/github-action` executes with the `RENOVATE_TOKEN` in scope. That token
+carries `contents` + `pull_request` + `issues` — enough to read files, open PRs, and
+write issues. An unpinned `@v40` tag can be re-pointed by the upstream maintainer
+(or a compromised maintainer account) at any time. A pinned digest (`@<sha>`) cannot
+be silently modified; the SHA is immutable. This is the same threat model applied to
+all privileged CI steps in this repo (see the `matchFileNames` rule in `renovate.json`
+for `.gitea/workflows/**`).
+
+Renovate itself will open a PR to bump the digest when a new release ships, which is
+the intended update path.
+
+### Why `osvVulnerabilityAlerts` is the load-bearing detector on Gitea
+
+Renovate's `vulnerabilityAlerts` config key triggers off a *platform* vulnerability
+graph. GitHub exposes the GitHub Advisory Database via its API; **Gitea does not
+expose an equivalent vulnerability graph**. On self-hosted Gitea, `vulnerabilityAlerts`
+is effectively a label carrier — it attaches the configured labels to PRs that
+`osvVulnerabilityAlerts` already detected, but it is not an independent detector.
+
+`osvVulnerabilityAlerts: true` is the load-bearing flag: Renovate queries
+[OSV.dev](https://osv.dev) directly (platform-agnostic). The runner host must be able
+to reach OSV.dev over HTTPS — if egress is filtered, allow `osv.dev:443` or the flag
+silently no-ops.
+
+### Why the root `schedule` does not mute security PRs
+
+`"schedule": ["before 6am on monday"]` in `renovate.json` batches **routine** dependency
+updates (version bumps outside any security context) to a weekly window. This reduces
+noise from routine update PRs while still allowing review before merge.
+
+**Security and vulnerability PRs bypass the schedule by design** — Renovate raises
+them immediately regardless of the schedule window. A future "tidy-up" that removes
+or widens the schedule cannot mute vulnerability alerts; this is worth stating
+explicitly to prevent that misunderstanding.
+
+### Why `lockFileMaintenance` has no `automerge`
+
+`lockFileMaintenance` refreshes transitive pins weekly so the dependency tree drifts
+into fewer advisories over time. It is explicitly set without `automerge: true` because
+a weekly transitive pin refresh can silently break the build if a transitive dep
+introduces a breaking change. These PRs are small and should be reviewed.
+
+### Why there is no entry in `l2-containers.puml`
+
+`docs/architecture/c4/l2-containers.puml` documents long-lived infrastructure
+containers (services that run continuously). Renovate is a scheduled CI job that runs
+on a Gitea Actions runner and exits — it is not a long-lived container. Adding it to
+the container diagram would misrepresent the architecture. This omission is deliberate,
+not an oversight.
+
+---
+
+## Consequences
+
+- Newly-published advisories against our frontend dependencies are surfaced within
+  one day (daily Renovate cron) rather than at the next contributor PR.
+- A nightly `npm audit` job provides an independent signal for dev-dependency advisories
+  that Renovate may not cover via OSV.
+- Two secrets (`RENOVATE_TOKEN`, `NIGHTLY_AUDIT_TOKEN`) must be manually provisioned
+  and rotated annually (or on suspected compromise). See
+  `docs/infrastructure/ci-gitea.md` for the runbook.
+- The bot account must be kept active and branch protection on `main` must forbid
+  it pushing directly. These are operational prerequisites, not code invariants.

docs/infrastructure/ci-gitea.md

@@ -462,3 +462,82 @@ jobs:
           name: e2e-results
           path: frontend/test-results/e2e/
 ```
+
+---
+
+## Renovate + Nightly Audit — Token Model
+
+> See [ADR-041](../adr/041-renovate-runner-setup.md) for full rationale.
+
+### Two-token model
+
+This repo uses two separate tokens for automated dependency work, both manually
+provisioned as Gitea secrets. There is **no auto-provided `GITEA_TOKEN`** on
+self-hosted Gitea runners — it must be created manually (see §Context Variable Names
+table above).
+
+| Secret | Scopes | Job | Reason |
+|--------|--------|-----|--------|
+| `RENOVATE_TOKEN` | `contents` + `pull_request` + `issues` | `renovate.yml` | Renovate needs to read/write files and open PRs |
+| `NIGHTLY_AUDIT_TOKEN` | `issues` only | `nightly.yml` → `npm-audit` job | Only needs to file a tracking issue; an `issues`-only token cannot push branches or read contents — limits blast radius on leak |
+
+Both tokens belong to a single dedicated bot account. **Branch protection on `main`
+must forbid the bot pushing directly**, because a `contents`-scoped token can push
+to any unprotected branch.
+
+### PAT rotation cadence
+
+Rotate both tokens:
+- **Annually** (calendar reminder)
+- **Immediately** on suspected compromise (runner log leak, accidental `set -x`, etc.)
+
+Tokens are stored exclusively as Gitea secrets. Never commit them to `.env` files or
+log them. The nightly audit step passes its token via `env:` at the step level, reads
+it as `$NIGHTLY_AUDIT_TOKEN` in the shell, and never runs the API `curl` under
+`set -x`.
+
+### OSV vs platform alerts on Gitea
+
+Renovate's `vulnerabilityAlerts` config key requires a *platform* vulnerability graph.
+**Gitea does not expose one** — it has no equivalent to the GitHub Advisory Database
+API. On this runner, `vulnerabilityAlerts` is a label carrier only: it attaches
+`security` and `P1-high` labels to PRs that `osvVulnerabilityAlerts` already raised.
+
+`osvVulnerabilityAlerts: true` is the load-bearing detector. Renovate queries
+[OSV.dev](https://osv.dev) directly, which works regardless of platform. The runner
+host must be able to reach `osv.dev:443`. If egress is filtered and OSV.dev is
+unreachable, the flag silently no-ops — verify egress when standing up the runner.
+
+### Nightly audit vs PR gate (divergence)
+
+| Gate | Command | Dev deps | When |
+|------|---------|----------|------|
+| PR gate (`ci.yml`) | `npm audit --audit-level=high --omit=dev` | ❌ excluded | Every PR |
+| Nightly audit (`nightly.yml`) | `npm audit --audit-level=high` | ✅ included | Nightly + `workflow_dispatch` |
+
+The nightly job is **deliberately broader** — it catches dev-tooling advisories
+(esbuild, Vite, vitest, etc.) that the PR gate ignores. A red nightly audit job does
+**not** mean the PR gate is broken; the two signals are independent.
+
+### Runbook: nightly-opened tracking issue
+
+When the `npm-audit` job opens or updates the tracking issue
+"Nightly npm audit: high-severity advisory":
+
+1. **Triage severity.** Check the advisory page (link in the issue body). Is it
+   exploitable in production? A dev-only dep (e.g. esbuild, prettier) has no
+   production attack surface — treat as low urgency.
+
+2. **Pin or upgrade.** If a non-breaking upgrade is available, update
+   `frontend/package.json` and regenerate the lockfile. Open a PR.
+
+3. **Override if justified.** If the advisory does not apply (dev-only dep, no
+   exploitable path), add an `npm audit` override in `package.json`:
+   ```json
+   "overrides": { "esbuild": ">=0.25.4" }
+   ```
+   Document the rationale in the PR body. See #817 for the reference decision tree.
+
+4. **Close the tracking issue** once the advisory is resolved or overridden and the
+   nightly job runs clean (verify via the `✅ npm audit clean` heartbeat in the job
+   summary).

docs/infrastructure/self-hosted-catalogue.md

@@ -151,7 +151,7 @@ receivers:
 name: Renovate
 on:
   schedule:
-    - cron: '0 3 * * 1'  # every Monday at 3am
+    - cron: '0 3 * * *'  # daily at 03:00 UTC — cuts OSV-alert latency to ≤1 day
   workflow_dispatch:
 
 jobs:
@@ -160,32 +160,58 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Run Renovate
-        uses: renovatebot/github-action@v40
+        # Pin by digest — this action holds contents+pull_request+issues token;
+        # an unpinned tag is a supply-chain risk. Update digest + renovate-version
+        # together when Renovate publishes a new release.
+        uses: renovatebot/github-action@8217b3fc286df088d7c27f3255fe8414463bc0fd  # v46.1.15
         with:
           configurationFile: renovate.json
-          token: ${{ secrets.GITEA_TOKEN }}
-          renovate-version: latest
+          token: ${{ secrets.RENOVATE_TOKEN }}
+          renovate-version: "46.1.15"
+        env:
+          RENOVATE_PLATFORM: gitea
+          RENOVATE_ENDPOINT: https://gitea.example.com   # replace with your Gitea URL
+          RENOVATE_REPOSITORIES: '["org/repo"]'          # replace with your repo slug
+          LOG_LEVEL: info
 ```
 
+> **Token:** `RENOVATE_TOKEN` must be a PAT on a dedicated bot account with scopes
+> `contents` + `pull_request` + `issues`. **Do not reuse** `GITEA_TOKEN` — that variable
+> is not auto-provided on self-hosted Gitea runners and must be manually created anyway;
+> using a single broad token violates least-privilege. See ADR-041.
+
 ### Renovate Configuration
 
+The `renovate.json` in the repo root carries only dependency rules — platform and
+endpoint config is injected via `env:` in the workflow above. Keep the two concerns
+separate so the config file remains portable.
+
 ```json
-// renovate.json
 {
-  "platform": "gitea",
-  "endpoint": "https://gitea.example.com",
-  "repositories": ["org/familienarchiv"],
-  "automerge": true,
-  "automergeType": "pr",
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "osvVulnerabilityAlerts": true,
+  "dependencyDashboard": true,
+  "schedule": ["before 6am on monday"],
+  "vulnerabilityAlerts": {
+    "labels": ["security", "P1-high"]
+  },
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": ["before 6am on monday"]
+  },
   "packageRules": [
     {
-      "matchUpdateTypes": ["patch"],
-      "automerge": true
+      "matchPackageNames": ["com.example:my-dep"],
+      "automerge": true,
+      "matchUpdateTypes": ["patch"]
     }
   ]
 }
 ```
 
+> **Do not add `automerge: true` at the root.** Security and digest-bump PRs should
+> always be reviewed manually. Per-rule `automerge` on patch-level routine deps is fine.
+
 ---
 
 ## Secrets Management -- age + git-crypt