feat: expose immutable postbox file references

src/govoplan_files/backend/manifest.py

@@ -13,6 +13,7 @@ from govoplan_core.core.encryption import CAPABILITY_ENCRYPTION_CONTENT_CIPHER
 from govoplan_core.core.files import (
     CAPABILITY_FILES_ACCESS,
     CAPABILITY_FILES_ARTIFACT_STORE,
+    CAPABILITY_FILES_POSTBOX_REFERENCES,
 )
 from govoplan_core.core.module_guards import (
     drop_table_retirement_provider,
@@ -424,11 +425,12 @@ manifest = ModuleManifest(
         CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
         CAPABILITY_AUTH_PERMISSION_EVALUATOR,
     ),
-    optional_dependencies=("campaigns", "encryption", "records", "search"),
+    optional_dependencies=("campaigns", "encryption", "postbox", "records", "search"),
     provides_interfaces=(
         ModuleInterfaceProvider(name="files.access", version="0.1.6"),
         ModuleInterfaceProvider(name="files.campaign_attachments", version="0.1.6"),
         ModuleInterfaceProvider(name=CAPABILITY_FILES_ARTIFACT_STORE, version="0.1.14"),
+        ModuleInterfaceProvider(name=CAPABILITY_FILES_POSTBOX_REFERENCES, version="1.0.0"),
         ModuleInterfaceProvider(name=CAPABILITY_RECORD_SOURCE_FILES, version="1.0.0"),
         ModuleInterfaceProvider(name=CAPABILITY_FORM_EVIDENCE_FILES, version="1.0.0"),
     ),
@@ -580,6 +582,51 @@ manifest = ModuleManifest(
         ),
     ),
     documentation=(
+        DocumentationTopic(
+            id="files.postbox.exact-version-references",
+            title="Resolve exact file versions for Postbox evidence",
+            summary="Keep Files authorization authoritative when Postbox displays a typed file reference.",
+            body=(
+                "Files exposes an optional capability that resolves file-asset and file-version references for an already authorized Postbox message. "
+                "The capability returns immutable version metadata and a version-specific download route only when the current principal has Files download "
+                "permission and direct resource access. It does not turn Postbox access into a file share."
+            ),
+            layer="configured",
+            documentation_types=("user", "admin"),
+            audience=("administrator", "user", "campaign_manager"),
+            related_modules=("postbox", "audit"),
+            conditions=(
+                DocumentationCondition(
+                    required_modules=("files",),
+                    any_scopes=("files:file:download", "files:file:admin"),
+                ),
+            ),
+            links=(
+                DocumentationLink(
+                    label="Files",
+                    href="/files",
+                    kind="runtime",
+                ),
+                DocumentationLink(
+                    label="Files handbook",
+                    href="govoplan-files/docs/FILES_HANDBOOK.md",
+                    kind="repository",
+                ),
+            ),
+            translations={
+                "de": {
+                    "title": "Exakte Dateiversionen für Postfachnachweise auflösen",
+                    "summary": "Die Files-Berechtigungsprüfung bleibt maßgeblich, wenn Postbox einen typisierten Dateiverweis anzeigt.",
+                    "body": (
+                        "Files stellt eine optionale Capability bereit, die Datei- und Dateiversionsverweise einer bereits autorisierten Postfachnachricht auflöst. "
+                        "Sie liefert unveränderliche Versionsmetadaten und einen versionsgenauen Download nur, wenn die aktuelle Person die Files-Downloadberechtigung "
+                        "und direkten Ressourcenzugriff besitzt. Postfachzugriff wird nicht automatisch zu einer Dateifreigabe."
+                    ),
+                }
+            },
+            metadata={"kind": "reference", "help_contexts": ["files.postbox-reference"]},
+            order=30,
+        ),
         DocumentationTopic(
             id="files.configuration-package.managed-storage",
             title="Validate deployment-managed file storage",
@@ -1478,6 +1525,10 @@ manifest = ModuleManifest(
             "govoplan_files.backend.capabilities",
             fromlist=["artifact_store_capability"],
         ).artifact_store_capability(context),
+        CAPABILITY_FILES_POSTBOX_REFERENCES: lambda context: __import__(
+            "govoplan_files.backend.capabilities",
+            fromlist=["postbox_reference_capability"],
+        ).postbox_reference_capability(context),
         "files.campaign_attachments": lambda context: __import__(
             "govoplan_files.backend.capabilities", fromlist=["campaign_capability"]
         ).campaign_capability(context),