Logo

Chapter 3 System Architecture & Data Flow

This chapter describes the high-level system components and the end-to-end data flow for upload, download, and sender management. The focus is on what is encrypted, what metadata is required, and how access control and revocation are enforced.

Document metadata

Whitepaper version
v1.0
Last updated
2026-01-14

3.1 Components

  • Client: chunks files, encrypts/decrypts, and manages CEK in the URL fragment.
  • API/Edge: issues and validates scoped tokens; serves manifest and ciphertext chunks.
  • Object storage: stores encrypted chunks and manifests; treated as untrusted for plaintext confidentiality.
  • State store: tracks transfer state (upload progress, expiration, revocation) with minimal metadata.

3.2 Data objects

  • Manifest: public parameters required to fetch and assemble chunks (cryptoVersion, chunk size/count, mapping); MUST NOT contain CEK.
  • Chunk: encrypted file piece (ciphertext) plus minimal metadata (length/etag), addressed by (transferId, fileId, chunkIndex).
  • State: server-side record for authorization, TTL, revocation, and resumability.

3.3 Upload flow

  1. Client creates a transfer and receives a short-lived, scoped upload token bound to transferId.
  2. Client generates per-file CEK locally, splits files into fixed-size chunks, and encrypts each chunk with AEAD.
  3. Client uploads ciphertext chunks in parallel; retries are idempotent per chunk.
  4. Client uploads the manifest (public parameters only). Server marks the transfer READY when required parts are present.

3.4 Download flow

  1. Recipient opens the share link. The URL fragment (CEK material) stays in the browser and is not sent to the server.
  2. Client fetches the manifest using a scoped download token and determines the chunk plan.
  3. Client downloads ciphertext chunks (optionally in parallel), verifies AEAD authentication, then assembles the plaintext file.
  4. On failures, the client resumes by requesting only missing chunks; integrity failures MUST fail closed.

3.5 Sender management & audit flow

  • Senders authenticate using a long-lived login token (stored on the client) for management operations.
  • Management APIs allow listing transfers, checking delivery evidence, and revoking/deleting transfers.
  • Audit data is designed to be visible to the sender only; it is not exposed to recipients by default.

3.6 Visibility & minimization

  • The server and storage only handle ciphertext and necessary public parameters; they cannot decrypt content without CEK.
  • Logs and analytics SHOULD be minimized and MUST NOT include URL fragments or CEK material.
  • Metadata collection SHOULD be purpose-limited (delivery evidence, abuse prevention, and operational reliability).