feat: harden file sharing and integrity

docs/FILES_HANDBOOK.md

@@ -187,9 +187,10 @@ The managed-file flow is:
 8. Connector-originated operations also emit their connector audit evidence.
 
 Blob storage is not part of the database transaction. An object may therefore
-be left without committed metadata after a process or database failure. No
-automatic orphan reconciliation exists yet; operators must account for this in
-integrity checks and retention plans.
+be left without committed metadata after a process or database failure. The
+operator integrity API scans database blobs and the tenant storage prefix in
+bounded, resumable phases. It reports orphan objects before any cleanup and
+never deletes them as part of a scan.
 
 ### Governed connector import
 
@@ -463,9 +464,30 @@ include:
 - deployment-owned connector profile files, referenced CA bundles, and secret
   environment configuration where those definitions are in use.
 
-There is no Files backup/restore API and no automated blob integrity or orphan
-reconciliation job. Use a write quiesce or coordinated snapshots so database
-references and objects represent the same recovery point.
+There is no Files backup/restore API. Use a write quiesce or coordinated
+snapshots so database references and objects represent the same recovery point.
+The integrity API verifies a restored set, but it does not replace a coordinated
+backup.
+
+Create a scan with `POST /api/v1/files/integrity/scans`, then call
+`POST /api/v1/files/integrity/scans/{scan_id}/run` until it reports
+`completed`. Each call advances at most the persisted batch size, so a stopped
+operator or worker can resume from the committed blob/object cursors.
+
+Findings distinguish:
+
+- `missing`: metadata references an absent object;
+- `size_mismatch` or `checksum_mismatch`: bytes do not match immutable blob
+  metadata and the blob is quarantined;
+- `orphan_object`: an object exists in the tenant Files prefix without a
+  corresponding blob row.
+
+Missing or corrupt blobs fail closed for ordinary downloads and Campaign
+attachment materialization. After restoring the expected bytes, use the finding
+`recheck` action first in dry-run mode and then apply it. Orphan cleanup is also
+dry-run by default, rechecks that no database reference exists, remains scoped
+to the scanned tenant prefix, and is idempotent. Both applied and dry-run
+actions emit audit evidence.
 
 After restore:
 
@@ -493,9 +515,10 @@ Legacy external secret references are detached and identified as non-owned;
 Files never calls a provider delete operation for them.
 
 The retirement executor drops database tables but does not delete corresponding
-objects from the configured blob backend. Operators must include those orphaned
-objects in the approved retention/destruction plan. Validate the installer
-snapshot and independent blob backup before retirement.
+objects from the configured blob backend. Operators must include those objects
+in the approved retention/destruction plan, report them with an integrity scan,
+and explicitly approve cleanup. Validate the installer snapshot and independent
+blob backup before retirement.
 
 ### Operational signals
 
@@ -657,8 +680,9 @@ delete against an already scrubbed tombstone does not recreate secret evidence.
 File versions and blobs are effectively retained indefinitely today. Although a
 blob has `ref_count` and `retained_until` fields, no complete retention-policy,
 legal-hold, hard-purge, or garbage-collection service enforces them. There is
-also no supported user restore endpoint for soft-deleted assets/folders and no
-automated orphan-object reconciliation.
+also no supported user restore endpoint for soft-deleted assets/folders.
+Integrity reconciliation is operator-triggered and is not a retention or
+automatic garbage-collection policy.
 
 Do not promise erasure, timed retention, legal hold, or self-service recovery
 from the current soft-delete behavior. Those require an explicit, auditable
@@ -735,10 +759,10 @@ returning different content or credentials.
 
 | Area | Implemented now | Planned or explicitly outside the current boundary |
 | --- | --- | --- |
-| Managed storage | Local durable-root backend, fallback read roots, tenant blob deduplication, checksums | Operational S3 after pinned SDK transport ([#34](https://git.add-ideas.de/GovOPlaN/govoplan-files/issues/34)); automated integrity/orphan reconciliation ([#36](https://git.add-ideas.de/GovOPlaN/govoplan-files/issues/36)) |
+| Managed storage | Local durable-root backend, fallback read roots, tenant blob deduplication, checksums, bounded resumable integrity scans, quarantine, and dry-run-first orphan cleanup | Operational S3 after pinned SDK transport ([#34](https://git.add-ideas.de/GovOPlaN/govoplan-files/issues/34)); scheduled scan execution |
 | Upload | Bounded direct upload, drag-and-drop UI, ZIP spool/extract limits, explicit conflicts | Malware scanning, quotas, type policy, resumable/chunked upload |
 | Organization | Folders, bulk rename preview/apply, move/copy, drag-and-drop, ZIP download, pattern resolution | General file-history UI and user-driven append-version/restore |
-| Sharing | User/group/tenant/campaign grant or permission update through API; campaign linkage display | Share revocation/expiry and complete general share-management UI ([#37](https://git.add-ideas.de/GovOPlaN/govoplan-files/issues/37)) |
+| Sharing | User/group/tenant/campaign grants, expiry, idempotent revocation, searchable share-management UI, and campaign linkage display | Richer policy-driven share lifecycles |
 | Deletion/retention | Soft-delete assets/folders/spaces; immediate audited connector-secret scrubbing | File restore API, hard purge, retention policy, legal hold, and blob GC ([#38](https://git.add-ideas.de/GovOPlaN/govoplan-files/issues/38)) |
 | Connector governance | Scoped profiles/credentials/policies, effective source explanation, separate credentials, linked user/group spaces | Provider-owned external secret lifecycle; API `secret_ref` remains rejected |
 | HTTP connectors | Pinned, bounded, no-redirect Seafile and WebDAV/Nextcloud browse/import/manual sync | Background/folder sync, remote mutation, long-running transfer workers |