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

3.5 KiB

Work materials / artifact delivery (candidate, not deployed)

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.