# Encryption

> What's encrypted, how, and who holds the keys.

## Stored zips and assets

Every file you upload is split into 16 MiB chunks, and **each chunk is encrypted with AES-256-GCM before it's stored**:

- Each bucket has its **own 256-bit data key**, created with the bucket (noted in its `bucket.created` event).
- Every chunk gets a fresh random 96-bit nonce and is bound to its object and position, so chunks can't be swapped or replayed into another file without failing authentication.
- The bucket's data key is never stored in plain form: it's **wrapped (encrypted) by a Clatter Labs master key** that lives only in our servers' secret configuration and is never sent to clients, logged, or kept with the data.
- Downloads are decrypted on the fly and verified; a tampered chunk fails instead of returning wrong bytes.

## The browsable code tree

When **preview** is on, the code unpacked from your zips is kept in private, access-controlled storage so it can be listed and read quickly. That copy is **not** encrypted with your bucket's data key. If a bucket must hold code only in encrypted form, turn preview off for it: new zips are then stored encrypted and never unpacked.

## Public files

Files you make [public](/code-buckets/public-files) stay encrypted in storage. When someone opens a public link, the file is decrypted on Code Buckets' servers and sent over HTTPS. Private files are never decrypted for the public hosts (img.cdn.clatterlabs.xyz for images, files.cdn-buckets.clatterlabs.xyz for everything else).

## In transit

All API and Console traffic uses HTTPS (TLS). Send `X-Content-SHA256` with each chunk to make sure what arrived is exactly what you sent.

## Access

Only requests with a valid API key **and** the matching Account ID (or your signed-in Console session) can read a bucket. Keys carry only the permissions you give them, and you can revoke them at any time in the Console.

## Summary

| Data | Protection |
| --- | --- |
| Uploaded zips and assets | AES-256-GCM per chunk, per-bucket data key wrapped by a Clatter Labs master key |
| Code tree (preview on) | Private, access-controlled storage; not encrypted with the bucket key |
| Projects, buckets, events, backups (metadata) | Private database, accessed only by Code Buckets' servers |
| Public files | Stored encrypted like any other; decrypted on our servers only when their public link is opened |
| Traffic | HTTPS |