@devultur/self-host 1.5.1 → 1.6.0

package/dist/transcode/container.js

@@ -1,7 +1,7 @@
 import {
   startTranscodeContainer,
   watchContainer
-} from "../chunk-PQO3X57I.js";
+} from "../chunk-BPHMKSQ7.js";
 
 // src/transcode/container.ts
 import { DurableObject } from "cloudflare:workers";

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/self-host",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Self-hosted media Worker for Cloudflare: R2 uploads, edge-cached delivery, image transforms, HLS transcode and captions",
   "keywords": [
     "cloudflare-workers",
@@ -47,7 +47,7 @@
     "@jsquash/resize": "2.1.1",
     "@jsquash/webp": "1.5.0",
     "hono": "^4.7.0",
-    "@devultur/core": "1.5.1"
+    "@devultur/core": "1.6.0"
   },
   "devDependencies": {
     "@cf-wasm/photon": "0.4.0",