Security

This page is the deep-dive companion to the Security overview on the marketing site. It covers how encryption, integrity checking, and network isolation actually work, and it's explicit about what's available today versus what's still on the roadmap.

Running a formal vendor security review? See Security Architecture - the threat model, a who-can-decrypt matrix across the managed and E2E tiers, key-custody specifics, and where each guarantee's limits are, written to hand to a security team.

Encryption#

Every private project on a paid plan (Starter and above) has its block contents encrypted at rest with AES-256-GCM by default. Each project gets its own key, wrapped by a hub-held key-encryption-key (KEK). Desktop writes are encrypted on your machine before upload; small files uploaded from the web are sent over TLS and encrypted by the hub the moment they arrive - so stored private blocks are always ciphertext. Because the hub holds the KEK for a managed project, Swarmfile can decrypt when it needs to (for example, to generate a preview or thumbnail). So managed encryption protects your data at rest from the storage layer, not from Swarmfile itself - for that stronger guarantee, use the end-to-end tier below.

Two cases are stored unencrypted (plaintext). The Free plan is one: its projects are plaintext at rest, the trade-off for no-card, no-cost storage. The other is a public project on any plan - anonymous public releases can only be served from unencrypted blocks, so a project has to be plaintext to be public (Free-plan projects are public by definition). Encryption tier and visibility are both fixed at project creation and never change afterward, so a project created on the Free plan or as public stays unencrypted even after the org upgrades; a new private project created post-upgrade gets managed encryption normally. If encryption at rest matters for a given project, create it private on Starter or above. Public exposure is still scoped by the publisher: a committed .swarmfile/publicignore.yml keeps matched paths - and derived data such as CI logs - out of what non-members can reach, enforced as each release is published (share links are not covered; see Security Architecture).

One carve-out inside an encrypted project: some git-LFS objects. When a managed project is used as a git-LFS server, objects uploaded directly by the stock git-lfs client, and uploads of 64 MiB or more through the Desktop App's built-in LFS agent, are stored without application-layer encryption. Smaller uploads through the built-in agent, and every upload through the standalone swarmfile-lfs agent, are encrypted like any other block. git-LFS is refused on end-to-end-encrypted projects. Files you save through the mounted drive are unaffected; if a binary must be encrypted at rest, keep it on the drive rather than routing it through LFS. The git-LFS guide has the full per-path table.

Opt-in end-to-end (customer-managed) encryption#

For projects that need a stronger guarantee than a hub-held key, you can opt into end-to-end encryption. Instead of wrapping the project key with a hub-held KEK, each member's copy of the key is wrapped to their own device keypair (X25519). The key never reaches Swarmfile's servers in plaintext at all, and grants happen client-side.

This is a content-only guarantee:

• File and folder contents become unreadable to the server.
• Filenames, folder structure, and file sizes stay server-visible - search, ACLs, browsing, and quota accounting keep working normally.
• Stored blocks are named by a hash of their plaintext chunk (so identical content deduplicates). No whole-file hash is kept for E2E content - see Security Architecture for exactly what that does and doesn't reveal.

The trade-offs are real and worth knowing before you turn it on:

• Server-side preview and thumbnail generation don't work for E2E content, because the server can't decrypt it.
• New members are enrolled into E2E projects automatically once an existing member's client has been online to complete the key wrap - no manual key ceremony. An optional always-on key-granter closes even that narrow window, delivering new-member and new-device keys automatically on a five-minute cadence at worst. See End-to-End Encryption Setup for the granter setup.

Losing every device with a wrapped copy of a project key would mean losing the data permanently, so E2E projects should be created under an org recovery key. That key is split using Shamir secret-sharing escrow (2-of-3 by default), so no single lost device or credential is catastrophic.

For the step-by-step - setting up the recovery key, creating an E2E project, enrollment, and the recovery ceremony - see End-to-End Encryption Setup.

Content integrity#

Every block is BLAKE3-verified on arrival. Corrupt data - from a misbehaving peer, a bad transport, or disk corruption in transit - never reaches the application layer.

Erasure coding#

Blocks are protected with adaptive Reed-Solomon 10+4 erasure coding: any 10 of the 14 shards reconstruct the full data, so up to 4 slow or offline peers never block your read. This page keeps that summary brief - for the admin-facing detail on deliberate shard placement across your seed nodes, see Self-Hosted Seed Nodes.

Private P2P swarm#

The peer-to-peer transport runs in a private swarm. Joining it requires a pre-shared key and a custom protocol identifier - a random host on the public internet can't dial into your blocks even if it somehow learned a peer's network address. Peers that connect directly do learn each other's network addresses, which is inherent to a direct connection; an org that can't accept that can turn on cloud-only mode (below), which disables peer-to-peer entirely.

Cloud-only (hub-only) data-plane mode#

Some enterprises need to block UDP/QUIC entirely, or eliminate peer-IP exposure between employees' machines outright. An org-level policy - or an engine-local SWARMFILE_HUB_ONLY toggle - disables peer-to-peer entirely: QUIC never binds, there's no peer discovery, no gossip, and swarmfile doctor reports clean. All reads fall through to HTTPS against our cloud storage instead. This is enforced at startup and re-checked every time a machine switches which project or organization it's working in, so a person who works across multiple orgs never inherits the previous org's policy; a check that can't complete (a hub outage, for instance) fails closed rather than silently allowing peer traffic.

This is admin-gated (owner or admin), and toggling it is itself an audited event. See Operations for where that shows up in your activity log.

Removing access#

Revoking access reaches every affected computer, not just the next sign-in. Remove someone from the org, revoke their access to a folder, or revoke a machine credential, and each affected drive drops the revoked content from its local cache and refuses further opens of it - including while offline, because the refusal is persisted locally the moment the notice arrives. A machine that was offline takes the same step when it reconnects. Organizations can also bound how long a disconnected machine may keep serving already-downloaded content at all (default: seven days); past that window the drive stops serving cached bytes until it next reaches the hub. Removed members' own unsaved work stays on their machine and uploads if their access is restored. Owners can see any revocation still pending under Settings → Access revocations.

Ransomware detection#

The system watches for a suspicious pattern inline, at high frequency: a large number of distinct entries overwritten (by content-hash) in a short window, scoped per-(user, machine). It counts distinct entries, not raw history rows, so re-saving the same file repeatedly doesn't inflate the signal.

The response is two-tier, and crossing the first line does not block anyone:

• Alert bar (a configurable number of distinct entries in the window) - the incident is recorded as alert-only and org owners are notified for review. Nothing is blocked.
• Block bar (a higher multiple of the alert bar) - this is what actually hard-quarantines the user, either on a genuinely large sweep or when an already-alerted user keeps going. Only past this bar do writes stop.

Writes are attributed to the machine that made them. A staged commit counts in the overwrite signal by its modifications - the submitting machine rides the submit, and the check runs as the commit lands, so a single 500-entry commit from one machine blocks on the spot (250-499 alerts) - while the server-side re-applies a restore, checkout, revert or merge performs (content the project already held) are excluded, so a legitimate 5,000-file restore does not trip the overwrite bars. A staged commit's creates are creates, never overwrites. A git push carries the pushing machine like any other client batch, so push sweeps are counted too. Two accepted exceptions remain: the web app's conflict tools (the resolve modal and the batch auto-resolve) carry no machine and are not counted, so a bulk auto-resolve is invisible to this signal; the separate create-and-delete signature is evaluated inline as a direct delete lands, while a merge that both adds and removes hundreds of entries - applied server-side with no inline check - and an over-cap folder-delete subtree reach it only through the daily scan, so coverage there is best-effort. A delete-only sweep has no signature at all and is not counted by design - deletes alone are how anyone empties a folder. An in-place sweep of hundreds of distinct files from one client can still reach either bar; orgs whose workflows routinely rewrite that many files in place can tune the thresholds.

When a user is quarantined, lock acquire and lock renew both check quarantine state, so they can't keep working even in the middle of holding a lock. New saves stop on that computer: on macOS and Linux they fail with the quarantined reason in Why did my save fail?, and on Windows the drive stays mounted while saves are accepted locally and held - they simply don't sync until the block is released. Work already queued on that machine is held, not lost - sync resumes on its own as soon as an owner releases the block. Alert-only incidents that no one acts on auto-expire after 7 days; blocks never auto-expire and require an admin or owner to clear. See Operations for the release/dismiss workflow.

No kernel extension on macOS#

The macOS installer ships a kext-free build using FUSE-T, which mounts entirely in user space. There's no kernel extension, no dropping into Recovery Mode to lower security settings, and no system-extension approval prompt on Apple Silicon.

Authentication and membership#

• Sign-in runs on Swarmfile's own OIDC IdP, and every account can add TOTP multi-factor authentication under Account → Security.
• Organizations can require MFA and/or a verified email - see Authentication policy. Enforcement is checked on every org-scoped API request with a grace window and a typed refusal that names the remedy; the owner always keeps an off-switch. A personal access token snapshots its session's factors and email assertion at mint time, so a token can never carry more than the session that created it.
• SSO: per-org OIDC (Entra/Okta), SCIM 2.0 provisioning, and an on-prem LDAP sync agent; an org can require that members sign in through its own identity provider, and machine credentials are held to the same binding.
• Machine credentials: project-scoped API keys for headless engines and personal access tokens for scripts; both are revocable and audited. API keys are additionally walled to one project and can carry their own budget; a personal access token acts as its owner and can never carry more than the session that minted it.

On the roadmap#

• SOC 2 is on our roadmap; we have not yet begun a formal audit. In the meantime, the team answers security questionnaires directly and walks customers through the architecture on request.
• SIEM forwarding - a managed Splunk, Datadog, or S3 stream of audit, access, and quarantine events - is planned. Today, a Pro-plan owner can export the activity feed to CSV (up to 100k rows per export), and outbound webhooks push events to an endpoint you control on a periodic schedule, not in real time.
• Legal hold & retention immutability - a per-entry legal-hold flag that overrides retention and trash purge - is planned.
• DLP & egress controls - watermarking, share-link domain allowlists, and export policy gating - are planned.

If any of these are a hard requirement for you today, talk to us directly - for details on the permission model that is live today, see Permissions.