feat: declare governed external provider state

docs/FILES_HANDBOOK.md

@@ -408,6 +408,8 @@ the table above says live access is disabled.
 | `FILE_STORAGE_LOCAL_FALLBACK_ROOTS` | empty | Comma-separated older read-only roots checked after the primary root |
 | `FILE_STORAGE_S3_ENDPOINT_URL` and related `FILE_STORAGE_S3_*` values | deployment-specific | S3-compatible endpoint, region, credentials, and bucket |
 | `FILE_STORAGE_S3_DEPLOYMENT_MANAGED` | `false` | Installer-only trust marker for the exact `http://garage:3900` service; never use it for another endpoint |
+| `FILE_STORAGE_S3_ENDPOINT_TRUSTED` | `false` | Deployment-owner acknowledgement for one clean HTTPS external S3 origin; never expose this through connector configuration |
+| `GOVOPLAN_STATE_PROFILE` | `local` | Selects `local`, one-host `host-shared`, or multi-host `shared` state validation |
 | `FILE_UPLOAD_MAX_BYTES` | 50 MiB | Direct-upload and extracted archive-member maximum |
 | `FILE_UPLOAD_ZIP_MAX_BYTES` | 250 MiB | Compressed archive request maximum (legacy name retained for compatibility) |
 | `FILE_ARCHIVE_MAX_ENTRIES` | 10,000 | Maximum declared archive entries |
@@ -421,20 +423,19 @@ under the configured root and rejects escape attempts. Fallback roots support a
 controlled storage-root migration: new writes go to the primary root while
 reads can still find older objects.
 
-The S3 managed-storage adapter fails closed before creating a boto3 client for
-arbitrary external endpoints because the SDK cannot yet guarantee
-connection-time DNS/IP pinning and redirect revalidation. The supported
-installer may provision a deployment-owned Garage service at the exact
-`http://garage:3900` endpoint and set
-`FILE_STORAGE_S3_DEPLOYMENT_MANAGED=true`. Files accepts only that exact
-service-discovery endpoint and forces path-style S3 addressing. The marker is
-deployment authority, not a general private-network bypass.
+The supported installer may provision a deployment-owned Garage service at the
+exact `http://garage:3900` endpoint and set
+`FILE_STORAGE_S3_DEPLOYMENT_MANAGED=true`. An operator-selected external S3
+backend instead requires a clean HTTPS origin and
+`FILE_STORAGE_S3_ENDPOINT_TRUSTED=true`. Both are deployment authority, not a
+general connector or private-network bypass. Core owns the shared backend
+implementation; Files owns metadata and the Files key namespace.
 
 Multiple API replicas require the same durable blob namespace. Separate local
-container filesystems will produce incomplete reads. Until a pinned shared
-object-storage transport is available, use one durable shared mount or constrain
-Files traffic to a deployment topology that preserves one consistent local
-root.
+container filesystems will produce incomplete reads. Use `host-shared` with one
+durable shared mount only for same-host replicas. Independent hosts require the
+`shared` profile with external S3, PostgreSQL, Redis, a stable installation id,
+and one immutable module composition.
 
 ### Connector egress
 
@@ -464,10 +465,12 @@ Override the connector response limits with
 `GOVOPLAN_CONNECTOR_MAX_FILE_TRANSFER_BYTES`. The smaller applicable limit wins
 when an import is also subject to `FILE_UPLOAD_MAX_BYTES`.
 
-Never work around a pinning failure by adding a raw IP, disabling TLS, or
-enabling private networks. SMB may redirect through DFS, and S3 SDKs may perform
-their own redirects or endpoint discovery; both remain disabled even for an IP
-literal until every connection peer can be governed.
+Never work around a connector pinning failure by adding a raw IP, disabling TLS,
+or enabling private networks. SMB may redirect through DFS, and user-configured
+S3 connectors may perform their own redirects or endpoint discovery; those
+connector transports remain disabled until every connection peer can be
+governed. The separately configured platform S3 backend is trusted only by the
+deployment owner and is not selectable by a user or connector profile.
 
 ### Backup and restore
 
@@ -477,6 +480,8 @@ include:
 - Files database rows, including asset/version/blob relationships, shares,
   connector settings, and campaign attachment-use evidence;
 - every object below `FILE_STORAGE_LOCAL_ROOT` and any still-used fallback root;
+  or the complete S3 bucket/prefix and version/lifecycle evidence for an S3
+  backend;
 - the exact `MASTER_KEY_B64` needed to decrypt retained connector credentials;
 - deployment-owned connector profile files, referenced CA bundles, and secret
   environment configuration where those definitions are in use.
@@ -779,7 +784,7 @@ 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, 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 |
+| Managed storage | Core local/S3 backend, exact managed-Garage or explicitly trusted HTTPS external S3, state-profile validation, fallback local read roots, tenant blob deduplication, checksums, bounded resumable integrity scans, quarantine, and dry-run-first orphan cleanup | Scheduled scan execution and deployment-specific S3 HA/backup automation |
 | Upload | Bounded direct upload, drag-and-drop UI, archive preview/selective extraction, password-protected ZIP support, 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 grants, expiry, idempotent revocation, searchable share-management UI, and campaign linkage display | Richer policy-driven share lifecycles |
@@ -808,8 +813,9 @@ Before releasing Files:
 5. Exercise an allowed and denied owner/share path.
 6. Exercise upload, ZIP bounds, conflict handling, download, and soft deletion.
 7. Exercise connector policy explanation and one pinned HTTP provider where
-   configured; verify managed Garage if selected, and verify arbitrary external
-   S3 and SMB still fail closed.
+   configured; verify the deployment-managed or trusted external S3 backend if
+   selected, and verify user-configured S3 and SMB connector peers still fail
+   closed.
 8. Verify credential deletion scrubs dependents and produces audit evidence.
 9. Verify a campaign attachment snapshot still identifies its exact version and
    checksum after the current file changes.