nuxt-media-library 0.0.44 → 0.0.48

package/README.md

@@ -82,6 +82,77 @@ If you use the uploader component in Nuxt, provide config via the Nuxt plugin
 </template>
 ```
 
+### Authorizing `/manage` with media grants
+
+The module's server proxies forward `/api/media-library/manage/*` to the
+media library. Without an `authorize` hook they forward the browser's
+credentials (or your static headers) as before. With one, every `/manage`
+request is checked by your rules and sent upstream with a short-lived
+**media grant** scoped to exactly that request (server:
+`docs/security/media-grants.md`). Your app never re-implements the
+endpoints, and no long-lived credential reaches the media library from the
+browser.
+
+```ts
+// server/api/media-library/[...].ts
+import { createMLCatchAllProxy, specFromNeed } from '@fritill-team/nuxt-media-library/server'
+
+const COVER = { kind: 'image', visibility: 'public', allowedMimeTypes: ['image/*'], maxSizeBytes: 5_000_000 }
+
+export default createMLCatchAllProxy({
+  async authorize(event, need) {
+    const user = await requireUser(event)              // your session
+    const subject = String(user.id)
+    if (need.scope === 'upload' && !need.sessionId) {  // creating an upload
+      return user.canUpload ? { scopes: ['upload'], profile: COVER, subject } : false
+    }
+    if (need.taskId) return false                      // or look up the task's asset
+    if (need.scope === 'manage:*') return user.isAdmin // tenant-wide list, stream
+    return (need.assetIds ?? []).every(id => user.canEdit(id))
+      ? { ...specFromNeed(need), subject }
+      : false
+  },
+})
+```
+
+- `need`: `{ scope, method, path, assetIds?, taskId?, sessionId?, upload? }`
+  (`upload` is the create body: MIME type, size, file name).
+- Return `false` (403), `true` (the need as is), or a spec
+  `{ scopes, assetIds?, sessionIds?, profile?, subject?, ttlSeconds? }`.
+  Creating an upload needs a `profile`: kind, visibility and processing come
+  from it, not from the browser. `manage:*` is only accepted for requests
+  that need it.
+- Grants are issued with the private runtime config
+  `mediaLibrary.serviceToken` (`NUXT_MEDIA_LIBRARY_SERVICE_TOKEN`), or pass
+  `issueGrant(spec)` to get them from your backend (e.g. the Python
+  client's `create_grant_router`). They are cached per spec until shortly
+  before they expire; an upload's parts, finalize and abort reuse the grant
+  that created the session.
+- `/delivery` and the processing metadata routes are not affected.
+
+### Showing assets of several services: read grants
+
+Every link comes from the media library; each service decides only for its
+own assets by returning a read grant (`mlg_…`, e.g. the Python client's
+`client.grants.read(ids)`) with the data that references them. Hand the
+grants to the module and every preview resolve sends them in one request:
+
+```ts
+const { addMediaGrants } = useMLMediaGrants()
+
+const lesson = await $fetch('/api/lessons/42')        // course service
+const profile = await $fetch('/api/profile')          // profile service
+addMediaGrants(lesson.mediaGrant, profile.mediaGrant) // "mlg_…" or { grant, expiresAt }
+```
+
+- Live grants (up to 10, latest expiry first) go in `X-Media-Grants` on
+  `POST /api/media-library/delivery/assets/resolve`; the proxy forwards
+  them. Expired ones are dropped.
+- Assets no grant lists come back `forbidden` from the server and are shown
+  as broken (`isBroken(id)`), as before; they are resolved again whenever
+  grants are added.
+- Grants live in the browser only, never in server-side state.
+
 ### Vue installation (non-Nuxt)
 
 ```bash

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "media-library",
   "configKey": "mediaLibrary",
-  "version": "0.0.44",
+  "version": "0.0.48",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -93,7 +93,10 @@ const module$1 = defineNuxtModule({
       ...existingPrivate,
       baseURL: existingPrivate.baseURL ?? envBaseURL ?? options.baseURL ?? "",
       routes: existingPrivate.routes ?? options.routes ?? routes,
-      headers: resolvedHeaders
+      headers: resolvedHeaders,
+      // Only read when a proxy has `authorize` and no `issueGrant` (media
+      // grants). Declared so NUXT_MEDIA_LIBRARY_SERVICE_TOKEN applies.
+      serviceToken: existingPrivate.serviceToken ?? ""
     };
     nuxt.options.runtimeConfig.public.mediaLibrary = {
       ...existingPublic,

package/dist/runtime/components/MLAssetManager/Processing.vue

@@ -1,6 +1,7 @@
 <script setup>
 import { computed, ref, onMounted, watch } from "vue";
 import { useMLResourcePolicy } from "../../composables/resourcePolicy/useMLResourcePolicy";
+import { mediaGrantHeaders } from "../../composables/useMLMediaGrants";
 const props = defineProps({
   assetId: { type: String, required: true },
   manager: { type: Object, required: true }
@@ -34,7 +35,8 @@ async function resolveVideoUrl() {
   }
   try {
     const result = await $fetch(
-      `/api/media-library/delivery/assets/${encodeURIComponent(props.assetId)}`
+      `/api/media-library/delivery/assets/${encodeURIComponent(props.assetId)}`,
+      { headers: mediaGrantHeaders() }
     );
     videoUrl.value = result.downloadUrl ?? null;
   } catch {

package/dist/runtime/components/MLUploader/Item.d.vue.ts

@@ -12,14 +12,14 @@ type __VLS_Props = {
     uploadFailedText?: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    remove: () => any;
     error: (message: string) => any;
+    remove: () => any;
     progress: (percent: number) => any;
     uploaded: (assetIds: string[]) => any;
     canceled: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onRemove?: (() => any) | undefined;
     onError?: ((message: string) => any) | undefined;
+    onRemove?: (() => any) | undefined;
     onProgress?: ((percent: number) => any) | undefined;
     onUploaded?: ((assetIds: string[]) => any) | undefined;
     onCanceled?: (() => any) | undefined;

package/dist/runtime/components/MLUploader/Item.vue.d.ts

@@ -12,14 +12,14 @@ type __VLS_Props = {
     uploadFailedText?: string;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    remove: () => any;
     error: (message: string) => any;
+    remove: () => any;
     progress: (percent: number) => any;
     uploaded: (assetIds: string[]) => any;
     canceled: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onRemove?: (() => any) | undefined;
     onError?: ((message: string) => any) | undefined;
+    onRemove?: (() => any) | undefined;
     onProgress?: ((percent: number) => any) | undefined;
     onUploaded?: ((assetIds: string[]) => any) | undefined;
     onCanceled?: (() => any) | undefined;

package/dist/runtime/composables/useMLAssetPreview.js

@@ -1,10 +1,13 @@
 import { ref } from "vue";
 import { $fetch } from "ofetch";
+import { mediaGrantHeaders } from "./useMLMediaGrants.js";
+import { onMediaGrantsAdded } from "../utils/grants/listeners.js";
 const assets = ref({});
 const pending = ref(/* @__PURE__ */ new Set());
 const broken = ref(/* @__PURE__ */ new Set());
 const forbidden = ref(/* @__PURE__ */ new Set());
 const loading = ref(false);
+const lockedByGrant = /* @__PURE__ */ new Set();
 function computeSources(asset) {
   const sources = [];
   for (const rendition of asset.renditions ?? []) {
@@ -62,9 +65,13 @@ async function fetchAssets(ids) {
   try {
     const result = await $fetch("/api/media-library/delivery/assets/resolve", {
       method: "POST",
-      body: { assetIds: targetIds }
+      body: { assetIds: targetIds },
+      headers: mediaGrantHeaders()
     });
     for (const item of result.items ?? []) {
+      if (item.status === "forbidden") {
+        lockedByGrant.add(item.assetId);
+      }
       if (item.status !== "ok" || !item.asset) {
         broken.value.add(item.assetId);
         continue;
@@ -135,6 +142,15 @@ async function flushPending() {
   pending.value.clear();
   await fetchAssets(ids);
 }
+onMediaGrantsAdded(() => {
+  if (!lockedByGrant.size) return;
+  for (const id of lockedByGrant) {
+    broken.value.delete(id);
+    pending.value.add(id);
+  }
+  lockedByGrant.clear();
+  if (import.meta.client) scheduleFetch();
+});
 export const useMLAssetPreview = () => {
   return {
     assets,

package/dist/runtime/composables/useMLMediaGrants.d.ts

@@ -0,0 +1,23 @@
+import type { GrantInput, HeldGrant } from '../utils/grants/store.js';
+/**
+ * Add read grants your services returned (`"mlg_…"` or `{ grant, expiresAt }`).
+ * Assets the server answered "forbidden" for are resolved again, since a
+ * new grant may list them. Every delivery resolve sends the live grants in `X-Media-Grants`.
+ */
+declare function addMediaGrants(...grants: GrantInput[]): void;
+declare function clearMediaGrants(): void;
+/** Headers to send on a `/delivery` request. */
+declare function mediaGrantHeaders(): Record<string, string>;
+export { addMediaGrants, clearMediaGrants, mediaGrantHeaders };
+export declare const useMLMediaGrants: () => {
+    grants: import("vue").Ref<{
+        grant: string;
+        expiresAt: number;
+    }[], HeldGrant[] | {
+        grant: string;
+        expiresAt: number;
+    }[]>;
+    addMediaGrants: typeof addMediaGrants;
+    clearMediaGrants: typeof clearMediaGrants;
+    mediaGrantHeaders: typeof mediaGrantHeaders;
+};

package/dist/runtime/composables/useMLMediaGrants.js

@@ -0,0 +1,22 @@
+import { ref } from "vue";
+import { grantHeaders, mergeGrants } from "../utils/grants/store.js";
+import { notifyMediaGrantsAdded } from "../utils/grants/listeners.js";
+const held = ref([]);
+function addMediaGrants(...grants) {
+  if (!import.meta.client) return;
+  held.value = mergeGrants(held.value, grants);
+  notifyMediaGrantsAdded();
+}
+function clearMediaGrants() {
+  held.value = [];
+}
+function mediaGrantHeaders() {
+  return import.meta.client ? grantHeaders(held.value) : {};
+}
+export { addMediaGrants, clearMediaGrants, mediaGrantHeaders };
+export const useMLMediaGrants = () => ({
+  grants: held,
+  addMediaGrants,
+  clearMediaGrants,
+  mediaGrantHeaders
+});

package/dist/runtime/composables/useMLServiceUpload.d.ts

@@ -0,0 +1,36 @@
+import type { UploadProgress } from '../types/uploader.js';
+import type { ServiceUploadOptions, ServiceUploadResult } from '../utils/uploader/serviceUpload.js';
+export type { ServiceUploadOptions, ServiceUploadResult } from '../utils/uploader/serviceUpload.js';
+/**
+ * Upload a file through one of the app's backend services (py_client
+ * `create_upload_router`). The service starts the upload and hands out a
+ * grant for that session; the file goes straight to the media library.
+ *
+ * ```ts
+ * const { upload, abort, uploading, progress, error } = useMLServiceUpload()
+ * const { sessionId, assetId } = await upload(file, {
+ *   start: '/api/videos/uploads',
+ *   body: { profile: 'lesson-video', context: { lessonId } },
+ *   onProgress: p => console.log(p.percent),
+ * })
+ * await $fetch(`/api/videos/lessons/${lessonId}/video`, { method: 'PUT', body: { sessionId, assetId } })
+ * ```
+ *
+ * One upload at a time per call of the composable; call it once per
+ * upload field. The media library must allow the site's origin (CORS).
+ */
+export declare function useMLServiceUpload(): {
+    upload: (file: File, options: ServiceUploadOptions) => Promise<ServiceUploadResult>;
+    abort: () => void;
+    uploading: import("vue").Ref<boolean, boolean>;
+    progress: import("vue").Ref<{
+        totalBytes: number;
+        uploadedBytes: number;
+        percent: number;
+    } | null, UploadProgress | {
+        totalBytes: number;
+        uploadedBytes: number;
+        percent: number;
+    } | null>;
+    error: import("vue").Ref<unknown, unknown>;
+};

package/dist/runtime/composables/useMLServiceUpload.js

@@ -0,0 +1,32 @@
+import { ref } from "vue";
+import { ChunkUploader } from "../utils/uploader/uploader.js";
+import { createServiceUpload } from "../utils/uploader/serviceUpload.js";
+export function useMLServiceUpload() {
+  const uploading = ref(false);
+  const progress = ref(null);
+  const error = ref(null);
+  const runner = createServiceUpload({
+    fetch: (url, opts) => $fetch(url, opts),
+    createUploader: (cfg) => new ChunkUploader(cfg)
+  });
+  async function upload(file, options) {
+    uploading.value = true;
+    progress.value = null;
+    error.value = null;
+    try {
+      return await runner.upload(file, {
+        ...options,
+        onProgress: (p) => {
+          progress.value = p;
+          options.onProgress?.(p);
+        }
+      });
+    } catch (err) {
+      error.value = err;
+      throw err;
+    } finally {
+      uploading.value = false;
+    }
+  }
+  return { upload, abort: runner.abort, uploading, progress, error };
+}

package/dist/runtime/server/create-ml-proxy.d.ts

@@ -1,4 +1,5 @@
 import type { H3Event } from 'h3';
+import type { MLAuthorize, MLIssueGrant } from './grants.js';
 export type MLProxyType = 'assets' | 'uploads' | 'delivery' | 'processing' | 'resource-policy';
 export interface MLProxyOptions {
     /**
@@ -8,6 +9,21 @@ export interface MLProxyOptions {
      * from runtimeConfig.
      */
     requestHeaders?: (event: H3Event, incoming: Record<string, string>) => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Media grants (server docs/security/media-grants.md). When set, `/manage`
+     * requests no longer carry the browser's or the static credentials: for
+     * each one the proxy asks `authorize(event, need)` (your rules: the user
+     * from your session, the asset ids in `need`) and sends a short-lived
+     * grant scoped to exactly that. `false` → 403. Unknown `/manage` routes →
+     * 404. `/delivery` is not affected.
+     */
+    authorize?: MLAuthorize<H3Event>;
+    /**
+     * How grants are issued. Default: `POST {baseURL}/manage/grants` with the
+     * private runtime config `mediaLibrary.serviceToken` (the Nuxt server is
+     * the app backend). Pass your own to ask your backend instead.
+     */
+    issueGrant?: MLIssueGrant;
 }
 /**
  * Create a Nitro event handler that replicates one of the media library's

package/dist/runtime/server/create-ml-proxy.js

@@ -1,5 +1,14 @@
-import { createError, defineEventHandler, getRequestHeaders, getRequestURL, proxyRequest, readRawBody } from "h3";
+import { createError, defineEventHandler, getRequestHeaders, getRequestURL, getRequestWebStream, proxyRequest, readBody, sendProxy, setResponseStatus } from "h3";
 import { useRuntimeConfig } from "#imports";
+import {
+  cachedIssuer,
+  grantFor,
+  grantNeed,
+  MLGrantIssueError,
+  serviceTokenIssuer,
+  SessionGrants,
+  stripProfileFields
+} from "./grants.js";
 const HOP_BY_HOP = ["connection", "transfer-encoding", "keep-alive", "upgrade", "expect", "host"];
 function stripHopByHop(headers) {
   return Object.fromEntries(Object.entries(headers).filter(([k]) => !HOP_BY_HOP.includes(k)));
@@ -33,7 +42,7 @@ function resolveRoute(route, params) {
     return value === void 0 ? "" : String(value);
   });
 }
-async function handleAssetsProxy(event, baseURL, staticHeaders, assetsBase, requestHeadersFn) {
+async function handleAssetsProxy(event, baseURL, staticHeaders, assetsBase, options) {
   const reqUrl = getRequestURL(event);
   const prefix = "/api/media-library/manage/assets";
   const rest = reqUrl.pathname.slice(prefix.length);
@@ -51,19 +60,15 @@ async function handleAssetsProxy(event, baseURL, staticHeaders, assetsBase, requ
   if (isItem && !["GET", "PATCH", "DELETE"].includes(method)) throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
   if (isSubResource && method !== "GET") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
   const upstreamUrl = buildUpstreamUrl(baseURL, `${assetsBase}${trimmedRest}`, reqUrl.search);
-  const headers = await buildProxyHeaders(event, staticHeaders, requestHeadersFn);
-  const result = await proxyRequest(event, upstreamUrl.toString(), { headers, streamRequest: true });
-  if (event.node.res.statusCode >= 400) {
-    console.error(`[media-library] assets-proxy upstream responded ${event.node.res.statusCode} for ${method} ${upstreamUrl}`);
-  }
-  return result;
+  return forward(event, "assets", upstreamUrl, method, baseURL, staticHeaders, options);
 }
-async function handleUploadsProxy(event, baseURL, staticHeaders, routes, requestHeadersFn) {
+async function handleUploadsProxy(event, baseURL, staticHeaders, routes, options) {
   const reqUrl = getRequestURL(event);
   const prefix = "/api/media-library/manage/uploads";
   const rest = reqUrl.pathname.slice(prefix.length);
   const method = event.node.req.method || "GET";
   let upstreamPath = "";
+  let upstreamMethod = method;
   if (rest === "/sessions" || rest === "/sessions/") {
     if (method !== "POST") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
     upstreamPath = routes.createSession;
@@ -79,7 +84,8 @@ async function handleUploadsProxy(event, baseURL, staticHeaders, routes, request
       if (method !== "POST") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
       upstreamPath = resolveRoute(routes.finalize, { id: finalizeMatch[1] });
     } else if (abortMatch && routes.abort) {
-      if (method !== "DELETE") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
+      if (method !== "POST" && method !== "DELETE") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
+      upstreamMethod = "POST";
       upstreamPath = resolveRoute(routes.abort, { id: abortMatch[1] });
     } else if (sessionMatch) {
       if (method !== "GET") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
@@ -88,14 +94,9 @@ async function handleUploadsProxy(event, baseURL, staticHeaders, routes, request
   }
   if (!upstreamPath) throw createError({ statusCode: 404, statusMessage: "Unknown upload route" });
   const upstreamUrl = buildUpstreamUrl(baseURL, upstreamPath, reqUrl.search);
-  const headers = await buildProxyHeaders(event, staticHeaders, requestHeadersFn);
-  const result = await proxyRequest(event, upstreamUrl.toString(), { headers, streamRequest: true });
-  if (event.node.res.statusCode >= 400) {
-    console.error(`[media-library] uploads-proxy upstream responded ${event.node.res.statusCode} for ${method} ${upstreamUrl}`);
-  }
-  return result;
+  return forward(event, "uploads", upstreamUrl, upstreamMethod, baseURL, staticHeaders, options);
 }
-async function handleDeliveryProxy(event, baseURL, staticHeaders, requestHeadersFn) {
+async function handleDeliveryProxy(event, baseURL, staticHeaders, options) {
   const reqUrl = getRequestURL(event);
   const prefix = "/api/media-library/delivery";
   const rest = reqUrl.pathname.slice(prefix.length);
@@ -109,14 +110,14 @@ async function handleDeliveryProxy(event, baseURL, staticHeaders, requestHeaders
   if (isResolve && method !== "POST") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
   if (isItem && method !== "GET") throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
   const upstreamUrl = buildUpstreamUrl(baseURL, `/delivery${trimmedRest}`, reqUrl.search);
-  const headers = await buildProxyHeaders(event, staticHeaders, requestHeadersFn);
+  const headers = await buildProxyHeaders(event, staticHeaders, options?.requestHeaders);
   const result = await proxyRequest(event, upstreamUrl.toString(), { headers, streamRequest: true });
   if (event.node.res.statusCode >= 400) {
     console.error(`[media-library] delivery-proxy upstream responded ${event.node.res.statusCode} for ${method} ${upstreamUrl}`);
   }
   return result;
 }
-async function handleProcessingProxy(event, baseURL, staticHeaders, requestHeadersFn) {
+async function handleProcessingProxy(event, baseURL, staticHeaders, options) {
   const reqUrl = getRequestURL(event);
   const prefix = "/api/media-library/manage/processing";
   const rest = reqUrl.pathname.slice(prefix.length);
@@ -124,15 +125,9 @@ async function handleProcessingProxy(event, baseURL, staticHeaders, requestHeade
   const allowed = /^\/stream$/.test(rest) && method === "GET" || /^\/assets\/[^/]+\/stream$/.test(rest) && method === "GET" || /^\/assets\/[^/]+\/tasks$/.test(rest) && method === "GET" || /^\/assets\/[^/]+\/process$/.test(rest) && method === "POST" || /^\/tasks\/[^/]+\/retry$/.test(rest) && method === "POST" || /^\/tasks\/[^/]+\/configure$/.test(rest) && method === "POST" || /^\/processors$/.test(rest) && method === "GET";
   if (!allowed) throw createError({ statusCode: 404, statusMessage: "Not found" });
   const upstreamUrl = buildUpstreamUrl(baseURL, `/manage/processing${rest}`, reqUrl.search);
-  const headers = await buildProxyHeaders(event, staticHeaders, requestHeadersFn);
-  const hasBody = method !== "GET" && method !== "HEAD";
-  const body = hasBody ? await readRawBody(event, false) : void 0;
-  return proxyRequest(event, upstreamUrl.toString(), {
-    headers,
-    ...body !== void 0 ? { body } : {}
-  });
+  return forward(event, "processing", upstreamUrl, method, baseURL, staticHeaders, options);
 }
-async function handleResourcePolicyProxy(event, baseURL, staticHeaders, requestHeadersFn) {
+async function handleResourcePolicyProxy(event, baseURL, staticHeaders, options) {
   const reqUrl = getRequestURL(event);
   const prefix = "/api/media-library/manage/resource-policies";
   const rest = reqUrl.pathname.slice(prefix.length);
@@ -152,10 +147,113 @@ async function handleResourcePolicyProxy(event, baseURL, staticHeaders, requestH
   if (isCollection && method !== "GET" && !(isDev && method === "POST")) throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
   if (isItem && method !== "GET" && !(isDev && writeMethods.includes(method))) throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
   const upstreamUrl = buildUpstreamUrl(baseURL, `/manage/resource-policies${trimmedRest}`, reqUrl.search);
-  const headers = await buildProxyHeaders(event, staticHeaders, requestHeadersFn);
-  const result = await proxyRequest(event, upstreamUrl.toString(), { headers, streamRequest: true });
+  return forward(event, "resource-policy", upstreamUrl, method, baseURL, staticHeaders, options);
+}
+const SESSION_GRANTS = new SessionGrants();
+const issuers = /* @__PURE__ */ new WeakMap();
+let defaultIssuer;
+function grantIssuer(options, baseURL, staticHeaders) {
+  if (options.issueGrant) {
+    let issue = issuers.get(options.issueGrant);
+    if (!issue) issuers.set(options.issueGrant, issue = cachedIssuer(options.issueGrant));
+    return issue;
+  }
+  const mlConfig = useRuntimeConfig().mediaLibrary ?? {};
+  const serviceToken = mlConfig.serviceToken;
+  if (!serviceToken) {
+    throw createError({ statusCode: 500, statusMessage: "mediaLibrary.serviceToken (private runtime config) or issueGrant is required with authorize." });
+  }
+  const tenant = headerValue(staticHeaders, "x-tenant");
+  const key = `${baseURL}|${tenant ?? ""}|${serviceToken}`;
+  if (defaultIssuer?.key !== key) {
+    defaultIssuer = { key, issue: cachedIssuer(serviceTokenIssuer({ baseURL, serviceToken, tenant })) };
+  }
+  return defaultIssuer.issue;
+}
+function headerValue(headers, name) {
+  const entry = Object.entries(headers).find(([k]) => k.toLowerCase() === name);
+  return entry?.[1] || void 0;
+}
+const JSON_BODY_ROUTES = [/\/manage\/assets\/resolve$/, /\/manage\/uploads\/sessions$/];
+async function forward(event, name, upstreamUrl, method, baseURL, staticHeaders, options) {
+  if (!options?.authorize) {
+    const headers2 = await buildProxyHeaders(event, staticHeaders, options?.requestHeaders);
+    return logged(event, name, method, upstreamUrl, proxyRequest(event, upstreamUrl.toString(), { headers: headers2, streamRequest: true, fetchOptions: { method } }));
+  }
+  const base = upstreamHeaders(await buildProxyHeaders(event, staticHeaders, options.requestHeaders));
+  const needsBody = method === "POST" && JSON_BODY_ROUTES.some((re) => re.test(upstreamUrl.pathname));
+  let body = needsBody ? await readBody(event) ?? {} : void 0;
+  const need = grantNeed(method, upstreamUrl.pathname, body);
+  if (need === null) throw createError({ statusCode: 404, statusMessage: "Not found" });
+  let headers = base;
+  if (need !== "public") {
+    let result;
+    try {
+      result = await grantFor(event, need, options.authorize, grantIssuer(options, baseURL, staticHeaders), SESSION_GRANTS);
+    } catch (error) {
+      if (error instanceof MLGrantIssueError) {
+        console.error(`[media-library] ${error.message}`);
+        throw createError({ statusCode: 502, statusMessage: "Media library refused to issue a grant" });
+      }
+      throw error;
+    }
+    if ("status" in result) throw createError({ statusCode: result.status, statusMessage: result.message });
+    headers = { ...base, Authorization: `Bearer ${result.grant.grant}` };
+    if (need.upload && result.spec.profile && body) body = stripProfileFields(body);
+    if (need.scope === "upload" && !need.sessionId) {
+      const json = JSON.stringify(body ?? {});
+      const response = await fetch(upstreamUrl.toString(), {
+        method: "POST",
+        // The body was rewritten: never reuse the browser's content-length.
+        headers: { ...withoutLength(headers), "content-type": "application/json" },
+        body: json
+      });
+      const text = await response.text();
+      let payload = text;
+      try {
+        payload = text ? JSON.parse(text) : null;
+      } catch {
+      }
+      const id = payload?.id;
+      if (response.ok && id) SESSION_GRANTS.set(String(id), result.grant);
+      setResponseStatus(event, response.status);
+      const contentType = response.headers.get("content-type");
+      if (contentType) event.node.res.setHeader("content-type", contentType);
+      return payload;
+    }
+    if (need.sessionId && /\/(?:finalize|abort)$/.test(need.path)) {
+      const sessionId = need.sessionId;
+      event.node.res.once("finish", () => {
+        if (event.node.res.statusCode < 400) SESSION_GRANTS.delete(sessionId);
+      });
+    }
+  }
+  const fetchOptions = { method, headers };
+  if (body !== void 0) {
+    const json = JSON.stringify(body);
+    fetchOptions.body = json;
+    fetchOptions.headers = { ...withoutLength(headers), "content-type": "application/json" };
+  } else if (PAYLOAD_METHODS.has((event.node.req.method || "GET").toUpperCase())) {
+    fetchOptions.body = getRequestWebStream(event);
+    fetchOptions.duplex = "half";
+  }
+  return logged(event, name, method, upstreamUrl, sendProxy(event, upstreamUrl.toString(), { fetchOptions }));
+}
+const PAYLOAD_METHODS = /* @__PURE__ */ new Set(["PATCH", "POST", "PUT", "DELETE"]);
+const NOT_FORWARDED = ["authorization", "cookie", "accept-encoding", "transfer-encoding", "connection", "keep-alive", "upgrade", "expect", "host", "content-length"];
+function withoutLength(headers) {
+  return Object.fromEntries(Object.entries(headers).filter(([k]) => k.toLowerCase() !== "content-length"));
+}
+function upstreamHeaders(headers) {
+  const out = Object.fromEntries(Object.entries(headers).filter(([k]) => !NOT_FORWARDED.includes(k.toLowerCase())));
+  const length = headerValue(headers, "content-length");
+  if (length) out["content-length"] = length;
+  return out;
+}
+async function logged(event, name, method, url, request) {
+  const result = await request;
   if (event.node.res.statusCode >= 400) {
-    console.error(`[media-library] resource-policy-proxy upstream responded ${event.node.res.statusCode} for ${method} ${upstreamUrl}`);
+    console.error(`[media-library] ${name}-proxy upstream responded ${event.node.res.statusCode} for ${method} ${url}`);
   }
   return result;
 }
@@ -183,16 +281,16 @@ export function createMLCatchAllProxy(options) {
           baseURL,
           staticHeaders,
           mlConfig.routes?.assets || "/manage/assets",
-          options?.requestHeaders
+          options
         );
       case "uploads":
-        return handleUploadsProxy(event, baseURL, staticHeaders, mlConfig.routes, options?.requestHeaders);
+        return handleUploadsProxy(event, baseURL, staticHeaders, mlConfig.routes, options);
       case "delivery":
-        return handleDeliveryProxy(event, baseURL, staticHeaders, options?.requestHeaders);
+        return handleDeliveryProxy(event, baseURL, staticHeaders, options);
       case "processing":
-        return handleProcessingProxy(event, baseURL, staticHeaders, options?.requestHeaders);
+        return handleProcessingProxy(event, baseURL, staticHeaders, options);
       case "resource-policy":
-        return handleResourcePolicyProxy(event, baseURL, staticHeaders, options?.requestHeaders);
+        return handleResourcePolicyProxy(event, baseURL, staticHeaders, options);
     }
   });
 }
@@ -209,7 +307,7 @@ export function createMLProxy(type, options) {
           baseURL,
           staticHeaders,
           mlConfig.routes?.assets || "/manage/assets",
-          options?.requestHeaders
+          options
         );
       case "uploads":
         return handleUploadsProxy(
@@ -217,14 +315,14 @@ export function createMLProxy(type, options) {
           baseURL,
           staticHeaders,
           mlConfig.routes,
-          options?.requestHeaders
+          options
         );
       case "delivery":
-        return handleDeliveryProxy(event, baseURL, staticHeaders, options?.requestHeaders);
+        return handleDeliveryProxy(event, baseURL, staticHeaders, options);
       case "processing":
-        return handleProcessingProxy(event, baseURL, staticHeaders, options?.requestHeaders);
+        return handleProcessingProxy(event, baseURL, staticHeaders, options);
       case "resource-policy":
-        return handleResourcePolicyProxy(event, baseURL, staticHeaders, options?.requestHeaders);
+        return handleResourcePolicyProxy(event, baseURL, staticHeaders, options);
       default:
         throw createError({ statusCode: 500, statusMessage: `Unknown MLProxy type: ${type}` });
     }

package/dist/runtime/server/grants.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Media grants for the proxy (server docs/security/media-grants.md).
+ *
+ * With an `authorize` hook, the proxy no longer forwards the browser's
+ * credentials to `/manage`. For each request it works out what the call
+ * needs (`MLGrantNeed`), asks the app (`authorize`), gets a short-lived grant
+ * scoped to exactly that and sends `Authorization: Bearer mlg_…` upstream.
+ * The media library enforces the grant, so the app's rules decide and the
+ * app never re-implements the endpoints.
+ *
+ * Pure functions plus `fetch`: no h3 imports, so they are unit-testable.
+ */
+export type MLGrantScope = 'upload' | 'read' | 'update' | 'delete' | 'process' | 'renditions' | 'manage:*';
+/** What one proxied `/manage` request needs. */
+export interface MLGrantNeed {
+    scope: MLGrantScope;
+    /** Upstream method and path (after the proxy's rewrite). */
+    method: string;
+    path: string;
+    /** Assets the request acts on (path id, or `assetIds` in the body). */
+    assetIds?: string[];
+    /** Processing task the request acts on (its asset is checked upstream). */
+    taskId?: string;
+    /** Upload session the request continues. */
+    sessionId?: string;
+    /** Parsed JSON body of `POST /manage/uploads/sessions` (MIME type, size, file name…). */
+    upload?: Record<string, unknown>;
+}
+/** Upload profile, as `POST /manage/grants` takes it (camelCase). */
+export interface MLGrantProfile {
+    kind: string;
+    visibility?: 'private' | 'public' | 'restricted';
+    collectionName?: string;
+    allowedMimeTypes?: string[];
+    maxSizeBytes?: number;
+    processingConfig?: Record<string, unknown>;
+}
+/** What to issue. Returned by `authorize` when the default is not enough. */
+export interface MLGrantSpec {
+    scopes: MLGrantScope[];
+    assetIds?: string[];
+    sessionIds?: string[];
+    profile?: MLGrantProfile;
+    /** The app's user reference; logged by the media library. */
+    subject?: string;
+    ttlSeconds?: number;
+}
+export interface MLIssuedGrant {
+    grant: string;
+    /** ISO timestamp. */
+    expiresAt: string;
+}
+/**
+ * The app's decision. `false`/`null`/`undefined`: 403. `true`: issue exactly
+ * the need (scope plus its asset or session; for a task, the app must return
+ * a spec with the task's asset ids). An upload create needs a spec with a
+ * `profile`: the profile, not the browser, decides kind, visibility and
+ * processing.
+ */
+export type MLAuthorize<E = unknown> = (event: E, need: MLGrantNeed) => boolean | MLGrantSpec | null | undefined | Promise<boolean | MLGrantSpec | null | undefined>;
+/**
+ * The need of an upstream `/manage` request, `'public'` for metadata routes
+ * that need no grant, or `null` when the route is unknown (deny).
+ */
+export declare function grantNeed(method: string, upstreamPath: string, body?: unknown): MLGrantNeed | 'public' | null;
+/** The spec `authorize: true` stands for. */
+export declare function specFromNeed(need: MLGrantNeed): MLGrantSpec;
+/** The upload-create body to forward under a grant with a profile. */
+export declare function stripProfileFields(body: Record<string, unknown>): Record<string, unknown>;
+export type MLIssueGrant = (spec: MLGrantSpec) => Promise<MLIssuedGrant>;
+/**
+ * Issue grants from the Nuxt server itself with the tenant's service token
+ * (`POST {baseURL}/manage/grants`). Use when the Nuxt server is the app
+ * backend; otherwise pass an `issueGrant` that asks your backend (e.g. the
+ * Python client's `create_grant_router`).
+ */
+export declare function serviceTokenIssuer(options: {
+    baseURL: string;
+    serviceToken: string;
+    tenant?: string;
+    fetch?: typeof fetch;
+}): MLIssueGrant;
+export declare class MLGrantIssueError extends Error {
+    status: number;
+    detail: string;
+    constructor(status: number, detail: string);
+}
+/**
+ * Reuse an issued grant for the same spec until shortly before it expires.
+ * Specs include `subject`, so users never share grants unless the app
+ * returns specs without one.
+ */
+export declare function cachedIssuer(issue: MLIssueGrant, options?: {
+    marginSeconds?: number;
+    maxEntries?: number;
+    now?: () => number;
+}): MLIssueGrant;
+/**
+ * Remember which grant created an upload session, so its parts, finalize
+ * and abort reuse it (the media library binds the session to that grant).
+ * `authorize` is still asked for every request.
+ * In-memory: with several Nitro instances a miss asks `authorize` again with
+ * the session id.
+ */
+export declare class SessionGrants {
+    private now;
+    private max;
+    private grants;
+    constructor(now?: () => number, max?: number);
+    set(sessionId: string, grant: MLIssuedGrant): void;
+    get(sessionId: string): MLIssuedGrant | undefined;
+    delete(sessionId: string): void;
+}
+/**
+ * Resolve the grant for one request. Returns the issued grant, or a status
+ * to answer with (403 refused, 404 unknown route).
+ */
+export declare function grantFor<E>(event: E, need: MLGrantNeed, authorize: MLAuthorize<E>, issue: MLIssueGrant, sessions?: SessionGrants): Promise<{
+    grant: MLIssuedGrant;
+    spec: MLGrantSpec;
+} | {
+    status: 403 | 422;
+    message: string;
+}>;

package/dist/runtime/server/grants.js

@@ -0,0 +1,161 @@
+const UUIDish = "[^/]+";
+const ROUTES = [
+  ["GET", /^\/manage\/assets$/, "manage:*", null],
+  ["POST", /^\/manage\/assets\/resolve$/, "read", "body"],
+  ["POST", /^\/manage\/assets\/bulk-visibility$/, "update", "body"],
+  ["GET", new RegExp(`^/manage/assets/(${UUIDish})$`), "read", "asset"],
+  ["PATCH", new RegExp(`^/manage/assets/(${UUIDish})$`), "update", "asset"],
+  ["DELETE", new RegExp(`^/manage/assets/(${UUIDish})$`), "delete", "asset"],
+  ["GET", new RegExp(`^/manage/assets/(${UUIDish})/renditions$`), "read", "asset"],
+  ["POST", new RegExp(`^/manage/assets/(${UUIDish})/renditions/[^/]+$`), "renditions", "asset"],
+  ["POST", new RegExp(`^/manage/processing/assets/(${UUIDish})/process$`), "process", "asset"],
+  ["GET", new RegExp(`^/manage/processing/assets/(${UUIDish})/(?:tasks|stream)$`), "read", "asset"],
+  ["POST", new RegExp(`^/manage/processing/tasks/(${UUIDish})/(?:configure|retry)$`), "process", "task"],
+  ["GET", /^\/manage\/processing\/stream$/, "manage:*", null],
+  ["POST", /^\/manage\/uploads\/sessions$/, "upload", null],
+  ["GET", new RegExp(`^/manage/uploads/sessions/(${UUIDish})$`), "upload", "session"],
+  ["PUT", new RegExp(`^/manage/uploads/sessions/(${UUIDish})/parts/[^/]+$`), "upload", "session"],
+  ["POST", new RegExp(`^/manage/uploads/sessions/(${UUIDish})/(?:finalize|abort)$`), "upload", "session"],
+  ["GET", /^\/manage\/resource-policies(?:\/[^/]+)?$/, "manage:*", null],
+  ["POST", /^\/manage\/resource-policies$/, "manage:*", null],
+  ["PUT", /^\/manage\/resource-policies\/[^/]+$/, "manage:*", null],
+  ["DELETE", /^\/manage\/resource-policies\/[^/]+$/, "manage:*", null]
+];
+const PUBLIC = [
+  /^\/manage\/processing\/processors$/,
+  /^\/manage\/processing-options\//,
+  /^\/manage\/resource-policies\/schema$/,
+  /^\/manage\/resource-policies\/pipelines\/available-steps$/
+];
+export function grantNeed(method, upstreamPath, body) {
+  const path = upstreamPath.replace(/\/+$/, "").replace(/^.*?(?=\/manage\/)/, "");
+  method = method.toUpperCase();
+  if (PUBLIC.some((re) => re.test(path))) return "public";
+  for (const [m, re, scope, target] of ROUTES) {
+    if (m !== method) continue;
+    const match = path.match(re);
+    if (!match) continue;
+    const need = { scope, method, path };
+    const id = match[1] ? decodeURIComponent(match[1]) : void 0;
+    if (target === "asset") need.assetIds = [id];
+    else if (target === "task") need.taskId = id;
+    else if (target === "session") need.sessionId = id;
+    else if (target === "body") {
+      const ids = body?.assetIds;
+      need.assetIds = Array.isArray(ids) ? ids.map(String) : [];
+    }
+    if (scope === "upload" && !target && body && typeof body === "object") {
+      need.upload = body;
+    }
+    return need;
+  }
+  return null;
+}
+export function specFromNeed(need) {
+  const spec = { scopes: [need.scope] };
+  if (need.assetIds?.length) spec.assetIds = need.assetIds;
+  if (need.sessionId) spec.sessionIds = [need.sessionId];
+  return spec;
+}
+const PROFILE_FIELDS = ["kind", "visibility", "processingConfig", "processing_config", "resourceType", "resource_type", "collectionName", "collection_name"];
+export function stripProfileFields(body) {
+  return Object.fromEntries(Object.entries(body).filter(([k]) => !PROFILE_FIELDS.includes(k)));
+}
+export function serviceTokenIssuer(options) {
+  const doFetch = options.fetch ?? fetch;
+  const url = new URL("./manage/grants", options.baseURL.endsWith("/") ? options.baseURL : `${options.baseURL}/`);
+  return async (spec) => {
+    const headers = {
+      "Authorization": `Bearer ${options.serviceToken}`,
+      "Content-Type": "application/json"
+    };
+    if (options.tenant) headers["X-Tenant"] = options.tenant;
+    const response = await doFetch(url.toString(), { method: "POST", headers, body: JSON.stringify(spec) });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new MLGrantIssueError(response.status, detail);
+    }
+    const body = await response.json();
+    return { grant: body.grant, expiresAt: body.expiresAt };
+  };
+}
+export class MLGrantIssueError extends Error {
+  constructor(status, detail) {
+    super(`media library refused to issue a grant (${status}): ${detail}`);
+    this.status = status;
+    this.detail = detail;
+  }
+}
+export function cachedIssuer(issue, options = {}) {
+  const margin = (options.marginSeconds ?? 30) * 1e3;
+  const max = options.maxEntries ?? 1e3;
+  const now = options.now ?? Date.now;
+  const cache = /* @__PURE__ */ new Map();
+  return async (spec) => {
+    const key = canonicalKey(spec);
+    const hit = cache.get(key);
+    if (hit && hit.until > now()) return { grant: hit.grant, expiresAt: hit.expiresAt };
+    const issued = await issue(spec);
+    const until = Date.parse(issued.expiresAt) - margin;
+    if (cache.size >= max) cache.delete(cache.keys().next().value);
+    if (until > now()) cache.set(key, { ...issued, until });
+    return issued;
+  };
+}
+function canonicalKey(spec) {
+  const sorted = (v) => v ? [...v].sort() : void 0;
+  return JSON.stringify({
+    s: sorted(spec.scopes),
+    a: sorted(spec.assetIds),
+    n: sorted(spec.sessionIds),
+    p: spec.profile ? stableStringify(spec.profile) : void 0,
+    u: spec.subject,
+    t: spec.ttlSeconds
+  });
+}
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+export class SessionGrants {
+  constructor(now = Date.now, max = 5e3) {
+    this.now = now;
+    this.max = max;
+  }
+  grants = /* @__PURE__ */ new Map();
+  set(sessionId, grant) {
+    if (this.grants.size >= this.max) this.grants.delete(this.grants.keys().next().value);
+    this.grants.set(sessionId, grant);
+  }
+  get(sessionId) {
+    const grant = this.grants.get(sessionId);
+    if (grant && Date.parse(grant.expiresAt) - 5e3 > this.now()) return grant;
+    this.grants.delete(sessionId);
+    return void 0;
+  }
+  delete(sessionId) {
+    this.grants.delete(sessionId);
+  }
+}
+export async function grantFor(event, need, authorize, issue, sessions) {
+  const decision = await authorize(event, need);
+  if (!decision) return { status: 403, message: "Not allowed" };
+  if (need.sessionId && sessions) {
+    const known = sessions.get(need.sessionId);
+    if (known) return { grant: known, spec: { scopes: ["upload"], sessionIds: [need.sessionId] } };
+  }
+  const spec = decision === true ? specFromNeed(need) : decision;
+  if (spec.scopes.includes("manage:*") && need.scope !== "manage:*") {
+    return { status: 403, message: "authorize returned manage:* for a scoped request" };
+  }
+  if (need.scope === "upload" && !need.sessionId && !spec.profile && !spec.scopes.includes("manage:*")) {
+    return { status: 422, message: "authorize must return a profile for upload sessions" };
+  }
+  if (need.taskId && decision === true) {
+    return { status: 422, message: "authorize must return assetIds for processing tasks" };
+  }
+  return { grant: await issue(spec), spec };
+}

package/dist/runtime/server/index.d.ts

@@ -1,2 +1,4 @@
 export { createMLProxy, createMLCatchAllProxy } from './create-ml-proxy.js';
 export type { MLProxyType, MLProxyOptions } from './create-ml-proxy.js';
+export { cachedIssuer, grantNeed, MLGrantIssueError, serviceTokenIssuer, specFromNeed, } from './grants.js';
+export type { MLAuthorize, MLGrantNeed, MLGrantProfile, MLGrantScope, MLGrantSpec, MLIssueGrant, MLIssuedGrant, } from './grants.js';

package/dist/runtime/server/index.js

@@ -1 +1,8 @@
 export { createMLProxy, createMLCatchAllProxy } from "./create-ml-proxy.js";
+export {
+  cachedIssuer,
+  grantNeed,
+  MLGrantIssueError,
+  serviceTokenIssuer,
+  specFromNeed
+} from "./grants.js";

package/dist/runtime/server/uploads-proxy.js

@@ -34,6 +34,7 @@ export default defineEventHandler(async (event) => {
     const rest = path.slice(prefix.length);
     let upstreamPath = "";
     const method = event.node.req.method || "GET";
+    let upstreamMethod = method;
     if (rest === "/sessions" || rest === "/sessions/") {
       if (method !== "POST") {
         throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
@@ -55,9 +56,10 @@ export default defineEventHandler(async (event) => {
         }
         upstreamPath = resolveRoute(resolvedRoutes.finalize, { id: finalizeMatch[1] });
       } else if (abortMatch && resolvedRoutes.abort) {
-        if (method !== "DELETE") {
+        if (method !== "POST" && method !== "DELETE") {
           throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
         }
+        upstreamMethod = "POST";
         upstreamPath = resolveRoute(resolvedRoutes.abort, { id: abortMatch[1] });
       } else if (sessionMatch) {
         if (method !== "GET") {
@@ -86,7 +88,8 @@ export default defineEventHandler(async (event) => {
     delete proxyHeaders.host;
     const result = await proxyRequest(event, upstreamUrl.toString(), {
       headers: proxyHeaders,
-      streamRequest: true
+      streamRequest: true,
+      fetchOptions: { method: upstreamMethod }
     });
     if (event.node.res.statusCode >= 400) {
       console.error(`[media-library] uploads-proxy upstream responded ${event.node.res.statusCode} for ${method} ${upstreamUrl.toString()}`);

package/dist/runtime/types/asset.d.ts

@@ -164,9 +164,11 @@ export interface DeliveryAssetListResponse {
 }
 export interface DeliveryBatchResolveItem {
     assetId: string;
-    status: 'ok' | 'not_found';
+    status: 'ok' | 'not_found' | 'forbidden' | 'error';
     asset: DeliveryAsset | null;
     error: string | null;
+    /** Public thumbnail, also sent for forbidden and error items. */
+    thumbnailUrl?: string | null;
 }
 export interface DeliveryBatchResolveResponse {
     items: DeliveryBatchResolveItem[];

package/dist/runtime/utils/grants/listeners.d.ts

@@ -0,0 +1,2 @@
+export declare function onMediaGrantsAdded(listener: () => void): () => void;
+export declare function notifyMediaGrantsAdded(): void;

package/dist/runtime/utils/grants/listeners.js

@@ -0,0 +1,8 @@
+const listeners = /* @__PURE__ */ new Set();
+export function onMediaGrantsAdded(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+export function notifyMediaGrantsAdded() {
+  for (const listener of listeners) listener();
+}

package/dist/runtime/utils/grants/store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Media grants the browser holds (server docs/security/media-grants.md).
+ *
+ * Each service returns a read grant (`mlg_…`) with the data that references
+ * its assets. The app adds them here; every delivery resolve sends the live
+ * ones in `X-Media-Grants`, so one request resolves assets of several
+ * services. Pure (no Vue), so it is unit-testable.
+ */
+export declare const GRANTS_HEADER = "X-Media-Grants";
+/** Server limit per request. */
+export declare const MAX_GRANTS = 10;
+export interface HeldGrant {
+    grant: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+export type GrantInput = string | {
+    grant: string;
+    expiresAt?: string | number | null;
+} | null | undefined;
+/** `exp` of an `mlg_<jwt>` grant, in epoch ms, or null when unreadable. */
+export declare function grantExpiry(grant: string): number | null;
+/** `held` plus `inputs`: deduplicated, expired ones dropped, newest kept. */
+export declare function mergeGrants(held: HeldGrant[], inputs: GrantInput[], now?: number, max?: number): HeldGrant[];
+/** Headers for a delivery request: the `MAX_GRANTS` live grants expiring last. */
+export declare function grantHeaders(held: HeldGrant[], now?: number): Record<string, string>;

package/dist/runtime/utils/grants/store.js

@@ -0,0 +1,37 @@
+export const GRANTS_HEADER = "X-Media-Grants";
+export const MAX_GRANTS = 10;
+const MARGIN_MS = 5e3;
+export function grantExpiry(grant) {
+  const jwt = grant.startsWith("mlg_") ? grant.slice(4) : grant;
+  const payload = jwt.split(".")[1];
+  if (!payload) return null;
+  try {
+    const json = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(payload.length / 4) * 4, "=")));
+    return typeof json.exp === "number" ? json.exp * 1e3 : null;
+  } catch {
+    return null;
+  }
+}
+function normalize(input) {
+  if (!input) return null;
+  const grant = typeof input === "string" ? input : input.grant;
+  if (!grant || !grant.startsWith("mlg_")) return null;
+  let expiresAt = null;
+  if (typeof input !== "string" && input.expiresAt != null) {
+    expiresAt = typeof input.expiresAt === "number" ? input.expiresAt : Date.parse(input.expiresAt);
+  }
+  if (expiresAt == null || Number.isNaN(expiresAt)) expiresAt = grantExpiry(grant);
+  if (expiresAt == null) return null;
+  return { grant, expiresAt };
+}
+export function mergeGrants(held, inputs, now = Date.now(), max = 50) {
+  const byToken = /* @__PURE__ */ new Map();
+  for (const g of [...held, ...inputs.map(normalize)]) {
+    if (g && g.expiresAt - MARGIN_MS > now) byToken.set(g.grant, g);
+  }
+  return [...byToken.values()].sort((a, b) => b.expiresAt - a.expiresAt).slice(0, max);
+}
+export function grantHeaders(held, now = Date.now()) {
+  const live = held.filter((g) => g.expiresAt - MARGIN_MS > now).slice(0, MAX_GRANTS);
+  return live.length ? { [GRANTS_HEADER]: live.map((g) => g.grant).join(", ") } : {};
+}

package/dist/runtime/utils/uploader/serviceUpload.d.ts

@@ -0,0 +1,84 @@
+import type { ChunkUploaderConfig, UploadFileOptions, UploadProgress, UploadResult } from '../../types/uploader.js';
+/**
+ * Browser uploads started by one of the app's backend services
+ * (py_client `create_upload_router`): the service creates the upload
+ * session and returns a grant for it; the browser uploads straight to the
+ * media library, refreshing the grant through the service, and gets back
+ * `{ sessionId, assetId }` to send to the service's attach endpoint.
+ */
+/** What the service's start endpoint answers (201). */
+export interface ServiceUploadStart {
+    sessionId: string;
+    grant: string;
+    expiresAt: string;
+    uploadBaseUrl: string;
+    tenant: string;
+    partSizeBytes?: number;
+}
+/** What the service's refresh endpoint answers. */
+export interface ServiceUploadGrant {
+    sessionId?: string;
+    grant: string;
+    expiresAt: string;
+}
+export interface ServiceUploadOptions {
+    /** The service's start endpoint, e.g. `/api/videos/uploads`. */
+    start: string;
+    /**
+     * Extra fields for the start request, e.g. `{ profile, context }`.
+     * `mimeType`, `sizeBytes` and `filename` are taken from the file
+     * (fields given here win).
+     */
+    body?: Record<string, unknown>;
+    /** The refresh endpoint. Default: `${start}/${sessionId}/grant`. */
+    refresh?: string | ((sessionId: string) => string);
+    /** Headers for the service's start and refresh requests (e.g. CSRF). */
+    headers?: Record<string, string>;
+    /** Refresh the grant this long before it expires. Default 60 s. */
+    refreshMarginMs?: number;
+    /** Parallel part uploads. Default 3. */
+    concurrency?: number;
+    onProgress?: (p: UploadProgress) => void;
+    onState?: (s: {
+        phase: string;
+        message?: string;
+    }) => void;
+}
+export interface ServiceUploadResult {
+    sessionId: string;
+    assetId: string;
+}
+type FetchLike = <T>(url: string, opts: {
+    method: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}) => Promise<T>;
+interface UploaderLike {
+    uploadFile: (file: File, options: UploadFileOptions) => Promise<UploadResult>;
+    abort: () => void;
+}
+export interface ServiceUploadDeps {
+    fetch: FetchLike;
+    createUploader: (cfg: ChunkUploaderConfig) => UploaderLike;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/** The media library routes a session grant allows (relative to `uploadBaseUrl`). */
+export declare const serviceUploadRoutes: {
+    createSession: string;
+    getSession: (id: string) => string;
+    uploadPart: (id: string, n: number) => string;
+    finalize: (id: string) => string;
+    abort: (id: string) => string;
+};
+/**
+ * One upload at a time per instance: `upload` runs the flow, `abort` stops
+ * it (the parts already sent stay with the session until it expires).
+ */
+export declare function createServiceUpload(deps: ServiceUploadDeps): {
+    upload: (file: File, options: ServiceUploadOptions) => Promise<ServiceUploadResult>;
+    abort: () => void;
+    isRunning: () => boolean;
+};
+export {};

package/dist/runtime/utils/uploader/serviceUpload.js

@@ -0,0 +1,109 @@
+const SESSIONS = "/manage/uploads/sessions";
+const DEFAULT_PART_SIZE = 8 * 1024 * 1024;
+const MIN_REFRESH_DELAY_MS = 1e3;
+export const serviceUploadRoutes = {
+  createSession: SESSIONS,
+  getSession: (id) => `${SESSIONS}/${encodeURIComponent(id)}`,
+  uploadPart: (id, n) => `${SESSIONS}/${encodeURIComponent(id)}/parts/${n}`,
+  finalize: (id) => `${SESSIONS}/${encodeURIComponent(id)}/finalize`,
+  abort: (id) => `${SESSIONS}/${encodeURIComponent(id)}/abort`
+};
+export function createServiceUpload(deps) {
+  const now = deps.now ?? Date.now;
+  const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h));
+  let current = null;
+  const abortError = () => new DOMException("Aborted", "AbortError");
+  async function upload(file, options) {
+    if (current) throw new Error("An upload is already running; abort it first.");
+    const run = { uploader: null, stop: () => {
+    }, aborted: false };
+    current = run;
+    try {
+      return await runUpload(file, options, run);
+    } finally {
+      run.stop();
+      current = null;
+    }
+  }
+  async function runUpload(file, options, run) {
+    const start = options.start.replace(/\/+$/, "");
+    const margin = options.refreshMarginMs ?? 6e4;
+    options.onState?.({ phase: "service.start" });
+    const started = await deps.fetch(start, {
+      method: "POST",
+      headers: options.headers,
+      body: {
+        mimeType: file.type || "application/octet-stream",
+        sizeBytes: file.size,
+        filename: file.name,
+        ...options.body
+      }
+    });
+    if (run.aborted) throw abortError();
+    const sessionId = started.sessionId;
+    const refreshUrl = typeof options.refresh === "function" ? options.refresh(sessionId) : options.refresh ?? `${start}/${encodeURIComponent(sessionId)}/grant`;
+    let grant = started.grant;
+    let timer = null;
+    let stopped = false;
+    let refreshError = null;
+    const schedule = (expiresAt) => {
+      const expiresMs = Date.parse(expiresAt);
+      if (Number.isNaN(expiresMs)) return;
+      const delay = Math.max(MIN_REFRESH_DELAY_MS, expiresMs - margin - now());
+      timer = setTimer(refresh, delay);
+    };
+    async function refresh() {
+      timer = null;
+      if (stopped) return;
+      try {
+        const next = await deps.fetch(refreshUrl, { method: "POST", headers: options.headers });
+        if (stopped) return;
+        grant = next.grant;
+        refreshError = null;
+        schedule(next.expiresAt);
+      } catch (err) {
+        refreshError = err;
+        if (!stopped) timer = setTimer(refresh, Math.max(MIN_REFRESH_DELAY_MS, margin / 4));
+      }
+    }
+    run.stop = () => {
+      stopped = true;
+      if (timer !== null) clearTimer(timer);
+      timer = null;
+    };
+    const uploader = deps.createUploader({
+      baseURL: started.uploadBaseUrl.replace(/\/+$/, ""),
+      routes: serviceUploadRoutes,
+      partSize: started.partSizeBytes ?? DEFAULT_PART_SIZE,
+      concurrency: options.concurrency ?? 3,
+      checksum: { algorithm: "SHA-256", perPart: true, final: true },
+      headers: () => ({ "Authorization": `Bearer ${grant}`, "X-Tenant": started.tenant })
+    });
+    run.uploader = uploader;
+    schedule(started.expiresAt);
+    try {
+      const result = await uploader.uploadFile(file, {
+        sessionId,
+        create: { mime_type: file.type || "application/octet-stream" },
+        onProgress: options.onProgress,
+        onState: options.onState
+      });
+      const assetId = result.finalize?.asset_id;
+      if (!assetId) throw new Error("The media library did not return an asset id.");
+      return { sessionId, assetId: String(assetId) };
+    } catch (err) {
+      if (refreshError && !(err instanceof DOMException && err.name === "AbortError")) {
+        throw new Error("Upload failed after the upload grant could not be refreshed.", { cause: err });
+      }
+      throw err;
+    }
+  }
+  function abort() {
+    if (!current) return;
+    current.aborted = true;
+    current.stop();
+    current.uploader?.abort();
+  }
+  return { upload, abort, isRunning: () => current !== null };
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "nuxt-media-library",
-  "version": "0.0.44",
+  "version": "0.0.48",
   "description": "Nuxt module for media library management — chunked uploads, asset previews, and resource policies",
-  "repository": "fritill-team/nuxt-media-library",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fritill-team/media_library_module.git"
+  },
   "license": "MIT",
   "type": "module",
   "types": "./dist/types.d.mts",