@devultur/core 1.5.2 → 1.6.0

package/dist/index.d.ts

@@ -389,6 +389,89 @@ interface AssetsClient {
     listAll(options?: Omit<ListAssetsOptions, "cursor">): AsyncGenerator<AssetEntry>;
 }
 
+/** Prefix of a grant's secret. */
+declare const DOWNLOAD_GRANT_PREFIX = "dvg_";
+/** Prefix of a grant's public id (to revoke and audit it; not a credential). */
+declare const DOWNLOAD_GRANT_ID_PREFIX = "dgr_";
+/** `HEAD /v1/grant/file`: whether the file is encrypted at rest (`true`/`false`). */
+declare const ENCRYPTED_HEADER = "x-devultur-encrypted";
+/** `HEAD /v1/grant/file`: when the grant expires (epoch ms). */
+declare const GRANT_EXPIRES_AT_HEADER = "x-devultur-grant-expires-at";
+/** `HEAD /v1/grant/file`: the key of the grant's file. */
+declare const GRANT_KEY_HEADER = "x-devultur-grant-key";
+/** `HEAD /v1/grant/file`: the grant's metadata, as URI-encoded JSON. */
+declare const GRANT_METADATA_HEADER = "x-devultur-grant-metadata";
+declare const DownloadGrantLimits: {
+    /** Longest grant lifetime of a file without a TTL. A file with one: its `expiresAt`. */
+    readonly MAX_LIFETIME_SECONDS: number;
+    readonly DEFAULT_LINK_EXPIRES_IN: 900;
+    readonly MAX_LINK_EXPIRES_IN: 86400;
+    readonly DEFAULT_LINK_MAX_USES: 1;
+    readonly MAX_LINK_MAX_USES: 10;
+    readonly DEFAULT_MAX_LINKS: 20;
+    readonly MAX_MAX_LINKS: 100;
+    /** Size of the metadata as JSON, in UTF-8 bytes. */
+    readonly MAX_METADATA_BYTES: 1024;
+};
+declare const DownloadGrantErrorCode: {
+    /** Unknown, malformed or not this Worker's grant. */
+    readonly INVALID: "invalid_grant";
+    /** Expired, revoked, or its file is gone. */
+    readonly GONE: "grant_gone";
+    /** It issued all of its links. */
+    readonly EXHAUSTED: "grant_exhausted";
+    /** A link above `link.maxExpiresIn` or `link.maxUses`. */
+    readonly LINK_EXCEEDS_GRANT: "link_exceeds_grant";
+    /** The grant was sent in `?token=`. */
+    readonly IN_QUERY: "grant_in_query";
+    /** `delete()` on a grant issued without `canDelete`. */
+    readonly CANNOT_DELETE: "grant_cannot_delete";
+    readonly NOT_FOUND: "grant_not_found";
+};
+interface DownloadGrantLinkCaps {
+    /** Longest `expiresIn` (seconds) of each link. */
+    maxExpiresIn: number;
+    /** Most `maxUses` of each link. */
+    maxUses: number;
+}
+interface CreateDownloadGrantOptions {
+    /** Grant lifetime in seconds. Default and cap: the file's `expiresAt`; without a TTL, 30 days. */
+    expiresIn?: number;
+    /** Caps of every link the grant issues. Default `{ maxExpiresIn: 900, maxUses: 1 }`. */
+    link?: Partial<DownloadGrantLinkCaps>;
+    /** Links the grant may issue in total (default 20, max 100). */
+    maxLinks?: number;
+    /** Allows `delete()` (default false). Needs a credential that can delete the file. */
+    canDelete?: boolean;
+    /** Opaque string → string metadata (≤ 1 KB as JSON), returned by `head()` and stored with every link. */
+    metadata?: Record<string, string>;
+}
+/** A grant as listed: everything but its secret. */
+interface DownloadGrantSummary {
+    /** Public id (`dgr_…`): revokes and identifies the grant, grants nothing. */
+    id: string;
+    key: string;
+    /** Epoch ms. */
+    expiresAt: number;
+    link: DownloadGrantLinkCaps;
+    maxLinks: number;
+    canDelete: boolean;
+    metadata?: Record<string, string>;
+}
+interface DownloadGrant extends DownloadGrantSummary {
+    /** The secret (`dvg_…`). Returned once. */
+    grant: string;
+}
+interface DownloadGrantListEntry extends DownloadGrantSummary {
+    linksIssued: number;
+    /** Epoch ms. */
+    createdAt: number;
+    /** Epoch ms, or null while live. */
+    revokedAt: number | null;
+}
+/** Is `value` shaped like a grant's secret? Pure. */
+declare function isDownloadGrant(value: string): boolean;
+
 interface CreateUploadTokenOptions {
     /** Prefix within `asset/` where the token can create files (`exports/inst-1/`). */
     prefix: string;
@@ -471,6 +554,8 @@ interface DownloadLinkOptions {
     filename?: string;
 }
 interface DownloadLink {
+    /** Opaque id of the link (the last segment of `url`), to correlate it with delivery logs and events. */
+    id: string;
     url: string;
     expiresAt: number;
     maxUses: number;
@@ -486,6 +571,15 @@ interface FilesClient {
     head(key: string): Promise<FileHead | null>;
     /** Single-use download link: the link doesn't carry the credential. */
     createDownloadLink(key: string, options?: DownloadLinkOptions): Promise<DownloadLink>;
+    /**
+     * A download grant over this one file: hand its `grant` to another system (see `createGrantClient`) so it can issue
+     * links within the caps you set, without your credential. The secret is returned once.
+     */
+    createDownloadGrant(key: string, options?: CreateDownloadGrantOptions): Promise<DownloadGrant>;
+    /** Revokes a grant by its public id (`dgr_…`). Idempotent. */
+    revokeDownloadGrant(id: string): Promise<void>;
+    /** The file's grants (live, revoked or expired until cleaned up), without their secrets. */
+    listDownloadGrants(key: string): Promise<DownloadGrantListEntry[]>;
     /** `Response` of the file to pipe from your backend to your user (without exposing a token). */
     stream(key: string, options?: {
         range?: string;
@@ -1040,6 +1134,34 @@ declare function sanitizeFilename(filename: string): string;
 declare function contentDispositionInline(filename: string): string;
 declare function contentDispositionAttachment(filename: string): string;
 
+interface GrantFileHead extends FileHead {
+    /** Whether the file is encrypted at rest. */
+    encrypted: boolean;
+    /** The grant's metadata, as its owner set it. */
+    metadata: Record<string, string>;
+    /** When the grant expires (epoch ms). */
+    grantExpiresAt: number;
+}
+interface GrantLinkOptions extends DownloadLinkOptions {
+    /** Opaque string → string metadata (≤ 1 KB as JSON) stored with the link. */
+    metadata?: Record<string, string>;
+}
+interface GrantClient {
+    /** The file's head, plus the grant's metadata and expiry. `null` once the grant or its file is gone. */
+    head(): Promise<GrantFileHead | null>;
+    /**
+     * A download link of the file. Above the grant's caps → `400 link_exceeds_grant` (nothing spent); every link
+     * already issued → `410 grant_exhausted`.
+     */
+    createDownloadLink(options?: GrantLinkOptions): Promise<DownloadLink>;
+    /** Deletes the file (`409 retention_active` while it's retained) and its grants. Only a grant with `canDelete`. */
+    delete(): Promise<void>;
+    /** Revokes the grant. Idempotent. */
+    revoke(): Promise<void>;
+}
+/** Client for the file a download grant covers. `baseUrl` is the Worker's origin. */
+declare function createGrantClient(grant: string, baseUrl: string): GrantClient;
+
 /** sha256 (hex) of the file: the client declares it on upload and the worker returns it on GET/HEAD. */
 declare const SHA256_HEADER = "x-devultur-sha256";
 /** `true` = the worker computed the sha256 over the bytes; `false` = the client declared it (multipart). */
@@ -1369,4 +1491,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_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_HEIGHT_HEADER, IMAGE_MIMES, IMAGE_WIDTH_HEADER, 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 };
+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 CreateDownloadGrantOptions, type CreateUploadTokenOptions, type CreateUploadUrlOptions, DEFAULT_ASSET_CACHE_CONTROL, DEFAULT_PRESIGN_EXPIRY_SECONDS, DEFAULT_RETENTION_DERIVATIVES, DEFAULT_SECURITY, DEFAULT_TOKEN_EXPIRY_SECONDS, DEFAULT_VISIBILITY, DOWNLOAD_GRANT_ID_PREFIX, DOWNLOAD_GRANT_PREFIX, type DeleteVideoResult, type DeliveryConfig, DevulturApiError, type DevulturConfig, type DevulturKind, type DevulturMedia, type DirectStorageConfig, type DownloadGrant, DownloadGrantErrorCode, DownloadGrantLimits, type DownloadGrantLinkCaps, type DownloadGrantListEntry, type DownloadGrantSummary, type DownloadLink, type DownloadLinkOptions, type DownloadUrlOptions, ENCRYPTED_HEADER, 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, GRANT_EXPIRES_AT_HEADER, GRANT_KEY_HEADER, GRANT_METADATA_HEADER, type GrantClient, type GrantFileHead, type GrantLinkOptions, HOLD_PAGE_SIZE, type HoldPage, type HoldSkip, type HoldTarget, IMAGE_HEIGHT_HEADER, IMAGE_MIMES, IMAGE_WIDTH_HEADER, 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, createGrantClient, 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, isDownloadGrant, 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

@@ -401,6 +401,44 @@ function getDownloadUrl(mediaUrl2, options) {
   return `${mediaUrl2}${separator}download${value}`;
 }
 
+// src/download-grant.ts
+var DOWNLOAD_GRANT_PREFIX = "dvg_";
+var DOWNLOAD_GRANT_ID_PREFIX = "dgr_";
+var ENCRYPTED_HEADER = "x-devultur-encrypted";
+var GRANT_EXPIRES_AT_HEADER = "x-devultur-grant-expires-at";
+var GRANT_KEY_HEADER = "x-devultur-grant-key";
+var GRANT_METADATA_HEADER = "x-devultur-grant-metadata";
+var DownloadGrantLimits = {
+  /** Longest grant lifetime of a file without a TTL. A file with one: its `expiresAt`. */
+  MAX_LIFETIME_SECONDS: 30 * 24 * 60 * 60,
+  DEFAULT_LINK_EXPIRES_IN: 900,
+  MAX_LINK_EXPIRES_IN: 86400,
+  DEFAULT_LINK_MAX_USES: 1,
+  MAX_LINK_MAX_USES: 10,
+  DEFAULT_MAX_LINKS: 20,
+  MAX_MAX_LINKS: 100,
+  /** Size of the metadata as JSON, in UTF-8 bytes. */
+  MAX_METADATA_BYTES: 1024
+};
+var DownloadGrantErrorCode = {
+  /** Unknown, malformed or not this Worker's grant. */
+  INVALID: "invalid_grant",
+  /** Expired, revoked, or its file is gone. */
+  GONE: "grant_gone",
+  /** It issued all of its links. */
+  EXHAUSTED: "grant_exhausted",
+  /** A link above `link.maxExpiresIn` or `link.maxUses`. */
+  LINK_EXCEEDS_GRANT: "link_exceeds_grant",
+  /** The grant was sent in `?token=`. */
+  IN_QUERY: "grant_in_query",
+  /** `delete()` on a grant issued without `canDelete`. */
+  CANNOT_DELETE: "grant_cannot_delete",
+  NOT_FOUND: "grant_not_found"
+};
+function isDownloadGrant(value) {
+  return value.startsWith(DOWNLOAD_GRANT_PREFIX);
+}
+
 // src/filenames.ts
 function sanitizeFilename(filename) {
   const lastDot = filename.lastIndexOf(".");
@@ -422,161 +460,45 @@ function contentDispositionAttachment(filename) {
   return contentDisposition("attachment", filename);
 }
 
-// src/integrity.ts
-var SHA256_HEADER = "x-devultur-sha256";
-var SHA256_VERIFIED_HEADER = "x-devultur-sha256-verified";
-var EXPIRES_AT_HEADER = "x-devultur-expires-at";
-var IMAGE_WIDTH_HEADER = "x-devultur-image-width";
-var IMAGE_HEIGHT_HEADER = "x-devultur-image-height";
-var REPR_DIGEST_HEADER = "Repr-Digest";
-var SHA256_HEX = /^[0-9a-f]{64}$/;
-function normalizeSha256(raw) {
-  if (typeof raw !== "string") return null;
-  const value = raw.trim().toLowerCase();
-  return SHA256_HEX.test(value) ? value : null;
-}
-function bytesToHex(bytes) {
-  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-async function sha256Hex(data) {
-  return bytesToHex(await crypto.subtle.digest("SHA-256", data));
-}
-function reprDigest(sha256) {
-  const pairs = sha256.match(/.{2}/g) ?? [];
-  const binary = pairs.map((pair) => String.fromCharCode(Number.parseInt(pair, 16))).join("");
-  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`);
+// src/api-error.ts
+var DevulturApiError = class extends Error {
+  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;
 }
-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"`);
+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 && !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 {
   }
-  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 };
+  return new DevulturApiError(message, response.status, code, limit, details);
 }
 
 // src/paths.ts
@@ -700,45 +622,29 @@ function publicUrl(baseUrl, media, options) {
   return buildMediaUrl(baseUrl, mediaPath(media), options);
 }
 
-// src/api-error.ts
-var DevulturApiError = class extends Error {
-  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;
+// src/integrity.ts
+var SHA256_HEADER = "x-devultur-sha256";
+var SHA256_VERIFIED_HEADER = "x-devultur-sha256-verified";
+var EXPIRES_AT_HEADER = "x-devultur-expires-at";
+var IMAGE_WIDTH_HEADER = "x-devultur-image-width";
+var IMAGE_HEIGHT_HEADER = "x-devultur-image-height";
+var REPR_DIGEST_HEADER = "Repr-Digest";
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+function normalizeSha256(raw) {
+  if (typeof raw !== "string") return null;
+  const value = raw.trim().toLowerCase();
+  return SHA256_HEX.test(value) ? value : null;
 }
-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 && !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, details);
+function bytesToHex(bytes) {
+  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function sha256Hex(data) {
+  return bytesToHex(await crypto.subtle.digest("SHA-256", data));
+}
+function reprDigest(sha256) {
+  const pairs = sha256.match(/.{2}/g) ?? [];
+  const binary = pairs.map((pair) => String.fromCharCode(Number.parseInt(pair, 16))).join("");
+  return `sha-256=:${btoa(binary)}:`;
 }
 
 // src/multipart.ts
@@ -912,196 +818,6 @@ async function uploadToCapabilityUrl(uploadUrl, file2, options = {}) {
   options.onProgress?.(100);
 }
 
-// src/path-prefix.ts
-var VISIBILITY_SEGMENTS2 = /* @__PURE__ */ new Set(["public", "private"]);
-var SAFE_SEGMENT2 = /^[A-Za-z0-9._-]+$/;
-var MAX_PATH_PREFIX_LENGTH = 256;
-function isSafeSegment2(segment) {
-  return SAFE_SEGMENT2.test(segment) && segment !== "." && segment !== "..";
-}
-function normalizePathPrefix(raw) {
-  if (typeof raw !== "string" || raw.length > MAX_PATH_PREFIX_LENGTH) return null;
-  const segments = raw.trim().replace(/^\/+|\/+$/g, "").split("/");
-  if (segments.length === 0 || segments[0] === "") return null;
-  if (VISIBILITY_SEGMENTS2.has(segments[0])) return null;
-  if (!segments.every(isSafeSegment2)) return null;
-  return `${segments.join("/")}/`;
-}
-function relativeMediaPath(virtualKey) {
-  const segments = virtualKey.split("/");
-  if (!VISIBILITY_SEGMENTS2.has(segments[0] ?? "")) return null;
-  const rest = segments.slice(1);
-  const isTrailingSlash = rest.at(-1) === "";
-  const named = isTrailingSlash ? rest.slice(0, -1) : rest;
-  if (named.length === 0 || !named.every(isSafeSegment2)) return null;
-  return `${named.join("/")}${isTrailingSlash ? "/" : ""}`;
-}
-function isWithinPathPrefix(relativePath, pathPrefix) {
-  if (!pathPrefix) return true;
-  return relativePath.startsWith(pathPrefix);
-}
-function isPrefixWithin(child, parent) {
-  if (!parent) return true;
-  if (!child) return false;
-  return child.startsWith(parent);
-}
-
-// src/providers.ts
-var StorageProvider = {
-  R2: "r2"
-};
-var TranscodeProvider = {
-  FLY_IO: "fly.io"
-};
-var SpeechProvider = {
-  GROQ_WHISPER: "groq-whisper"
-};
-var TranslationProvider = {
-  MISTRAL: "mistral"
-};
-var ImageFit = {
-  COVER: "cover",
-  CONTAIN: "contain",
-  FILL: "fill",
-  INSIDE: "inside"
-};
-var ImageFormat = {
-  WEBP: "webp",
-  AVIF: "avif",
-  JPEG: "jpeg",
-  PNG: "png",
-  AUTO: "auto"
-};
-var SecurityLevel = {
-  SIGNED_URLS: 1,
-  TOKEN_BINDING: 2,
-  IP_FINGERPRINT: 3,
-  AES_128_HLS: 4
-};
-
-// src/signing.ts
-async function importHmacKey(secret) {
-  const encoder2 = new TextEncoder();
-  return crypto.subtle.importKey("raw", encoder2.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
-    "sign",
-    "verify"
-  ]);
-}
-function bufferToHex(buffer) {
-  return Array.from(new Uint8Array(buffer)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-function hexToBuffer(hex) {
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < hex.length; i += 2) {
-    bytes[i / 2] = Number.parseInt(hex.slice(i, i + 2), 16);
-  }
-  return bytes.buffer;
-}
-async function signPayload(payload, secret) {
-  const key = await importHmacKey(secret);
-  const encoder2 = new TextEncoder();
-  const signature = await crypto.subtle.sign("HMAC", key, encoder2.encode(payload));
-  return bufferToHex(signature);
-}
-async function verifySignature(payload, signature, secret) {
-  const key = await importHmacKey(secret);
-  const encoder2 = new TextEncoder();
-  const signatureBuffer = hexToBuffer(signature);
-  return crypto.subtle.verify("HMAC", key, signatureBuffer, encoder2.encode(payload));
-}
-async function signUrl(url, secret, expiresIn) {
-  const expiry = expiresIn ?? DEFAULT_PRESIGN_EXPIRY_SECONDS;
-  const expires = Math.floor(Date.now() / 1e3) + expiry;
-  const parsed = new URL(url);
-  parsed.searchParams.set("expires", String(expires));
-  const payload = `${parsed.origin}${parsed.pathname}?expires=${expires}`;
-  const signature = await signPayload(payload, secret);
-  parsed.searchParams.set("signature", signature);
-  return parsed.toString();
-}
-async function verifySignedUrl(signedUrl, secret) {
-  const parsed = new URL(signedUrl);
-  const expires = parsed.searchParams.get("expires");
-  const signature = parsed.searchParams.get("signature");
-  if (!expires || !signature) return false;
-  const now = Math.floor(Date.now() / 1e3);
-  if (now > Number(expires)) return false;
-  const payload = `${parsed.origin}${parsed.pathname}?expires=${expires}`;
-  return verifySignature(payload, signature, secret);
-}
-
-// src/storage.ts
-import {
-  DeleteObjectCommand,
-  GetObjectCommand,
-  HeadObjectCommand,
-  PutObjectCommand,
-  S3Client
-} from "@aws-sdk/client-s3";
-import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
-function createStorageClient(config) {
-  const client = new S3Client({
-    region: "auto",
-    endpoint: `https://${config.accountId}.r2.cloudflarestorage.com`,
-    credentials: {
-      accessKeyId: config.accessKeyId,
-      secretAccessKey: config.secretAccessKey
-    }
-  });
-  return {
-    async createUploadUrl(options) {
-      const command = new PutObjectCommand({
-        Bucket: config.bucket,
-        Key: options.key,
-        ContentType: options.contentType,
-        Metadata: options.metadata,
-        ...options.storageClass ? { StorageClass: options.storageClass } : {},
-        ...options.contentDisposition ? { ContentDisposition: options.contentDisposition } : {}
-      });
-      return getSignedUrl(client, command, {
-        expiresIn: options.expiresIn ?? DEFAULT_PRESIGN_EXPIRY_SECONDS
-      });
-    },
-    async createDownloadUrl(options) {
-      const command = new GetObjectCommand({
-        Bucket: config.bucket,
-        Key: options.key
-      });
-      return getSignedUrl(client, command, {
-        expiresIn: options.expiresIn ?? DEFAULT_PRESIGN_EXPIRY_SECONDS
-      });
-    },
-    async deleteObject(key) {
-      await client.send(
-        new DeleteObjectCommand({
-          Bucket: config.bucket,
-          Key: key
-        })
-      );
-    },
-    async headObject(key) {
-      try {
-        const response = await client.send(
-          new HeadObjectCommand({
-            Bucket: config.bucket,
-            Key: key
-          })
-        );
-        return {
-          size: response.ContentLength ?? 0,
-          contentType: response.ContentType ?? "application/octet-stream",
-          lastModified: response.LastModified ?? /* @__PURE__ */ new Date()
-        };
-      } catch (error) {
-        if (error instanceof Error && "name" in error && error.name === "NotFound") {
-          return null;
-        }
-        throw error;
-      }
-    }
-  };
-}
-
 // src/worker-assets.ts
 function assetListQuery(options) {
   const params = new URLSearchParams();
@@ -1216,6 +932,18 @@ function createFilesClient(fetchApi, request) {
         body: JSON.stringify({ key, ...options })
       });
     },
+    createDownloadGrant(key, options = {}) {
+      return request("/v1/token/grant", {
+        method: "POST",
+        body: JSON.stringify({ key, ...options })
+      });
+    },
+    async revokeDownloadGrant(id) {
+      await fetchApi(`/v1/token/grant/${encodeURIComponent(id)}`, { method: "DELETE" });
+    },
+    listDownloadGrants(key) {
+      return request(`/v1/token/grant?key=${encodeURIComponent(key)}`);
+    },
     stream(key, options = {}) {
       return fetchApi(`/v1/media/${encodeKey(key)}`, {
         headers: options.range ? { Range: options.range } : {},
@@ -1392,6 +1120,363 @@ function createWorkerClient(credential, baseUrl) {
   };
 }
 
+// src/grant-client.ts
+function grantMetadata(response) {
+  const header = response.headers.get(GRANT_METADATA_HEADER);
+  return header ? JSON.parse(decodeURIComponent(header)) : {};
+}
+var isGone = (error) => error instanceof DevulturApiError && (error.status === 404 || error.status === 410);
+function createGrantClient(grant, baseUrl) {
+  const { fetchApi, request, requestVoid } = createWorkerTransport(grant, baseUrl);
+  return {
+    async head() {
+      try {
+        const response = await fetchApi("/v1/grant/file", { method: "HEAD" });
+        return {
+          ...headFromResponse(response.headers.get(GRANT_KEY_HEADER) ?? "", response),
+          encrypted: response.headers.get(ENCRYPTED_HEADER) === "true",
+          metadata: grantMetadata(response),
+          grantExpiresAt: Number(response.headers.get(GRANT_EXPIRES_AT_HEADER))
+        };
+      } catch (error) {
+        if (isGone(error)) return null;
+        throw error;
+      }
+    },
+    createDownloadLink(options = {}) {
+      return request("/v1/grant/links", { method: "POST", body: JSON.stringify(options) });
+    },
+    delete() {
+      return requestVoid("/v1/grant/file", { method: "DELETE" });
+    },
+    revoke() {
+      return requestVoid("/v1/grant", { method: "DELETE" });
+    }
+  };
+}
+
+// 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/path-prefix.ts
+var VISIBILITY_SEGMENTS2 = /* @__PURE__ */ new Set(["public", "private"]);
+var SAFE_SEGMENT2 = /^[A-Za-z0-9._-]+$/;
+var MAX_PATH_PREFIX_LENGTH = 256;
+function isSafeSegment2(segment) {
+  return SAFE_SEGMENT2.test(segment) && segment !== "." && segment !== "..";
+}
+function normalizePathPrefix(raw) {
+  if (typeof raw !== "string" || raw.length > MAX_PATH_PREFIX_LENGTH) return null;
+  const segments = raw.trim().replace(/^\/+|\/+$/g, "").split("/");
+  if (segments.length === 0 || segments[0] === "") return null;
+  if (VISIBILITY_SEGMENTS2.has(segments[0])) return null;
+  if (!segments.every(isSafeSegment2)) return null;
+  return `${segments.join("/")}/`;
+}
+function relativeMediaPath(virtualKey) {
+  const segments = virtualKey.split("/");
+  if (!VISIBILITY_SEGMENTS2.has(segments[0] ?? "")) return null;
+  const rest = segments.slice(1);
+  const isTrailingSlash = rest.at(-1) === "";
+  const named = isTrailingSlash ? rest.slice(0, -1) : rest;
+  if (named.length === 0 || !named.every(isSafeSegment2)) return null;
+  return `${named.join("/")}${isTrailingSlash ? "/" : ""}`;
+}
+function isWithinPathPrefix(relativePath, pathPrefix) {
+  if (!pathPrefix) return true;
+  return relativePath.startsWith(pathPrefix);
+}
+function isPrefixWithin(child, parent) {
+  if (!parent) return true;
+  if (!child) return false;
+  return child.startsWith(parent);
+}
+
+// src/providers.ts
+var StorageProvider = {
+  R2: "r2"
+};
+var TranscodeProvider = {
+  FLY_IO: "fly.io"
+};
+var SpeechProvider = {
+  GROQ_WHISPER: "groq-whisper"
+};
+var TranslationProvider = {
+  MISTRAL: "mistral"
+};
+var ImageFit = {
+  COVER: "cover",
+  CONTAIN: "contain",
+  FILL: "fill",
+  INSIDE: "inside"
+};
+var ImageFormat = {
+  WEBP: "webp",
+  AVIF: "avif",
+  JPEG: "jpeg",
+  PNG: "png",
+  AUTO: "auto"
+};
+var SecurityLevel = {
+  SIGNED_URLS: 1,
+  TOKEN_BINDING: 2,
+  IP_FINGERPRINT: 3,
+  AES_128_HLS: 4
+};
+
+// src/signing.ts
+async function importHmacKey(secret) {
+  const encoder2 = new TextEncoder();
+  return crypto.subtle.importKey("raw", encoder2.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify"
+  ]);
+}
+function bufferToHex(buffer) {
+  return Array.from(new Uint8Array(buffer)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function hexToBuffer(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = Number.parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes.buffer;
+}
+async function signPayload(payload, secret) {
+  const key = await importHmacKey(secret);
+  const encoder2 = new TextEncoder();
+  const signature = await crypto.subtle.sign("HMAC", key, encoder2.encode(payload));
+  return bufferToHex(signature);
+}
+async function verifySignature(payload, signature, secret) {
+  const key = await importHmacKey(secret);
+  const encoder2 = new TextEncoder();
+  const signatureBuffer = hexToBuffer(signature);
+  return crypto.subtle.verify("HMAC", key, signatureBuffer, encoder2.encode(payload));
+}
+async function signUrl(url, secret, expiresIn) {
+  const expiry = expiresIn ?? DEFAULT_PRESIGN_EXPIRY_SECONDS;
+  const expires = Math.floor(Date.now() / 1e3) + expiry;
+  const parsed = new URL(url);
+  parsed.searchParams.set("expires", String(expires));
+  const payload = `${parsed.origin}${parsed.pathname}?expires=${expires}`;
+  const signature = await signPayload(payload, secret);
+  parsed.searchParams.set("signature", signature);
+  return parsed.toString();
+}
+async function verifySignedUrl(signedUrl, secret) {
+  const parsed = new URL(signedUrl);
+  const expires = parsed.searchParams.get("expires");
+  const signature = parsed.searchParams.get("signature");
+  if (!expires || !signature) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  if (now > Number(expires)) return false;
+  const payload = `${parsed.origin}${parsed.pathname}?expires=${expires}`;
+  return verifySignature(payload, signature, secret);
+}
+
+// src/storage.ts
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+function createStorageClient(config) {
+  const client = new S3Client({
+    region: "auto",
+    endpoint: `https://${config.accountId}.r2.cloudflarestorage.com`,
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey
+    }
+  });
+  return {
+    async createUploadUrl(options) {
+      const command = new PutObjectCommand({
+        Bucket: config.bucket,
+        Key: options.key,
+        ContentType: options.contentType,
+        Metadata: options.metadata,
+        ...options.storageClass ? { StorageClass: options.storageClass } : {},
+        ...options.contentDisposition ? { ContentDisposition: options.contentDisposition } : {}
+      });
+      return getSignedUrl(client, command, {
+        expiresIn: options.expiresIn ?? DEFAULT_PRESIGN_EXPIRY_SECONDS
+      });
+    },
+    async createDownloadUrl(options) {
+      const command = new GetObjectCommand({
+        Bucket: config.bucket,
+        Key: options.key
+      });
+      return getSignedUrl(client, command, {
+        expiresIn: options.expiresIn ?? DEFAULT_PRESIGN_EXPIRY_SECONDS
+      });
+    },
+    async deleteObject(key) {
+      await client.send(
+        new DeleteObjectCommand({
+          Bucket: config.bucket,
+          Key: key
+        })
+      );
+    },
+    async headObject(key) {
+      try {
+        const response = await client.send(
+          new HeadObjectCommand({
+            Bucket: config.bucket,
+            Key: key
+          })
+        );
+        return {
+          size: response.ContentLength ?? 0,
+          contentType: response.ContentType ?? "application/octet-stream",
+          lastModified: response.LastModified ?? /* @__PURE__ */ new Date()
+        };
+      } catch (error) {
+        if (error instanceof Error && "name" in error && error.name === "NotFound") {
+          return null;
+        }
+        throw error;
+      }
+    }
+  };
+}
+
 // src/router.ts
 function isDirectStorageConfig(config) {
   return "storage" in config;
@@ -1876,13 +1961,21 @@ export {
   DEFAULT_SECURITY,
   DEFAULT_TOKEN_EXPIRY_SECONDS,
   DEFAULT_VISIBILITY,
+  DOWNLOAD_GRANT_ID_PREFIX,
+  DOWNLOAD_GRANT_PREFIX,
   DevulturApiError,
+  DownloadGrantErrorCode,
+  DownloadGrantLimits,
+  ENCRYPTED_HEADER,
   ENCRYPTION_ALG,
   ENCRYPTION_VERSION,
   EXPIRES_AT_HEADER,
   FILE_MIMES,
   GENERATED_PRIVATE_CACHE_CONTROL,
   GENERATED_PUBLIC_CACHE_CONTROL,
+  GRANT_EXPIRES_AT_HEADER,
+  GRANT_KEY_HEADER,
+  GRANT_METADATA_HEADER,
   HOLD_PAGE_SIZE,
   IMAGE_HEIGHT_HEADER,
   IMAGE_MIMES,
@@ -1944,6 +2037,7 @@ export {
   counterForBlock,
   coversScope,
   createDecryptStream,
+  createGrantClient,
   createHTTPWebhookHandler,
   createLockClient,
   createMediaRouter,
@@ -1972,6 +2066,7 @@ export {
   importEncryptionKey,
   isAssetKey,
   isBearerOf,
+  isDownloadGrant,
   isIsoInstant,
   isLocked,
   isPrefixWithin,

package/package.json

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