feat: support optional encrypted file content

docs/FILES_HANDBOOK.md

@@ -29,12 +29,18 @@ a document collaboration engine, or a records-management system.
 A managed file is a tenant-scoped logical asset with exactly one user or group
 owner, a normalized path, and a current version. The current version points to a
 blob record containing the storage location, SHA-256 checksum, byte size, and
-content type. Current service paths append a version when connector sync finds
+content type. A protected blob also records its Encryption envelope, protection
+discriminator, stored-ciphertext checksum, and stored-ciphertext size. Current
+service paths append a version when connector sync finds
 changed content; they do not mutate the previous version record.
 
-Content with the same tenant, SHA-256 checksum, and size can reuse one blob.
-This is storage deduplication and integrity evidence, not proof of authorship or
-source authenticity.
+Unprotected content with the same tenant, plaintext SHA-256 checksum, size, and
+protection discriminator can reuse one blob. Protected content is deduplicated
+only inside the same vault/profile discriminator; ciphertext is never silently
+reused across protection boundaries. Plaintext checksums remain semantic
+version evidence, while download and integrity scans verify stored ciphertext
+before asking Encryption to open it. Neither digest proves authorship or source
+authenticity.
 
 The main domain objects are:
 
@@ -42,7 +48,7 @@ The main domain objects are:
 | --- | --- | --- |
 | File asset | The user-facing file identity, owner, logical path, description, metadata, and current version | Created, organized, shared, and soft-deleted |
 | File version | A numbered snapshot of one asset and its blob | Appended by connector sync when bytes change; retained |
-| File blob | Stored bytes plus checksum, size, backend, key, reference count, and optional retention timestamp | Reused within a tenant; no automated garbage collection |
+| File blob | Stored plaintext semantics plus stored-byte integrity, backend key, optional Encryption envelope, reference count, and retention timestamp | Reused only within a tenant and matching protection boundary; no automated garbage collection |
 | Folder | An explicit logical path in a user or group space | Created, moved/renamed through organize operations, and soft-deleted |
 | Share | A grant from an asset to a user, group, tenant, or campaign with `read`, `write`, or `manage` permission | Created or updated; no public revocation endpoint yet |
 | Connector profile | A governed external endpoint, scope, optional credential link, policy, and descriptive capabilities | Created, updated, disabled, or credential-scrubbed on deletion |
@@ -634,13 +640,17 @@ Files baseline indiscriminately.
   secrets and deployment references.
 - API metadata is recursively checked for secret-like values.
 - Downloads use sanitized attachment filenames.
-- SHA-256 and byte size are recorded for every blob/version.
+- Plaintext semantic and stored-byte SHA-256/size evidence are recorded for
+  every protected blob; they are identical for unprotected blobs.
+- Upload and archive-confirm APIs can select an Encryption vault. Protected
+  writes and reads fail closed if the optional Encryption capability is absent.
 
 The module does **not** currently provide malware scanning, content disarm and
-reconstruction, a file-type allowlist, per-user quota, at-rest encryption for
-local blob bytes, or a dedicated preview sandbox. Deployments that require
-these controls must supply them outside Files until explicit module contracts
-exist.
+reconstruction, a file-type allowlist, per-user quota, automatic encryption
+policy assignment, client E2EE, or a dedicated preview sandbox. The optional
+server-envelope profile protects selected managed blob bytes at rest but remains
+server-decryptable. Deployments that require the other controls must supply
+them outside Files until explicit module contracts exist.
 
 ### Provenance