@devultur/self-host 1.5.2 → 1.6.1

package/README.md

@@ -15,7 +15,7 @@ pnpm add @devultur/self-host
 ```typescript
 // src/index.ts
 import { createWorker } from "@devultur/self-host";
-export { DownloadLink } from "@devultur/self-host";
+export { DownloadGrants, DownloadLink } from "@devultur/self-host";
 
 export default createWorker();
 ```
@@ -42,9 +42,17 @@ id = "<your 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"]
 ```
 
 ```bash

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

@@ -420,6 +420,7 @@ async function watchContainer(exited, env) {
 }
 
 export {
+  isConstantTimeEqual,
   isBearerAuthorized,
   getRequestState,
   isAuthenticated,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as hono_types from 'hono/types';
 import { Context, MiddlewareHandler, Hono } from 'hono';
-import { Visibility, ObjectLock, SecurityPolicy, CacheRule, TranscodeSettings, RetentionMode, TranscodeOutputKeys, TranscodeOutputUrls } from '@devultur/core';
+import { Visibility, ObjectLock, SecurityPolicy, CacheRule, TranscodeSettings, DownloadGrantLinkCaps, RetentionMode, TranscodeOutputKeys, TranscodeOutputUrls } from '@devultur/core';
 import { T as TranscodeContainerNamespace } from './cloudflare-kZ7J3LQ2.js';
 
 /** What an upload token allows (claims `res`, `visibility`, `max_bytes`, `max_files`, `file_ttl`, `lock`). */
@@ -37,7 +37,20 @@ interface TranscodeJob {
     /** Plugin context of the request that launched the job, as it was. */
     context?: PluginContext;
 }
+/** A download grant as the Worker hands it to plugins, with its public id (`dgr_…`). */
+interface DownloadGrantEvent {
+    publicId: string;
+    grant: DownloadGrantInfo;
+}
 interface RouteResult {
+    /** `POST /v1/token/grant` issued this grant. */
+    issuedGrant?: DownloadGrantEvent;
+    /** The grant was revoked: by its bearer (`DELETE /v1/grant`, or with its file) or by the owner (by public id). */
+    revokedGrant?: DownloadGrantEvent & {
+        by: "bearer" | "owner";
+    };
+    /** `DELETE /v1/grant/file` deleted this file (its key, relative to the storage prefix). */
+    grantDeletedKey?: string;
     /** `GET /v1/download/{id}` redeemed this link (one use spent). */
     redeemedLink?: DownloadLinkInfo;
     /** `transcode.complete` deleted the video's original (`config.transcode.deleteOriginalOnSuccess`). */
@@ -73,6 +86,7 @@ interface WorkerEnv {
     WORKER_AUTH_SECRET?: string;
     TRANSCODE_WEBHOOK_SECRET?: string;
     DOWNLOAD_LINKS?: DurableObjectNamespace;
+    DOWNLOAD_GRANTS?: DurableObjectNamespace;
     IMAGE_TRANSFORMS?: string;
     IMAGE_TRANSFORMS_MAX_MEGAPIXELS?: string;
 }
@@ -233,6 +247,79 @@ declare function isAuthenticated(context: AnyContext$2): boolean;
  */
 declare function updateRequestState(context: AnyContext$2, patch: RequestStatePatch): RequestState;
 
+interface DownloadGrantRecord {
+    /** Grant id, unique within its file. */
+    id: string;
+    /** SHA-256 (hex) of the grant's secret. */
+    secretHash: string;
+    /** Full storage key (with the storage prefix). */
+    storageKey: string;
+    /** Virtual key (`{visibility}/…`). */
+    key: string;
+    /** R2 `version` of the object the grant was issued for: a file uploaded later at the same key isn't covered. */
+    version: string;
+    /** Storage prefix the grant was issued under. */
+    storagePrefix: string;
+    /** Epoch ms. */
+    expiresAt: number;
+    link: DownloadGrantLinkCaps;
+    maxLinks: number;
+    linksIssued: number;
+    canDelete: boolean;
+    metadata?: Record<string, string>;
+    /** Plugin context of the request that issued the grant (opaque to the Worker); its links inherit it. */
+    context?: PluginContext;
+    /** Epoch ms. */
+    createdAt: number;
+    /** Epoch ms, or null while live. */
+    revokedAt: number | null;
+}
+/** A grant without its secret hash: what the Worker hands to routes, hooks and the owner. */
+type DownloadGrantInfo = Omit<DownloadGrantRecord, "secretHash">;
+/** Storage surface of a DO that the class uses (the Workers one satisfies it; tests pass a Map). */
+interface DownloadGrantStorage {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    list<T>(options: {
+        prefix: string;
+    }): Promise<Map<string, T>>;
+    delete(key: string): Promise<boolean>;
+    setAlarm(scheduledTime: number): Promise<void>;
+    deleteAlarm(): Promise<void>;
+}
+interface DownloadGrantState {
+    storage: DownloadGrantStorage;
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+}
+declare class DownloadGrants {
+    private readonly state;
+    private readonly storage;
+    constructor(state: DownloadGrantState);
+    fetch(request: Request): Promise<Response>;
+    private handlerFor;
+    private create;
+    private recordOf;
+    /** The record whose secret hash matches, live or not, or 401. */
+    private matchingRecord;
+    /** The live record whose secret hash matches, or the response explaining why not. */
+    private liveRecord;
+    private identify;
+    private authorize;
+    /** Spends one link: caps first (a refused link spends nothing), then the total. */
+    private issue;
+    private refund;
+    /** Without `secretHash` the route already authorized the owner; with it, only the grant's own secret revokes it. */
+    private revoke;
+    private getOne;
+    private records;
+    private list;
+    private revokeAll;
+    /** Alarm at the earliest expiry among the stored grants; none left: no alarm. */
+    private scheduleAlarm;
+    /** Drops the grants past their expiry (revoked ones stay listed until then) and schedules the next alarm. */
+    alarm(): Promise<void>;
+}
+
 declare const LOCK_AUDIT_PREFIX = "__lock-audit/";
 type LockAuditAction = "set" | "extend" | "shorten" | "remove" | "hold" | "release" | "delete_rejected" | "overwrite_rejected" | "original_retained";
 interface LockAuditRecord {
@@ -253,13 +340,19 @@ interface LockAuditRecord {
     reason?: string;
 }
 
-/** What is being issued: a viewer token, an upload token, a download link or the transcode runner's token. */
-type CredentialKind = "viewer" | "upload" | "download-link" | "service";
+/**
+ * What is being issued: a viewer token, an upload token, a download link, a download grant or the transcode runner's
+ * token.
+ */
+type CredentialKind = "viewer" | "upload" | "download-link" | "download-grant" | "service";
 interface CredentialRequest {
     kind: CredentialKind;
     /** Scopes the credential will carry. */
     scopes: string[];
-    /** What it is bound to: the upload prefix (`asset/…/`), the download link's key or the original being transcoded. */
+    /**
+     * What it is bound to: the upload prefix (`asset/…/`), the key of the download link or grant, or the original being
+     * transcoded.
+     */
     path?: string;
     /** Expiry the request asked for (epoch ms). */
     expiresAt: number;
@@ -286,6 +379,20 @@ type AnyContext$1 = Context<any>;
 type IssueCredentialHook = (context: AnyContext$1, request: CredentialRequest) => CredentialDecision | Promise<CredentialDecision>;
 /** A response refuses the redemption (returned as is, and the use is NOT spent); `null` lets it go on. */
 type BeforeLinkRedeemHook = (context: AnyContext$1, link: DownloadLinkInfo) => Response | null | Promise<Response | null>;
+/**
+ * What a download grant is used for: its bearer reads the file's head, issues a link, deletes the file or revokes the
+ * grant; or the owner revokes it by its public id.
+ */
+type GrantAction = "head" | "issue-link" | "delete-file" | "revoke" | "owner-revoke";
+interface GrantAccessRequest {
+    action: GrantAction;
+    grant: DownloadGrantInfo;
+}
+/**
+ * Before a download grant is used (or revoked by the owner), once the Worker checked it belongs to the request's storage
+ * prefix. A response refuses (returned as is; a refused link spends nothing); `null` lets it go on.
+ */
+type AuthorizeGrantHook = (context: AnyContext$1, request: GrantAccessRequest) => Response | null | Promise<Response | null>;
 /**
  * What a lock change does: `set` a first (or expired) retention, `extend` it, `shorten` or `remove` it; `hold` or
  * `release` a hold.
@@ -317,6 +424,7 @@ type OnLockAuditHook = (context: AnyContext$1, record: LockAuditRecord) => void
 interface PluginHooks {
     issueCredential: IssueCredentialHook[];
     beforeLinkRedeem: BeforeLinkRedeemHook[];
+    authorizeGrant: AuthorizeGrantHook[];
     authorizeLockChange: AuthorizeLockChangeHook[];
     onLockAudit: OnLockAuditHook[];
 }
@@ -349,6 +457,8 @@ interface WorkerPlugin {
     issueCredential?: IssueCredentialHook;
     /** Before `GET /v1/download/{id}` spends a use of a link that still has one. */
     beforeLinkRedeem?: BeforeLinkRedeemHook;
+    /** Before a download grant is used, or revoked by its public id. */
+    authorizeGrant?: AuthorizeGrantHook;
     /** Before `PUT /v1/lock` changes a lock: refuse it, or approve a governance bypass. */
     authorizeLockChange?: AuthorizeLockChangeHook;
     /** After every lock event, with its audit record. Runs after the response. */
@@ -374,6 +484,10 @@ interface DownloadLinkRecord {
     storagePrefix: string;
     /** Plugin context of the request that issued the link (opaque to the Worker). */
     context?: PluginContext;
+    /** Public id (`dgr_…`) of the download grant that issued the link. */
+    grantId?: string;
+    /** Opaque metadata the link was issued with. */
+    metadata?: Record<string, string>;
 }
 /** Storage surface of a DO that the class uses (the Workers one satisfies it; tests pass a Map). */
 interface DownloadLinkStorage {
@@ -618,6 +732,7 @@ declare const WorkerAuthErrorCode: {
  * - `/health` and the playback metrics endpoint: public by design.
  * - Media delivery: public media is tokenless; the route itself requires a viewer token for private media.
  * - Download links: the opaque link id is the credential.
+ * - The bearer's download grant routes: the grant is the credential (the route checks it).
  * - Webhooks: they check their own shared secret.
  */
 declare function isOpenRoute(method: string, path: string): boolean;
@@ -665,6 +780,18 @@ declare function isObjectExpired(customMetadata: Record<string, string> | undefi
 /** The unit's tag: a hash (Cloudflare's tags are case-insensitive but paths aren't). */
 declare function edgeCacheTag(storagePrefix: string, virtualKey: string): Promise<string>;
 
+/** A grant as its bearer presented it: its public id and record (no secret). */
+interface IdentifiedGrant {
+    publicId: string;
+    grant: DownloadGrantInfo;
+}
+/**
+ * The grant in the request's `Authorization: Bearer`, live or not, or the response refusing it (`401 invalid_grant`,
+ * `grant_in_query`, `501`). For a platform that resolves the grant's tenant before authorizing the request: the
+ * routes still check it's live, belongs to the request's storage prefix, and run the hooks.
+ */
+declare function identifyDownloadGrant(anyContext: Context<any>): Promise<IdentifiedGrant | Response>;
+
 /** `Cache-Control` served: the one stored on the object (for private, no shared caches) or the one for a generated id. */
 declare function servedCacheControl(stored: string | undefined, isPrivate: boolean): string;
 
@@ -770,4 +897,4 @@ interface CreateWorkerOptions {
 }
 declare function createWorker(options?: CreateWorkerOptions): Hono<WorkerApp, hono_types.BlankSchema, "/">;
 
-export { type AllowedCredential, type AssetListEntry, type AuthorizeLockChangeHook, type BeforeLinkRedeemHook, type ComposedPlugins, type ContentSniffingMode, type CreateWorkerOptions, type CredentialDecision, type CredentialKind, type CredentialPolicyOptions, type CredentialRequest, DownloadLink, type DownloadLinkInfo, type DownloadLinkRecord, type DownloadLinkStorage, ENCRYPTION_KEY_MISSING_CODE, type EncodeMetrics, HOLD_PAGE_SIZE, type HoldSkip, type ImageTransformParams, type IssueCredentialHook, type Json, KEYS_BUCKET_MISSING_CODE, LOCK_AUDIT_PREFIX, LOCK_HOLD_HEADER, LOCK_METADATA_KEY, LOCK_SIDECAR_PREFIX, LOCK_UNTIL_HEADER, type LockAuditAction, type LockAuditRecord, type LockChangeAction, type LockChangeDecision, type LockChangeRequest, type LockLookupOptions, type LockSidecar, type LockSource, MAX_ASSET_LIST_LIMIT, MAX_EXPIRED_LOOKUPS, MAX_UPLOAD_TOKEN_TTL_SECONDS, MaxResolution, ObjectMeta, type OnLockAuditHook, type PendingUploadInfo, type PluginContext, type PluginMiddleware, type PluginRoute, type PrefixDeleteOptions, type PrefixDeleteResult, type PrefixWalkOptions, RESERVED_LOCK_PREFIXES, type RawStorageClass, type RequestAccess, type RequestState, type RequestStatePatch, type RetainedObject, type RetainedSummary, type RouteResult, type StoredObjectLock, TOKEN_REJECTED_CODE, type TranscodeConfig, type TranscodeJob, UPLOAD_TOKEN_TYPE, type UploadGrant, type UploadRules, type UploadTypeRule, type WorkerApp, WorkerAuthErrorCode, type WorkerConfig, type WorkerEnv, type WorkerPlugin, type WorkerVariables, cancelPendingUpload, createWorker, credentialPolicy, defaultPlugins, deletePrefix, deletePrefixRespectingLocks, downloadLinks, edgeCacheTag, getPendingUpload, getRequestState, getRouteResult, hashKey, imageOriginAuthorization, isAuthenticated, isImageOriginRequest, isObjectExpired, isOpenRoute, isServiceToken, isUploadUrl, isVariantKey, logEncodeMetrics, parseEncodeMetrics, parseTransformParams, readImageOriginScope, readObjectLock, readStoryboardKey, readTokenScopes, readTranscodeOutputKeys, readTranscodeOutputs, retainedSummary, servedCacheControl, staticConfig, storageKey, updateRequestState, uploadGrantFromClaims, variantPrefix, vcpuSecondsPerVideoMinute, verifyViewerToken, withOutputUrls, workerSecretAuth };
+export { type AllowedCredential, type AssetListEntry, type AuthorizeGrantHook, type AuthorizeLockChangeHook, type BeforeLinkRedeemHook, type ComposedPlugins, type ContentSniffingMode, type CreateWorkerOptions, type CredentialDecision, type CredentialKind, type CredentialPolicyOptions, type CredentialRequest, type DownloadGrantEvent, type DownloadGrantInfo, type DownloadGrantRecord, type DownloadGrantState, type DownloadGrantStorage, DownloadGrants, DownloadLink, type DownloadLinkInfo, type DownloadLinkRecord, type DownloadLinkStorage, ENCRYPTION_KEY_MISSING_CODE, type EncodeMetrics, type GrantAccessRequest, type GrantAction, HOLD_PAGE_SIZE, type HoldSkip, type IdentifiedGrant, type ImageTransformParams, type IssueCredentialHook, type Json, KEYS_BUCKET_MISSING_CODE, LOCK_AUDIT_PREFIX, LOCK_HOLD_HEADER, LOCK_METADATA_KEY, LOCK_SIDECAR_PREFIX, LOCK_UNTIL_HEADER, type LockAuditAction, type LockAuditRecord, type LockChangeAction, type LockChangeDecision, type LockChangeRequest, type LockLookupOptions, type LockSidecar, type LockSource, MAX_ASSET_LIST_LIMIT, MAX_EXPIRED_LOOKUPS, MAX_UPLOAD_TOKEN_TTL_SECONDS, MaxResolution, ObjectMeta, type OnLockAuditHook, type PendingUploadInfo, type PluginContext, type PluginMiddleware, type PluginRoute, type PrefixDeleteOptions, type PrefixDeleteResult, type PrefixWalkOptions, RESERVED_LOCK_PREFIXES, type RawStorageClass, type RequestAccess, type RequestState, type RequestStatePatch, type RetainedObject, type RetainedSummary, type RouteResult, type StoredObjectLock, TOKEN_REJECTED_CODE, type TranscodeConfig, type TranscodeJob, UPLOAD_TOKEN_TYPE, type UploadGrant, type UploadRules, type UploadTypeRule, type WorkerApp, WorkerAuthErrorCode, type WorkerConfig, type WorkerEnv, type WorkerPlugin, type WorkerVariables, cancelPendingUpload, createWorker, credentialPolicy, defaultPlugins, deletePrefix, deletePrefixRespectingLocks, downloadLinks, edgeCacheTag, getPendingUpload, getRequestState, getRouteResult, hashKey, identifyDownloadGrant, imageOriginAuthorization, isAuthenticated, isImageOriginRequest, isObjectExpired, isOpenRoute, isServiceToken, isUploadUrl, isVariantKey, logEncodeMetrics, parseEncodeMetrics, parseTransformParams, readImageOriginScope, readObjectLock, readStoryboardKey, readTokenScopes, readTranscodeOutputKeys, readTranscodeOutputs, retainedSummary, servedCacheControl, staticConfig, storageKey, updateRequestState, uploadGrantFromClaims, variantPrefix, vcpuSecondsPerVideoMinute, verifyViewerToken, withOutputUrls, workerSecretAuth };