@devultur/core 1.0.3 → 1.2.0

package/dist/index.d.ts

@@ -30,6 +30,65 @@ declare function timingSafeEqual(received: string, expected: string): boolean;
  */
 declare function isBearerOf(authHeader: string | null | undefined, secret: string | null | undefined): boolean;
 
+/** `compliance`: nobody shortens or removes it. `governance`: a privileged call can. */
+type RetentionMode = "governance" | "compliance";
+/** `inherit`: derived files (transcode outputs, captions) are retained too. `original-only`: only the upload. */
+type RetentionDerivatives = "inherit" | "original-only";
+interface Retention {
+    mode: RetentionMode;
+    /** Fixed expiry (ISO 8601 with a time zone). Mutually exclusive with `period`. */
+    until?: string;
+    /** Seconds from upload, or from hold release when a hold was set. Mutually exclusive with `until`. */
+    period?: number;
+    /** Default `inherit`. */
+    derivatives?: RetentionDerivatives;
+}
+interface ObjectLock {
+    retention?: Retention;
+    /** Retained indefinitely while true, whatever `retention` says. */
+    hold?: boolean;
+}
+type ResolvedRetention = Retention & {
+    derivatives: RetentionDerivatives;
+};
+interface ResolvedLock {
+    retention?: ResolvedRetention;
+    hold: boolean;
+}
+type LockValidation = {
+    ok: true;
+    lock: ObjectLock;
+} | {
+    ok: false;
+    errors: string[];
+};
+type LockResolution = {
+    ok: true;
+    lock: ResolvedLock;
+} | {
+    ok: false;
+    errors: string[];
+};
+declare const RETENTION_MODES: readonly RetentionMode[];
+declare const RETENTION_DERIVATIVES: readonly RetentionDerivatives[];
+declare const DEFAULT_RETENTION_DERIVATIVES: RetentionDerivatives;
+/** Longest `period`: 100 years, in seconds. Beyond it an expiry can't be computed as a date. */
+declare const MAX_RETENTION_PERIOD_SECONDS: number;
+/** True for an ISO 8601 instant with a time zone (`2030-01-01T00:00:00Z`) that names a real date. */
+declare function isIsoInstant(value: unknown): value is string;
+/**
+ * Validates an untrusted lock (request body, upload token, config). A past `until` is valid: it is
+ * simply not locked any more, so an app default with a fixed date never breaks once it passes.
+ */
+declare function validateLock(input: unknown, path?: string): LockValidation;
+/**
+ * Resolves the effective lock: resource override → app default → off. `hold` resolves on its own.
+ * `retention` resolves as a whole (its mode and expiry come from the same level, so `until` and
+ * `period` never mix), except `derivatives`, which falls back to the app default and then `inherit`.
+ * A resource can't drop an app default retention; it can only replace it.
+ */
+declare function resolveLock(resource?: ObjectLock, appDefault?: ObjectLock): LockResolution;
+
 interface MediaUrlOptions {
     /** Viewer token for authorized media. Added as `?token=`. */
     token?: string;
@@ -100,6 +159,11 @@ interface DevulturMedia<V extends Visibility = Visibility> {
     readonly visibility: V;
     /** Original upload name (display / download). */
     readonly filename?: string;
+    /**
+     * Key of the uploaded object (`{visibility}/{kind}/{id}/…`; a video's raw file), as the upload returned it. Optional
+     * and informational: delivery paths are still derived from the other fields (`mediaPath`), never from it.
+     */
+    readonly key?: string;
     /** Intrinsic width (px) — enables `<img>` with no CLS. */
     readonly width?: number;
     /** Intrinsic height (px). */
@@ -144,7 +208,12 @@ declare class DevulturApiError extends Error {
     readonly status: number;
     readonly code?: string;
     readonly limit?: number;
-    constructor(message: string, status: number, code?: string, limit?: number);
+    /**
+     * The response body's fields other than `error` and `code`, e.g. `{ key, mode, until, hold }`
+     * on a `409 retention_active`. `undefined` when the body had none (or wasn't JSON).
+     */
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(message: string, status: number, code?: string, limit?: number, details?: Record<string, unknown>);
 }
 
 declare const TranscodePreset: {
@@ -277,6 +346,15 @@ interface AssetEntry {
     uploaded: string;
     cacheControl: string | null;
     visibility: Visibility;
+    /**
+     * Past its `expiresAt` but still retained by a lock: viewers get `410`, the worker's credential can still read it,
+     * and it isn't deleted until its lock ends. Absent on a live entry (expired free entries aren't listed).
+     */
+    expired?: true;
+    /** The effective expiry of the retention keeping an expired entry, when it has a date (ISO 8601). */
+    retainedUntil?: string;
+    /** An expired entry kept by a hold. */
+    hold?: true;
 }
 interface ListAssetsOptions {
     /** Prefix within `asset/` (`site/`). Empty = the whole namespace the key can reach. */
@@ -312,6 +390,8 @@ interface CreateUploadTokenOptions {
     fileExpiresIn?: number;
     /** Visibility of the token's files (default `private`). */
     visibility?: Visibility;
+    /** Minimum lock of every file uploaded with the token: an upload can make it stricter, never looser. */
+    lock?: ObjectLock;
 }
 interface UploadToken {
     token: string;
@@ -340,6 +420,10 @@ interface UploadAssetOptions {
      * config's per-prefix rule, or `public, max-age=60, stale-while-revalidate=86400`.
      */
     cacheControl?: string;
+    /** Lock of the file (retention and/or hold), written with its bytes. */
+    lock?: ObjectLock;
+    /** Shorthand for `lock.hold`. */
+    hold?: boolean;
     /** Parts in flight at once in a multipart upload (default 4). */
     concurrency?: number;
     onProgress?: (percent: number) => void;
@@ -395,10 +479,70 @@ interface FilesClient {
     delete(key: string): Promise<void>;
 }
 
+/** The lock in force on an object. */
+interface LockView {
+    key: string;
+    mode: RetentionMode | null;
+    /** Effective expiry (ISO): a fixed `until`, or a `period` from upload (or from the hold's release). */
+    until: string | null;
+    period: number | null;
+    hold: boolean;
+    derivatives: RetentionDerivatives | null;
+    /** `upload`: set when the file was uploaded. `sidecar`: changed since. `none`: not locked. */
+    source: "sidecar" | "upload" | "none";
+    /** Number of changes since upload (`null` while the upload lock is in force). */
+    revision: number | null;
+}
+/** A retention change. Fields merge over the current retention; `until` and `period` replace each other. */
+interface SetLockOptions {
+    mode?: RetentionMode;
+    until?: string;
+    period?: number;
+    derivatives?: RetentionDerivatives;
+    /** Drop the retention (governance only, with `bypassGovernance`). */
+    remove?: true;
+    /** Shorten or remove a governance retention: the worker's `authorizeLockChange` hook must approve it. */
+    bypassGovernance?: boolean;
+}
+/** What a hold request names: a list of keys (at most {@link HOLD_PAGE_SIZE} per call), or every key under a prefix. */
+type HoldTarget = string[] | {
+    prefix: string;
+};
+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 the worker can't read: an operator must repair it).
+     */
+    reason: "not_found" | "unchanged" | "lock_conflict" | "lock_record_unreadable";
+}
+interface HoldPage {
+    updated: string[];
+    skipped: HoldSkip[];
+    /** More objects under the prefix: pass it back to get the next page. */
+    cursor?: string;
+}
+/** Objects the worker changes per hold request (keys per call, and objects per prefix page). */
+declare const HOLD_PAGE_SIZE = 50;
+interface LockClient {
+    get(key: string): Promise<LockView>;
+    set(key: string, options: SetLockOptions): Promise<LockView>;
+    /** One page: up to {@link HOLD_PAGE_SIZE} keys, or one page of a prefix (`cursor` for the next). */
+    hold(target: HoldTarget, options?: {
+        cursor?: string;
+    }): Promise<HoldPage>;
+    release(target: HoldTarget, options?: {
+        cursor?: string;
+    }): Promise<HoldPage>;
+    /** Every page: a long key list in chunks, or a prefix following its cursor. */
+    holdAll(target: HoldTarget): AsyncGenerator<HoldPage>;
+    releaseAll(target: HoldTarget): AsyncGenerator<HoldPage>;
+}
+type JsonRequest$1 = <T>(path: string, init?: RequestInit) => Promise<T>;
+declare function createLockClient(request: JsonRequest$1): LockClient;
+
 interface WorkerClient {
-    uploadFile(file: File, options?: {
-        metadata?: Record<string, string>;
-    }): Promise<UploadFileResult>;
+    uploadFile(file: File, options?: UploadFileOptions): Promise<UploadFileResult>;
     createUploadUrl(options: CreateUploadUrlOptions): Promise<WorkerUploadResult>;
     getMediaUrl(media: DevulturMedia, options?: MediaUrlOptions): string;
     extractKey(url: string): string | null;
@@ -417,6 +561,11 @@ interface WorkerClient {
     files: FilesClient;
     /** Paginated listing of the `asset/` namespace. */
     assets: AssetsClient;
+    /** Object lock: retention (read, set, extend) and holds. */
+    lock: LockClient;
+}
+interface UploadFileOptions extends Pick<CreateUploadUrlOptions, "lock" | "hold"> {
+    metadata?: Record<string, string>;
 }
 interface UploadFileResult {
     key: string;
@@ -568,6 +717,10 @@ interface CreateUploadUrlOptions {
     /** Intrinsic dimensions (captured client-side for images) → carried into the reference. */
     width?: number;
     height?: number;
+    /** Lock of the new file (retention and/or hold), written with its bytes. Needs a media worker. */
+    lock?: ObjectLock;
+    /** Shorthand for `lock.hold`: retain the file indefinitely from the moment it exists. */
+    hold?: boolean;
 }
 interface UploadUrlResult {
     url: string;
@@ -888,6 +1041,45 @@ declare function sha256Hex(data: BufferSource): Promise<string>;
 /** `Repr-Digest` value (RFC 9530) for a hex sha256: `sha-256=:<base64>:`. */
 declare function reprDigest(sha256: string): string;
 
+/** A point in time: a `Date`, an ISO 8601 string or epoch milliseconds. */
+type LockInstant = Date | string | number;
+interface LockTiming {
+    /** When the object was uploaded: a `period` without a hold counts from here. */
+    uploadedAt?: LockInstant;
+    /** When the hold was released: a `period` counts from here instead when a hold was used. */
+    holdReleasedAt?: LockInstant;
+}
+type LockChangeReason = "compliance_extend_only" | "lock_privilege_required";
+/** `bypass`: the change shortened or removed a governance retention, so it used the privilege (audit it). */
+type LockChange = {
+    ok: true;
+    bypass: boolean;
+} | {
+    ok: false;
+    reason: LockChangeReason;
+};
+interface LockChangeOptions {
+    /** The caller passed the app's `authorizeLockChange` check. */
+    privileged: boolean;
+    now: LockInstant;
+    /** Needed when either side has a `period` without a hold. */
+    timing?: LockTiming;
+}
+/**
+ * The retention expiry as an ISO string. `undefined` when there is no retention, or when a period
+ * is still waiting for its hold to be released (the object stays locked by the hold meanwhile).
+ */
+declare function effectiveUntil(lock: ObjectLock, timing?: LockTiming): string | undefined;
+/** True while a hold is set or the retention hasn't expired. Delete and overwrite are rejected meanwhile. */
+declare function isLocked(lock: ObjectLock, now: LockInstant, timing?: LockTiming): boolean;
+/**
+ * Whether a lock may go from `before` to `after` (both already validated). Holds can always be set
+ * and released, and releasing one starts its period now. While a retention is active: `compliance`
+ * only extends (no earlier expiry, no switch to governance, no `original-only`); `governance` is
+ * shortened, weakened or removed only with `privileged`. An expired retention can be replaced freely.
+ */
+declare function canChange(before: ObjectLock, after: ObjectLock, options: LockChangeOptions): LockChange;
+
 declare const VIDEO_MIMES: string[];
 declare const IMAGE_MIMES: string[];
 declare const FILE_MIMES: string[];
@@ -1158,4 +1350,4 @@ declare function createHTTPWebhookHandler(options: {
     }>;
 };
 
-export { AES_BLOCK_BYTES, ASSET_NAMESPACE, type AssetEntry, type AssetListing, type AssetUploadResult, type AssetsClient, BYTES_PER_UNIT, ByteUnit, CACHE_CONTROL_PRESETS, CacheControlPreset, type CacheRule, type CapabilityUploadResult, CaptionLocale, CaptionLocaleLabel, CaptionStatus, type CaptionsJobResult, type CaptionsStatusResult, type CreateUploadTokenOptions, type CreateUploadUrlOptions, DEFAULT_ASSET_CACHE_CONTROL, DEFAULT_PRESIGN_EXPIRY_SECONDS, DEFAULT_SECURITY, DEFAULT_TOKEN_EXPIRY_SECONDS, DEFAULT_VISIBILITY, type DeleteVideoResult, type DeliveryConfig, DevulturApiError, type DevulturConfig, type DevulturKind, type DevulturMedia, type DirectStorageConfig, type DownloadLink, type DownloadLinkOptions, type DownloadUrlOptions, ENCRYPTION_ALG, ENCRYPTION_VERSION, EXPIRES_AT_HEADER, type EncryptionMeta, FILE_MIMES, type FailureReason, type FetchApi, type FileBuilderConfig, type FileHead, type FilesClient, GENERATED_PRIVATE_CACHE_CONTROL, GENERATED_PUBLIC_CACHE_CONTROL, IMAGE_MIMES, type ImageBuilderConfig, ImageFit, ImageFormat, type IssueTokenOptions, type JsonRequest, LEGACY_PRESET_SPECS, type ListAssetsOptions, MAIN_VARIANT, MAX_ASSET_PATH_DEPTH, MAX_ASSET_PATH_LENGTH, MAX_BITRATE_KBPS, MAX_CACHE_CONTROL_LENGTH, MAX_CACHE_RULES, MAX_VARIANTS, MIN_BITRATE_KBPS, MULTIPART_PART_SIZE_BYTES, MULTIPART_QUERY, MULTIPART_THRESHOLD_BYTES, type MediaEvent, MediaEventName, type MediaEventNameValue, type MediaEventType, type MediaRouter, type MediaRouterConfig, MediaStatus, type MediaStatusValue, MediaType, type MediaUrlOptions, type Mp4Output, MultipartAction, type MultipartPart, type MultipartSession, type MultipartUploadOptions, POSTER_FORMATS, type PartUploader, type PosterAt, type PosterFormat, type PosterUrls, type PresetResolution, type PresetSource, type ProcessingPhase, REPR_DIGEST_HEADER, SESSION_HEADER, SHA256_HEADER, SHA256_VERIFIED_HEADER, type ScopeCoverage, SecurityLevel, type SecurityPolicy, type SignOptions, type SpecValidation, type SpeechConnectorConfig, SpeechProvider, type StorageClient, type StorageConfig, type StorageConnectorConfig, StorageProvider, type StoredRendition, TRANSCODE_CROPS, TRANSCODE_RUNGS, TRANSCODE_TEMPLATES, type TokenResult, TokenScope, type TranscodeConnectorConfig, type TranscodeCrop, type TranscodeJobResult, type TranscodeOptions, type TranscodeOutputKeys, type TranscodeOutputUrls, type TranscodeOutputs, TranscodePreset, TranscodeProvider, type TranscodeRendition, type TranscodeRung, type TranscodeSettings, type TranscodeSpec, TranscodeStatus, type TranscodeStatusResult, TranscodeTemplate, type TranscodeVariant, type TranslationConnectorConfig, TranslationProvider, type UploadAssetOptions, type UploadFileResult, UploadRequestKind, type UploadToken, type UploadUrlResult, type UploadsClient, VIDEO_MIMES, type VideoBuilderConfig, type VideoModuleConfig, type VideoOutputRef, type Visibility, type WebhookVerifyOptions, type WorkerClient, type WorkerConfig, type WorkerTransport, type WorkerUploadResult, assetKey, assetRelativePath, buildMediaUrl, buildPosterUrls, buildStoryboardUrl, buildTranscodeOutputUrls, buildVideoMp4Url, bytesToHex, captionPath, classifyUploadRequest, computeFingerprint, contentDispositionAttachment, contentDispositionInline, counterForBlock, coversScope, createDecryptStream, createHTTPWebhookHandler, createMediaRouter, createStorageClient, createWorkerClient, createWorkerTransport, decodeEncryptionMeta, decryptChunk, edgeTtlSeconds, encodeEncryptionMeta, encryptBytes, exportEncryptionKey, extractId, extractKeyFromUrl, file, filePath, formatSize, generateEncryptionKey, generateId, generateIv, getDownloadUrl, handleWebhook, image, imagePath, importEncryptionKey, isAssetKey, isBearerOf, isPrefixWithin, isValidMime, isValidOutputName, isVideoRawKey, isWithinPathPrefix, isWorkerUploadUrl, matchCacheRule, mediaCaptionPath, mediaPath, mediaThumbnailPath, mediaUrl, missingScopes, multipartAbortUrl, multipartCompleteUrl, multipartCreateUrl, multipartPartCount, multipartPartRange, multipartPartUrl, normalizeAssetPath, normalizeAssetPrefix, normalizeCacheRules, normalizePathPrefix, normalizeSha256, parseSize, publicUrl, relativeMediaPath, reprDigest, resolveCacheControl, resolveSecurity, resolveTranscodePreset, resolveVisibility, sanitizeFilename, sha256Hex, shouldUseMultipart, signPayload, signUrl, timingSafeEqual, toPrivateCacheControl, uploadMultipart, uploadToCapabilityUrl, validateTranscodeSpec, verifySignature, verifySignedUrl, video, videoBasePath, videoHlsPath, videoHlsPlaylistPath, videoMp4Dir, videoMp4Path, videoPosterPath, videoRawPath, videoStoryboardDir, videoStoryboardPath, videoThumbnailPath, visibilityFromKey };
+export { AES_BLOCK_BYTES, ASSET_NAMESPACE, type AssetEntry, type AssetListing, type AssetUploadResult, type AssetsClient, BYTES_PER_UNIT, ByteUnit, CACHE_CONTROL_PRESETS, CacheControlPreset, type CacheRule, type CapabilityUploadResult, CaptionLocale, CaptionLocaleLabel, CaptionStatus, type CaptionsJobResult, type CaptionsStatusResult, type CreateUploadTokenOptions, type CreateUploadUrlOptions, DEFAULT_ASSET_CACHE_CONTROL, DEFAULT_PRESIGN_EXPIRY_SECONDS, DEFAULT_RETENTION_DERIVATIVES, DEFAULT_SECURITY, DEFAULT_TOKEN_EXPIRY_SECONDS, DEFAULT_VISIBILITY, type DeleteVideoResult, type DeliveryConfig, DevulturApiError, type DevulturConfig, type DevulturKind, type DevulturMedia, type DirectStorageConfig, type DownloadLink, type DownloadLinkOptions, type DownloadUrlOptions, ENCRYPTION_ALG, ENCRYPTION_VERSION, EXPIRES_AT_HEADER, type EncryptionMeta, FILE_MIMES, type FailureReason, type FetchApi, type FileBuilderConfig, type FileHead, type FilesClient, GENERATED_PRIVATE_CACHE_CONTROL, GENERATED_PUBLIC_CACHE_CONTROL, HOLD_PAGE_SIZE, type HoldPage, type HoldSkip, type HoldTarget, IMAGE_MIMES, type ImageBuilderConfig, ImageFit, ImageFormat, type IssueTokenOptions, type JsonRequest, LEGACY_PRESET_SPECS, type ListAssetsOptions, type LockChange, type LockChangeOptions, type LockChangeReason, type LockClient, type LockInstant, type LockResolution, type LockTiming, type LockValidation, type LockView, MAIN_VARIANT, MAX_ASSET_PATH_DEPTH, MAX_ASSET_PATH_LENGTH, MAX_BITRATE_KBPS, MAX_CACHE_CONTROL_LENGTH, MAX_CACHE_RULES, MAX_RETENTION_PERIOD_SECONDS, MAX_VARIANTS, MIN_BITRATE_KBPS, MULTIPART_PART_SIZE_BYTES, MULTIPART_QUERY, MULTIPART_THRESHOLD_BYTES, type MediaEvent, MediaEventName, type MediaEventNameValue, type MediaEventType, type MediaRouter, type MediaRouterConfig, MediaStatus, type MediaStatusValue, MediaType, type MediaUrlOptions, type Mp4Output, MultipartAction, type MultipartPart, type MultipartSession, type MultipartUploadOptions, type ObjectLock, POSTER_FORMATS, type PartUploader, type PosterAt, type PosterFormat, type PosterUrls, type PresetResolution, type PresetSource, type ProcessingPhase, REPR_DIGEST_HEADER, RETENTION_DERIVATIVES, RETENTION_MODES, type ResolvedLock, type ResolvedRetention, type Retention, type RetentionDerivatives, type RetentionMode, SESSION_HEADER, SHA256_HEADER, SHA256_VERIFIED_HEADER, type ScopeCoverage, SecurityLevel, type SecurityPolicy, type SetLockOptions, type SignOptions, type SpecValidation, type SpeechConnectorConfig, SpeechProvider, type StorageClient, type StorageConfig, type StorageConnectorConfig, StorageProvider, type StoredRendition, TRANSCODE_CROPS, TRANSCODE_RUNGS, TRANSCODE_TEMPLATES, type TokenResult, TokenScope, type TranscodeConnectorConfig, type TranscodeCrop, type TranscodeJobResult, type TranscodeOptions, type TranscodeOutputKeys, type TranscodeOutputUrls, type TranscodeOutputs, TranscodePreset, TranscodeProvider, type TranscodeRendition, type TranscodeRung, type TranscodeSettings, type TranscodeSpec, TranscodeStatus, type TranscodeStatusResult, TranscodeTemplate, type TranscodeVariant, type TranslationConnectorConfig, TranslationProvider, type UploadAssetOptions, type UploadFileOptions, type UploadFileResult, UploadRequestKind, type UploadToken, type UploadUrlResult, type UploadsClient, VIDEO_MIMES, type VideoBuilderConfig, type VideoModuleConfig, type VideoOutputRef, type Visibility, type WebhookVerifyOptions, type WorkerClient, type WorkerConfig, type WorkerTransport, type WorkerUploadResult, assetKey, assetRelativePath, buildMediaUrl, buildPosterUrls, buildStoryboardUrl, buildTranscodeOutputUrls, buildVideoMp4Url, bytesToHex, canChange, captionPath, classifyUploadRequest, computeFingerprint, contentDispositionAttachment, contentDispositionInline, counterForBlock, coversScope, createDecryptStream, createHTTPWebhookHandler, createLockClient, createMediaRouter, createStorageClient, createWorkerClient, createWorkerTransport, decodeEncryptionMeta, decryptChunk, edgeTtlSeconds, effectiveUntil, encodeEncryptionMeta, encryptBytes, exportEncryptionKey, extractId, extractKeyFromUrl, file, filePath, formatSize, generateEncryptionKey, generateId, generateIv, getDownloadUrl, handleWebhook, image, imagePath, importEncryptionKey, isAssetKey, isBearerOf, isIsoInstant, isLocked, isPrefixWithin, isValidMime, isValidOutputName, isVideoRawKey, isWithinPathPrefix, isWorkerUploadUrl, matchCacheRule, mediaCaptionPath, mediaPath, mediaThumbnailPath, mediaUrl, missingScopes, multipartAbortUrl, multipartCompleteUrl, multipartCreateUrl, multipartPartCount, multipartPartRange, multipartPartUrl, normalizeAssetPath, normalizeAssetPrefix, normalizeCacheRules, normalizePathPrefix, normalizeSha256, parseSize, publicUrl, relativeMediaPath, reprDigest, resolveCacheControl, resolveLock, resolveSecurity, resolveTranscodePreset, resolveVisibility, sanitizeFilename, sha256Hex, shouldUseMultipart, signPayload, signUrl, timingSafeEqual, toPrivateCacheControl, uploadMultipart, uploadToCapabilityUrl, validateLock, validateTranscodeSpec, verifySignature, verifySignedUrl, video, videoBasePath, videoHlsPath, videoHlsPlaylistPath, videoMp4Dir, videoMp4Path, videoPosterPath, videoRawPath, videoStoryboardDir, videoStoryboardPath, videoThumbnailPath, visibilityFromKey };

package/dist/index.js

@@ -445,6 +445,138 @@ function reprDigest(sha256) {
   return `sha-256=:${btoa(binary)}:`;
 }
 
+// src/lock.ts
+var RETENTION_MODES = ["governance", "compliance"];
+var RETENTION_DERIVATIVES = ["inherit", "original-only"];
+var DEFAULT_RETENTION_DERIVATIVES = "inherit";
+var MAX_RETENTION_PERIOD_SECONDS = 100 * 366 * 24 * 60 * 60;
+var LOCK_FIELDS = /* @__PURE__ */ new Set(["retention", "hold"]);
+var RETENTION_FIELDS = /* @__PURE__ */ new Set(["mode", "until", "period", "derivatives"]);
+var ISO_8601_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isIsoInstant(value) {
+  return typeof value === "string" && ISO_8601_INSTANT.test(value) && !Number.isNaN(Date.parse(value));
+}
+function rejectUnknownKeys(input, allowed, path, errors) {
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) errors.push(`${path}.${key}: unknown field`);
+  }
+}
+function validateRetention(input, path, errors) {
+  if (!isObject(input)) {
+    errors.push(`${path}: must be an object`);
+    return void 0;
+  }
+  const errorCount = errors.length;
+  rejectUnknownKeys(input, RETENTION_FIELDS, path, errors);
+  const { mode, until, period, derivatives } = input;
+  if (!RETENTION_MODES.includes(mode)) {
+    errors.push(`${path}.mode: must be "governance" or "compliance"`);
+  }
+  if (until !== void 0 && !isIsoInstant(until)) {
+    errors.push(`${path}.until: must be an ISO 8601 date-time with a zone`);
+  }
+  const isPeriodValid = Number.isSafeInteger(period) && period > 0 && period <= MAX_RETENTION_PERIOD_SECONDS;
+  if (period !== void 0 && !isPeriodValid) {
+    errors.push(`${path}.period: must be a positive integer number of seconds, at most 100 years`);
+  }
+  if (until !== void 0 && period !== void 0) errors.push(`${path}: set either until or period, not both`);
+  if (until === void 0 && period === void 0) errors.push(`${path}: until or period is required`);
+  if (derivatives !== void 0 && !RETENTION_DERIVATIVES.includes(derivatives)) {
+    errors.push(`${path}.derivatives: must be "inherit" or "original-only"`);
+  }
+  if (errors.length > errorCount) return void 0;
+  const retention = { mode };
+  if (until !== void 0) retention.until = until;
+  if (period !== void 0) retention.period = period;
+  if (derivatives !== void 0) retention.derivatives = derivatives;
+  return retention;
+}
+function validateLock(input, path = "lock") {
+  if (!isObject(input)) return { ok: false, errors: [`${path}: must be an object`] };
+  const errors = [];
+  rejectUnknownKeys(input, LOCK_FIELDS, path, errors);
+  const lock = {};
+  if (input.retention !== void 0) lock.retention = validateRetention(input.retention, `${path}.retention`, errors);
+  if (input.hold !== void 0 && typeof input.hold !== "boolean") errors.push(`${path}.hold: must be a boolean`);
+  if (typeof input.hold === "boolean") lock.hold = input.hold;
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, lock };
+}
+function resolveLock(resource, appDefault) {
+  const errors = [];
+  const resourceLock = resource === void 0 ? {} : collect(validateLock(resource, "lock"), errors);
+  const defaultLock = appDefault === void 0 ? {} : collect(validateLock(appDefault, "default"), errors);
+  if (errors.length > 0) return { ok: false, errors };
+  const lock = { hold: resourceLock.hold ?? defaultLock.hold ?? false };
+  const retention = resourceLock.retention ?? defaultLock.retention;
+  if (!retention) return { ok: true, lock };
+  const derivatives = resourceLock.retention?.derivatives ?? defaultLock.retention?.derivatives ?? DEFAULT_RETENTION_DERIVATIVES;
+  lock.retention = { ...retention, derivatives };
+  return { ok: true, lock };
+}
+function collect(validation, errors) {
+  if (validation.ok) return validation.lock;
+  errors.push(...validation.errors);
+  return {};
+}
+
+// src/lock-change.ts
+var toMs = (instant) => instant instanceof Date ? instant.getTime() : new Date(instant).getTime();
+function retentionEnd(lock, timing) {
+  const { retention } = lock;
+  if (!retention) return { kind: "none" };
+  if (retention.until !== void 0) return { kind: "at", ms: toMs(retention.until) };
+  const period = retention.period ?? 0;
+  if (lock.hold) return { kind: "pending", period };
+  const start = timing?.holdReleasedAt ?? timing?.uploadedAt;
+  if (start === void 0) throw new RangeError("lock: a retention period needs uploadedAt or holdReleasedAt");
+  return { kind: "at", ms: toMs(start) + period * 1e3 };
+}
+function effectiveUntil(lock, timing) {
+  const end = retentionEnd(lock, timing);
+  return end.kind === "at" ? new Date(end.ms).toISOString() : void 0;
+}
+function isLocked(lock, now, timing) {
+  if (lock.hold) return true;
+  const end = retentionEnd(lock, timing);
+  return end.kind === "at" && toMs(now) < end.ms;
+}
+function afterTiming(before, after, options) {
+  if (!before.hold || after.hold) return options.timing;
+  return { ...options.timing, holdReleasedAt: options.now };
+}
+function earliestEndMs(end, nowMs) {
+  if (end.kind === "none") return Number.NEGATIVE_INFINITY;
+  return end.kind === "at" ? end.ms : nowMs + end.period * 1e3;
+}
+function isShortened(beforeEnd, afterEnd, nowMs, isStillHeld) {
+  if (afterEnd.kind === "none") return true;
+  if (beforeEnd.kind === "pending" && afterEnd.kind === "at" && isStillHeld) return true;
+  return earliestEndMs(afterEnd, nowMs) < earliestEndMs(beforeEnd, nowMs);
+}
+function isWeakerSetting(before, after) {
+  if (!after) return true;
+  if (before.mode === "compliance" && after.mode === "governance") return true;
+  return (before.derivatives ?? "inherit") === "inherit" && after.derivatives === "original-only";
+}
+function isRetentionActive(end, nowMs) {
+  if (end.kind === "pending") return true;
+  return end.kind === "at" && nowMs < end.ms;
+}
+function canChange(before, after, options) {
+  const nowMs = toMs(options.now);
+  const beforeEnd = retentionEnd(before, options.timing);
+  if (!before.retention || !isRetentionActive(beforeEnd, nowMs)) return { ok: true, bypass: false };
+  const afterEnd = retentionEnd(after, afterTiming(before, after, options));
+  const isShortenedEnd = isShortened(beforeEnd, afterEnd, nowMs, after.hold === true);
+  const isWeakened = isShortenedEnd || isWeakerSetting(before.retention, after.retention);
+  if (!isWeakened) return { ok: true, bypass: false };
+  if (before.retention.mode === "compliance") return { ok: false, reason: "compliance_extend_only" };
+  if (!options.privileged) return { ok: false, reason: "lock_privilege_required" };
+  return { ok: true, bypass: true };
+}
+
 // src/paths.ts
 function videoBasePath(id) {
   return `video/${id}`;
@@ -571,28 +703,40 @@ var DevulturApiError = class extends Error {
   status;
   code;
   limit;
-  constructor(message, status, code, limit) {
+  /**
+   * The response body's fields other than `error` and `code`, e.g. `{ key, mode, until, hold }`
+   * on a `409 retention_active`. `undefined` when the body had none (or wasn't JSON).
+   */
+  details;
+  constructor(message, status, code, limit, details) {
     super(message);
     this.name = "DevulturApiError";
     this.status = status;
     this.code = code;
     this.limit = limit;
+    this.details = details;
   }
 };
+function detailsFrom(body) {
+  const { error: _error, code: _code, ...rest } = body;
+  return Object.keys(rest).length > 0 ? rest : void 0;
+}
 async function errorFromResponse(response) {
   let message = `API error: ${response.status}`;
   let code;
   let limit;
+  let details;
   try {
     const body = await response.json();
-    if (typeof body === "object" && body !== null) {
+    if (typeof body === "object" && body !== null && !Array.isArray(body)) {
       if ("error" in body && typeof body.error === "string") message = body.error;
       if ("code" in body && typeof body.code === "string") code = body.code;
       if ("limit" in body && typeof body.limit === "number") limit = body.limit;
+      details = detailsFrom(body);
     }
   } catch {
   }
-  return new DevulturApiError(message, response.status, code, limit);
+  return new DevulturApiError(message, response.status, code, limit, details);
 }
 
 // src/multipart.ts
@@ -1020,7 +1164,9 @@ function createUploadsClient(base, request) {
           expiresIn: options.expiresIn,
           overwrite: options.overwrite,
           visibility: options.visibility,
-          cacheControl: options.cacheControl
+          cacheControl: options.cacheControl,
+          lock: options.lock,
+          hold: options.hold
         })
       });
       const uploadUrl = `${base}${created.uploadUrl}`;
@@ -1064,6 +1210,46 @@ function createFilesClient(fetchApi, request) {
   };
 }
 
+// src/worker-lock.ts
+var HOLD_PAGE_SIZE = 50;
+var encodeKey2 = (key) => key.split("/").map(encodeURIComponent).join("/");
+function chunks(keys) {
+  const pages = [];
+  for (let start = 0; start < keys.length; start += HOLD_PAGE_SIZE)
+    pages.push(keys.slice(start, start + HOLD_PAGE_SIZE));
+  return pages;
+}
+function createLockClient(request) {
+  const page = (hold, target, cursor) => request("/v1/lock/hold", {
+    method: "POST",
+    body: JSON.stringify({
+      hold,
+      ...Array.isArray(target) ? { keys: target } : { prefix: target.prefix },
+      ...cursor ? { cursor } : {}
+    })
+  });
+  async function* every(hold, target) {
+    if (Array.isArray(target)) {
+      for (const keys of chunks(target)) yield page(hold, keys);
+      return;
+    }
+    let cursor;
+    do {
+      const result = await page(hold, target, cursor);
+      yield result;
+      cursor = result.cursor;
+    } while (cursor);
+  }
+  return {
+    get: (key) => request(`/v1/lock/${encodeKey2(key)}`),
+    set: (key, options) => request(`/v1/lock/${encodeKey2(key)}`, { method: "PUT", body: JSON.stringify(options) }),
+    hold: (target, options) => page(true, target, options?.cursor),
+    release: (target, options) => page(false, target, options?.cursor),
+    holdAll: (target) => every(true, target),
+    releaseAll: (target) => every(false, target)
+  };
+}
+
 // src/worker-client.ts
 function createWorkerTransport(credential, baseUrl) {
   async function fetchApi(path, options = {}) {
@@ -1098,13 +1284,16 @@ function createWorkerClient(credential, baseUrl) {
     uploads: createUploadsClient(base, request),
     files: createFilesClient(fetchApi, request),
     assets: createAssetsClient(request),
+    lock: createLockClient(request),
     async uploadFile(file2, options) {
       const result = await request("/v1/upload", {
         method: "POST",
         body: JSON.stringify({
           filename: file2.name,
           contentType: file2.type,
-          metadata: options?.metadata
+          metadata: options?.metadata,
+          lock: options?.lock,
+          hold: options?.hold
         })
       });
       await uploadToCapabilityUrl(`${base}${result.uploadUrl}`, file2);
@@ -1122,7 +1311,9 @@ function createWorkerClient(credential, baseUrl) {
           filename: options.filename,
           contentType: options.contentType,
           metadata: options.metadata,
-          visibility: options.visibility
+          visibility: options.visibility,
+          lock: options.lock,
+          hold: options.hold
         })
       });
       return {
@@ -1230,6 +1421,8 @@ function createMediaRouter(config) {
       if (!isDirectStorageConfig(config) || !storage) {
         throw new Error("No storage client or worker client available.");
       }
+      if (options.lock || options.hold)
+        throw new Error("Object lock needs a media worker; direct storage can't enforce it.");
       const mediaType = resolveMediaType(options.contentType, config);
       if (!mediaType) {
         throw new Error(`Unsupported content type: "${options.contentType}"`);
@@ -1372,13 +1565,13 @@ var MIN_BITRATE_KBPS = 200;
 var MAX_BITRATE_KBPS = 4e4;
 var MAX_POSTER_SECONDS = 3600;
 var NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
-var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var isRung = (value) => TRANSCODE_RUNGS.includes(value);
 var isCrop = (value) => TRANSCODE_CROPS.includes(value);
 function isValidOutputName(name) {
   return typeof name === "string" && NAME_PATTERN.test(name);
 }
-function rejectUnknownKeys(raw, allowed, path, errors) {
+function rejectUnknownKeys2(raw, allowed, path, errors) {
   for (const key of Object.keys(raw)) {
     if (!allowed.includes(key)) errors.push(`${path}.${key}: unknown field`);
   }
@@ -1396,7 +1589,7 @@ function readRungs(value, path, errors) {
   return value;
 }
 function readBitrate(value, rungs, path, errors) {
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     errors.push(`${path}: must be an object of rung \u2192 kbps`);
     return void 0;
   }
@@ -1408,22 +1601,22 @@ function readBitrate(value, rungs, path, errors) {
   return value;
 }
 function readMp4(value, path, errors) {
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     errors.push(`${path}: must be an object`);
     return void 0;
   }
-  rejectUnknownKeys(value, ["rungs", "bitrate"], path, errors);
+  rejectUnknownKeys2(value, ["rungs", "bitrate"], path, errors);
   const rungs = readRungs(value.rungs, `${path}.rungs`, errors);
   if (!rungs) return void 0;
   if (value.bitrate === void 0) return { rungs };
   return { rungs, bitrate: readBitrate(value.bitrate, rungs, `${path}.bitrate`, errors) };
 }
 function readHls(value, path, errors) {
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     errors.push(`${path}: must be an object`);
     return void 0;
   }
-  rejectUnknownKeys(value, ["rungs"], path, errors);
+  rejectUnknownKeys2(value, ["rungs"], path, errors);
   if (value.rungs === void 0) return {};
   return { rungs: readRungs(value.rungs, `${path}.rungs`, errors) };
 }
@@ -1439,11 +1632,11 @@ function readPosterAt(value, path, errors) {
   return value;
 }
 function readPoster(value, path, errors) {
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     errors.push(`${path}: must be an object`);
     return void 0;
   }
-  rejectUnknownKeys(value, ["at", "formats"], path, errors);
+  rejectUnknownKeys2(value, ["at", "formats"], path, errors);
   const at = readPosterAt(value.at, `${path}.at`, errors);
   if (value.formats === void 0) return { at };
   const isFormatList = Array.isArray(value.formats) && value.formats.length > 0 && value.formats.every((format) => POSTER_FORMATS.includes(format));
@@ -1451,11 +1644,11 @@ function readPoster(value, path, errors) {
   return { at, formats: value.formats };
 }
 function readVariant(value, path, errors) {
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     errors.push(`${path}: must be an object`);
     return void 0;
   }
-  rejectUnknownKeys(value, ["name", "crop", "mp4"], path, errors);
+  rejectUnknownKeys2(value, ["name", "crop", "mp4"], path, errors);
   if (!isValidOutputName(value.name) || value.name === MAIN_VARIANT) {
     errors.push(`${path}.name: must be a lowercase slug (a-z, 0-9, -; max 32) other than "${MAIN_VARIANT}"`);
   }
@@ -1470,7 +1663,7 @@ function readVariants(value, errors) {
     return void 0;
   }
   const variants = value.map((variant, index) => readVariant(variant, `variants[${index}]`, errors));
-  const names = value.map((variant) => isObject(variant) ? variant.name : void 0);
+  const names = value.map((variant) => isObject2(variant) ? variant.name : void 0);
   if (new Set(names).size !== names.length) errors.push("variants: names must be unique");
   return variants.filter((variant) => variant !== void 0);
 }
@@ -1488,9 +1681,9 @@ function readSwitches(input, spec, errors) {
   }
 }
 function validateTranscodeSpec(input) {
-  if (!isObject(input)) return { ok: false, errors: ["spec: must be an object"] };
+  if (!isObject2(input)) return { ok: false, errors: ["spec: must be an object"] };
   const errors = [];
-  rejectUnknownKeys(input, SPEC_FIELDS, "spec", errors);
+  rejectUnknownKeys2(input, SPEC_FIELDS, "spec", errors);
   const spec = {};
   if (input.hls !== void 0) spec.hls = readHls(input.hls, "hls", errors);
   if (input.mp4 !== void 0) spec.mp4 = readMp4(input.mp4, "mp4", errors);
@@ -1661,6 +1854,7 @@ export {
   CaptionStatus,
   DEFAULT_ASSET_CACHE_CONTROL,
   DEFAULT_PRESIGN_EXPIRY_SECONDS,
+  DEFAULT_RETENTION_DERIVATIVES,
   DEFAULT_SECURITY,
   DEFAULT_TOKEN_EXPIRY_SECONDS,
   DEFAULT_VISIBILITY,
@@ -1671,6 +1865,7 @@ export {
   FILE_MIMES,
   GENERATED_PRIVATE_CACHE_CONTROL,
   GENERATED_PUBLIC_CACHE_CONTROL,
+  HOLD_PAGE_SIZE,
   IMAGE_MIMES,
   ImageFit,
   ImageFormat,
@@ -1681,6 +1876,7 @@ export {
   MAX_BITRATE_KBPS,
   MAX_CACHE_CONTROL_LENGTH,
   MAX_CACHE_RULES,
+  MAX_RETENTION_PERIOD_SECONDS,
   MAX_VARIANTS,
   MIN_BITRATE_KBPS,
   MULTIPART_PART_SIZE_BYTES,
@@ -1692,6 +1888,8 @@ export {
   MultipartAction,
   POSTER_FORMATS,
   REPR_DIGEST_HEADER,
+  RETENTION_DERIVATIVES,
+  RETENTION_MODES,
   SESSION_HEADER,
   SHA256_HEADER,
   SHA256_VERIFIED_HEADER,
@@ -1717,6 +1915,7 @@ export {
   buildTranscodeOutputUrls,
   buildVideoMp4Url,
   bytesToHex,
+  canChange,
   captionPath,
   classifyUploadRequest,
   computeFingerprint,
@@ -1726,6 +1925,7 @@ export {
   coversScope,
   createDecryptStream,
   createHTTPWebhookHandler,
+  createLockClient,
   createMediaRouter,
   createStorageClient,
   createWorkerClient,
@@ -1733,6 +1933,7 @@ export {
   decodeEncryptionMeta,
   decryptChunk,
   edgeTtlSeconds,
+  effectiveUntil,
   encodeEncryptionMeta,
   encryptBytes,
   exportEncryptionKey,
@@ -1751,6 +1952,8 @@ export {
   importEncryptionKey,
   isAssetKey,
   isBearerOf,
+  isIsoInstant,
+  isLocked,
   isPrefixWithin,
   isValidMime,
   isValidOutputName,
@@ -1779,6 +1982,7 @@ export {
   relativeMediaPath,
   reprDigest,
   resolveCacheControl,
+  resolveLock,
   resolveSecurity,
   resolveTranscodePreset,
   resolveVisibility,
@@ -1791,6 +1995,7 @@ export {
   toPrivateCacheControl,
   uploadMultipart,
   uploadToCapabilityUrl,
+  validateLock,
   validateTranscodeSpec,
   verifySignature,
   verifySignedUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/core",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Shared config, types, storage path conventions, media references and URL signing for the Devultur media SDKs",
   "keywords": [
     "media",