@devultur/self-host 1.0.3 → 1.1.0

package/README.md

@@ -30,6 +30,10 @@ compatibility_date = "2026-10-01"
 binding = "MEDIA_BUCKET"
 bucket_name = "my-media"
 
+[[r2_buckets]]
+binding = "KEYS_BUCKET" # per-object encryption keys: required when security.encrypt is on
+bucket_name = "my-media-keys"
+
 [[kv_namespaces]]
 binding = "MEDIA_KV" # pending uploads and transcode job state
 id = "<your KV namespace id>"
@@ -44,13 +48,16 @@ new_sqlite_classes = ["DownloadLink"]
 ```
 
 ```bash
+wrangler r2 bucket create my-media
+wrangler r2 bucket create my-media-keys        # keep it private and backed up
 wrangler secret put DELIVERY_SIGN_SECRET       # signs viewer tokens and links
 wrangler secret put WORKER_AUTH_SECRET         # your backend's bearer on control routes
 wrangler secret put TRANSCODE_WEBHOOK_SECRET   # signs transcode callbacks
 wrangler deploy
 ```
 
-Without its secrets the Worker fails closed: control routes answer `503`. Call it from your backend with
+Without its secrets the Worker fails closed: control routes answer `503`. With encryption at rest on and no
+`KEYS_BUCKET`, private writes answer `503 keys_bucket_missing` instead of storing plaintext. Call it from your backend with
 [`@devultur/server`](https://www.npmjs.com/package/@devultur/server). The Worker is built from plugins:
 `createWorker({ plugins })` takes your rules, your own auth, hooks before a credential is issued, and routes and
 middleware of your own.
@@ -61,6 +68,8 @@ middleware of your own.
   [github.com/devultur/devultur/blob/main/docs/guides/self-host.md](https://github.com/devultur/devultur/blob/main/docs/guides/self-host.md).
 - Plugins (auth, request state, hooks, example plugins):
   [github.com/devultur/devultur/blob/main/docs/guides/plugins.md](https://github.com/devultur/devultur/blob/main/docs/guides/plugins.md).
+- 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).
 
 ## License
 

package/dist/{chunk-VF4KBW3I.js → chunk-PQO3X57I.js}

@@ -187,9 +187,9 @@ async function encryptForStorage(keysBucket, objectStorageKey, body, keyMetadata
   const { cryptoKey, iv, enc } = await createObjectEncryption(keysBucket, objectStorageKey, keyMetadata);
   return { body: await encryptBytes(body, cryptoKey, iv), enc };
 }
-function shouldEncryptAtRest(policy, key, hasKeysBucket) {
+function shouldEncryptAtRest(policy, key) {
   const isHlsAsset = key.endsWith(".ts") || key.endsWith(".m3u8");
-  return Boolean(policy.encrypt) && visibilityFromKey(key) === "private" && !isHlsAsset && hasKeysBucket;
+  return Boolean(policy.encrypt) && visibilityFromKey(key) === "private" && !isHlsAsset;
 }
 async function loadStorageKey(keysBucket, objectStorageKey, keyId) {
   if (!keysBucket) return null;
@@ -262,7 +262,8 @@ async function signJobTicket(secret, job, nowMs = Date.now()) {
       jti: runId,
       iat: issuedAt,
       exp: issuedAt + JOB_TICKET_TTL_SECONDS,
-      ...job.context ? { context: job.context } : {}
+      ...job.context ? { context: job.context } : {},
+      ...job.location ? { loc: { root: job.location.root, folder: job.location.folder } } : {}
     },
     ticketKey(secret)
   );
@@ -279,6 +280,12 @@ async function verifyJobTicket(secret, ticket, videoId) {
     ...isRecord(claims.context) ? { context: claims.context } : {}
   };
 }
+async function verifyJobLocation(secret, ticket, videoId) {
+  const claims = await verifyViewerToken(ticket, ticketKey(secret));
+  if (claims?.typ !== JOB_TICKET_TYPE || claims.sub !== videoId || !isRecord(claims.loc)) return null;
+  const { root, folder } = claims.loc;
+  return typeof root === "string" && typeof folder === "string" ? { root, folder } : null;
+}
 
 // src/transcode/runner.ts
 var TranscodeRunnerName = {
@@ -446,6 +453,7 @@ export {
   JOB_TICKET_HEADER,
   signJobTicket,
   verifyJobTicket,
+  verifyJobLocation,
   TranscodeRunnerName,
   RUN_SCRIPT_COMMAND,
   TranscodeLaunchErrorCode,

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as hono_types from 'hono/types';
 import { Context, MiddlewareHandler, Hono } from 'hono';
-import { Visibility, SecurityPolicy, CacheRule, TranscodeSettings, TranscodeOutputKeys, TranscodeOutputUrls } from '@devultur/core';
+import { Visibility, ObjectLock, SecurityPolicy, CacheRule, TranscodeSettings, TranscodeOutputKeys, TranscodeOutputUrls } from '@devultur/core';
 import { T as TranscodeContainerNamespace } from './cloudflare-kZ7J3LQ2.js';
 
-/** What an upload token allows (claims `res`, `visibility`, `max_bytes`, `max_files`, `file_ttl`). */
+/** What an upload token allows (claims `res`, `visibility`, `max_bytes`, `max_files`, `file_ttl`, `lock`). */
 interface UploadGrant {
     /** Token's `jti`: best-effort counter for `maxFiles`. */
     tokenId: string;
@@ -14,6 +14,8 @@ interface UploadGrant {
     maxFiles?: number;
     /** TTL (seconds) of each file uploaded with the token. */
     fileExpiresIn?: number;
+    /** Lock every file uploaded with the token gets at least (a request can make it stricter, never looser). */
+    lock?: ObjectLock;
 }
 
 /** A download link as the Worker hands it to plugins. */
@@ -40,6 +42,8 @@ interface RouteResult {
     redeemedLink?: DownloadLinkInfo;
     /** `transcode.complete` deleted the video's original (`config.transcode.deleteOriginalOnSuccess`). */
     originalDeleted?: boolean;
+    /** `transcode.complete` was asked to delete the original but kept it: it's locked (retention or hold). */
+    originalRetained?: boolean;
     /** The transcode callback carried a valid job ticket: the job it belongs to. */
     transcodeJob?: TranscodeJob;
 }
@@ -154,9 +158,14 @@ interface WorkerConfig {
     /**
      * R2 custom metadata added to every object the request uploads (also on the later credential-less PUT), for example
      * which app or user uploaded it. Keys the Worker owns (integrity `sha256*`, `expiresAt`, `security`, `enc`,
-     * `derivedFrom`) are dropped from it.
+     * `derivedFrom`, `lock`) are dropped from it.
      */
     uploadMetadata?: Record<string, string>;
+    /**
+     * Default lock of an uploaded file: retention (`governance` or `compliance`, until a date or for a period) and hold.
+     * The upload request (or its upload token) overrides it. Unset: files aren't locked.
+     */
+    lock?: ObjectLock;
     transcode?: TranscodeConfig;
 }
 /** What an auth plugin established about the request's credential. */
@@ -209,6 +218,26 @@ declare function isAuthenticated(context: AnyContext$2): boolean;
  */
 declare function updateRequestState(context: AnyContext$2, patch: RequestStatePatch): RequestState;
 
+declare const LOCK_AUDIT_PREFIX = "__lock-audit/";
+type LockAuditAction = "set" | "extend" | "shorten" | "remove" | "hold" | "release" | "delete_rejected" | "overwrite_rejected" | "original_retained";
+interface LockAuditRecord {
+    /** ISO time of the event. */
+    at: string;
+    action: LockAuditAction;
+    /** Virtual keys the event is about. */
+    keys: string[];
+    before: ObjectLock | null;
+    after: ObjectLock | null;
+    /** The request's plugin context (who the auth layer said is calling), or null. */
+    actor: PluginContext | null;
+    /** `applied`: the change landed. `rejected`: the Worker refused it. `skipped`: a delete didn't run (retained raw). */
+    outcome: "applied" | "rejected" | "skipped";
+    /** The change used the governance privilege (`bypassGovernance` approved by `authorizeLockChange`). */
+    bypass?: boolean;
+    /** Why it was rejected (a response code). */
+    reason?: string;
+}
+
 /** What is being issued: a viewer token, an upload token, a download link or the transcode runner's token. */
 type CredentialKind = "viewer" | "upload" | "download-link" | "service";
 interface CredentialRequest {
@@ -242,10 +271,39 @@ type AnyContext$1 = Context<any>;
 type IssueCredentialHook = (context: AnyContext$1, request: CredentialRequest) => CredentialDecision | Promise<CredentialDecision>;
 /** A response refuses the redemption (returned as is, and the use is NOT spent); `null` lets it go on. */
 type BeforeLinkRedeemHook = (context: AnyContext$1, link: DownloadLinkInfo) => Response | null | Promise<Response | null>;
+/**
+ * What a lock change does: `set` a first (or expired) retention, `extend` it, `shorten` or `remove` it; `hold` or
+ * `release` a hold.
+ */
+type LockChangeAction = "set" | "extend" | "shorten" | "remove" | "hold" | "release";
+interface LockChangeRequest {
+    action: LockChangeAction;
+    /** The virtual keys it changes (for a bulk hold by prefix: this page of them). */
+    keys: string[];
+    /** A bulk hold by prefix: the prefix the request named. */
+    prefix?: string;
+    before: ObjectLock | null;
+    after: ObjectLock | null;
+}
+type LockChangeDecision = {
+    allow: false;
+    response: Response;
+} | {
+    allow: true;
+};
+/**
+ * Before the Worker changes a lock. Refuse with a response, or allow. Approving a governance `shorten`/`remove` asked
+ * with `bypassGovernance` takes at least one of these hooks, and all of them must allow it (decision 4 of #3).
+ */
+type AuthorizeLockChangeHook = (context: AnyContext$1, request: LockChangeRequest) => LockChangeDecision | Promise<LockChangeDecision>;
+/** After a lock event (change, rejected delete or overwrite, retained original), to store the record elsewhere. */
+type OnLockAuditHook = (context: AnyContext$1, record: LockAuditRecord) => void | Promise<void>;
 /** The hooks of every plugin, in plugin order. */
 interface PluginHooks {
     issueCredential: IssueCredentialHook[];
     beforeLinkRedeem: BeforeLinkRedeemHook[];
+    authorizeLockChange: AuthorizeLockChangeHook[];
+    onLockAudit: OnLockAuditHook[];
 }
 
 type AnyMiddleware = MiddlewareHandler<any>;
@@ -276,6 +334,10 @@ interface WorkerPlugin {
     issueCredential?: IssueCredentialHook;
     /** Before `GET /v1/download/{id}` spends a use of a link that still has one. */
     beforeLinkRedeem?: BeforeLinkRedeemHook;
+    /** Before `PUT /v1/lock` changes a lock: refuse it, or approve a governance bypass. */
+    authorizeLockChange?: AuthorizeLockChangeHook;
+    /** After every lock event, with its audit record. Runs after the response. */
+    onLockAudit?: OnLockAuditHook;
 }
 interface ComposedPlugins {
     middleware: AnyMiddleware[];
@@ -339,6 +401,11 @@ declare function isServiceToken(payload: Record<string, unknown> | null | undefi
  */
 declare function verifyViewerToken(token: string | undefined, secret: string): Promise<Record<string, unknown> | null>;
 declare function hashKey(key: string): Promise<string>;
+/**
+ * Lists and batch-deletes every object under `prefix` (R2 deletes up to 1000 keys/call) and returns how many it
+ * deleted. Idempotent: empty prefix → 0. It bypasses object locks: routes delete through `guardedDeletePrefix` and
+ * `deleteKeysFor` (object-lock/guard.ts). Use this only for regenerable data (image variants) or after the guard ran.
+ */
 declare function deletePrefix(bucket: R2Bucket, prefix: string): Promise<number>;
 
 interface ImageTransformParams {
@@ -369,6 +436,45 @@ declare function readImageOriginScope(request: Request, secret: string | undefin
 /** Is this Cloudflare Images' signed subrequest? It's not delivery to the client: it isn't gated or counted. */
 declare function isImageOriginRequest(request: Request, secret: string | undefined): Promise<boolean>;
 
+declare const KEYS_BUCKET_MISSING_CODE = "keys_bucket_missing";
+declare const ENCRYPTION_KEY_MISSING_CODE = "encryption_key_missing";
+
+/** Retention expiry (ISO) of a locked object. */
+declare const LOCK_UNTIL_HEADER = "x-devultur-lock-until";
+/** `true` while a hold is set. */
+declare const LOCK_HOLD_HEADER = "x-devultur-lock-hold";
+
+/** Prefixes the Worker keeps for lock sidecars and audit records: no route reads or writes a key under them. */
+declare const RESERVED_LOCK_PREFIXES: readonly ["__lock/", "__lock-audit/"];
+
+/** Objects changed per request: a list of keys may name at most this many; a prefix is walked this many at a time. */
+declare const HOLD_PAGE_SIZE = 50;
+interface HoldSkip {
+    key: string;
+    /**
+     * `not_found`, `unchanged` (already in that state), `lock_conflict` (changed concurrently: retry it) or
+     * `lock_record_unreadable` (a release of a lock record that can't be read: an operator must repair it).
+     */
+    reason: "not_found" | "unchanged" | "lock_conflict" | "lock_record_unreadable";
+}
+
+/** `customMetadata` key holding the lock set at upload (JSON `{ retention?, hold }`). Owned by the Worker. */
+declare const LOCK_METADATA_KEY = "lock";
+
+declare const LOCK_SIDECAR_PREFIX = "__lock/";
+interface LockSidecar {
+    /** Increases by one on every change. */
+    revision: number;
+    /** The object version this lock applies to (see `objectVersionOf`). */
+    objectVersion: string;
+    lock: ObjectLock;
+    /** ISO time the hold was released (a `period` then counts from here). */
+    holdReleasedAt?: string;
+    /** ISO time of the last change. */
+    updatedAt: string;
+}
+type LockSource = "sidecar" | "upload" | "none";
+
 interface CredentialPolicyOptions {
     /** Longest lifetime, in seconds, per kind of credential. A longer request is shortened to it, not refused. */
     maxTtlSeconds?: Partial<Record<CredentialKind, number>>;
@@ -407,6 +513,11 @@ declare function workerSecretAuth(): WorkerPlugin;
 declare function defaultPlugins(config?: WorkerConfig): WorkerPlugin[];
 
 declare const MAX_ASSET_LIST_LIMIT = 1000;
+/**
+ * Lock-record reads per page (one subrequest each, plus the listing's own): well under the Workers subrequest limit
+ * on any plan, whatever share of the page has expired.
+ */
+declare const MAX_EXPIRED_LOOKUPS = 32;
 interface AssetListEntry {
     key: string;
     path: string;
@@ -417,17 +528,23 @@ interface AssetListEntry {
     uploaded: string;
     cacheControl: string | null;
     visibility: Visibility;
+    /** Past its `expiresAt` but still retained: listed (the owner can still read it), and not deleted. */
+    expired?: true;
+    /** The retention that keeps an expired entry (its effective expiry), when it has a date. */
+    retainedUntil?: string;
+    /** An expired entry kept by a hold. */
+    hold?: true;
 }
 
+/** Has the object expired (TTL)? From then on we respond 410 even if the sweeper hasn't deleted it yet. Pure. */
+declare function isObjectExpired(customMetadata: Record<string, string> | undefined, now?: number): boolean;
+
 /** The unit's tag: a hash (Cloudflare's tags are case-insensitive but paths aren't). */
 declare function edgeCacheTag(storagePrefix: string, virtualKey: string): Promise<string>;
 
 /** `Cache-Control` served: the one stored on the object (for private, no shared caches) or the one for a generated id. */
 declare function servedCacheControl(stored: string | undefined, isPrivate: boolean): string;
 
-/** Has the object expired (TTL)? From then on we respond 410 even if the sweeper hasn't deleted it yet. Pure. */
-declare function isObjectExpired(customMetadata: Record<string, string> | undefined, now?: number): boolean;
-
 declare const UPLOAD_TOKEN_TYPE = "upload";
 /** Short-lived: it's a JWT (an auth layer can also reject it if the credential that issued it is no longer valid). */
 declare const MAX_UPLOAD_TOKEN_TTL_SECONDS: number;
@@ -527,4 +644,4 @@ interface CreateWorkerOptions {
 }
 declare function createWorker(options?: CreateWorkerOptions): Hono<WorkerApp, hono_types.BlankSchema, "/">;
 
-export { type AllowedCredential, type AssetListEntry, type BeforeLinkRedeemHook, type ComposedPlugins, type CreateWorkerOptions, type CredentialDecision, type CredentialKind, type CredentialPolicyOptions, type CredentialRequest, DownloadLink, type DownloadLinkInfo, type DownloadLinkRecord, type DownloadLinkStorage, type EncodeMetrics, type ImageTransformParams, type IssueCredentialHook, type Json, MAX_ASSET_LIST_LIMIT, MAX_UPLOAD_TOKEN_TTL_SECONDS, MaxResolution, ObjectMeta, type PendingUploadInfo, type PluginContext, type PluginMiddleware, type PluginRoute, type RawStorageClass, type RequestAccess, type RequestState, type RequestStatePatch, type RouteResult, TOKEN_REJECTED_CODE, type TranscodeConfig, type TranscodeJob, UPLOAD_TOKEN_TYPE, type UploadGrant, type UploadRules, type UploadTypeRule, type WorkerApp, WorkerAuthErrorCode, type WorkerConfig, type WorkerEnv, type WorkerPlugin, type WorkerVariables, cancelPendingUpload, createWorker, credentialPolicy, defaultPlugins, deletePrefix, downloadLinks, edgeCacheTag, getPendingUpload, getRequestState, getRouteResult, hashKey, imageOriginAuthorization, isAuthenticated, isImageOriginRequest, isObjectExpired, isOpenRoute, isServiceToken, isUploadUrl, isVariantKey, logEncodeMetrics, parseEncodeMetrics, parseTransformParams, readImageOriginScope, readStoryboardKey, readTokenScopes, readTranscodeOutputKeys, readTranscodeOutputs, servedCacheControl, staticConfig, storageKey, updateRequestState, uploadGrantFromClaims, variantPrefix, vcpuSecondsPerVideoMinute, verifyViewerToken, withOutputUrls, workerSecretAuth };
+export { type AllowedCredential, type AssetListEntry, type AuthorizeLockChangeHook, type BeforeLinkRedeemHook, type ComposedPlugins, type CreateWorkerOptions, type CredentialDecision, type CredentialKind, type CredentialPolicyOptions, type CredentialRequest, DownloadLink, type DownloadLinkInfo, type DownloadLinkRecord, type DownloadLinkStorage, ENCRYPTION_KEY_MISSING_CODE, type EncodeMetrics, HOLD_PAGE_SIZE, type HoldSkip, type ImageTransformParams, type IssueCredentialHook, type Json, KEYS_BUCKET_MISSING_CODE, LOCK_AUDIT_PREFIX, LOCK_HOLD_HEADER, LOCK_METADATA_KEY, LOCK_SIDECAR_PREFIX, LOCK_UNTIL_HEADER, type LockAuditAction, type LockAuditRecord, type LockChangeAction, type LockChangeDecision, type LockChangeRequest, type LockSidecar, type LockSource, MAX_ASSET_LIST_LIMIT, MAX_EXPIRED_LOOKUPS, MAX_UPLOAD_TOKEN_TTL_SECONDS, MaxResolution, ObjectMeta, type OnLockAuditHook, type PendingUploadInfo, type PluginContext, type PluginMiddleware, type PluginRoute, RESERVED_LOCK_PREFIXES, type RawStorageClass, type RequestAccess, type RequestState, type RequestStatePatch, type RouteResult, TOKEN_REJECTED_CODE, type TranscodeConfig, type TranscodeJob, UPLOAD_TOKEN_TYPE, type UploadGrant, type UploadRules, type UploadTypeRule, type WorkerApp, WorkerAuthErrorCode, type WorkerConfig, type WorkerEnv, type WorkerPlugin, type WorkerVariables, cancelPendingUpload, createWorker, credentialPolicy, defaultPlugins, deletePrefix, downloadLinks, edgeCacheTag, getPendingUpload, getRequestState, getRouteResult, hashKey, imageOriginAuthorization, isAuthenticated, isImageOriginRequest, isObjectExpired, isOpenRoute, isServiceToken, isUploadUrl, isVariantKey, logEncodeMetrics, parseEncodeMetrics, parseTransformParams, readImageOriginScope, readStoryboardKey, readTokenScopes, readTranscodeOutputKeys, readTranscodeOutputs, servedCacheControl, staticConfig, storageKey, updateRequestState, uploadGrantFromClaims, variantPrefix, vcpuSecondsPerVideoMinute, verifyViewerToken, withOutputUrls, workerSecretAuth };