Security Architecture

This is the deep technical companion to Security - written to be handed directly to a security team running a vendor review. It states plainly what each layer protects against, who can decrypt what, and where the honest limits are. If your review needs something not covered here, contact us and we'll answer specifics.

The one-paragraph version#

Swarmfile's data plane is zero-knowledge by construction: every block is encrypted with AES-256-GCM on the machine that writes it, before it leaves that machine. Peer-to-peer nodes and our cloud object storage only ever see ciphertext addressed by a BLAKE3 content hash. The only party that can turn ciphertext back into your files is whoever holds the project key - and you choose who that is. On the default managed tier that party is the Swarmfile hub (so we can give you server-side previews, search, and proxies). On the opt-in end-to-end (E2E) tier the key never reaches our servers in a form we can open, so we structurally cannot read your content. Both tiers are real products, shipping today; the difference is a deliberate trade you make per project, not a weakness in one of them.

Threat model - what each tier defends against#

The two ⚠️ rows on the managed tier are the entire reason the E2E tier exists. If "the vendor can technically decrypt our footage" fails your review, the answer is the E2E tier - not a promise about the managed one.

How block encryption works (both tiers)#

Encryption of the bytes is identical on both tiers; only custody of the project key differs.

• Each project has one 32-byte project master key.
• Every content block gets its own key: HKDF-SHA256(master_key, salt = chunk_CID, info = "swarmfile-block-encryption/v1"). The CID is the BLAKE3 hash of the plaintext chunk, so the per-block key is bound to the content it protects.
• The block is sealed with AES-256-GCM and stored as [version:1][nonce:12][ciphertext + GCM tag], keyed in object storage by its CID.
• On read, the reader re-derives the key, decrypts, and re-verifies the BLAKE3 CID before any byte reaches an application - so a tampered or corrupted block is rejected, not served.

Content-defined chunking means identical content across file revisions shares a CID and deduplicates, and the per-project key scoping means dedup never crosses a project boundary.

Managed tier (default)#

The project master key is generated once, wrapped by a hub-held key-encryption-key (KEK), and stored as ciphertext in the per-tenant database. The hub unwraps it only when it needs to act on your behalf - serving a download, generating a thumbnail, or transcoding a preview proxy.

What this protects: your data at rest against the storage layer, a leaked bucket, a lost disk, or a peer on your swarm. What it does not protect against: the hub itself, since the hub custodies the KEK. That is the honest, standard posture of essentially every managed B2B file service (it is what lets us offer previews and search) - and it is why, between two members of the same org, the confidentiality boundary is the block ACL, not cryptography. Every block fetch is authorized per CID against the project's permission model; encryption is the at-rest guarantee, the ACL is the member-to-member guarantee.

Web uploads (small files sent from the browser over TLS) are encrypted by the hub the instant they arrive, before anything is written to storage - so managed data is always ciphertext at rest, matching what the desktop engine writes client-side.

One honest caveat about server-side previews. Because the hub can decrypt managed content, it generates thumbnails, image/PDF previews, video posters, scrubbable video proxies, and point-cloud renders on the server - and it caches those derived artifacts in plaintext (they are the whole point: a rendered preview). So while your source files are ciphertext at rest, their server-generated previews are not: a compromise of the storage layer could expose a reduced-fidelity rendering of previewed content (a poster frame, a 720p proxy, a top-down point-cloud image) even though the originals stay sealed. This is inherent to any service that renders previews of encrypted content on its own infrastructure, and it is exactly the residual the E2E tier removes - on E2E the hub can't decrypt, so no server-side previews (and therefore no plaintext derivatives) exist. If preview confidentiality at rest matters for your content, choose E2E.

End-to-end (E2E) tier (opt-in, per project)#

On an E2E project the project key is never wrapped with a hub-held KEK. Instead:

• Each member has an X25519 keypair. The private key is derived from their password (Argon2id) or device-enrolled; it never leaves the member's machine.
• The project key is wrapped to each member's public key. Granting a new member = an existing member's client wraps the project key to the newcomer's public key and uploads the (un-openable) wrapped blob. The hub distributes wrapped blobs but never sees the plaintext project key.

This is a content-only guarantee, and we say so up front: file and folder contents become unreadable to the server, but filenames, folder structure, and file sizes stay server-visible so that search, ACLs, browsing, and quota accounting keep working. Encrypting metadata too would break all of those and is a separate, much larger effort - nearly every B2B "E2E" product draws this same line.

To be precise about which metadata: what the server sees is the entry-level metadata it keeps in its database - the name, its place in the folder tree, and the file's total size. It does not see the file's internal structure. The per-file block manifest (the ordered list of content-chunk hashes and their sizes) is itself encrypted alongside the content - the engine runs it through the same block-encryption as the chunks - so on the E2E tier the server holds the total size but the chunk-level layout is opaque to it. (This is why an E2E share is fetched and reassembled entirely in the recipient's browser: the server can't read the manifest to hand out a chunk list, let alone assemble the file.)

Share links on an E2E project#

A public share link has no account and no device keypair, so it can't receive the project key wrapped the member way. Instead the link carries the project key wrapped to a per-share random "link key" that lives only in the URL #fragment - browsers never send a fragment to a server, so the hub distributes the wrapped blob but never sees the link key or the project key. The recipient's browser unwraps it and decrypts the file locally.

Be precise with your reviewer about which key that is: it is the project master key, not a per-file key - the block cipher derives every block's key from the project key, so there is no narrower key to hand out. Two consequences follow, and we state both plainly:

• The share's block endpoint is scoped to the shared file. The hub serves a share's raw ciphertext blocks through one endpoint, restricted to the shared file's own block set: its manifest plus the chunk hashes the creator's browser enumerated at share time (the hub can't read the E2E manifest to derive them itself). A recipient cannot pull other files' ciphertext through the link, even though the key they hold could decrypt it.
• That boundary is the endpoint, not the key. Because the recipient genuinely holds the project key, the scoping is a serving-layer control, not cryptographic isolation - a recipient who obtained another file's ciphertext through some other channel could decrypt it. Closing that residual fully requires per-file share keys, a planned key-derivation change. Until then, read a single-file E2E share as "this person can read this file, and holds a key that could read the project if they got at its bytes another way": scope links with expiry and revocation, and share narrowly. Sharing is an explicit trust decision.

The trades E2E makes (know these before you turn it on)#

• Server-side previews/proxies are disabled for E2E content - the server can't decrypt to render them. Image/PDF preview can move to in-browser decryption; server-generated video posters and point-cloud rasters cannot. This is a deliberate, headline trade, not a bug.
• SSO/SCIM grants authentication, not key access. A provisioned user can sign in but sees nothing until an existing member's client (or the optional key-granter, below) wraps the project key to them.
• Recovery is via an org recovery key, or not at all. Losing every device holding a wrapped copy means losing the data. The enterprise-viable answer is an org recovery key: project keys are also wrapped to a recovery public key whose private half is escrowed via Shamir secret sharing (2-of-3 by default) across your admins. This reintroduces a party that can decrypt, so "E2E with recovery" is a point on a spectrum - customers who choose no-recovery accept unrecoverable loss, and we describe it that way at the point of choice.

Optional always-on key-granter#

For orgs that add many members while their existing members are offline, an opt-in key-granter service can hold an escrowed recovery share and fulfill pending grants on a tight cadence. It is off by default and, like the recovery key, is a decrypting party you are choosing to introduce for operational convenience - enrolled explicitly per org, never automatically.

Integrity, availability, and network isolation#

• Content integrity. Every block is BLAKE3-verified on arrival; corrupt data from a bad peer, transport, or disk never reaches the application layer.
• Erasure coding. Blocks are protected with adaptive Reed-Solomon 10+4 - any 10 of 14 shards reconstruct the data, so up to 4 slow or offline peers never block a read.
• Private P2P swarm. The peer transport requires a pre-shared key and a custom protocol identifier; a random internet host cannot dial your blocks even if it learns a peer's address.
• Hub-only data-plane mode. An org policy (or engine-local SWARMFILE_HUB_ONLY) disables P2P entirely - QUIC never binds, no peer discovery, no gossip, no peer-IP exposure - and all reads fall through to HTTPS against cloud storage. Toggling it is itself an audited event.
• Ransomware detection. The system watches for the signature of encryption malware - many distinct content-hash overwrites in a short window from one user/machine - and quarantines that user, blocking further writes even mid-lock. (Content entropy is deliberately not a signal: every block is already AES-encrypted, so ciphertext entropy separates nothing.)

For the strictest buyers: self-hosted control plane#

Where "the vendor's infrastructure touches our data at all" is disqualifying (some government, defense, and critical-infrastructure work), the E2E tier may still not be enough because metadata is server-visible. For those cases the entire control plane is self-hostable on your own infrastructure (Enterprise). That is the top of the spectrum; the E2E tier is the middle; managed is the default. Talk to us about which point fits your procurement.

What we do not yet have#

We don't claim certifications or controls we don't have:

• SOC 2 Type I - not started (Type II follows once Type I is issued). Today we answer security questionnaires directly and walk teams through this architecture on request.
• SIEM forwarding - Splunk/Datadog/S3 export of audit, access, and quarantine streams. Events are stored internally today; there is no export path yet.
• Legal hold & retention immutability - a per-entry legal-hold flag overriding retention/trash purge is not built.
• DLP & egress controls - watermarking, share-link domain allowlists, and export-policy gating are not built.

If any of these is a hard requirement for you today, contact us - several are on the roadmap and we're glad to talk sequencing. For the permission model that is live today, see Permissions; for the E2E setup walkthrough, see End-to-End Encryption Setup.