Files
ecs-relay-service/deployable/WORK_FILES.md

4.6 KiB

Work materials / artifact delivery (test deployment accepted)

Branch feat/work-files-20261110. Requires paired PC feat/client-foundation-20261110 and broker mode. Off by default. Existing users/keys/permissions are not migrated by this source change.

Flow: platform-verified private file messages stage encrypted materials; user sends all files, waits for receipts, then sends task instructions. The next task in that exact owner/device/binding/chat claims them. Device capability work-files-v1 is signed in its handshake; older PCs are told to upgrade instead of receiving a text-only task that silently omits files. In-progress downloads block dispatch; failed inputs remain explicit per-file records.

Separate /work/v2/files/list, /download, /upload, /state routes use current device signatures and task binding. Upload metadata is signed and supplied in X-Hainuo-File-Request; bytes have exact length/SHA256 and independent path size limits. No caller URL/recipient or arbitrary source message is accepted. Downloads are verified on PC. Output manifests are restricted to the current task outputs, not arbitrary local paths.

All material/output bytes are AES-GCM encrypted using the existing server keyring with scoped AAD. Server stores ciphertext in DB, so backups, disk capacity and retention matter. File content is cleared after confirmed send, expiry or binding discard. Metadata persists for idempotency. Per-owner/global quotas serialize checks across workers.

Output stages: ready -> uploading -> uploaded -> sending -> sent. Failure after a mutating platform call is unknown and never automatically replayed. Client lost upload receipt first queries original file state before re-upload; ECS received is not platform sent, and sent is not user read. Stale uploading/sending states become unknown. Uploading to Work and replying to the original source_message_id are separate durable steps.

Deployment defaults (configurable, not measured product commitments): 10MiB/file, 20/task, 24h retention, 512MiB/owner and 2GiB/global encrypted payload allowance. Encryption/base64 and DB backups require extra capacity. Verify corporate reverse proxy limits too. Formatted documents are not executed; macro/embedded/external active-content handling remains PC policy.

Platform adapters use GET im/v1/messages/{message_id}/resources/{file_key}?type=file; POST im/v1/files multipart; POST im/v1/messages/{message_id}/reply file content. Scope and private-platform compatibility must be checked against internal docs and real synthetic test files. These are bot message resource APIs, distinct from user-token docx media download.

Tests: synthetic platform events, encrypted routing over loopback WebSocket, signed PC requests to actual FastAPI routes, 3 Word/Excel/PDF materials, real local Office conversion, lost HTTP receipt recovery, one original-message file reply, cross-user/binding checks, conflicting IDs, quotas, body limits and invalid names. Mock platform acceptance does not prove real Work functionality.

Existing ECS parent confirmed by user: /home/cnooc/hainuo-broker-update-20261105-recovery, connector image hainuo-relay:broker-update-30585d6d28a18521, digest sha256:a32e13a92d2191ad0619a8f34e4703fd3e3ce8e44ca784f2b0d092cc49476b02. Before deployment verify router also matches parent, source branch availability and inactive tasks. prepare-update --enable-work-files creates a new plan with the flag; rollback keeps the parent's previous flag and existing key material. Do not run from the initial prepared plan or regenerate keyring. No production deployment performed.

Live test acceptance, 2026-11-10

Candidate 79c15ee was activated on the test ECS using /home/cnooc/hainuo-broker-update-20261110-files, image hainuo-relay:broker-update-f6b1859625e89b5f. Connector/router reported healthy. This supersedes the historical pre-deployment status above. Future prepare-update operations must use this newly activated plan as parent; retain bindings and key material.

A real private Work task received Word, Excel and PDF materials, verified their hashes on the updated PC, and returned two generated files to the original conversation. Both remote file states were sent; text was replied. User screenshots confirmed both outputs opened in WPS: department totals 120 and 80, formula checks/chart consistent, and the report disclosed missing metadata and the 19.5 difference between source totals 200 and 219.5.

Acceptance is scoped to this task. Full installer release, network/restart faults, partial platform failures, and real multi-user/device acceptance remain pending. No master merge or new client installer is implied.