Files are encrypted on the client, bound to an object, and registered in the space's CRDT. Content is cached locally and backed up to the network's fileV2 nodes. There are no standalone file objects.
Surface: Space.Files() (space/files.go) for members,
Space.Payloads() (space/payloads.go) for keyless readers, and the
cache controls on SDK (FileCacheSize, FreeUpFileCache,
SweepFileCache).
Each file is one row in the payloads dataset on a payloads object:
a derived child of the object the file is bound to, created on the
first Attach.
- Signed owner: seed
builtin:payloadswithParentId = ownerId. any-sync cascade-deletes it with the owner. - Derived owner: unparented seed
builtin:payloads/<ownerId>. any-sync rejects a derived object as a parent, so the owner id goes into the seed to keep the child id unique per owner. Being derived itself, it is never deleted and outlives its owner.
A deleted owner's files are gone from the delete on, for both shapes: reads check the owner, so its rows neither list, resolve by fileId nor count in stats, even while the payloads object is loaded. GC reclaims their CARs and the queue drops their pending uploads.
A payloads object's tree changes are plaintext at the any-sync
level, so nodes can read rows for refcount, GC, quota and durability
without a space key. The privacy boundary is the sealed enc field.
| Field | Scope | Meaning |
|---|---|---|
| row id | — | fileId, derived from the creating change |
rootCid |
synced | UnixFS root of the encrypted file; absent for inline files |
size |
synced | plaintext size in bytes |
networkSign |
synced | verified custody receipt {fileNetworkId}/{base64(sig)}; absent until durable, never on inline rows |
objectId |
synced | the object the file is bound to |
author |
derived | account that attached the file |
enc |
synced | {kid, ct}: member-only secrets |
ct is AES-256-GCM under a key derived from the space read key; kid
is the ACL key-record id of that read key, so rows sealed before a key
rotation still open. The sealed payload is
{key, name, sha256, mime, inline, variant, variantOf}. Unknown keys
are ignored on read, so metadata can grow without breaking older
readers. The schema is non-dynamic: undeclared cleartext fields are
rejected on both routes.
Attach picks the tier from the content; callers never choose. The one
exception is the account avatar (identities.md § Avatars), which the
SDK itself pins to the full tier so non-members can fetch it by
rootCid.
- Inline — size < 4096 bytes. The bytes ride inside
enc. NorootCid, no upload, durable by construction. - Bound — the per-space dedup index (plaintext SHA-256) finds an
existing file with the same content. The new row reuses the donor's
rootCid, wrapped key and receipt; no bytes move. A row bound to a not-yet-durable donor gets its own backup job. - Full — a random per-file key, AES-256-CFB with a zero IV (byte-compatible with anytype-heart), a UnixFS DAG over the ciphertext, and one CARv2 per file keyed by its root CID. The zero IV is safe because keys are never reused. Integrity comes from the CIDs, so only CID-verified bytes reach the decryptor.
Dedup is per space. Per-file random keys mean a rootCid never repeats
across spaces.
- Check the owner before touching the reader:
ErrNotFoundwhen it isn't on this device,ErrObjectDeletedwhen it is deleted or queued for deletion (a child cascaded from its parent included). - Spool the reader, compute SHA-256, choose the tier.
- Full tier: encrypt, build the DAG, finalize the local CAR.
- Register the row: one CRDT change. The file now exists for every member, whether or not backup succeeds.
- Enqueue a
durablejob and return. Attach never waits on the network:FileInfo.Durableis true only for an inline file or one bound to a durable donor. - A queue worker runs the durable phase: broker
Upload→ presigned HTTP PUT of the CAR →RequestSign→ verify the receipt → writenetworkSign. The flip reaches every member as a row update and the local status stream as adurabletransition.
The bytes are servable to peers from the moment Attach returns: the P2P
file source reads the local CAR and does not look at networkSign.
The receipt is signed by the file fleet key (fileNetworkId from the
network config) over {networkId, spaceId, rootCid, size, signedAt};
every field is checked before networkSign is recorded. A network
config without fileNetworkId leaves files registered but never
durable.
Transport failures (offline, node down, object store unreachable) end
the attempt and leave the job to the queue's backoff. Broker outcomes
from lazy space activation, NotResponsible routing and the post-PUT
visibility window retry the broker call alone, inside the durable-wait
budget; the bytes move once per attempt. Limit and auth refusals are
terminal for the attempt. A PUT that moves no byte for a minute is
aborted; a slow one runs as long as it progresses.
Rows that share a root share one upload: drives of one root are serialized, and a row whose sibling already holds a receipt takes that receipt.
Crash safety: each attach writes its own intent marker on the root before the row write, and the job is persisted before Attach returns, so a crash never leaves an unsigned row that GC treats as garbage or the queue forgets. When registration fails before the row write, for any reason (the owner was deleted during the upload, the space key is unavailable, the context ended), no row references the new CAR, so it and its marker are dropped; a bound upload drops only its marker, the CAR being the donor's. A failure in the write itself keeps both for the sweep. For a root no live row references, the sweep keeps the CAR while any marker remains and re-links every row of each marking owner that holds the root; when no marking owner has such a row (its owner was deleted since, or the crash preceded the row), the markers and the CAR go.
One persistent queue (internal/files/status) with two job kinds:
durable— drive an unsigned row to a verified receipt.pin— fetch a file's full content (Files().Pin).
Up to four jobs run at once, and the two kinds alternate when both are due. Deleting a file removes its jobs and cancels a running attempt.
Jobs survive restarts, and a backoff does not: every job that ran in an earlier session without succeeding is due when the queue starts and its backoff starts over, so a file attached offline backs up as soon as the app next runs online. Within a session failures back off from 30 s, doubling to 10 min.
- Storage limit: the job parks on a 10-minute cadence and the file
reports
limited.Files().Retrymakes it due immediately (e.g. after a quota raise). - No file nodes in the network config (a local-only network):
nothing is attempted and no failure is counted; the job re-checks
every minute, so the backup starts once a config with file nodes
arrives. The file reports
inflight.
Open(ctx, fileId, variant) returns a seekable reader over verified
plaintext. Content resolves through a source ladder:
- Local store.
- A peer holding the CAR, when p2p is enabled (
internal/files/filep2p). Peers serve ciphertext and every block is CID-verified, so a peer can neither read nor corrupt content. - Public HTTP GET with Range on
{publicReadBaseUrl}/blob/{spaceId}/{rootCid}, for durable files only. The base URL is resolved once from the network's fileV2 nodes and cached;config.Files.PublicReadBaseUrloverrides it for deployments that front the object store themselves.
Every fetched block is verified and persisted into a sparse local CAR,
so streaming, seeking and interrupted reads accrete toward a complete
copy. A file that is neither local, durable, nor held by a reachable
peer fails with ErrFileNotAvailable.
Status derives state on read from the row and the queue:
| State | Meaning |
|---|---|
durable |
receipt recorded, or inline |
inflight |
registered; backup queued, running, or driven by another device |
limited |
the network refused backup for storage limit |
FileStatus also reports Cached (complete local copy), Attempts and
LastErr. SubscribeStatus delivers local transitions only (attach,
backup progress and failure, pin completion, retries); a backup finished
by another device shows up through Status / Get. Stats returns
per-space counts.
A variant (e.g. a thumbnail the embedder rendered) is an ordinary sibling
row on the same object, tagged with variant / variantOf inside enc.
It has its own tier, durability and lifecycle; the network sees
independent files. Attach requires both fields together and an original
bound to the same object (ErrFileVariantInvalid).
Open(originalId, variant) resolves the sibling.
Delete removes the row in one synced change, cancels pending work and
releases the local content ref. Deleting an original also deletes its
variants; a keyless reader cannot see variantOf and deletes only the
addressed row. Content shared with a surviving row stays. fileprotov2
has no delete RPC: the broker's row-driven accounting stops counting a
file once the deletion syncs. A second Delete returns ErrNotFound.
Layout under the store root:
<root>/tmp/<rand>.car in-progress builds, swept on open
<root>/<spaceId>/<shard>/<rootCid>.car one CARv2 per file
The CAR is byte-identical to the uploaded object. Hot metadata (download bitmap, refs, dedup index, LRU access time) lives in any-store; blob bytes never enter the DB. Space deletion is one recursive remove.
Reclamation is embedder-driven. The rule everywhere: bytes are dropped only when refetchable (a referencing row carries a receipt) or unreferenced; the only copy of a not-yet-durable file is never dropped.
Files().Offload(fileId)— drop one file's local bytes.ErrFileNotBackedUpunless durable; inline files are a no-op. Content shared through dedup is offloaded for every row that uses it.SDK.FreeUpFileCache(bytes)— LRU sweep toward a byte target; returns what was actually freed.SDK.SweepFileCache— safety pass: prune refs of deleted rows, delete CARs unreferenced for 24 h, offload partials of durable files untouched for 7 days. Runs periodically only whenconfig.Files.GCInterval > 0.SDK.FileCacheSize— local bytes across all spaces.
List(opts)— typedFileInfos;ObjectIdis the indexed fast path,Limitcaps the result. An unfiltered listing walks every file in the space; large-space consumers page or useQuery/Changes.Query(objectId)— the generic query surface over one object's rows (cleartext fields only).ErrNotFounduntil the object's first file is attached.Get(fileId)— oneFileInfo. Member-only fields (Name,Mime,Variant,VariantOf) are empty without the space key.
Space.Payloads() exposes the cleartext index for an embedder without
the space key, such as the filenode-v2 broker running headless with
selective sync: ListObjects returns payloads objects classified by their
signed root change type, ListRows returns one object's rows with the
sealed secrets withheld.