@devultur/self-host 1.5.0 → 1.5.1

package/README.md

@@ -71,6 +71,8 @@ middleware of your own.
 - Retention and holds (compliance and governance locks, holds, audit, caveats):
   [github.com/devultur/devultur/blob/main/docs/guides/object-lock.md](https://github.com/devultur/devultur/blob/main/docs/guides/object-lock.md).
 
+The three guides ship with the package, for the installed version, in `node_modules/@devultur/self-host/docs/guides/`.
+
 ## License
 
 [AGPL-3.0-only](https://github.com/devultur/devultur/blob/main/packages/self-host/LICENSE)

package/docs/guides/object-lock.md

@@ -0,0 +1,517 @@
+# Retention and holds
+
+Keep a file from being deleted or overwritten until a date, or until you say so (WORM storage). The media Worker
+enforces it on every route that deletes or replaces stored bytes.
+
+- [The model](#the-model)
+- [Compliance and governance](#compliance-and-governance)
+- [What's enforced, and where](#whats-enforced-and-where)
+- [Derived files](#derived-files)
+- [Transcoding a locked video](#transcoding-a-locked-video)
+- [Locking at upload](#locking-at-upload)
+- [Retention vs expiry](#retention-vs-expiry)
+- [Changing a lock](#changing-a-lock)
+- [Holds](#holds)
+- [Audit](#audit)
+- [Deleting a prefix from your own code](#deleting-a-prefix-from-your-own-code)
+- [Caveats](#caveats)
+- [Recipes](#recipes)
+
+## The model
+
+```typescript
+type ObjectLock = {
+  retention?: {
+    mode: "governance" | "compliance";
+    until?: string; // a fixed date (ISO 8601 with a time zone)
+    period?: number; // or seconds from upload, or from the hold's release
+    derivatives?: "inherit" | "original-only"; // default "inherit"
+  };
+  hold?: boolean; // retained indefinitely while true
+};
+```
+
+- **Retention** keeps the file until `until`, or for `period` seconds (at most 100 years). Set one of the two: passing
+  both is a `400`. A `period` counts from the upload, or from the moment a hold is released.
+- **Hold** keeps the file indefinitely, whatever its retention says. Releasing it starts the retention's `period`.
+  If there's no retention, the file is free again.
+
+If you know S3 Object Lock or Google Cloud Storage, it's the same model:
+
+| Here | S3 Object Lock | Google Cloud Storage |
+| --- | --- | --- |
+| `retention.mode: "compliance"` | Compliance mode | Object retention, `Locked` mode |
+| `retention.mode: "governance"` | Governance mode (`s3:BypassGovernanceRetention`) | Object retention, `Unlocked` mode |
+| `retention.until` | Retain until date | Retention expiration time |
+| `hold` | Legal hold | Temporary hold |
+| `hold` + `retention.period` | (no equivalent) | Event-based hold + retention period |
+
+**Resolution order.** It works like `visibility` and the [security flags](https://github.com/devultur/devultur/blob/main/docs/guides/security.md): the resource's own lock,
+then the Worker's default (`config.lock`), then no lock. `hold` resolves on its own. `retention` resolves as a whole:
+its mode and its date come from the same level, so `until` and `period` never mix. `derivatives` falls back to the
+default's, then to `inherit`. A resource can replace the default retention but can't drop it.
+
+A past `until` is valid. It just means the file isn't locked any more, so a default with a fixed date keeps working
+after that date passes.
+
+## Compliance and governance
+
+- **`compliance`**: nobody can delete or overwrite the file before its date, and the lock can only get stricter. Its
+  date can move later, it can't switch to `governance`, and it can't move from `inherit` to `original-only`. Not even
+  the Worker secret can shorten it.
+- **`governance`**: the same, except that a privileged call can shorten or remove it. Privileged means the request
+  asks for `bypassGovernance: true` **and** an [`authorizeLockChange`](plugins.md#hooks) plugin approves it. Without
+  such a plugin, nothing can shorten a governance retention (`403 lock_privilege_required`).
+
+Any lock can be made stricter without privilege: set a later date, a longer period, `inherit`, or a hold. An expired
+retention can be replaced freely.
+
+While a hold is set, a `period` can't be swapped for a fixed `until`. The period only starts at the release, so any
+date could end before it: compliance refuses it, and governance needs the privilege. Release the hold first, or
+extend the period.
+
+## What's enforced, and where
+
+The Worker checks the lock before it deletes or replaces anything:
+
+| Path | A locked file |
+| --- | --- |
+| `DELETE /v1/media/<key>` | `409 retention_active`. Its image variants and encryption keys stay too. |
+| `DELETE /v1/media/videos/<id>` | `409 retention_active` when any of the video's originals is locked. Nothing is deleted. |
+| Deleting a file's encryption keys | Refused the same way, since deleting them destroys the file (crypto-shredding) |
+| `PUT /v1/upload/<key>`, multipart create and complete | `409 retention_active` when they would replace a locked file |
+| `POST /v1/upload` with `overwrite: true` | `409 retention_active` before any bytes are sent |
+| `POST /v1/captions` | `409 retention_active` for a locale that already exists on a locked video. A new locale is allowed. |
+| `POST /v1/transcode` | `409 retention_active` for a re-transcode (see [Transcoding a locked video](#transcoding-a-locked-video)) |
+| `transcode.complete` with `deleteOriginalOnSuccess` | The original is kept (see [below](#transcoding-a-locked-video)) |
+
+A write to a key that doesn't exist yet is a create, not an overwrite, so it's always allowed.
+
+Every write is conditional on the object the check saw. If the file changes between the check and the write (for
+example, a lock lands meanwhile), R2 refuses the write and the Worker answers `409 write_conflict`. The Worker doesn't
+retry, because the new object may be locked: retry the request and you get the current answer.
+
+A refused delete or overwrite answers:
+
+```json
+{
+  "error": "private/file/f1/deed.pdf is retained and can't be deleted",
+  "code": "retention_active",
+  "key": "private/file/f1/deed.pdf",
+  "mode": "compliance",
+  "until": "2031-01-01T00:00:00.000Z",
+  "hold": false
+}
+```
+
+`key` names the locked original. For a derived file (a caption, an HLS segment), that's the video's original. `mode`
+is left out for a hold with no retention, and `until` is left out while a hold keeps a `period` from starting.
+
+All the lock error codes:
+
+| Status | `code` | When |
+| --- | --- | --- |
+| `409` | `retention_active` | A delete or overwrite of a locked file |
+| `409` | `write_conflict` | The file changed between the check and the write: retry |
+| `409` | `compliance_extend_only` | A change that would weaken a compliance retention |
+| `409` | `lock_conflict` | Another lock change landed first: retry |
+| `409` | `lock_record_unreadable` | A change to a file whose lock record can't be read (see [Caveats](#caveats)) |
+| `403` | `lock_privilege_required` | Shortening or removing a governance retention without an approved bypass |
+| `403` | `lock_below_minimum` | An upload asks for a looser lock than its upload token requires |
+| `400` | `invalid_lock`, `invalid_hold` | A malformed lock or hold request |
+| `400` | `reserved_key` | A key under `__lock/` or `__lock-audit/`, which the Worker keeps for itself |
+
+Owner reads (the Worker secret on `GET /v1/media/<key>`) also get `x-devultur-lock-until` and, while a hold is set,
+`x-devultur-lock-hold: true`. An owner read never goes through the edge cache: it isn't answered from a public copy
+and doesn't store one. Its `Cache-Control` is the private form of the file's own, so no shared cache keeps the lock
+headers either.
+
+## Derived files
+
+A video's transcode outputs and captions live under its folder (`{visibility}/video/{id}/…`).
+`retention.derivatives` decides whether they're retained with the original:
+
+- **`inherit`** (the default): transcode outputs and captions can't be deleted or overwritten while the original is
+  locked. New outputs and new caption locales can still be added.
+- **`original-only`**: only the uploaded file is retained. Its outputs and captions can be deleted or regenerated
+  freely. Deleting the whole video is still refused, since the original is in it.
+
+Image variants and mezzanines are regenerable caches. They're never retained.
+
+Derived files also expire with their original. An HLS playlist or segment, an MP4, a thumbnail, poster or storyboard
+written by the transcode runner gets the earliest `expiresAt` of the video's raws, and a caption gets the one of the
+file it was made from. Past it, they answer `410` like the original. The value is copied when the output is written
+(the raw is deleted by `deleteOriginalOnSuccess` only after the transcode completes), so changing a raw's expiry
+later doesn't reach outputs already written. The HLS encryption key (`.key`) has no expiry of its own: it's useless
+without the segments.
+
+## Transcoding a locked video
+
+- **The first transcode** of a locked video is allowed, since it only creates outputs.
+- **A transcode that never completed** (failed, or the runner died) can be retried, and the new job may overwrite
+  the partial outputs.
+- **Once a transcode has completed**, re-transcoding is refused with `409 retention_active`, because it would
+  overwrite retained outputs. The Worker records the completion durably, under
+  `__lock/{visibility}/video/{id}/transcode-completed`.
+- **While a job is in progress** (`queued` or `running`), the runner may rewrite its own outputs (HLS, MP4,
+  thumbnails, storyboard), for example to retry an upload. From `transcode.complete` on, they're protected like any
+  derived file.
+
+**Deleting the original after transcode.** With `transcode.deleteOriginalOnSuccess`, the Worker deletes the original
+once a transcode completes. A locked original wins: it's kept, the skip is audited (`original_retained`), and the
+webhook still succeeds. `getRouteResult(context).originalRetained` tells a plugin it happened. The original keeps
+taking storage until its lock ends, and in Infrequent Access (`originalStorageClass`) it also keeps that class's
+30-day minimum and per-read retrieval charge. Once the lock ends, delete it yourself: `deleteOriginalOnSuccess`
+doesn't come back for it.
+
+## Locking at upload
+
+An upload can carry its lock, so the file never exists unprotected. The lock is written with the bytes, and nothing
+can strip it later (the Worker drops a `lock` key from `config.uploadMetadata`).
+
+```typescript
+const client = createWorkerClient(secret, workerUrl);
+
+await client.createUploadUrl({
+  filename: "deed.pdf",
+  contentType: "application/pdf",
+  lock: { retention: { mode: "compliance", period: 7 * 365 * 24 * 3600 } },
+});
+await client.createUploadUrl({ filename: "evidence.mp4", contentType: "video/mp4", hold: true });
+```
+
+`hold: true` is shorthand for `lock: { hold: true }`. `uploadFile` and `uploads.uploadAsset` take the same options.
+A Worker-wide default goes in `config.lock`:
+
+```typescript
+export default createWorker({
+  plugins: defaultPlugins({ lock: { retention: { mode: "governance", period: 30 * 24 * 3600 } } }),
+});
+```
+
+**Upload tokens** can pin a minimum lock: `uploads.createToken({ prefix, lock })`. An upload with that token gets at
+least that lock. It can ask for a stricter one, never a looser one (`403 lock_below_minimum`).
+
+**Expiry.** A lock may outlive the file's `expiresAt` (`expiresIn`, the token's or the config's TTL): see
+[Retention vs expiry](#retention-vs-expiry).
+
+**Uploads without a pending upload.** A `PUT /v1/upload/<key>` with the Worker secret and no `POST /v1/upload` before
+it gets `config.lock` too, unless the key is a video's derived output (those follow their original through
+`derivatives`).
+
+Locks need the media Worker. In direct-storage mode, `createMediaRouter` throws when an upload asks for a lock,
+because a presigned PUT to the bucket can't enforce one.
+
+## Retention vs expiry
+
+Retention and expiry are separate, as in S3 Object Lock. **Retention preserves** the object: it can't be deleted or
+overwritten. **Expiry ends access** to it: past `expiresAt`, nobody but the owner reads it, and that covers a video's
+transcode outputs and captions (see [Derived files](#derived-files)). A lock doesn't extend access, and an expiry
+doesn't shorten a lock. A file can be shared for 30 days and kept for 10 years.
+
+| State | Viewers, public requests, download links | The owner (Worker secret) | The object |
+| --- | --- | --- | --- |
+| Before `expiresAt` | Normal access | Normal access | Kept (and protected while locked) |
+| After `expiresAt`, still retained | `410` | Can read it, to export or audit | Not deleted: delete and overwrite answer `409 retention_active` |
+| After `expiresAt`, free | `410` | `410` | Stays in the bucket until your expiry cleanup deletes it |
+
+- **Download links are access.** A link never outlives the file's `expiresAt`, even for a retained file. Creating one
+  for an expired file answers `410`, and redeeming one after the file expired does too.
+- **Edge copies.** A public file's edge copy never outlives its `expiresAt`: its TTL is capped there, and a copy found
+  past it is ignored, so the request reaches the Worker and gets `410`.
+- **Listings.** `GET /v1/assets` (an owner route) includes an expired file that's still retained, marked
+  `expired: true` with `retainedUntil` (its retention's end) or `hold: true`. An expired free file isn't listed.
+  Telling them apart reads each expired file's lock record (one subrequest each), so a page reads at most 32
+  (`MAX_EXPIRED_LOOKUPS`): past that, it ends early with a `cursor` that resumes right after its last entry. A page
+  can hold fewer entries than `limit` while more remain; keep following the `cursor` until it's `null`.
+- **The expiry cleanup is yours to run.** Nothing in `@devultur/self-host` deletes expired files: the Worker only
+  refuses access to them. Run your own job (a cron Worker, a script) that deletes them through the Worker
+  (`DELETE /v1/media/<key>`, or `/v1/media/videos/<id>` for a video), so each delete goes through the lock check: a
+  retained file answers `409 retention_active` and is kept until its lock ends, then the job's next run deletes it.
+  Don't use an R2 lifecycle rule for it: it doesn't go through the Worker and deletes retained files too (see
+  [Caveats](#caveats)).
+
+## Changing a lock
+
+`GET /v1/lock/<key>` and `PUT /v1/lock/<key>` are control routes. The default auth accepts only the Worker secret.
+
+```typescript
+await client.lock.get(key);
+// { key, mode, until, period, hold, derivatives, source: "upload" | "sidecar" | "none", revision }
+
+await client.lock.set(key, { until: "2032-01-01T00:00:00Z" }); // extend
+await client.lock.set(key, { mode: "governance", period: 90 * 24 * 3600 }); // set on an unlocked file
+await client.lock.set(key, { until: "2026-12-31T00:00:00Z", bypassGovernance: true }); // shorten (governance)
+await client.lock.set(key, { remove: true, bypassGovernance: true }); // remove (governance)
+```
+
+The fields merge over the current retention, and `until` and `period` replace each other. `PUT` changes the retention
+only. Holds have [their own route](#holds).
+
+R2 can't edit an object's metadata in place, so a change goes to a small record at `{storagePrefix}__lock/<key>`. The
+record is bound to the object version it was written for (R2's per-write `version`, never the etag, which repeats when
+the same bytes are uploaded again). Deleting or overwriting the file leaves the record in place, inert: it never
+applies to another version, so a file uploaded again at the same key starts from its own upload lock, and a lock
+change made on the new file right after it landed can't be lost to a cleanup of the old record. A record of a deleted
+file is a few hundred bytes and stays as evidence of its last lock. To reclaim them, delete only records whose file no
+longer exists: deleting the record of an existing file drops every change made to its lock. Two concurrent changes
+can't both land: the second gets `409 lock_conflict`.
+
+## Holds
+
+`POST /v1/lock/hold` is the one way to set or release a hold, including on a single file:
+
+```typescript
+await client.lock.hold([key]);
+await client.lock.release([key]);
+
+// Every page of a prefix, or a long list of keys
+for await (const page of client.lock.holdAll({ prefix: "private/asset/case-17/" })) {
+  console.log(page.updated, page.skipped);
+}
+```
+
+- A request names up to 50 keys (`HOLD_PAGE_SIZE`), or a prefix. A prefix is walked 50 objects per request, with a
+  `cursor`. Each object costs about four subrequests, so a page stays well under the Workers limit. `holdAll` and
+  `releaseAll` follow the cursor and split long key lists for you.
+- The answer is `{ updated: string[], skipped: { key, reason }[], cursor? }`. The `reason` is `not_found`,
+  `unchanged` (already in that state), `lock_conflict` (changed concurrently: retry it) or `lock_record_unreadable`
+  (a release of a file whose lock record can't be read, see [Caveats](#caveats)).
+- A hold never touches the retention, so it can only add protection. A hold on a compliance file is allowed, and its
+  date stays.
+- **Releasing:** with a `retention.period`, the period starts now. With a fixed `until`, that date still applies.
+  With no retention, the file is free.
+- Image variants under a prefix are skipped, since they're caches. The Worker's own records (`__lock/`,
+  `__lock-audit/`) are never listed or changed, whatever the prefix.
+
+## Audit
+
+Every lock event gets one record. That covers every change (including holds and releases), the lock set at upload,
+every rejected delete or overwrite, and every original kept after a transcode.
+
+```typescript
+interface LockAuditRecord {
+  at: string; // ISO time
+  action: "set" | "extend" | "shorten" | "remove" | "hold" | "release"
+    | "delete_rejected" | "overwrite_rejected" | "original_retained";
+  keys: string[];
+  before: ObjectLock | null;
+  after: ObjectLock | null;
+  actor: PluginContext | null; // the request's plugin context; for an upload, the uploader's
+  outcome: "applied" | "rejected" | "skipped";
+  bypass?: true; // the change used the governance privilege
+  reason?: string; // why it was rejected
+}
+```
+
+Each record goes to three places:
+
+- a structured log line (`{"event":"lock.audit", …}`);
+- one create-only object at `{storagePrefix}__lock-audit/{yyyy-mm-dd}/{ts}-{uuid}.json` in the media bucket;
+- every plugin's [`onLockAudit`](plugins.md#hooks) hook, to store it elsewhere.
+
+The object and the hooks run after the response. A failure there is logged, never surfaced. The audit isn't a general
+access log: reads aren't recorded.
+
+## Deleting a prefix from your own code
+
+Code that runs in your Worker and deletes whole prefixes straight from the R2 binding (an app's teardown, a user's
+data export cleanup, a sweeper for expired files) bypasses the routes' checks. `@devultur/self-host` exports the
+guard's lock resolution for it, so it can skip retained files:
+
+```typescript
+import { deletePrefixRespectingLocks, readObjectLock, retainedSummary } from "@devultur/self-host";
+
+// The lock in force on one stored object (its full R2 key), or null when there's no such object.
+const lock = await readObjectLock({ mediaBucket: env.MEDIA_BUCKET }, "apps/a1/private/file/f1/deed.pdf");
+// { locked: true, hold: false, until: "2031-01-01T00:00:00.000Z", mode: "compliance" }
+
+// Delete what's free under a storage prefix, keep what's retained. Call again with `cursor` until it's gone.
+let cursor: string | undefined;
+do {
+  const result = await deletePrefixRespectingLocks({
+    mediaBucket: env.MEDIA_BUCKET,
+    keysBucket: env.KEYS_BUCKET,
+    prefix: "apps/a1/",
+    cursor,
+  });
+  // result: { deletedCount, deletedBytes, deletedKeyCount, retainedCount, retainedBytes, retained, skippedCount,
+  //           cursor?, subrequests }
+  cursor = result.cursor;
+} while (cursor);
+```
+
+- **Keys are storage keys**: the full R2 keys, your storage prefix included. Nothing needs a request. The storage
+  prefix each key lives under (where its lock record is) is read from the key: everything before its first `public`
+  or `private` segment. Pass `root` when you walk a single storage prefix that has a segment named `public` or
+  `private`. One prefix can span several storage prefixes, each read on its own.
+- **Keys it can't place are kept.** A key with no `public` or `private` segment (or none right after the `root` you
+  passed) isn't laid out like the Worker's, so its lock record can't be found. It's never deleted: it comes back in
+  `retained` with `unrecognized: true`. A key with a segment ending in `__lock` or `__lock-audit` (a lock record or
+  audit object, even under a storage prefix with no trailing `/`) is never touched, and is counted in `skippedCount`.
+- **Same resolution as the routes.** The upload's lock, or the lock record bound to the stored version (a record left
+  by a replaced version is ignored). An unreadable record counts as held (`unreadable: true`). Each object's own lock
+  is checked on the version read (HEAD) right before its delete. A video's files inherit from its raws, and an image's
+  variants from the image, unless the lock is `original-only`. That inherited lock is read once and reused for at
+  most 50 objects or 5 seconds. `lockedBy` names the original whose lock it is.
+- **What goes.** A free object goes the way `DELETE /v1/media/<key>` deletes it: with its encryption keys in
+  `KEYS_BUCKET` (except those of an upload in flight over it) and its variants'. A video folder left empty also loses
+  the rest of its keys written before the call started (the HLS key) and its transcode-completed marker, as with
+  `DELETE /v1/media/videos/<id>`, when the whole folder is under the prefix. `deletedBytes` adds up the sizes of the
+  versions deleted.
+- **Real time only.** The delete takes no `now`: locks are judged by the real clock, so no option can make a retention
+  read as expired. `readObjectLock` and `retainedSummary` take a `now`, to ask what's retained at another time.
+- **Cursors are bound to their prefix.** A cursor works only with the `prefix` it was returned for. One that's
+  malformed, from another prefix, or pointing outside it throws a `RangeError` before any bucket call.
+- **What stays.** Retained files, with their variants, keys and lock records. The lock records of deleted files stay
+  too, inert, as with the routes. Nothing under `__lock/` or `__lock-audit/` is touched: once a storage prefix has
+  nothing retained left, delete those yourself if you're tearing it down.
+- **Bounded.** A Worker invocation has a subrequest limit. Every bucket call is counted, and a call never makes more
+  than `maxSubrequests`. It reads everything an object needs before deleting any of it, and only deletes if the budget
+  left covers it, so it never stops halfway through an object. It returns a `cursor` to go on from (a video folder it
+  emptied is finished by the next call). The default, 40, fits under the Workers Free plan's 50 subrequests per
+  request and leaves room for your own calls. On a paid plan, raise it (to a few hundred, say) so each call gets
+  further. A bound too small to finish even one object throws a `RangeError`. `batchSize` (default 100, at most 1000)
+  sets how many objects it lists at a time. Run a large prefix over several invocations (a queue, or a cron that
+  keeps the cursor).
+- **Not audited.** The call is your code, not a request, so no audit record or hook runs: log `retained` if you need a
+  trail. R2 deletes aren't conditional: a lock set between an object's check and its delete isn't seen. That gap is
+  milliseconds for the object's own lock, and up to 5 seconds for an inherited one (see [Caveats](#caveats)).
+
+`retainedSummary({ mediaBucket, prefix, cursor?, now? })` answers "can this be deleted?" without deleting anything:
+`{ scannedCount, retainedCount, retainedBytes, latestUntil?, hasHold, cursor?, subrequests }`, with the same bounds.
+Add up the counts of each call. With `hasHold`, something stays until it's released, not until `latestUntil`.
+
+## Caveats
+
+- **The check/delete window.** R2 deletes aren't conditional, so a lock set in the milliseconds between the Worker's
+  check and its delete isn't seen. Writes are conditional, and protected.
+- **Only the Worker enforces locks.** R2 lifecycle rules, the R2 dashboard, `wrangler r2`, and any S3 or binding
+  access that doesn't go through the Worker can delete a locked file. Treat locks as compliance only as long as nobody
+  else can write to the bucket. This isn't a certified WORM store.
+- **R2 bucket locks** can be an optional second layer: an R2 bucket lock rule refuses deletes at the storage level.
+  Anyone who can edit the bucket's configuration can remove the rule, though, so it raises the bar rather than
+  closing it. [Self-host](self-host.md#r2-bucket-lock-defense-in-depth) has the safe prefixes and what
+  changes once a rule is on.
+- **The runner credential.** While a transcode job is in progress, a request with the runner's credential may rewrite
+  that job's outputs on a locked video. With `workerSecretAuth()`, that credential is `WORKER_AUTH_SECRET`, which your
+  backend holds too. To limit the exemption to the runner, give the runner a narrower credential from your own auth
+  plugin (`updateRequestState(context, { runnerCredential })`) and accept it only for uploads of transcode outputs.
+- **Direct storage** (`createMediaRouter` with your own bucket and no Worker) refuses locks: nothing would enforce
+  them.
+- **`deletePrefix`**, exported by `@devultur/self-host`, deletes everything under a prefix and bypasses locks. Use it
+  only for regenerable data. The routes delete through the guarded helpers; your own code can use
+  [`deletePrefixRespectingLocks`](#deleting-a-prefix-from-your-own-code).
+- **Listings show retention.** An expired, retained entry of `GET /v1/assets` carries `retainedUntil` and `hold`:
+  whoever can list a prefix learns what's retained in it. With `workerSecretAuth()`, listing takes the Worker secret,
+  the same credential as `GET /v1/lock`. An auth plugin of your own that lets a narrower credential list (a sync
+  script's, say) gives it that view too. If that credential shouldn't see what's retained, keep it off
+  `GET /v1/assets`.
+- **An unreadable lock record** (the record at `__lock/<key>`, or the upload's `lock` metadata, isn't valid JSON or
+  isn't a valid lock) fails closed: the file reads as held, for whatever version is stored at the key. Since nobody can
+  tell what it really said (it might be a compliance retention), the API never weakens it: a release is skipped with
+  `lock_record_unreadable`, `PUT /v1/lock/<key>` answers `409 lock_record_unreadable`, and deletes and overwrites
+  answer `409 retention_active`. Recovery is an operator's job, outside the Worker: find the record's last good
+  content in the audit (the `after` of the key's last `applied` record under `__lock-audit/`), write it back to
+  `__lock/<key>` as `{ revision, objectVersion, lock, updatedAt }` with the current object's R2 `version` as
+  `objectVersion` (for bad upload metadata, `lock` is the lock it was uploaded with), and check it with
+  `GET /v1/lock/<key>`.
+
+## Recipes
+
+### Keep a record until N years after an event
+
+The end date depends on an event that hasn't happened yet (a contract ends, a case closes). Upload with a hold and a
+`period`, and release the hold when the event happens: the period starts then.
+
+```typescript
+const SEVEN_YEARS = 7 * 365 * 24 * 3600;
+
+// At upload: retained indefinitely until the event
+const upload = await client.createUploadUrl({
+  filename: "record.pdf",
+  contentType: "application/pdf",
+  lock: { retention: { mode: "compliance", period: SEVEN_YEARS }, hold: true },
+});
+
+// When the event happens: the 7 years start now
+await client.lock.release([upload.key]);
+
+// Or every file of the record at once
+for await (const page of client.lock.releaseAll({ prefix: "private/asset/record-42/" })) {
+  if (page.skipped.length > 0) console.warn(page.skipped);
+}
+```
+
+### Share for 30 days, keep for 10 years
+
+Access ends after 30 days, and the file stays (undeletable) for 10 years:
+
+```typescript
+await client.createUploadUrl({
+  filename: "statement.pdf",
+  contentType: "application/pdf",
+  expiresIn: 30 * 24 * 3600,
+  lock: { retention: { mode: "compliance", period: 10 * 365 * 24 * 3600 } },
+});
+```
+
+After 30 days, viewers and download links get `410`. Your backend can still read the file with the Worker secret,
+and `GET /v1/assets` lists it with `expired: true` and `retainedUntil`. Until the 10 years pass, your
+[expiry cleanup](#retention-vs-expiry) gets `409 retention_active` for it; its first run after that deletes it.
+
+### Compliance retention for N years from upload
+
+```typescript
+export default createWorker({
+  plugins: defaultPlugins({
+    lock: { retention: { mode: "compliance", period: 10 * 365 * 24 * 3600 } },
+  }),
+});
+```
+
+Every upload gets the lock, unless it asks for a stricter one. To scope it to some uploads, set the lock per upload
+instead, or hand out [upload tokens](#locking-at-upload) with a minimum `lock`.
+
+### Convex
+
+The [Convex component](https://github.com/devultur/devultur/blob/main/packages/convex/README.md#object-lock) exposes the same operations to your own
+functions. A Worker refusal arrives as a `ConvexError` whose `data.code` is the code above:
+
+```typescript
+import { Devultur, devulturErrorOf } from "@devultur/convex";
+import { v } from "convex/values";
+import { components } from "./_generated/api";
+import { action } from "./_generated/server";
+
+const devultur = new Devultur(components.devultur);
+
+export const extendRetention = action({
+  args: { key: v.string(), until: v.string() },
+  handler: async (ctx, { key, until }) => {
+    try {
+      return await devultur.setLock(ctx, key, { until });
+    } catch (error) {
+      const refusal = devulturErrorOf(error);
+      if (refusal?.code === "compliance_extend_only") return { ok: false, reason: "can only move later" } as const;
+      if (refusal?.code === "lock_conflict") return devultur.setLock(ctx, key, { until }); // changed meanwhile
+      throw error;
+    }
+  },
+});
+
+export const deleteFile = action({
+  args: { key: v.string() },
+  handler: async (ctx, { key }) => {
+    try {
+      await ctx.runAction(components.devultur.public.deleteMediaAction, { key });
+    } catch (error) {
+      const refusal = devulturErrorOf(error);
+      // { key, mode, until, hold } of the locked original
+      if (refusal?.code === "retention_active") return { deleted: false, lock: refusal.details } as const;
+      throw error;
+    }
+    return { deleted: true } as const;
+  },
+});
+```

package/docs/guides/plugins.md

@@ -0,0 +1,205 @@
+# Plugins
+
+The media Worker is built from plugins. `createWorker()` is `createWorker({ plugins: defaultPlugins() })`: the
+Worker secret auth, the rules of every request, the credential policy and download links are plugins that use the
+same API as yours. Add plugins to extend the Worker, or replace a default one.
+
+```typescript
+import { createWorker, defaultPlugins } from "@devultur/self-host";
+import { usageLog } from "./plugins/usage-log";
+
+export { DownloadLink } from "@devultur/self-host";
+
+export default createWorker({
+  plugins: [...defaultPlugins({ transcode: { maxResolution: "1080p" } }), usageLog()],
+});
+```
+
+## Default plugins
+
+| Plugin | What it does |
+| --- | --- |
+| `staticConfig(config)` | Applies the [rules](self-host.md#rules) to every request. Put it first: later plugins narrow it. |
+| `workerSecretAuth()` | Control routes require `Authorization: Bearer <WORKER_AUTH_SECRET>`; the transcode runner uploads with the same secret. |
+| `credentialPolicy(options?)` | Decides before a credential is issued. Without options it issues what is asked; `maxTtlSeconds: { viewer: 3600 }` caps a kind. |
+| `downloadLinks()` | `POST /v1/token/download` and `GET /v1/download/<id>` (needs the `DOWNLOAD_LINKS` Durable Object). Without it both answer `404`. |
+
+`createWorker()` refuses to start when no plugin authenticates requests, so dropping `workerSecretAuth()` without
+an auth plugin of yours fails at deploy, not in production.
+
+## Writing a plugin
+
+A plugin is an object:
+
+```typescript
+interface WorkerPlugin {
+  name: string;
+  middleware?: {
+    beforeAuth?: MiddlewareHandler[];
+    auth?: MiddlewareHandler[];
+    afterAuth?: MiddlewareHandler[];
+  };
+  routes?: Array<{ path: string; app: Hono }>;
+  issueCredential?: (context: Context, request: CredentialRequest) => CredentialDecision | Promise<CredentialDecision>;
+  beforeLinkRedeem?: (context: Context, link: DownloadLinkInfo) => Response | null | Promise<Response | null>;
+  authorizeLockChange?: (context: Context, request: LockChangeRequest) => LockChangeDecision | Promise<LockChangeDecision>;
+  onLockAudit?: (context: Context, record: LockAuditRecord) => void | Promise<void>;
+}
+```
+
+Middleware are [Hono](https://hono.dev) middleware. Every request goes through all plugins' `beforeAuth`, then
+their `auth`, then their `afterAuth`, each phase in plugin order, and then the route:
+
+- **`beforeAuth`**: work that doesn't need to know the caller, like rate limiting or an endpoint the plugin answers
+  itself.
+- **`auth`**: who is calling and what the request may touch. At least one plugin needs it.
+- **`afterAuth`**: authorization and per-request rules, and anything that reads `context.res` after `await next()`
+  (logs, metrics, cache purges).
+
+`routes` are mounted after the Worker's own routes, behind every plugin's middleware.
+
+## Request state
+
+A plugin tells the routes about the current request with `updateRequestState(context, patch)`, and reads it with
+`getRequestState(context)`. Top-level fields replace; `config`, `access` and `context` merge field by field.
+
+| Field | What it does |
+| --- | --- |
+| `storagePrefix` | Prefix of every storage key the request touches (`""` = the bucket root). Keeps each of your apps in its own folder. |
+| `config` | The [rules](self-host.md#rules), field by field over `staticConfig` |
+| `access.authenticated` | The credential was verified. Without it, an upload URL only acts on the upload an authenticated `POST /v1/upload` created. |
+| `access.trustedRead` | Serve private media without a viewer token. Only set it for a credential sent in `Authorization`, never for a `?token=` query. |
+| `access.uploadGrant` | The credential is an upload token: `POST /v1/upload` stays inside its prefix |
+| `runnerCredential` | Bearer the transcode runner uploads its outputs with (`workerSecretAuth()` sets the Worker secret) |
+| `webhookCredential` | Bearer sent to a job's `callbackUrl`. Unset: `runnerCredential`; `""`: none. |
+| `context` | Plugin context: see below |
+
+### Plugin context
+
+`context` is any JSON a plugin attaches to the request. The Worker stores it with the uploads and download links the
+request creates and in the transcode job, and hands it back when they're used: the upload PUT, a link redemption and
+the runner's callbacks carry no credential, so it's how a plugin knows who started them. The Worker never reads it.
+
+Type your plugin's keys by augmenting the interface:
+
+```typescript
+declare module "@devultur/self-host" {
+  interface PluginContext {
+    appId?: string;
+  }
+}
+
+updateRequestState(context, { context: { appId: "web" } });
+```
+
+## Hooks
+
+**`issueCredential`** runs before the Worker issues a viewer token, an upload token, a download link or the runner's
+service token. It gets the `kind`, the `scopes`, the `path` it is bound to and the requested `expiresAt` (epoch ms).
+Return `{ allow: false, response }` to refuse, or `{ allow: true, expiresAt?, claims? }` to issue it: `expiresAt`
+caps the expiry, and `claims` are added to a token. The hooks of every plugin run in order: the first refusal wins,
+the earliest `expiresAt` applies, and the claims of all of them are added.
+
+```typescript
+const viewerTokensOnlyRead: WorkerPlugin = {
+  name: "viewer-tokens-only-read",
+  issueCredential: (context, { kind, scopes }) => {
+    if (kind === "viewer" && scopes.some((scope) => scope !== "media:read")) {
+      return { allow: false, response: context.json({ error: "Viewer tokens only read" }, 403) };
+    }
+    return { allow: true };
+  },
+};
+```
+
+The Worker sets the claims that bound a token itself, and a plugin can't override them: `aud` is the storage
+prefix it was issued under (without its trailing slash) and `scope` its space-separated scopes. The delivery gate
+also enforces `res`, a path prefix its keys must fall under, when a plugin adds it. A token outside what its claims
+allow gets `403 { "code": "token_rejected" }`; which claim failed is only logged.
+
+**`beforeLinkRedeem`** runs before `GET /v1/download/<id>` spends a use of a link. Return a `Response` to refuse it
+(the use isn't spent), or `null` to let it go on. It gets the link's `storagePrefix`, `key` and plugin `context`.
+
+**`authorizeLockChange`** runs before the Worker changes a lock ([Retention and holds](object-lock.md)):
+`PUT /v1/lock/<key>` once per change, and `POST /v1/lock/hold` once per page. It gets:
+
+- `action`: `set`, `extend`, `shorten`, `remove`, `hold` or `release`;
+- `keys`, and the `prefix` of a bulk hold;
+- `before` and `after`, the locks (`null` / `{ hold }` for a hold page).
+
+Return `{ allow: false, response }` to refuse, or `{ allow: true }`. The first refusal wins. The hook also decides
+the governance privilege: shortening or removing a governance retention takes `bypassGovernance: true` in the request
+**and** at least one `authorizeLockChange` hook, with every hook allowing it. With no such hook, nothing can shorten a
+governance retention.
+
+This one lets only a records officer, who sends a second credential, shorten or remove a governance retention:
+
+```typescript
+import { isBearerOf } from "@devultur/core";
+import type { WorkerPlugin } from "@devultur/self-host";
+
+const recordsOfficer: WorkerPlugin = {
+  name: "records-officer",
+  authorizeLockChange: (context, { action }) => {
+    if (action !== "shorten" && action !== "remove") return { allow: true };
+    // Bound with `wrangler secret put RECORDS_OFFICER_SECRET`; the request still carries the Worker secret.
+    if (isBearerOf(context.req.header("X-Records-Officer"), context.env.RECORDS_OFFICER_SECRET)) {
+      return { allow: true };
+    }
+    return {
+      allow: false,
+      response: context.json({ error: "Only a records officer can shorten a retention", code: "officer_required" }, 403),
+    };
+  },
+};
+```
+
+**`onLockAudit`** gets every [audit record](object-lock.md#audit) after the response (`waitUntil`): lock changes, the
+lock set at upload, refused deletes and overwrites, and originals kept after a transcode. Use it to store the records
+somewhere other than the default `__lock-audit/` objects, for example a database or a log pipeline. A failure is
+logged and never reaches the caller.
+
+```typescript
+const auditToD1: WorkerPlugin = {
+  name: "audit-to-d1",
+  onLockAudit: async (context, record) => {
+    await context.env.AUDIT_DB.prepare("INSERT INTO lock_audit (at, action, keys, record) VALUES (?, ?, ?, ?)")
+      .bind(record.at, record.action, record.keys.join(" "), JSON.stringify(record))
+      .run();
+  },
+};
+```
+
+## After the route
+
+- `getRouteResult(context)` tells a middleware that runs after `await next()` what the route did: `redeemedLink`
+  (the download link just redeemed), `originalDeleted` (`transcode.complete` deleted the original),
+  `originalRetained` (it kept a locked original instead) and
+  `transcodeJob` (the job a runner callback belongs to, with its plugin `context`).
+- `getPendingUpload(context)`, before the route, returns the upload an upload URL points to: its key, storage key,
+  content type and plugin `context`. `cancelPendingUpload(context, uploadUrl)` makes an upload URL stop working, for
+  a plugin that rejects an upload after `POST /v1/upload` created it.
+- `parseEncodeMetrics(body)` reads the encode measurement of a runner's `transcode.complete`
+  (see [Measuring encode cost](self-host.md#measuring-encode-cost)).
+
+## Deleting from a plugin
+
+A plugin route (or a scheduled handler next to the Worker) that deletes from `MEDIA_BUCKET` directly skips the
+routes' lock checks. Delete a prefix with `deletePrefixRespectingLocks` instead, and read one object's lock with
+`readObjectLock`: they keep retained files, their keys and their lock records, and stay within a subrequest bound
+(see [Deleting a prefix from your own code](object-lock.md#deleting-a-prefix-from-your-own-code)). The storage
+prefix of the request is `getRequestState(context).storagePrefix`.
+
+## Example plugins
+
+Three small plugins in [`examples/plugins`](https://github.com/devultur/devultur/blob/main/examples/plugins/src), typechecked and tested with the packages:
+
+- **[`jwt-auth`](https://github.com/devultur/devultur/blob/main/examples/plugins/src/jwt-auth.ts)** authenticates with JWTs from your identity provider
+  (its JWKS, or a shared HS256 `JWT_SECRET`) instead of the Worker secret, and can map a claim to a storage
+  prefix. The transcode runner keeps using the Worker secret, so a job outlives any user token.
+- **[`usage-log`](https://github.com/devultur/devultur/blob/main/examples/plugins/src/usage-log.ts)** records the bytes and requests of media delivery and
+  download links, counted as they stream, into the log or a D1 table.
+- **[`rate-limit`](https://github.com/devultur/devultur/blob/main/examples/plugins/src/rate-limit.ts)** answers `429` to a client over its limit, with
+  Cloudflare's Rate Limiting binding, before any token is verified.
+
+[`worker.ts`](https://github.com/devultur/devultur/blob/main/examples/plugins/src/worker.ts) puts them together.

package/docs/guides/self-host.md

@@ -0,0 +1,523 @@
+# Self-host (bring your own R2)
+
+Run the Devultur media Worker and SDKs against your own Cloudflare account and R2 bucket.
+
+There are two ways to use Devultur on your own infrastructure:
+
+- **Media Worker** (recommended): deploy `@devultur/self-host` on your Cloudflare account. It handles uploads,
+  delivery, transcode, captions and image transforms, and your backend talks to it with `@devultur/server`.
+- **Direct R2**: point `@devultur/server` at your R2 bucket with S3 credentials and sign delivery yourself, with
+  no Worker in between.
+
+## Direct R2
+
+The server SDK presigns uploads straight to your bucket and signs delivery URLs:
+
+```typescript
+import { createMediaRouter, video, image, file } from "@devultur/server";
+
+export const media = createMediaRouter({
+  storage: {
+    provider: "r2",
+    bucket: "my-media",
+    accountId: process.env.CF_ACCOUNT_ID!,
+    accessKeyId: process.env.R2_ACCESS_KEY!,
+    secretAccessKey: process.env.R2_SECRET_KEY!,
+  },
+  delivery: {
+    signSecret: process.env.DELIVERY_SIGN_SECRET!,
+  },
+  video: video({ maxSize: "2GB" }),
+  image: image({ maxSize: "10MB" }),
+  file: file({ maxSize: "500MB" }),
+});
+```
+
+> [!NOTE]
+> The Worker honors the `preset` you pass, so transcode resolution is yours to control. Cap it with
+> `config.transcode.maxResolution` (see below).
+
+## The media Worker
+
+To run uploads, delivery, transcode and captions on your own Cloudflare account, deploy the
+media Worker from `@devultur/self-host`:
+
+```typescript
+import { createWorker } from "@devultur/self-host";
+export { DownloadLink } from "@devultur/self-host";
+
+export default createWorker();
+```
+
+The Worker needs an R2 bucket bound as `MEDIA_BUCKET`, a second R2 bucket as `KEYS_BUCKET` (encryption keys), a KV
+namespace as `MEDIA_KV` (pending uploads, transcode job state), the `DownloadLink` Durable Object (single-use download
+links) and three secrets. The steps below set them up in order.
+
+### Step by step
+
+#### 1. Pick the account
+
+If your login can see more than one Cloudflare account, non-interactive Wrangler commands fail with "More than one
+account available but unable to select one in non-interactive mode". Pin the account before anything else, either in
+`wrangler.toml`:
+
+```toml
+account_id = "<your-account-id>"
+```
+
+or in the environment, for CI and scripts:
+
+```bash
+export CLOUDFLARE_ACCOUNT_ID=<your-account-id>
+```
+
+To check auth from a script, run `wrangler r2 bucket list`: it returns, and it proves both the login and R2 access.
+Don't use `wrangler whoami` for that check: some versions print the account and then hang.
+
+#### 2. Create the buckets
+
+```bash
+wrangler r2 bucket create media
+wrangler r2 bucket create media-keys
+```
+
+`KEYS_BUCKET` holds the key of every file encrypted at rest ([L4 encryption](https://github.com/devultur/devultur/blob/main/docs/guides/security.md#l4--encryption)). With
+`security.encrypt` on, the Worker fails closed without it: a private upload, transcode or captions request answers
+`503 keys_bucket_missing` and nothing is stored, instead of storing the file unencrypted. Keep it a separate
+bucket, never public, and [back it up](#backing-up-keys_bucket): losing a key loses its file for good.
+
+#### 3. Create the KV namespace
+
+```bash
+wrangler kv namespace create media-state
+```
+
+It prints a config snippet with the new namespace's `id`. Paste that id into the `MEDIA_KV` binding of
+`wrangler.toml`. Running `create` again doesn't give you the id of a namespace that already exists: find it with
+`wrangler kv namespace list`, which prints every namespace of the account with its `title` and `id`.
+
+#### 4. Write `wrangler.toml`
+
+Bind both buckets, the KV namespace and the `DownloadLink` Durable Object:
+
+```toml
+name = "media"
+main = "src/index.ts"
+compatibility_date = "2026-10-01"
+account_id = "<your-account-id>"
+
+[[r2_buckets]]
+binding = "MEDIA_BUCKET"
+bucket_name = "media"
+
+# Per-object key material for encryption at rest. Required when `security.encrypt` is on.
+[[r2_buckets]]
+binding = "KEYS_BUCKET"
+bucket_name = "media-keys"
+
+[[kv_namespaces]]
+binding = "MEDIA_KV"
+id = "<kv-namespace-id>"
+
+[[durable_objects.bindings]]
+name = "DOWNLOAD_LINKS"
+class_name = "DownloadLink"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["DownloadLink"]
+```
+
+Without the `DOWNLOAD_LINKS` binding, `POST /v1/token/download` answers `501`. For staging and production in one
+file, see [Per-environment config](#per-environment-config).
+
+#### 5. Set the secrets
+
+The Worker requires all three secrets, even if you never transcode a video. Without them it fails closed: it doesn't
+fall back to open access.
+
+```bash
+wrangler secret put DELIVERY_SIGN_SECRET        # openssl rand -base64 32
+wrangler secret put WORKER_AUTH_SECRET          # openssl rand -base64 32
+wrangler secret put TRANSCODE_WEBHOOK_SECRET    # openssl rand -base64 32
+```
+
+- **`DELIVERY_SIGN_SECRET`** signs viewer tokens, download links and transcode job tickets. Without it,
+  issuing or verifying them fails with `500`.
+- **`WORKER_AUTH_SECRET`** is your backend's credential. Every control route requires
+  `Authorization: Bearer <WORKER_AUTH_SECRET>`. Without the secret, those routes answer
+  `503 worker_auth_secret_missing`. With a missing or wrong bearer, they answer `401`. The transcode
+  runner also uploads its renditions with this secret, and a job's `callbackUrl` receives it as its bearer (the
+  Convex component checks it against `DEVULTUR_SECRET`).
+- **`TRANSCODE_WEBHOOK_SECRET`** signs the transcode callbacks (see [Transcode runners](#transcode-runners)).
+  Without it, the Worker answers `503` to every callback, so no transcode ever completes: the first video upload
+  would stay in progress for good. Set it even if you don't plan to transcode.
+
+For captions, also set `GROQ_API_KEY` (transcription) and `MISTRAL_API_KEY` (translation) as secrets. Secrets are
+per environment: with [environments](#per-environment-config), add `--env <name>` to each `wrangler secret put`.
+
+#### 6. Deploy
+
+```bash
+wrangler deploy                    # with environments: wrangler deploy --env production
+```
+
+#### 7. Verify
+
+```bash
+curl https://media.example.com/health
+curl https://media.example.com/v1/assets -H "Authorization: Bearer $WORKER_AUTH_SECRET"
+```
+
+`/health` is open. `GET /v1/assets` takes the Worker secret: it answers `401` with a wrong bearer, and
+`503 worker_auth_secret_missing` if the secret didn't reach this environment. Then upload one file from your backend
+and fetch it back.
+
+### Per-environment config
+
+Under `[env.<name>]`, Wrangler doesn't inherit `r2_buckets`, `kv_namespaces` or `durable_objects` from the top
+level: repeat every binding in every environment, `KEYS_BUCKET` included. `migrations` stays top-level. Give each
+environment its own buckets, KV namespace and secrets:
+
+```toml
+name = "media"
+main = "src/index.ts"
+compatibility_date = "2026-10-01"
+account_id = "<your-account-id>"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["DownloadLink"]
+
+# Staging
+[env.staging]
+name = "media-staging"
+
+[[env.staging.r2_buckets]]
+binding = "MEDIA_BUCKET"
+bucket_name = "media-staging"
+
+[[env.staging.r2_buckets]]
+binding = "KEYS_BUCKET"
+bucket_name = "media-keys-staging"
+
+[[env.staging.kv_namespaces]]
+binding = "MEDIA_KV"
+id = "<staging-kv-namespace-id>"
+
+[[env.staging.durable_objects.bindings]]
+name = "DOWNLOAD_LINKS"
+class_name = "DownloadLink"
+
+# Production
+[env.production]
+name = "media-production"
+
+[[env.production.r2_buckets]]
+binding = "MEDIA_BUCKET"
+bucket_name = "media-production"
+
+[[env.production.r2_buckets]]
+binding = "KEYS_BUCKET"
+bucket_name = "media-keys-production"
+
+[[env.production.kv_namespaces]]
+binding = "MEDIA_KV"
+id = "<production-kv-namespace-id>"
+
+[[env.production.durable_objects.bindings]]
+name = "DOWNLOAD_LINKS"
+class_name = "DownloadLink"
+```
+
+`vars` aren't inherited either: repeat `[env.<name>.vars]` (for example `TRANSCODE_RUNNER`) in each one. Then set
+the secrets and deploy per environment:
+
+```bash
+wrangler secret put WORKER_AUTH_SECRET --env staging
+wrangler deploy --env staging
+```
+
+[Wrangler environments](https://developers.cloudflare.com/workers/wrangler/environments/) lists what is and isn't
+inherited.
+
+### Backing up `KEYS_BUCKET`
+
+R2 has no built-in backup, and losing a key loses its file for good: the encrypted bytes in `MEDIA_BUCKET` can't be
+read without it. Copy `KEYS_BUCKET` to a bucket of its own, ideally in another account or with another provider:
+
+- **A cron Worker** bound to `KEYS_BUCKET` and the backup bucket, which lists the keys bucket and copies each object
+  the backup doesn't have yet. A key is written once and never changes, so copying the new ones is enough. Copy each
+  object's `customMetadata` along with its body.
+- **rclone** with [R2's S3 API](https://developers.cloudflare.com/r2/examples/rclone/), from a machine or a CI job on
+  a schedule.
+
+Each key lives at `{storageKey}/{keyId}`: the full storage key of its file plus a random id. To restore, copy the
+objects back to the same keys, with their metadata. The Worker finds a file's key by that path, so a key restored
+under another path is as good as lost. Give the backup the same access rules as the keys bucket: whoever holds both
+the keys and the media can read your encrypted files.
+
+### R2 bucket lock (defense in depth)
+
+[Retention and holds](object-lock.md) are enforced by the Worker. An
+[R2 bucket lock rule](https://developers.cloudflare.com/r2/buckets/bucket-locks/) adds a storage-level layer: R2
+itself refuses overwrites and deletes of matching objects, also from the dashboard, `wrangler r2` or the S3 API.
+Lock the same prefix in both buckets, so a file and its key are kept together:
+
+```bash
+# {root} is the Worker's storage prefix ("" if you don't set one)
+wrangler r2 bucket lock add media records-retention "{root}private/asset/records/" --retention-days 3650
+wrangler r2 bucket lock add media-keys records-retention "{root}private/asset/records/" --retention-days 3650
+```
+
+An asset is stored at `{root}{visibility}/asset/{path}` in `MEDIA_BUCKET`, and its key at
+`{root}{visibility}/asset/{path}/{keyId}` in `KEYS_BUCKET`, so one prefix covers both. Use `--retention-days`,
+`--retention-date` or `--retention-indefinite` to match the longest retention you set through the Worker.
+
+> [!WARNING]
+> Never lock `__lock/` or `__lock-audit/`, or a prefix that contains them, such as `""` or `{root}` alone. The Worker
+> rewrites those records on every lock change, and a bucket lock on them makes lock changes and holds fail.
+
+What changes once the rule is on:
+
+- Nothing under the prefix can be deleted or replaced until its R2 retention ends, whatever the Worker's own lock
+  says. That includes image variants (`{key}/__variants/…`) and the cleanup of `maxFileLifetimeSeconds`.
+- **Racing duplicate uploads.** When two create-only uploads race for the same asset path, the loser deletes the
+  key it made for its failed write. Under the lock R2 refuses that delete, so the loser gets a `500` instead of
+  `409 already_exists`. Retry it: the retry sees the existing file and answers `409 already_exists`.
+- **Don't trust `wrangler r2 object delete` to test the rule.** On a locked object it prints "Delete complete." and
+  exits `0`, but the object stays. Check for the object afterwards instead:
+
+  ```bash
+  wrangler r2 object delete "media/private/asset/records/test.pdf" --remote
+  wrangler r2 object get "media/private/asset/records/test.pdf" --remote --file check.pdf  # still there
+  ```
+
+Anyone who can edit the bucket's configuration can still remove the rule, so it raises the bar rather than closing
+it.
+
+### Calling the Worker
+
+Your backend calls the Worker with the server SDK. Pass the Worker URL as `baseUrl` and the
+secret as `secret`. Never ship the secret to the browser.
+
+```typescript
+import { createMediaRouter } from "@devultur/server";
+
+export const media = createMediaRouter({
+  baseUrl: "https://media.example.com",
+  secret: process.env.WORKER_AUTH_SECRET!,
+});
+```
+
+| Route | Access |
+| --- | --- |
+| `POST /v1/upload` | Worker secret, or an upload token from `POST /v1/token/upload` (only inside its prefix) |
+| `PUT`, `POST`, `DELETE /v1/upload/<key>?u=<id>` | The URL that `POST /v1/upload` returned is the credential: its random `u` id names the upload, and a missing or wrong id gets `404`. Without that URL, only the Worker secret can write. |
+| `DELETE /v1/media/…`, `GET /v1/assets` | Worker secret |
+| `/v1/transcode`, `/v1/captions` | Worker secret |
+| `POST /v1/token`, `/v1/token/upload`, `/v1/token/download` | Worker secret |
+| `GET`/`PUT /v1/lock/<key>`, `POST /v1/lock/hold` | Worker secret ([Retention and holds](object-lock.md)) |
+| `GET`/`HEAD /v1/media/…` | Public media is open. Private media needs a viewer token from `POST /v1/token`, or the Worker secret. |
+| `GET /v1/download/<id>` | The link id is the credential (single use) |
+| `POST /v1/webhooks/transcode` | `TRANSCODE_WEBHOOK_SECRET` |
+| `GET /health`, `POST /v1/metrics/playback` | Open |
+
+The browser never talks to a control route. It uploads to the URL your backend got from
+`POST /v1/upload`, and plays private media with a viewer token your backend issued.
+
+> [!WARNING]
+> The Worker secret check is the `workerSecretAuth()` plugin. To authenticate with your own credentials, replace it
+> with an auth plugin of yours (see [Plugins](plugins.md)): `createWorker()` refuses to start without one.
+
+## Rules
+
+`createWorker()` runs the [default plugins](plugins.md#default-plugins). Pass the rules every request follows to
+`defaultPlugins(config)`:
+
+```typescript
+import { createWorker, defaultPlugins } from "@devultur/self-host";
+
+export default createWorker({
+  plugins: defaultPlugins({
+    security: { sessionBinding: true, ipBinding: false, encrypt: true }, // encrypt needs KEYS_BUCKET
+    uploadRules: { image: { maxSizeBytes: 10_000_000, accept: ["image/*"] } },
+    captionsLocales: ["en", "es"],
+    transcode: { maxResolution: "1080p", deleteOriginalOnSuccess: true },
+  }),
+});
+```
+
+| `config` field | What it does |
+| --- | --- |
+| `security` | Default security policy: session and IP binding, encryption at rest |
+| `uploadRules` | Per media type (`video`, `image`, `file`): `maxSizeBytes`, `accept` and default `visibility` |
+| `captionsLocales` | Locales `/v1/captions` accepts (unset: any) |
+| `cacheRules` | `Cache-Control` per prefix of the `asset/` namespace |
+| `originalStorageClass` | R2 storage class of an uploaded video original (`Standard` or `InfrequentAccess`) |
+| `maxFileLifetimeSeconds` | Longest lifetime of an uploaded file, in seconds: the default TTL and a ceiling (a shorter `expiresIn` still wins). For a demo or scratch Worker whose uploads clean themselves up. A [locked](object-lock.md#retention-vs-expiry) file still expires (viewers get `410`) but isn't deleted until its lock ends. |
+| `uploadMetadata` | String map added to the R2 `customMetadata` of every uploaded object (for example which app uploaded it). Keys the Worker owns (`security`, `enc`, `expiresAt`, `derivedFrom`, `lock`, `sha256*`) are dropped. |
+| `lock` | Default lock of an uploaded file: retention and hold (see [Retention and holds](object-lock.md)). An upload or its upload token overrides it. |
+| `contentSniffing` | What an upload whose bytes contradict its declared type gets: `scriptable` (default: `415 content_type_mismatch` only for markup such as HTML or SVG under an inert type), `reject` (every mismatch), `octet-stream` or `off`. Every mismatch is logged as `[content-sniff] {…}`. See [Content verification](https://github.com/devultur/devultur/blob/main/docs/guides/security.md#content-verification). |
+| `transcode.presets` | Named presets and the default one, used when a request names no preset |
+| `transcode.maxResolution` | Highest rung of the HLS ladder (`720p`, `1080p`, `4k`) |
+| `transcode.deleteOriginalOnSuccess` | Delete the original once a transcode completes. It's never deleted after a failure, nor while it's [locked](object-lock.md#transcoding-a-locked-video). |
+| `transcode.outputBaseUrl` | Base of the output URLs in your webhook. Unset: the origin of the transcode request. |
+
+A plugin can narrow these rules per request, for example to give each of your apps its own storage prefix,
+upload rules and credentials. [Plugins](plugins.md) covers the request state, the hooks before a credential is
+issued or a download link is redeemed, and three example plugins: JWT auth, a usage log and rate limiting.
+
+## Transcode runners
+
+The self-host media Worker doesn't run FFmpeg itself. It generates a shell script for each
+video and hands it to a **runner**. The runner starts that script inside the transcode image
+(`infra/transcode/Dockerfile`, Alpine + FFmpeg + curl). The script downloads the raw video from
+your Worker, encodes the HLS ladder, uploads the renditions back, and reports progress through
+signed webhooks to `/v1/webhooks/transcode`. Every runner uses the same script, and job status
+always comes from those webhooks, never from the provider.
+
+Pick the runner with the `TRANSCODE_RUNNER` var:
+
+| Runner | `TRANSCODE_RUNNER` | Best for | Needs |
+| --- | --- | --- | --- |
+| Cloudflare Containers | `cloudflare` (default when unset) | **Recommended.** Same deploy and account as the Worker | Workers Paid plan, Docker where you run `wrangler deploy` |
+| Fly Machines | `fly` | An existing Fly setup | A Fly app, an API token, a pushed image |
+| HTTP | `http` | A VPS or your own queue | A host running the reference runner behind HTTPS |
+
+Set `TRANSCODE_WEBHOOK_SECRET` ([step 5](#5-set-the-secrets)) whatever runner you pick. The
+script sends it on every callback, and the Worker rejects callbacks that don't carry it. If the
+secret is unset, the Worker answers `503` to every callback.
+
+### Cloudflare Containers (recommended)
+
+Each video gets its own Durable Object, and that Durable Object starts one container with
+the transcode image. Wrangler builds and pushes the image on `wrangler deploy`.
+
+1. Re-export the container class from your Worker entry:
+
+   ```typescript
+   import { createWorker } from "@devultur/self-host";
+   export { TranscodeContainer } from "@devultur/self-host/transcode-container";
+
+   export default createWorker();
+   ```
+
+2. Add the container, the binding and the var to `wrangler.toml` (full snippet in
+   `infra/transcode/wrangler.containers.example.toml`):
+
+   ```toml
+   [vars]
+   TRANSCODE_RUNNER = "cloudflare"
+   # CF_TRANSCODE_INSTANCE = "standard-4"   # default: 4 vCPU, 12 GiB, 20 GB disk
+
+   [[containers]]
+   class_name = "TranscodeContainer"
+   scheduling_policy = "durable_object"
+
+   [containers.images.transcode]
+   dockerfile = "../../infra/transcode/Dockerfile"
+
+   [[durable_objects.bindings]]
+   name = "TRANSCODE_CONTAINER"
+   class_name = "TranscodeContainer"
+
+   [exports.TranscodeContainer]
+   type = "durable-object"
+   storage = "sqlite"
+   ```
+
+3. Run `wrangler deploy` with a recent Wrangler (4.150 accepts `scheduling_policy = "durable_object"`, `images` and `exports`; 4.103 rejects them).
+
+> [!WARNING]
+> The instance disk has to hold the raw upload plus every rendition. On `standard-4` that's
+> 20 GB, so a very long 4K source may not fit. If a container dies without running the
+> script's failure trap (out of memory, host restart), its Durable Object reports
+> `transcode.failed` for it.
+
+### Fly Machines
+
+Each job runs on a fresh Fly Machine that destroys itself when the job ends. Creating a
+machine is retried on 429/5xx with exponential backoff, because the Machines API allows 1
+create per second.
+
+```bash
+fly apps create my-transcode
+cd infra/transcode && fly deploy --ha=false   # note the image tag it prints
+wrangler secret put FLY_API_TOKEN
+```
+
+| Var | Default | |
+| --- | --- | --- |
+| `FLY_APP_NAME` | — | Fly app that runs the machines |
+| `FLY_TRANSCODE_IMAGE` | — | `registry.fly.io/<app>:<tag>` |
+| `FLY_API_TOKEN` | — | Secret |
+| `FLY_TRANSCODE_CPU_KIND` | `performance` | Avoid `shared`: FFmpeg gets throttled to its 6.25% CPU baseline |
+| `FLY_TRANSCODE_CPUS` | `4` | |
+| `FLY_TRANSCODE_MEMORY_MB` | `8192` | |
+| `FLY_REGION` | — | Region of the machines (`iad`, `fra`, …). Unset: Fly picks one. |
+
+### HTTP (VPS or your own queue)
+
+The Worker POSTs each job to `TRANSCODE_RUNNER_URL` with `Authorization: Bearer <TRANSCODE_RUNNER_SECRET>`:
+
+```json
+{
+  "version": 1,
+  "videoId": "abc123",
+  "command": ["sh", "-c", "echo \"$TRANSCODE_SCRIPT_B64\" | base64 -d | sh"],
+  "env": { "TRANSCODE_SCRIPT_B64": "…", "WORKER_URL": "…", "CALLBACK_URL": "…" }
+}
+```
+
+Your runner runs `command` with `env` in the transcode image and answers `2xx`, optionally
+with `{ "jobId": "…" }`. The Worker retries 429/5xx responses with backoff. The reference
+runner `infra/transcode/http-runner/server.ts` (Node 22.18+, no dependencies) queues jobs
+and runs each one with `docker run`:
+
+```bash
+docker build -t devultur-ffmpeg infra/transcode
+RUNNER_SECRET=$(openssl rand -base64 32) MAX_CONCURRENT_JOBS=2 \
+  node infra/transcode/http-runner/server.ts
+```
+
+Then set `TRANSCODE_RUNNER = "http"` and `TRANSCODE_RUNNER_URL = "https://runner.example.com/jobs"`
+on the Worker, plus `wrangler secret put TRANSCODE_RUNNER_SECRET`. Optionally set
+`TRANSCODE_RUNNER_CPUS` to the cores per job, which feeds the encode measurement.
+
+> [!CAUTION]
+> The job `env` carries the runner's upload credential and the callback secret. Only expose the
+> runner over HTTPS, for example behind Caddy or a Cloudflare Tunnel.
+
+### Measuring encode cost
+
+Every `transcode.complete` the runner sends carries an `encode` measurement, for you as the operator: `seconds`
+(FFmpeg wall-clock time), `cpus`, `runner` and `topRung` (the highest rendition), plus the per-title `complexity`,
+`probeSeconds` and `params`. The Worker logs it as `[transcode-metrics] {…"vcpuSecondsPerVideoMinute":…}` (vCPU
+seconds per minute of video, to size and compare runners), and a plugin can read it with `parseEncodeMetrics`.
+Your app's webhook doesn't get it.
+
+For presets, templates and inline specs, each entry of `renditions` in the webhook carries the output's real
+`width` and `height` in pixels (an HLS ladder by its top rung), measured on the encoded file.
+
+## Image transforms
+
+Image transforms (`?w=`, `?h=`, `?fit=`, `?format=`, `?q=`) run inside the media Worker with WebAssembly
+codecs. Each unique transform is computed once and stored in your bucket next to the original
+(`{key}/__variants/…`), so later requests are served like any other object, with `Range` support and
+the edge cache.
+
+- **Large originals.** The Worker decodes images up to 4 megapixels (`IMAGE_TRANSFORMS_MAX_MEGAPIXELS`).
+  For a larger original, the first transform asks Cloudflare Images for one downscaled master and stores
+  it next to the original. Every later variant is built from that master in the Worker.
+- **Cloudflare Images fallback.** GIFs, animated images, sizes that need more pixels than the master
+  has, and any codec failure go to Cloudflare Images for that request. Image Transformations must be
+  enabled on the zone that serves the Worker.
+- **`fit=fill`** stretches to the exact `w`×`h`, ignoring the aspect ratio.
+- **`format=auto`** is negotiated from the `Accept` header: AVIF for outputs up to about 1 megapixel, then
+  WebP, then JPEG (PNG for PNG originals). Responses carry `Vary: Accept`.
+- **Private and encrypted images.** Variants of a private image stay private. If the original is
+  encrypted at rest, its variants are encrypted too, each with its own key.
+- **Deleting** an original also deletes its variants and their keys.
+
+Set `IMAGE_TRANSFORMS = "cloudflare"` to send every transform to Cloudflare Images instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/self-host",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Self-hosted media Worker for Cloudflare: R2 uploads, edge-cached delivery, image transforms, HLS transcode and captions",
   "keywords": [
     "cloudflare-workers",
@@ -37,7 +37,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "dependencies": {
     "@jsquash/avif": "2.1.1",
@@ -46,7 +47,7 @@
     "@jsquash/resize": "2.1.1",
     "@jsquash/webp": "1.5.0",
     "hono": "^4.7.0",
-    "@devultur/core": "1.5.0"
+    "@devultur/core": "1.5.1"
   },
   "devDependencies": {
     "@cf-wasm/photon": "0.4.0",
@@ -60,7 +61,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/transcode/container.ts --format esm --dts --external cloudflare:workers --external '*.wasm' --clean",
+    "build": "tsup src/index.ts src/transcode/container.ts --format esm --dts --external cloudflare:workers --external '*.wasm' --clean && node ../../scripts/copy-guides.mts",
     "typecheck": "tsc --noEmit"
   }
 }