nuxt-media-library 0.0.44 → 0.0.49

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.49",
   "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/MLMedia/Dropzone.d.vue.ts

@@ -0,0 +1,60 @@
+import { type RejectedFile } from '../../utils/fileAccept.js';
+type __VLS_Props = {
+    /** Browser accept syntax ("image/*,.glb"). Build one from kinds with acceptForKinds(). */
+    accept?: string;
+    multiple?: boolean;
+    /** Bytes. Larger files are rejected with reason "size". */
+    maxSize?: number | null;
+    /** How many more files fit. Extra files are rejected with reason "count". */
+    maxFiles?: number | null;
+    disabled?: boolean;
+    /**
+     * `area`: a dashed box with an upload button (fields, picker).
+     * `overlay`: wraps the default slot and only shows a highlight while files are dragged over it (gallery).
+     */
+    variant?: 'area' | 'overlay';
+    title?: string;
+    hint?: string;
+    /** The button that opens the computer's file dialog. Defaults to "Upload file(s)". */
+    buttonLabel?: string;
+    /** One short row instead of a box, for places where the drop zone is secondary (the picker). */
+    compact?: boolean;
+};
+type __VLS_Slots = {
+    default?: (props: {
+        isDragging: boolean;
+        open: () => void;
+    }) => unknown;
+    actions?: (props: {
+        open: () => void;
+    }) => unknown;
+};
+declare function open(): void;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
+    open: typeof open;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    files: (files: File[]) => any;
+    rejected: (files: RejectedFile[]) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onFiles?: ((files: File[]) => any) | undefined;
+    onRejected?: ((files: RejectedFile[]) => any) | undefined;
+}>, {
+    title: string;
+    accept: string;
+    maxSize: number | null;
+    variant: "area" | "overlay";
+    compact: boolean;
+    disabled: boolean;
+    multiple: boolean;
+    maxFiles: number | null;
+    hint: string;
+    buttonLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/MLMedia/Dropzone.vue

@@ -0,0 +1,137 @@
+<script setup>
+import { computed, ref } from "vue";
+import { useFileUpload } from "#imports";
+import { formatBytes } from "../../utils/assetFormat";
+import { partitionFiles } from "../../utils/fileAccept";
+const props = defineProps({
+  accept: { type: String, required: false, default: "*" },
+  multiple: { type: Boolean, required: false, default: true },
+  maxSize: { type: [Number, null], required: false, default: null },
+  maxFiles: { type: [Number, null], required: false, default: null },
+  disabled: { type: Boolean, required: false, default: false },
+  variant: { type: String, required: false, default: "area" },
+  title: { type: String, required: false, default: void 0 },
+  hint: { type: String, required: false, default: void 0 },
+  buttonLabel: { type: String, required: false, default: void 0 },
+  compact: { type: Boolean, required: false, default: false }
+});
+const emit = defineEmits(["files", "rejected"]);
+defineSlots();
+const { isDragging, dropzoneRef } = useFileUpload({
+  accept: "*",
+  multiple: true,
+  dropzone: true,
+  onUpdate: (files) => handle(files)
+});
+const input = ref();
+function handle(files) {
+  if (props.disabled || !files.length) return;
+  const max = props.multiple ? props.maxFiles : Math.min(1, props.maxFiles ?? 1);
+  const { accepted, rejected } = partitionFiles(files, { accept: props.accept, maxSize: props.maxSize, maxFiles: max });
+  if (accepted.length) emit("files", accepted);
+  if (rejected.length) emit("rejected", rejected);
+}
+function open() {
+  if (!props.disabled) input.value?.click();
+}
+function onInput(e) {
+  const el = e.target;
+  handle(Array.from(el.files ?? []));
+  el.value = "";
+}
+const carriesFiles = ref(false);
+function onDragEnter(e) {
+  carriesFiles.value = !!e.dataTransfer && Array.from(e.dataTransfer.types).includes("Files");
+}
+const active = computed(() => isDragging.value && carriesFiles.value && !props.disabled);
+const sizeHint = computed(() => props.maxSize ? `Up to ${formatBytes(props.maxSize)}` : "");
+defineExpose({ open });
+</script>
+
+<template>
+  <div
+    ref="dropzoneRef"
+    class="relative"
+    @dragenter.capture="onDragEnter"
+    :data-dragging="active || void 0"
+    :aria-disabled="disabled || void 0"
+  >
+    <input
+      ref="input"
+      type="file"
+      class="sr-only"
+      tabindex="-1"
+      aria-hidden="true"
+      :accept="accept === '*' ? void 0 : accept"
+      :multiple="multiple"
+      :disabled="disabled"
+      @change="onInput"
+    >
+
+    <template v-if="variant === 'overlay'">
+      <slot
+        :is-dragging="active"
+        :open="open"
+      />
+      <div
+        v-if="active"
+        class="pointer-events-none absolute inset-0 z-20 grid place-items-center rounded-[inherit] border-2 border-dashed border-primary bg-primary/10 backdrop-blur-[1px]"
+      >
+        <span class="flex items-center gap-2 rounded-md bg-default px-3 py-1.5 text-sm font-semibold text-primary shadow-sm">
+          <UIcon
+            name="i-lucide-upload"
+            class="size-4"
+          />
+          {{ title ?? "Drop to upload" }}
+        </span>
+      </div>
+    </template>
+
+    <div
+      v-else
+      class="flex items-center rounded-lg border-[1.5px] border-dashed text-center transition-colors motion-reduce:transition-none"
+      :class="[
+  compact ? 'flex-row flex-wrap justify-center gap-x-3 gap-y-1.5 px-3 py-2.5' : 'flex-col gap-2.5 px-4 py-5',
+  active ? 'border-primary bg-primary/10' : 'border-accented bg-default',
+  disabled ? 'opacity-60' : ''
+]"
+    >
+      <slot
+        :is-dragging="active"
+        :open="open"
+      >
+        <UIcon
+          v-if="!compact"
+          name="i-lucide-upload"
+          class="size-5"
+          :class="active ? 'text-primary' : 'text-dimmed'"
+        />
+        <p class="text-sm">
+          <span :class="compact ? 'text-muted' : 'font-semibold'">{{ title ?? (multiple ? "Drop files here" : "Drop a file here") }}</span>
+          <span class="text-muted"> or</span>
+        </p>
+        <div class="flex flex-wrap justify-center gap-1.5">
+          <UButton
+            size="sm"
+            color="neutral"
+            variant="outline"
+            icon="i-lucide-upload"
+            :label="buttonLabel ?? (multiple ? 'Upload files' : 'Upload file')"
+            :disabled="disabled"
+            @click="open"
+          />
+          <slot
+            name="actions"
+            :open="open"
+          />
+        </div>
+        <p
+          v-if="hint || sizeHint"
+          class="text-xs text-dimmed"
+        >
+          {{ [hint, sizeHint].filter(Boolean).join(" \xB7 ") }}
+        </p>
+      </slot>
+    </div>
+  </div>
+</template>

package/dist/runtime/components/MLMedia/Dropzone.vue.d.ts

@@ -0,0 +1,60 @@
+import { type RejectedFile } from '../../utils/fileAccept.js';
+type __VLS_Props = {
+    /** Browser accept syntax ("image/*,.glb"). Build one from kinds with acceptForKinds(). */
+    accept?: string;
+    multiple?: boolean;
+    /** Bytes. Larger files are rejected with reason "size". */
+    maxSize?: number | null;
+    /** How many more files fit. Extra files are rejected with reason "count". */
+    maxFiles?: number | null;
+    disabled?: boolean;
+    /**
+     * `area`: a dashed box with an upload button (fields, picker).
+     * `overlay`: wraps the default slot and only shows a highlight while files are dragged over it (gallery).
+     */
+    variant?: 'area' | 'overlay';
+    title?: string;
+    hint?: string;
+    /** The button that opens the computer's file dialog. Defaults to "Upload file(s)". */
+    buttonLabel?: string;
+    /** One short row instead of a box, for places where the drop zone is secondary (the picker). */
+    compact?: boolean;
+};
+type __VLS_Slots = {
+    default?: (props: {
+        isDragging: boolean;
+        open: () => void;
+    }) => unknown;
+    actions?: (props: {
+        open: () => void;
+    }) => unknown;
+};
+declare function open(): void;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
+    open: typeof open;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    files: (files: File[]) => any;
+    rejected: (files: RejectedFile[]) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onFiles?: ((files: File[]) => any) | undefined;
+    onRejected?: ((files: RejectedFile[]) => any) | undefined;
+}>, {
+    title: string;
+    accept: string;
+    maxSize: number | null;
+    variant: "area" | "overlay";
+    compact: boolean;
+    disabled: boolean;
+    multiple: boolean;
+    maxFiles: number | null;
+    hint: string;
+    buttonLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/MLMedia/Editor.d.vue.ts

@@ -0,0 +1,23 @@
+import type { MediaUsage } from './UsageList.vue.js';
+export type MediaEditorResult = {
+    action: 'save';
+    alt: Record<string, string>;
+} | {
+    action: 'remove';
+    assetId: string;
+};
+type __VLS_Props = {
+    assetId: string;
+    siblings?: readonly string[];
+    alt?: Readonly<Record<string, string>>;
+    readonly?: boolean;
+    removeLabel?: string;
+    usages?: Readonly<Record<string, MediaUsage[]>>;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    close: (result: MediaEditorResult | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClose?: ((result: MediaEditorResult | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/MLMedia/Editor.vue

@@ -0,0 +1,34 @@
+<script setup>
+defineProps({
+  assetId: { type: String, required: true },
+  siblings: { type: Array, required: false },
+  alt: { type: Object, required: false },
+  readonly: { type: Boolean, required: false },
+  removeLabel: { type: String, required: false },
+  usages: { type: Object, required: false }
+});
+const emit = defineEmits(["close"]);
+</script>
+
+<template>
+  <UModal
+    :title="readonly ? 'Preview' : 'Edit media'"
+    :close="{ onClick: () => emit('close', null) }"
+    :ui="{ content: 'sm:max-w-5xl', body: 'p-0 sm:p-0' }"
+    @update:open="(open) => !open && emit('close', null)"
+  >
+    <template #body>
+      <MLMediaEditorPanel
+        :asset-id="assetId"
+        :siblings="siblings"
+        :alt="alt"
+        :readonly="readonly"
+        :remove-label="removeLabel"
+        :usages="usages"
+        @save="({ alt: a }) => emit('close', { action: 'save', alt: a })"
+        @remove="(id) => emit('close', { action: 'remove', assetId: id })"
+        @cancel="emit('close', null)"
+      />
+    </template>
+  </UModal>
+</template>

package/dist/runtime/components/MLMedia/Editor.vue.d.ts

@@ -0,0 +1,23 @@
+import type { MediaUsage } from './UsageList.vue.js';
+export type MediaEditorResult = {
+    action: 'save';
+    alt: Record<string, string>;
+} | {
+    action: 'remove';
+    assetId: string;
+};
+type __VLS_Props = {
+    assetId: string;
+    siblings?: readonly string[];
+    alt?: Readonly<Record<string, string>>;
+    readonly?: boolean;
+    removeLabel?: string;
+    usages?: Readonly<Record<string, MediaUsage[]>>;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    close: (result: MediaEditorResult | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClose?: ((result: MediaEditorResult | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/MLMedia/EditorPanel.d.vue.ts

@@ -0,0 +1,38 @@
+import type { MediaUsage } from './UsageList.vue.js';
+type __VLS_Props = {
+    /** The file to show first. */
+    assetId: string;
+    /** The record's other files, in order. Enables previous / next. */
+    siblings?: readonly string[];
+    /** Current alt text per asset ID. Alt text lives on the host record, not the file. */
+    alt?: Readonly<Record<string, string>>;
+    /** Preview only: no alt editing, no Save. Used from the picker. */
+    readonly?: boolean;
+    /** Label for the remove button, e.g. "Remove from product". Empty hides it. */
+    removeLabel?: string;
+    /** Where each file is used, per asset ID. Omit to hide the section. */
+    usages?: Readonly<Record<string, MediaUsage[]>>;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    currentId: import("vue").ComputedRef<string>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    remove: (assetId: string) => any;
+    cancel: () => any;
+    save: (result: {
+        alt: Record<string, string>;
+    }) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRemove?: ((assetId: string) => any) | undefined;
+    onCancel?: (() => any) | undefined;
+    onSave?: ((result: {
+        alt: Record<string, string>;
+    }) => any) | undefined;
+}>, {
+    usages: Readonly<Record<string, MediaUsage[]>>;
+    siblings: readonly string[];
+    alt: Readonly<Record<string, string>>;
+    readonly: boolean;
+    removeLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;