@devultur/convex 1.5.2 → 1.6.0

package/dist/{chunk-RDVBE3G3.js → chunk-34XXHYL3.js}

@@ -7,7 +7,7 @@ import {
   formatBytes,
   formatDate,
   labelText
-} from "./chunk-YYOZ3PDH.js";
+} from "./chunk-V5YH4YJG.js";
 
 // src/locales/es.ts
 var LOCALE = "es";
@@ -57,6 +57,18 @@ var devulturErrorLabels = {
   link_expired: "Este enlace de descarga ya venci\xF3.",
   link_used: "Este enlace de descarga ya se us\xF3.",
   not_configured: "Esta funci\xF3n no est\xE1 configurada.",
+  invalid_grant: "Este permiso de descarga no es v\xE1lido.",
+  grant_gone: "Este permiso de descarga ya no es v\xE1lido.",
+  grant_exhausted: "Este permiso de descarga ya emiti\xF3 todos sus enlaces.",
+  grant_exists: "Este permiso de descarga ya existe.",
+  grant_in_query: "Env\xEDa el permiso de descarga en el encabezado Authorization, nunca en una URL.",
+  grant_not_found: "Este permiso de descarga no existe.",
+  grant_cannot_delete: "Este permiso de descarga no puede eliminar su archivo.",
+  link_exceeds_grant: "El enlace de descarga supera lo que permite el permiso.",
+  invalid_link_caps: "Los l\xEDmites del enlace de descarga no son v\xE1lidos.",
+  invalid_max_links: "El n\xFAmero de enlaces no es v\xE1lido.",
+  invalid_can_delete: "Si el permiso puede eliminar su archivo debe ser verdadero o falso.",
+  invalid_metadata: "Los metadatos no son v\xE1lidos.",
   retention_active: (details) => {
     if (details.hold === true) return "Este archivo tiene una retenci\xF3n legal y no se puede modificar ni eliminar.";
     const until = formatDate(details.until, LOCALE);

package/dist/{chunk-YYOZ3PDH.js → chunk-V5YH4YJG.js}

@@ -40,6 +40,19 @@ var DEVULTUR_ERROR_CODES = [
   "link_expired",
   "link_used",
   "not_configured",
+  // Download grants
+  "invalid_grant",
+  "grant_gone",
+  "grant_exhausted",
+  "grant_exists",
+  "grant_in_query",
+  "grant_not_found",
+  "grant_cannot_delete",
+  "link_exceeds_grant",
+  "invalid_link_caps",
+  "invalid_max_links",
+  "invalid_can_delete",
+  "invalid_metadata",
   // Retention and holds
   "retention_active",
   "lock_conflict",
@@ -170,6 +183,18 @@ var devulturErrorLabels = {
   link_expired: "This download link has expired.",
   link_used: "This download link was already used.",
   not_configured: "This feature isn't set up.",
+  invalid_grant: "This download grant isn't valid.",
+  grant_gone: "This download grant is no longer valid.",
+  grant_exhausted: "This download grant has issued all its links.",
+  grant_exists: "This download grant already exists.",
+  grant_in_query: "Send the download grant in the Authorization header, never in a URL.",
+  grant_not_found: "This download grant doesn't exist.",
+  grant_cannot_delete: "This download grant can't delete its file.",
+  link_exceeds_grant: "The download link exceeds what the grant allows.",
+  invalid_link_caps: "The download link limits aren't valid.",
+  invalid_max_links: "The number of links isn't valid.",
+  invalid_can_delete: "Whether the grant can delete its file must be true or false.",
+  invalid_metadata: "The metadata isn't valid.",
   retention_active: (details) => {
     if (details.hold === true) return "This file is on hold and can't be changed or deleted.";
     const until = formatDate(details.until, "en");

package/dist/{error-labels-D0Vbp-qA.d.ts → error-labels-Sf6gow24.d.ts}

@@ -1,4 +1,4 @@
-declare const DEVULTUR_ERROR_CODES: readonly ["file_too_large", "content_type_not_allowed", "content_type_mismatch", "content_unverified", "unsupported_content_type", "media_type_mismatch", "already_exists", "write_conflict", "upload_not_found", "invalid_upload_key", "invalid_path", "path_required", "invalid_expires_in", "invalid_file_expires_in", "invalid_cache_control", "invalid_limits", "invalid_prefix", "invalid_visibility", "invalid_cursor", "invalid_sha256", "sha256_mismatch", "max_files_reached", "invalid_multipart", "invalid_size", "invalid_part", "invalid_parts", "part_size_mismatch", "part_sha256_required", "invalid_media_metadata", "expired", "invalid_key", "invalid_max_uses", "link_exists", "link_not_found", "link_expired", "link_used", "not_configured", "retention_active", "lock_conflict", "compliance_extend_only", "lock_privilege_required", "lock_record_unreadable", "lock_below_minimum", "invalid_lock", "invalid_hold", "reserved_key", "keys_bucket_missing", "encryption_key_missing", "unauthorized", "session_mismatch", "token_rejected", "reserved_user_id", "invalid_scopes", "user_mismatch", "transcode_not_configured", "transcode_runner_unavailable", "transcode_launch_failed", "original_not_retained", "locale_not_allowed", "captions_provider_rate_limited", "captions_provider_error", "captions_failed", "webhook_secret_missing", "worker_auth_secret_missing", "worker_error", "http_error", "too_large", "unsupported_type", "type_mismatch", "token_unavailable", "page_cap", "render_failed", "capability_unavailable"];
+declare const DEVULTUR_ERROR_CODES: readonly ["file_too_large", "content_type_not_allowed", "content_type_mismatch", "content_unverified", "unsupported_content_type", "media_type_mismatch", "already_exists", "write_conflict", "upload_not_found", "invalid_upload_key", "invalid_path", "path_required", "invalid_expires_in", "invalid_file_expires_in", "invalid_cache_control", "invalid_limits", "invalid_prefix", "invalid_visibility", "invalid_cursor", "invalid_sha256", "sha256_mismatch", "max_files_reached", "invalid_multipart", "invalid_size", "invalid_part", "invalid_parts", "part_size_mismatch", "part_sha256_required", "invalid_media_metadata", "expired", "invalid_key", "invalid_max_uses", "link_exists", "link_not_found", "link_expired", "link_used", "not_configured", "invalid_grant", "grant_gone", "grant_exhausted", "grant_exists", "grant_in_query", "grant_not_found", "grant_cannot_delete", "link_exceeds_grant", "invalid_link_caps", "invalid_max_links", "invalid_can_delete", "invalid_metadata", "retention_active", "lock_conflict", "compliance_extend_only", "lock_privilege_required", "lock_record_unreadable", "lock_below_minimum", "invalid_lock", "invalid_hold", "reserved_key", "keys_bucket_missing", "encryption_key_missing", "unauthorized", "session_mismatch", "token_rejected", "reserved_user_id", "invalid_scopes", "user_mismatch", "transcode_not_configured", "transcode_runner_unavailable", "transcode_launch_failed", "original_not_retained", "locale_not_allowed", "captions_provider_rate_limited", "captions_provider_error", "captions_failed", "webhook_secret_missing", "worker_auth_secret_missing", "worker_error", "http_error", "too_large", "unsupported_type", "type_mismatch", "token_unavailable", "page_cap", "render_failed", "capability_unavailable"];
 /** A stable error code: match on it, not on `message`. */
 type DevulturErrorCode = (typeof DEVULTUR_ERROR_CODES)[number];
 declare function isDevulturErrorCode(code: unknown): code is DevulturErrorCode;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { FunctionReference, PaginationResult, FunctionVisibility, DefaultFunctio
 import { PropertyValidators, Value, ConvexError } from 'convex/values';
 import { M as MediaRecord, P as ProgressRecord, D as DevulturComponentConfig } from './types-C0ruHUcu.js';
 export { a as DevulturUploadConfig } from './types-C0ruHUcu.js';
-export { a as DEVULTUR_ERROR_CODES, b as DevulturErrorCode, c as DevulturErrorDetails, d as DevulturErrorLabel, D as DevulturErrorLabels, e as describeDevulturError, f as devulturErrorLabels, i as isDevulturErrorCode } from './error-labels-D0Vbp-qA.js';
+export { a as DEVULTUR_ERROR_CODES, b as DevulturErrorCode, c as DevulturErrorDetails, d as DevulturErrorLabel, D as DevulturErrorLabels, e as describeDevulturError, f as devulturErrorLabels, i as isDevulturErrorCode } from './error-labels-Sf6gow24.js';
 export { dv } from './validators.js';
 
 /**

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   devulturErrorOf,
   isDevulturError,
   isDevulturErrorCode
-} from "./chunk-YYOZ3PDH.js";
+} from "./chunk-V5YH4YJG.js";
 
 // src/index.ts
 import {

package/dist/locales/es-formal.d.ts

@@ -1,6 +1,6 @@
 import { VideoPlayerLabels } from '@devultur/react';
 import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-C2nUUY_f.js';
-import { D as DevulturErrorLabels } from '../error-labels-D0Vbp-qA.js';
+import { D as DevulturErrorLabels } from '../error-labels-Sf6gow24.js';
 import '../types-C0ruHUcu.js';
 import '@devultur/core';
 import 'convex/values';

package/dist/locales/es-formal.js

@@ -5,12 +5,12 @@ import {
   mediaPickerLabels,
   previewLabels,
   videoPlayerLabels
-} from "../chunk-RDVBE3G3.js";
+} from "../chunk-34XXHYL3.js";
 import "../chunk-QBHIZBOQ.js";
 import {
   describeDevulturError,
   labelText
-} from "../chunk-YYOZ3PDH.js";
+} from "../chunk-V5YH4YJG.js";
 
 // src/locales/es-formal.ts
 var TRY_AGAIN = "Vuelva a intentarlo.";
@@ -30,6 +30,7 @@ var devulturErrorLabels2 = {
     if (details.field === "tags") return "Use como m\xE1ximo 20 etiquetas, de hasta 50 caracteres cada una.";
     return labelText(devulturErrorLabels.invalid_media_metadata, details);
   },
+  grant_in_query: "Env\xEDe el permiso de descarga en el encabezado Authorization, nunca en una URL.",
   lock_conflict: `La protecci\xF3n del archivo cambi\xF3 mientras tanto. ${TRY_AGAIN}`,
   lock_privilege_required: "No tiene permiso para acortar ni quitar la protecci\xF3n de este archivo.",
   encryption_key_missing: "Este archivo ya no se puede leer. Vuelva a subirlo.",

package/dist/locales/es.d.ts

@@ -1,6 +1,6 @@
 import { VideoPlayerLabels } from '@devultur/react';
 import { A as AttachmentLabels, M as MediaLibraryLabels, a as MediaPickerLabels, P as PreviewLabels } from '../preview-labels-C2nUUY_f.js';
-import { D as DevulturErrorLabels } from '../error-labels-D0Vbp-qA.js';
+import { D as DevulturErrorLabels } from '../error-labels-Sf6gow24.js';
 import '../types-C0ruHUcu.js';
 import '@devultur/core';
 import 'convex/values';

package/dist/locales/es.js

@@ -5,9 +5,9 @@ import {
   mediaPickerLabels,
   previewLabels,
   videoPlayerLabels
-} from "../chunk-RDVBE3G3.js";
+} from "../chunk-34XXHYL3.js";
 import "../chunk-QBHIZBOQ.js";
-import "../chunk-YYOZ3PDH.js";
+import "../chunk-V5YH4YJG.js";
 export {
   attachmentLabels,
   devulturErrorLabels,

package/dist/react.js

@@ -28,7 +28,7 @@ import {
 } from "./chunk-QBHIZBOQ.js";
 import {
   describeDevulturError
-} from "./chunk-YYOZ3PDH.js";
+} from "./chunk-V5YH4YJG.js";
 import {
   DevulturApiContext,
   DevulturCapabilityError,

package/docs/guides/plugins.md

@@ -8,7 +8,7 @@ same API as yours. Add plugins to extend the Worker, or replace a default one.
 import { createWorker, defaultPlugins } from "@devultur/self-host";
 import { usageLog } from "./plugins/usage-log";
 
-export { DownloadLink } from "@devultur/self-host";
+export { DownloadGrants, DownloadLink } from "@devultur/self-host";
 
 export default createWorker({
   plugins: [...defaultPlugins({ transcode: { maxResolution: "1080p" } }), usageLog()],
@@ -22,7 +22,7 @@ export default createWorker({
 | `staticConfig(config)` | Applies the [rules](self-host.md#rules) to every request. Put it first: later plugins narrow it. |
 | `workerSecretAuth()` | Control routes require `Authorization: Bearer <WORKER_AUTH_SECRET>`; the transcode runner uploads with the same secret. |
 | `credentialPolicy(options?)` | Decides before a credential is issued. Without options it issues what is asked; `maxTtlSeconds: { viewer: 3600 }` caps a kind. |
-| `downloadLinks()` | `POST /v1/token/download` and `GET /v1/download/<id>` (needs the `DOWNLOAD_LINKS` Durable Object). Without it both answer `404`. |
+| `downloadLinks()` | `POST /v1/token/download` and `GET /v1/download/<id>` (needs the `DOWNLOAD_LINKS` Durable Object), and download grants: `/v1/token/grant` and `/v1/grant/*` (also need `DOWNLOAD_GRANTS`). Without it they answer `404`. |
 
 `createWorker()` refuses to start when no plugin authenticates requests, so dropping `workerSecretAuth()` without
 an auth plugin of yours fails at deploy, not in production.
@@ -42,6 +42,7 @@ interface WorkerPlugin {
   routes?: Array<{ path: string; app: Hono }>;
   issueCredential?: (context: Context, request: CredentialRequest) => CredentialDecision | Promise<CredentialDecision>;
   beforeLinkRedeem?: (context: Context, link: DownloadLinkInfo) => Response | null | Promise<Response | null>;
+  authorizeGrant?: (context: Context, request: GrantAccessRequest) => Response | null | Promise<Response | null>;
   authorizeLockChange?: (context: Context, request: LockChangeRequest) => LockChangeDecision | Promise<LockChangeDecision>;
   onLockAudit?: (context: Context, record: LockAuditRecord) => void | Promise<void>;
 }
@@ -94,8 +95,8 @@ updateRequestState(context, { context: { appId: "web" } });
 
 ## Hooks
 
-**`issueCredential`** runs before the Worker issues a viewer token, an upload token, a download link or the runner's
-service token. It gets the `kind`, the `scopes`, the `path` it is bound to and the requested `expiresAt` (epoch ms).
+**`issueCredential`** runs before the Worker issues a viewer token, an upload token, a download link, a download grant
+or the runner's service token. It gets the `kind`, the `scopes`, the `path` it is bound to and the requested `expiresAt` (epoch ms).
 Return `{ allow: false, response }` to refuse, or `{ allow: true, expiresAt?, claims? }` to issue it: `expiresAt`
 caps the expiry, and `claims` are added to a token. The hooks of every plugin run in order: the first refusal wins,
 the earliest `expiresAt` applies, and the claims of all of them are added.
@@ -120,6 +121,12 @@ allow gets `403 { "code": "token_rejected" }`; which claim failed is only logged
 **`beforeLinkRedeem`** runs before `GET /v1/download/<id>` spends a use of a link. Return a `Response` to refuse it
 (the use isn't spent), or `null` to let it go on. It gets the link's `storagePrefix`, `key` and plugin `context`.
 
+**`authorizeGrant`** runs before a download grant is used, once the Worker checked the grant is live and belongs to the
+request's storage prefix: `action` is `head`, `issue-link`, `delete-file` or `revoke` (its bearer), or `owner-revoke`
+(the owner, by its public id). It also gets the `grant` (its key, caps, `linksIssued`, metadata and the plugin `context`
+it was issued with, never its secret). Return a `Response` to refuse (a refused link spends nothing), or `null`. Use it
+to tie a grant to the credential that issued it, for example to refuse it once that credential is revoked.
+
 **`authorizeLockChange`** runs before the Worker changes a lock ([Retention and holds](object-lock.md)):
 `PUT /v1/lock/<key>` once per change, and `POST /v1/lock/hold` once per page. It gets:
 
@@ -173,7 +180,8 @@ const auditToD1: WorkerPlugin = {
 ## After the route
 
 - `getRouteResult(context)` tells a middleware that runs after `await next()` what the route did: `redeemedLink`
-  (the download link just redeemed), `originalDeleted` (`transcode.complete` deleted the original),
+  (the download link just redeemed), `issuedGrant` and `revokedGrant` (a download grant, with its public id; a revoke
+  says `by: "bearer"` or `"owner"`), `grantDeletedKey` (a grant deleted its file), `originalDeleted` (`transcode.complete` deleted the original),
   `originalRetained` (it kept a locked original instead) and
   `transcodeJob` (the job a runner callback belongs to, with its plugin `context`).
 - `getPendingUpload(context)`, before the route, returns the upload an upload URL points to: its key, storage key,

package/docs/guides/self-host.md

@@ -44,7 +44,7 @@ media Worker from `@devultur/self-host`:
 
 ```typescript
 import { createWorker } from "@devultur/self-host";
-export { DownloadLink } from "@devultur/self-host";
+export { DownloadGrants, DownloadLink } from "@devultur/self-host";
 
 export default createWorker();
 ```
@@ -98,7 +98,7 @@ It prints a config snippet with the new namespace's `id`. Paste that id into the
 
 #### 4. Write `wrangler.toml`
 
-Bind both buckets, the KV namespace and the `DownloadLink` Durable Object:
+Bind both buckets, the KV namespace and the `DownloadLink` and `DownloadGrants` Durable Objects:
 
 ```toml
 name = "media"
@@ -123,13 +123,22 @@ id = "<kv-namespace-id>"
 name = "DOWNLOAD_LINKS"
 class_name = "DownloadLink"
 
+[[durable_objects.bindings]]
+name = "DOWNLOAD_GRANTS"
+class_name = "DownloadGrants"
+
 [[migrations]]
 tag = "v1"
 new_sqlite_classes = ["DownloadLink"]
+
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["DownloadGrants"]
 ```
 
-Without the `DOWNLOAD_LINKS` binding, `POST /v1/token/download` answers `501`. For staging and production in one
-file, see [Per-environment config](#per-environment-config).
+Without the `DOWNLOAD_LINKS` binding, `POST /v1/token/download` answers `501`; without `DOWNLOAD_GRANTS`, the download
+grant routes do. A Worker deployed before download grants keeps its `v1` migration and adds `v2`. For staging and
+production in one file, see [Per-environment config](#per-environment-config).
 
 #### 5. Set the secrets
 
@@ -189,6 +198,10 @@ account_id = "<your-account-id>"
 tag = "v1"
 new_sqlite_classes = ["DownloadLink"]
 
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["DownloadGrants"]
+
 # Staging
 [env.staging]
 name = "media-staging"
@@ -209,6 +222,10 @@ id = "<staging-kv-namespace-id>"
 name = "DOWNLOAD_LINKS"
 class_name = "DownloadLink"
 
+[[env.staging.durable_objects.bindings]]
+name = "DOWNLOAD_GRANTS"
+class_name = "DownloadGrants"
+
 # Production
 [env.production]
 name = "media-production"
@@ -228,6 +245,10 @@ id = "<production-kv-namespace-id>"
 [[env.production.durable_objects.bindings]]
 name = "DOWNLOAD_LINKS"
 class_name = "DownloadLink"
+
+[[env.production.durable_objects.bindings]]
+name = "DOWNLOAD_GRANTS"
+class_name = "DownloadGrants"
 ```
 
 `vars` aren't inherited either: repeat `[env.<name>.vars]` (for example `TRANSCODE_RUNNER`) in each one. Then set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/convex",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Convex component for Devultur media: media records, uploads, transcodes, watch progress and React bindings",
   "keywords": [
     "convex",
@@ -69,8 +69,8 @@
     "docs"
   ],
   "dependencies": {
-    "@devultur/core": "1.5.2",
-    "@devultur/react": "1.5.2"
+    "@devultur/core": "1.6.0",
+    "@devultur/react": "1.6.0"
   },
   "peerDependencies": {
     "convex": ">=1.25.0",