Get started with files, storage and encryption

Files, data and secrets: where to keep each, how to share it, how to lock it, and how to check it's really kept. The Storage page ([zaryn.xyz/storage](/storage)) is where everything you keep on Zaryn comes together. ## 1. Three places to keep things ```diagram type: cards title: What goes where --- 🔗 | Files you share by link | A PDF, a video, a build: upload it, send the link, no account needed to open it | accent 📁 | Repositories | A project with every version: code, a thesis, a dataset, a model. Public, private or encrypted | good 📦 | Packages and images | Things other software installs: npm, PyPI, Cargo, Zig, containers | ``` The rule of thumb: **one file to hand someone** → a link; **work that changes over time** → a repository; **something software installs** → a [package](/docs/en/packages). ## 2. A link to the content, not to a place ```diagram type: graph title: Same bytes, same name, anywhere alt: A file's bytes are hashed into its CID; the link names the CID, so any IPFS gateway or node can serve exactly that file, and a changed file gets a different CID legend: path=Opens height: 36 --- node file | report.pdf | 10 18 | file | accent | Its bytes, as uploaded node cid | bafy…fbzdi | 42 18 | hash | good | Its CID: a fingerprint of the bytes. Change one byte, get another CID node gw1 | ipfs.io | 80 6 | cloud | | A public gateway node gw2 | any IPFS node | 80 30 | storage | | Or your own: the CID is the same everywhere link file cid | hashed | path link cid gw1 | | path link cid gw2 | | path2 ``` Everything Zaryn keeps is named by its **content**: a hash of the bytes, called a **CID**. A link that names a CID can only ever open those exact bytes. Nobody, Zaryn included, can swap the file behind it, and any IPFS node can serve it, not just Zaryn. ## 3. Public, private, or encrypted ```diagram type: flow title: How private does it need to be? or: or --- Public | Shared files and public repositories: anyone with the link can read them | | 🌐 ? Private repository | Only you and the people you invite; Zaryn can read it to show it to them ~ more private Encrypted repository | Encrypted on your computer: only your devices hold the key, not Zaryn | good | 🔐 ``` Files shared by link are always public, so passwords, contracts and private photos don't belong there. For private work use a private repository, and for work that must stay private even from the host, an **encrypted** one. ## 4. Share a file by link ```diagram type: flow title: Three clicks --- Open Storage | In the top menu, or zaryn.xyz/storage | | 🗂 ~ drop the file Uploaded | It gets its CID, and a receipt signed by the server | accent | ⇡ ~ Copy link Sent | Whoever gets the link opens it; no account needed | good | 🔗 ``` Your files are listed under **My files**, newest first, with **Copy link** and **Open** next to each. The link looks like `https://ipfs.io/ipfs/bafy…?filename=report.pdf`. ## 5. A new version is a new link ```diagram type: history title: Each version, its own link start: Version 1 --- branch report.pdf | accent commit v1 report.pdf | bafy…fbzdi | info The link you sent opens exactly this, forever step You fix a typo and upload again | New bytes, new CID, new link. The old link still opens version 1. commit v2 report.pdf | bafy…k3q7a | info A new link for the new version ``` That's a feature, not a limitation: a link in an email, a paper or a contract always shows what was there when it was sent. Uploading the same file twice uses space once. ## 6. One address that always shows the latest ```diagram type: flow title: An address you can update (IPNS) --- A name | Under Advanced on the Storage page: one address, yours | accent | 🏷 ~ points at Version 1 | Today it opens bafy…fbzdi | | 📄 ~ you publish an update Version 2 | The same address now opens bafy…k3q7a | good | 📄 ``` When you do want "always the latest" (a download page, a dataset that's refreshed), use an **IPNS address**. To take a file offline, open its ▾ menu and choose **Stop hosting**. Copies other people made may keep working for a while: another reason private things don't go here. ## 7. Encrypt a repository ```diagram type: flow title: Before the first push, in this order --- Private | `zev new`, choose private, nothing pushed yet | | 🔒 ~ zev encrypt on Encrypted | File contents encrypted on your computer from now on | accent | 🔐 ~ zev encrypt recovery Recovery code | Shown once: write it down | warn | 🧾 ~ zev push Pushed | Zaryn stores what it can't read | good | ⇡ ``` ```bash zev new # choose "private" zev encrypt on zev encrypt recovery # write the code down, or keep it in a password manager zev push ``` File and folder names, commit messages and sizes stay readable, so the website can still list them. Contents don't. Because Zaryn can't read them, code search and scans don't work inside encrypted files. ## 8. Teammates and their devices ```diagram type: graph title: Who can read what alt: Your laptop and a teammate's laptop hold the key; Zaryn stores only encrypted contents; a browser you approve can show the files legend: path=Encrypted files; path2=The key, per device height: 40 --- node me | your laptop | 12 10 | laptop | accent | Has the key node tm | teammate's laptop | 12 32 | laptop | good | Gets the key with `zev encrypt share` node z | Zaryn | 50 20 | cloud | | Stores and serves contents it can't read node web | a browser you approved | 88 20 | user | | `zev encrypt approve <fingerprint>`: decrypts on your screen only link me z | encrypted | path link tm z | key for this device | path2 link z web | | path ``` 1. Add the person as a collaborator on Zaryn. 2. They register their device: `zev clone you/project` (or `zev encrypt unlock` in an existing copy). 3. Anyone who has the key runs `zev encrypt share`. From then on, their pulls and pushes encrypt and decrypt by themselves. To read encrypted files on the website, approve that browser from a device with the key. Zaryn's server still never sees them. ## 9. A lost laptop, a new one ```diagram type: flow title: Rotate, then recover or: or --- Lost or leaving | Remove the device or the person on Zaryn | bad | ✂ ~ zev encrypt rotate New key | For everything pushed from now on; devices that still belong get it | accent | 🔑 ~ on your new computer Teammate shares | `zev clone`, then someone runs `zev encrypt share` | good | 🤝 ? On your own | `zev encrypt unlock --recovery XXXX-…` with your recovery code | warn ``` Lose every device **and** the recovery code, and nobody can open the files, Zaryn included. That's the price of real end-to-end encryption. ## 10. Check your last push, without trusting us ```diagram type: sequence title: What zev verify-storage checks lanes: zev | Zaryn | Transparency log alt: Zaryn re-reads every object and signs a receipt; zev checks the push is in the receipt, the signature, and that the receipt is in the public transparency log --- note Zaryn : re-reads every object against its hash, signs a receipt | good zev -> Zaryn : the latest receipt note zev : every object of my last push listed? the signature Zaryn's? zev -> Transparency log : is this receipt recorded? Transparency log --> zev : yes, and it can't be changed later ``` ```bash zev verify-storage ``` Each step uses math, not Zaryn's word. If one fails, zev says which. The same check runs in your browser from the repository's settings: **Verify, without trusting Zaryn**. ## 11. A few bytes of a huge file, still proven ```diagram type: flow title: Read part of a big file --- Ask | `zev fetch-range <hash> <start> <length>` | | ⇣ ~ Zaryn sends The part | Just those bytes, with a proof they belong to the object | accent | 🧩 ~ zev checks Proven | Against the whole file's hash, without downloading the rest | good | ✓ ``` A sample of a multi-gigabyte dataset or model, checked as if you'd downloaded it all. ## 12. How your data is kept ```diagram type: cards --- #️⃣ | Named by content | Damage is always detectable: the bytes no longer match their name | accent ⧉ | Two copies, checked daily | A daily scrub repairs either copy from the other | good 🧱 | Erasure coding | The resilient policy spreads big files over several servers | 📌 | Pinned on IPFS | Shared files are pinned; Premium pins on every peer of the cluster | good ``` More in [Verified storage](/docs/en/verified-storage) and [Pinning and IPFS Cluster](/docs/en/pinning-and-cluster). ## 13. From scripts and agents ```bash # upload: the response has the CID, a ready link and a signed receipt curl -X POST "https://api.zaryn.xyz/v1/pins?name=report.pdf" \ -H "Authorization: Bearer $ZARYN_TOKEN" --data-binary @report.pdf curl -H "Authorization: Bearer $ZARYN_TOKEN" https://api.zaryn.xyz/v1/pins # your files and space curl -X DELETE -H "Authorization: Bearer $ZARYN_TOKEN" https://api.zaryn.xyz/v1/pins/<cid> ``` A token with the `pin:write` scope is enough. Every upload's receipt (which file, how big, when) can be checked by anyone, later. ## 14. Space, and where next ```diagram type: stats title: The Free plan --- 20 GB | files shared by link | counted once deduplicated | | 2 GB | repositories | files up to 250 MB | | accent 500 MB | packages and images | mirrors never count | | ``` The bars on the Storage page turn amber past 75%, and Zaryn tells you when you reach a limit. Need more? [Plans](/docs/en/billing-and-credits). Next: [Storing files](/docs/en/storing-files), [Encrypted repositories](/docs/en/encrypted-repositories) and [Verified storage](/docs/en/verified-storage) in depth.