Release govoplan-access v0.1.25: harden authentication and repair identity mappings

2026-09-08 01:32:20 +02:00
parent 0f8a05f8b9
commit 8f8072b4ae
25 changed files with 742 additions and 38 deletions
@@ -0,0 +1,79 @@
+# External function mapping schema repair
+
+Access owns `access_external_function_role_assignments`. Some older databases
+record the Access baseline (`4a5b6c7d8e9f`) without this table. The mapping list
+and `/api/v1/admin/external-function-role-mappings/delta` then fail with an
+undefined-table error. This is a schema/history mismatch, not a reason to change
+user permissions or recreate tenant data.
+
+Forward repair revision `d8f1b4e7a0c3` follows Access `c7e0a3d6f9b2` on the
+release track and `b6d9f2a5c8e1` on the disposable-development track. The latter
+also requires Core's existing scope-table rename `4f2a9c8e7b6d`; this is a Core
+contract and does not require the optional Tenancy or Organizations modules.
+
+Before applying deployment migrations, back up and verify the database backup.
+Use the configured migration track and ordinary deployment migration workflow,
+including its deployment-wide advisory lock. Inspect the pending revision plan
+before any targeted repair. Never replay or stamp the baseline, initialize dev
+data, reset the database, or switch migration tracks to bypass the error.
+
+The development launcher can run pending migrations when its file watcher
+reloads the backend. Prepare and test a migration outside the watched source
+tree, and complete the backup/preflight before placing a new migration file in
+that tree. Do not assume that waiting to invoke a migration command prevents a
+running development instance from applying it automatically.
+
+The repair:
+
+- Creates the absent mapping table only, with its baseline columns, role/scope
+  cascade foreign keys, primary key, tenant/source/function/role uniqueness,
+  and four lookup indexes.
+- Does nothing if the table already exists. It does not alter partial tables;
+  any other schema mismatch needs separate inspection.
+- Never invents mappings or changes roles, memberships, permissions, or other
+  application records. An empty list means no mappings have been configured.
+- Keeps the table and any stored mappings on downgrade, because the table
+  belongs to the baseline and removing it would delete authorization policy.
+
+After migration, verify both mapping list endpoints return success for an
+authorized user in the active tenant, and check the table's constraints and
+indexes. Existing read scopes and tenant isolation remain enforced. A missing
+table cannot reveal whether historical mappings were once removed: this repair
+does not reconstruct lost policy; investigate backups if mappings were expected.
+
+Regression coverage in `tests/test_external_function_mapping_migration.py`
+recreates the observed missing-table failure in isolated databases on both
+tracks. It checks the HTTP list/delta responses, repeated upgrades, no-op
+upgrades with existing mappings, downgrade/re-upgrade preservation, unchanged
+parent rows/permissions, constraints, denied unprivileged reads, and tenant
+isolation.
+
+## Deutsch
+
+Bei älteren Datenbanken kann die Access-Basismigration als angewendet vermerkt
+sein, obwohl `access_external_function_role_assignments` fehlt. Die Liste der
+Funktions-Rollenzuordnungen und ihre Delta-API melden dann einen internen Fehler.
+Dies ist ein Widerspruch zwischen Schema und Migrationsstand, kein Anlass zur
+Erweiterung von Berechtigungen oder zum Neuerstellen von Mandantendaten.
+
+Vor der regulären, vorwärtsgerichteten Migration `d8f1b4e7a0c3` eine überprüfte
+Datenbanksicherung erstellen. Den konfigurierten Migrationstrack und den
+regulären Bereitstellungsablauf mit installationsweiter Migrationssperre nutzen;
+bei einer gezielten Reparatur zuvor die ausstehenden Revisionen prüfen.
+Basismigrationen nicht erneut ausführen oder lediglich als angewendet markieren,
+keine Entwicklungsdaten initialisieren und die Datenbank nicht zurücksetzen.
+Der Entwicklungsstarter kann ausstehende Migrationen bereits beim automatischen
+Neuladen des Backends anwenden. Neue Migrationsdateien deshalb außerhalb des
+überwachten Quellbaums vorbereiten und testen; Sicherung und Vorprüfung vor dem
+Kopieren in den überwachten Quellbaum abschließen. Das Warten mit einem manuellen
+Migrationsaufruf verhindert die automatische Anwendung nicht.
+
+Die Reparatur erstellt nur die fehlende Tabelle einschließlich Fremdschlüsseln,
+Eindeutigkeitsbedingung und Indizes. Vorhandene Tabellen und Datensätze bleiben
+unverändert; auch ein Downgrade entfernt keine Zuordnungsdaten. Teilweise
+vorhandene Tabellen werden nicht umgebaut und erfordern eine gesonderte Prüfung.
+Es entstehen keine automatischen Zuordnungen oder neuen Rechte. Anschließend
+beide Listenendpunkte im aktiven Mandanten mit einer berechtigten Person prüfen.
+Eine leere Liste bedeutet, dass keine Zuordnungen konfiguriert sind. Falls früher
+Zuordnungen erwartet wurden, Sicherungen prüfen: Verlorene Berechtigungsregeln
+lassen sich aus einer fehlenden Tabelle nicht rekonstruieren.