@adonis-agora/media 0.12.1 → 0.13.0

package/skills/media-stores-delivery/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: media-stores-delivery
+description: >-
+  Pluggable storage seams and delivery in @adonis-agora/media — the MediaStore SPI
+  (stores.memory / stores.lucid with the published migration, custom stores via
+  StoreFactory, cross-owner keyset list() with encodeMediaCursor/clampMediaListLimit),
+  the ImageProcessor SPI (processors.sharp, custom processors), the structural Disk
+  contract (putStream, getVisibility), createDriveBackedResolver (module namespace,
+  not default export), the bundled disks.s3() with extended operations
+  (copy/move/deleteMany/list/size/stat) and declarative visibility, presignS3Url,
+  delivery.mode auto|public|signed|proxy, MediaDeliveryHandler and HlsDeliveryHandler
+  route mounting, and the @adonis-agora/media/testing doubles. Use when choosing or
+  writing a store, wiring S3, serving media, signing URLs, or testing without disks.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/media"
+  library_version: "0.12.1"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-media:docs/stores-and-processors.mdx"
+  - "DavideCarvalho/adonis-media:docs/storage/s3-disk.mdx"
+  - "DavideCarvalho/adonis-media:docs/delivery.mdx"
+  - "DavideCarvalho/adonis-media:docs/testing.mdx"
+  - "DavideCarvalho/adonis-media:packages/adonis/src/disks/drive.ts"
+---
+
+# Storage seams & delivery
+
+The library delegates everything heavy to three pluggable seams — the `MediaStore`
+(metadata persistence), the `ImageProcessor` (conversions), and a structural `Disk`
+contract that real `@adonisjs/drive` disks satisfy directly. `delivery` is the mirror-image
+strategy for **reads**.
+
+## Setup
+
+```ts title="config/media.ts"
+import { defineConfig, stores, processors, disks } from '@adonis-agora/media'
+
+export default defineConfig({
+  disk: 's3',
+  disks: { s3: disks.s3({ bucket: 'my-bucket', region: 'us-east-1' }) },
+  store: 'lucid',
+  stores: { lucid: stores.lucid({ connection: 'pg', table: 'media' }) },
+  imageProcessor: processors.sharp(),
+  delivery: { mode: 'auto', signedTtlSeconds: 300 },
+})
+```
+
+```sh
+node ace migration:run   # publishes the media table for stores.lucid()
+npm i @aws-sdk/client-s3 # optional peer, imported only because s3 is selected
+```
+
+Source: `docs/configuration.mdx`, `docs/stores-and-processors.mdx`.
+
+## Core patterns
+
+### Pattern 1 — the cross-owner `MediaStore.list` read
+
+`listByOwner` answers "what has this entity got"; `list` answers "everything, paginated,
+newest first" — the read the dashboard's Collections view is built on:
+
+```ts
+import media from '@adonis-agora/media/services/main'
+
+const page = await media.store.list({
+  collection: 'gallery',
+  ownerType: 'Post',
+  prefix: 'Post/42/',
+  limit: 50, // default 50, clamped to 200
+})
+
+page.items      // ordered createdAt desc, then id desc (stable keyset under writes)
+page.nextCursor // opaque string, or null on the last page
+```
+
+Ordering is a stable keyset so paging stays consistent while rows are written underneath.
+`encodeMediaCursor` / `decodeMediaCursor` / `clampMediaListLimit` and the
+`DEFAULT_MEDIA_LIST_LIMIT` / `MAX_MEDIA_LIST_LIMIT` constants are exported for implementers.
+
+Source: `docs/dashboard/collections.mdx`, `docs/stores-and-processors.mdx`.
+
+### Pattern 2 — wire a custom store or processor
+
+Both seams are tiny interfaces; wire them through a factory thunk so any peer loads lazily:
+
+```ts
+import { defineConfig } from '@adonis-agora/media'
+import type { ImageProcessor, MediaStore, StoreFactory } from '@adonis-agora/media'
+
+class RedisMediaStore implements MediaStore { /* save/find/listByOwner/list/delete/nextOrder */ }
+class PassthroughProcessor implements ImageProcessor {
+  async convert(input: Buffer, preset) {
+    return { data: input, format: preset.format ?? 'webp', contentType: 'image/webp' }
+  }
+}
+
+defineConfig({
+  store: 'redis',
+  stores: {
+    redis: (() => async () => new RedisMediaStore()) as unknown as StoreFactory,
+  },
+  imageProcessor: new PassthroughProcessor(), // or a factory thunk
+})
+```
+
+A `StoreFactory` receives the booted app as `StoreContext`, so a driver can resolve a peer's
+service when it builds.
+
+Source: `docs/stores-and-processors.mdx` (Writing your own store / processor).
+
+### Pattern 3 — the bundled S3 disk and its extended operations
+
+`disks.s3()` implements the base `Disk` contract plus `ExtendedDisk` (detected structurally
+with `isExtendedDisk`) and `MultipartUploadDisk` (`isMultipartCapable`):
+
+```ts
+const s3 = media.disk('s3')
+
+if (isExtendedDisk(s3)) {
+  await s3.copy('a/photo.jpg', 'b/photo.jpg', { toBucket: 'archive' })
+  await s3.deleteMany(['a/1.jpg', 'a/2.jpg'])
+  await s3.stat('a/photo.jpg') // { size, contentType?, lastModified? }
+  const page = await s3.list('uploads/', { delimiter: '/', limit: 100 })
+  page.folders // sub-prefixes from CommonPrefixes
+}
+```
+
+Key options: `endpoint` + `forcePathStyle` for MinIO/R2/Spaces, `publicEndpoint` for the
+host presigned URLs are signed against (the browser's endpoint), `publicBaseUrl` for stable
+`getUrl()` output, and `visibility: 'public' | 'private'` (default `private`) — declarative,
+read by `delivery.mode: 'auto'`, never applied as an ACL and never probed.
+
+Source: `docs/storage/s3-disk.mdx`.
+
+### Pattern 4 — serve media through a delivery route you own
+
+`delivery.mode` (`auto` default) decides what `deliver()` returns: `public`/`signed` yield
+`{ kind: 'redirect', url }`; `proxy` yields `{ kind: 'stream', stream, mimeType, size,
+fileName }`. `auto` asks the disk's `getVisibility` — public ⇒ public, private ⇒ signed,
+unknown ⇒ signed. `MediaDeliveryHandler` is framework-agnostic: YOU mount the route behind
+YOUR auth:
+
+```ts title="start/routes.ts"
+import { MediaDeliveryHandler, MediaManager } from '@adonis-agora/media'
+
+const media = await app.container.make(MediaManager)
+const delivery = new MediaDeliveryHandler({ library: media })
+
+router.get('/media/:id', async ({ params, request, response, auth }) => {
+  await authorizeMediaAccess(auth.user, params.id) // ← your rule, before handle()
+
+  const result = await delivery.handle({ mediaId: params.id, conversion: request.input('conversion') })
+  if (result.kind === 'redirect') return response.redirect(result.url)
+
+  response.header('content-type', result.mimeType)
+  if (result.size !== undefined) response.header('content-length', String(result.size))
+  response.header('content-disposition', `inline; filename="${result.fileName}"`)
+  return response.stream(result.stream)
+}).use(middleware.auth())
+```
+
+The handler's own `mode` / `signedTtlSeconds` override the configured ones per call. For
+transformer-generated HLS packages use `HlsDeliveryHandler` — playlists are rewritten per
+request, segment files are validated against the persisted artifact list (no caller input
+ever reaches the disk as a path).
+
+Source: `docs/delivery.mdx`, `docs/transformers.mdx` (Serving HLS).
+
+## Common mistakes
+
+### [CRITICAL] Passing the drive service default export instead of the module namespace
+
+Wrong:
+
+```ts
+import driveService from '@adonisjs/drive/services/main' // captured default
+const resolve = createDriveBackedResolver({ driveService, configuredDisks: {}, defaultDisk: 's3' })
+```
+
+Correct:
+
+```ts
+import * as driveService from '@adonisjs/drive/services/main' // the NAMESPACE
+const resolve = createDriveBackedResolver({ driveService, configuredDisks: {}, defaultDisk: 's3' })
+```
+
+Mechanism: Drive's service module assigns its manager inside an `app.booted()` callback, so
+at import time the default export is still `undefined` — a captured value stays `undefined`
+forever (writes fail with `DriveNotReadyError`), while the namespace's ESM live binding
+reflects the later assignment.
+Source: `docs/stores-and-processors.mdx` (createDriveBackedResolver).
+
+### [CRITICAL] Exposing a delivery route without authorization
+
+Wrong:
+
+```ts
+router.get('/media/:id', async ({ params, response }) => {
+  const result = await delivery.handle({ mediaId: params.id })
+  if (result.kind === 'redirect') return response.redirect(result.url)
+  return response.stream(result.stream)
+}) // no middleware — every record is public to anyone who can guess an id
+```
+
+Correct:
+
+```ts
+router.get('/media/:id', async ({ params, request, response, auth }) => {
+  await authorizeMediaAccess(auth.user, params.id)
+  const result = await delivery.handle({ mediaId: params.id })
+  /* ... */
+}).use(middleware.auth())
+```
+
+Mechanism: `MediaDeliveryHandler` resolves a media id to bytes or a URL and performs NO
+authorization — the same split as `TusUploadHandler`. This is also why the provider mounts
+no delivery route of its own: there is no safe default.
+Source: `docs/delivery.mdx` (error callout: The handler performs NO authorization).
+
+### [HIGH] Relying on auto delivery for storage the browser cannot reach
+
+Wrong:
+
+```ts
+disks.s3({ bucket: 'media', endpoint: 'http://minio.internal:9000' }) // internal host
+// delivery auto signs URLs against the INTERNAL host → unresolvable in the browser
+```
+
+Correct:
+
+```ts
+disks.s3({
+  bucket: 'media',
+  endpoint: 'http://minio.internal:9000',       // server-side operations
+  publicEndpoint: 'https://files.example.com',  // what presigned URLs are signed for
+  forcePathStyle: true,
+})
+```
+
+Mechanism: `auto` resolves to `signed` (never `proxy`) when visibility is unknown, and
+SigV4 bakes the host into the signature — presigned URLs must be signed for the endpoint
+the BROWSER reaches. Proxying is a deployment decision and must be opted into explicitly.
+Source: `docs/delivery.mdx` (auto never picks proxy), `docs/storage/s3-disk.mdx` (publicEndpoint).
+
+### [MEDIUM] Implementing a custom MediaStore without a working list()
+
+Wrong:
+
+```ts
+class MyStore implements MediaStore {
+  async list() { return { items: [], nextCursor: null } } // stubbed "for now"
+  // save/find/listByOwner/delete/nextOrder implemented
+}
+```
+
+Correct:
+
+```ts
+class MyStore implements MediaStore {
+  async list(options?: MediaListOptions): Promise<MediaListPage> {
+    // keyset page over { createdAt desc, id desc } with cursor + clamped limit
+  }
+}
+```
+
+Mechanism: nothing inside `attach`/`url`/`delete` calls `list()`, so a stubbed
+implementation surfaces only later — the dashboard's Collections view renders empty and
+admin tooling sees nothing. `list` is part of the `MediaStore` interface, not optional.
+Source: `docs/stores-and-processors.mdx` (The MediaStore), `docs/dashboard/collections.mdx`.
+
+### [MEDIUM] Setting s3 visibility public and expecting an ACL to be applied
+
+Wrong:
+
+```ts
+disks.s3({ bucket: 'media', visibility: 'public' }) // expecting objects to become readable
+// → 403s from the bucket: no bucket policy grants anonymous reads
+```
+
+Correct:
+
+```ts
+// make the bucket readable via its policy/CDN, THEN declare it:
+disks.s3({ bucket: 'media', visibility: 'public', publicBaseUrl: 'https://cdn.example.com' })
+```
+
+Mechanism: `visibility` is declarative metadata read by `delivery.mode: 'auto'` — the disk
+never applies an ACL and never probes the bucket, so the declaration must match reality the
+infrastructure already enforces.
+Source: `docs/storage/s3-disk.mdx` (visibility option, getVisibility).
+
+## References
+
+- Testing doubles for all three seams: use `@adonis-agora/media/testing` —
+  `InMemoryMediaStore`, `inMemoryDiskResolver` (with a `DiskVisibility` argument to test
+  `auto` delivery's unknown-visibility branch), `FakeImageProcessor`, `InMemoryUploadSessionStore`,
+  `FakeTransformer`. See `docs/testing.mdx`.
+
+See also: `media-dashboard-console/SKILL.md` — the console browses through these same
+ExtendedDisk operations and `MediaStore.list`.

package/skills/media-uploads-resumable/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: media-uploads-resumable
+description: >-
+  Large-file uploads in @adonis-agora/media — the uploads config key (mode auto|proxy|
+  direct, partSize, presignTtlSeconds, opt-in routes), media.uploads
+  (initiateDirectUpload/completeDirectUpload/proxyUpload, resolveUploadMode), resumable
+  TUS sessions via media.resumable and TusUploadHandler (UploadSessionStore, in-memory +
+  Lucid, byte-offset resume), direct sessions via media.direct (presigned part URLs,
+  part-granular resume, confirmPart/status), the DirectUploadPolicy hooks
+  (onInitiate/resolveComplete/onComplete/mapError, server-side keys), and adopting
+  finished uploads with completeUploadToLibrary / completeDirectUploadToLibrary /
+  attachExisting. Use when uploading big files, resuming interrupted uploads, writing an
+  upload policy, or fixing UploadNotSupportedError / UploadPartsIncompleteError /
+  ResumableUploadsNotConfiguredError.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/media"
+  library_version: "0.12.1"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-media:docs/uploads/upload-modes.mdx"
+  - "DavideCarvalho/adonis-media:docs/uploads/resumable-tus.mdx"
+  - "DavideCarvalho/adonis-media:docs/uploads/direct-sessions.mdx"
+  - "DavideCarvalho/adonis-media:docs/uploads/direct-upload-policy.mdx"
+  - "DavideCarvalho/adonis-media:packages/adonis/src/upload_mode.ts"
+---
+
+# Large-file uploads: proxy, direct-S3, TUS, and policies
+
+Beyond buffer-once `attach`, the library ships upload coordinators with three strategies:
+**proxy** (bytes stream through your app — any disk), **direct** (browser PUTs presigned
+multipart parts straight to S3 — multipart-capable disk only), and **resumable TUS**
+(byte-offset resume over the tus 1.0.0 protocol). `media.direct` adds session-backed direct
+uploads whose state survives a reload.
+
+## Setup
+
+```ts title="config/media.ts"
+import { defineConfig, disks, stores, uploadSessions } from '@adonis-agora/media'
+
+export default defineConfig({
+  disk: 's3',
+  disks: { s3: disks.s3({ bucket: 'my-bucket', region: 'us-east-1' }) },
+  store: 'lucid',
+  stores: { lucid: stores.lucid() },
+
+  uploads: {
+    mode: 'auto',              // auto picks direct on a multipart-capable disk, else proxy
+    partSize: 8 * 1024 * 1024, // S3 floor is 5 MiB, cap 10,000 parts
+    routes: { enabled: true, prefix: '/media/uploads' }, // opt-in, UNGUARDED routes
+
+    resumable: {               // opt-in — makes media.resumable exist
+      store: 'lucid',
+      stores: { lucid: uploadSessions.lucid() }, // durable, multi-process sessions
+      routes: { enabled: true, prefix: '/media/uploads/tus', maxSize: 5 * 1024 ** 3 },
+    },
+
+    direct: {                  // opt-in — makes media.direct exist
+      store: 'lucid',
+      stores: { lucid: uploadSessions.lucid() }, // same session store SPI as TUS
+      partSize: 20 * 1024 * 1024,
+      routes: {
+        enabled: true,
+        prefix: '/media/uploads/direct/sessions',
+        collection: 'videos',  // gate the declared type at initiate
+        middleware: [middleware.auth()], // the ONLY gate on these routes
+      },
+    },
+  },
+})
+```
+
+Naming a session `store` with no matching factory throws
+`UploadSessionStoreNotConfiguredError` — never a silent in-memory fallback.
+
+Source: `docs/uploads/upload-modes.mdx`, `docs/uploads/resumable-tus.mdx`, `docs/uploads/direct-sessions.mdx`.
+
+## Core patterns
+
+### Pattern 1 — resolve the mode yourself
+
+`proxy` is always allowed; `direct` is a REQUIREMENT that throws
+`UploadNotSupportedError` on an incapable disk; `auto` is a PREFERENCE that downgrades:
+
+```ts
+import { resolveUploadMode, isMultipartCapable } from '@adonis-agora/media'
+import type { ResolvedUploadMode, UploadModeLevels } from '@adonis-agora/media'
+
+const mode: ResolvedUploadMode = resolveUploadMode(
+  { global: 'auto', perCall: request.input('mode') } satisfies UploadModeLevels,
+  isMultipartCapable(media.disk('s3')),
+  's3',
+)
+```
+
+Source: `docs/uploads/upload-modes.mdx` (Resolving the mode yourself).
+
+### Pattern 2 — resumable TUS sessions
+
+The engine is framework-agnostic (`TusUploadHandler`); the provider mounts thin routes.
+Programmatically:
+
+```ts
+import media from '@adonis-agora/media/services/main'
+
+const session = await media.resumable.createUpload({
+  disk: 's3', key: `users/1/video.mp4`, size: file.size, contentType: 'video/mp4',
+})
+
+let { offset } = await media.resumable.writeChunk(session.id, 0, chunk1)
+;({ offset } = await media.resumable.writeChunk(session.id, offset, chunk2))
+await media.resumable.status(session.id) // { offset, size, expiresAt }
+
+const { key, disk, size } = await media.resumable.complete(session.id)
+```
+
+`media.hasResumable` guards access; `media.resumable` throws
+`ResumableUploadsNotConfiguredError` without config. A standard tus client (or
+`@adonis-agora/media-react`) points at `routes.prefix` and works unchanged.
+
+Source: `docs/uploads/resumable-tus.mdx` (media.resumable).
+
+### Pattern 3 — adopt finished uploads into the library (zero-copy)
+
+Do NOT read the bytes back through `attach()` — that buffers and rewrites the object.
+Register the object where it already is:
+
+```ts
+// TUS finalize:
+const record = await media.completeUploadToLibrary(session.id, {
+  ownerType: 'Patient', ownerId: patient.id, collection: 'exams',
+  fileName: 'exam.pdf', mimeType: 'application/pdf',
+})
+
+// direct sessions:
+const record2 = await media.completeDirectUploadToLibrary(created.id, {
+  ownerType: 'Lesson', ownerId: lesson.id, collection: 'videos',
+  fileName: 'original.mp4', mimeType: 'video/mp4',
+}, partsFromClient)
+```
+
+Both chain `library.attachExisting({ ..., key, disk, size })` — the collection's whitelist
+is re-validated against the real bytes (a short head read), `single: true` replace and
+ordering still apply, and nothing streams through the app.
+
+Source: `docs/uploads/resumable-tus.mdx` (Turning a finished upload into a media record).
+
+### Pattern 4 — a DirectUploadPolicy owns every app decision
+
+The handler owns mechanics; the policy owns decisions. With a policy, `keyFor` is never
+called — the key is computed server-side from authenticated context:
+
+```ts title="app/media/lesson_video_policy.ts"
+import { cuid } from '@adonisjs/core/helpers'
+import type { HttpContext } from '@adonisjs/core/http'
+import type { DirectUploadPolicy, InitiateDecision, CompleteResolution } from '@adonis-agora/media'
+
+export default class LessonVideoPolicy implements DirectUploadPolicy<HttpContext, { uploadRowId: string }> {
+  async onInitiate(ctx: HttpContext, input): Promise<InitiateDecision<{ uploadRowId: string }>> {
+    const user = ctx.auth.getUserOrFail()
+    const lesson = await Lesson.findOrFail(ctx.params.lessonId)
+    await ctx.bouncer.authorize('uploadLessonVideo', lesson) // ← authorization lives HERE
+
+    const key = `tenants/${user.tenantId}/lessons/${lesson.id}/${cuid()}.mp4`
+    const row = await LessonUpload.create({ lessonId: lesson.id, key, status: 'pending' })
+
+    return {
+      key,
+      collection: 'videos',
+      context: { uploadRowId: row.id },
+      rollback: () => row.delete(), // runs if anything AFTER this decision throws
+    }
+  }
+
+  async resolveComplete(ctx, input): Promise<CompleteResolution<{ uploadRowId: string }>> {
+    const row = await LessonUpload.findByOrFail('uploadSessionId', input.id)
+    return {
+      sessionId: input.id,
+      target: { ownerType: 'Lesson', ownerId: row.lessonId, collection: 'videos',
+                fileName: row.fileName, mimeType: 'video/mp4' },
+      context: { uploadRowId: row.id },
+    }
+  }
+
+  async onComplete(_ctx, { record, resolution }) {
+    await LessonUpload.query().where('id', resolution.context!.uploadRowId)
+      .update({ status: 'stored', mediaId: record.id })
+    return { mediaId: record.id, status: 'processing' } // ← IS the response body
+  }
+
+  mapError(_ctx, error) {
+    if (error instanceof AuthorizationException) return { status: 403, body: { error: 'forbidden' } }
+    return undefined // fall through to the handler's mapping
+  }
+}
+```
+
+Register it as a lazy thunk: `routes: { policy: () => import('#media/lesson_video_policy') }`.
+The module's default export is used — a class is instantiated with no arguments.
+
+Source: `docs/uploads/direct-upload-policy.mdx`.
+
+## Common mistakes
+
+### [CRITICAL] Shipping upload routes without middleware or a policy
+
+Wrong:
+
+```ts
+uploads: { direct: { routes: { enabled: true } } } // middleware defaults to []
+```
+
+Correct:
+
+```ts
+uploads: {
+  direct: {
+    routes: { enabled: true, middleware: [middleware.auth()],
+              policy: () => import('#media/lesson_video_policy') },
+  },
+}
+```
+
+Mechanism: the built-in routes are unguarded by design — `routes.middleware` defaults to
+`[]` and the handlers perform no authorization whatsoever, so the endpoints are open to the
+internet. Use middleware for "are you logged in" and policy hooks for "may you upload to
+THIS resource".
+Source: `docs/uploads/direct-sessions.mdx` (routes.middleware), `docs/uploads/direct-upload-policy.mdx` (warn callout).
+
+### [CRITICAL] Re-reading finished upload bytes through library.attach()
+
+Wrong:
+
+```ts
+const { key, disk } = await media.resumable.complete(session.id)
+const bytes = await media.disk(disk).getBytes(key) // buffers the whole file…
+await media.library.attach({ ..., contents: bytes }) // …and rewrites it to a new key
+```
+
+Correct:
+
+```ts
+const record = await media.completeUploadToLibrary(session.id, {
+  ownerType: 'Patient', ownerId: patient.id, collection: 'exams',
+  fileName: 'exam.pdf', mimeType: 'application/pdf',
+})
+```
+
+Mechanism: `attach` buffers the payload once and writes a NEW object — exactly what a
+resumable upload exists to avoid. `completeUploadToLibrary` /
+`completeDirectUploadToLibrary` chain `attachExisting`, which registers the existing key
+zero-copy.
+Source: `docs/uploads/resumable-tus.mdx` (Turning a finished upload into a media record).
+
+### [CRITICAL] Expecting direct uploads to work without bucket CORS exposing ETag
+
+Wrong:
+
+```json
+// bucket CORS: allowed origins/methods only
+{ "AllowedOrigins": ["https://app.example.com"], "AllowedMethods": ["PUT"] }
+```
+
+Correct:
+
+```json
+{ "AllowedOrigins": ["https://app.example.com"], "AllowedMethods": ["PUT"],
+  "ExposeHeaders": ["ETag"] }
+```
+
+Mechanism: the browser must read the `ETag` response header of each part PUT to confirm it;
+without `ExposeHeaders: ["ETag"]` no part can ever be confirmed — the single most common
+direct-upload misconfiguration (the client fails with an explicit "S3 did not expose an
+ETag" message).
+Source: `docs/uploads/direct-sessions.mdx` (warn callout: Bucket CORS must expose ETag), `docs/react/client.mdx`.
+
+### [MEDIUM] Forcing mode:direct on a disk without native multipart
+
+Wrong:
+
+```ts
+uploads: { mode: 'direct' } // disk is the local FS driver
+```
+
+Correct:
+
+```ts
+uploads: { mode: 'auto' } // downgrades to proxy on incapable disks
+```
+
+Mechanism: `direct` is a requirement, `auto` is a preference — forcing `direct` on a disk
+without native multipart throws `UploadNotSupportedError` (`E_MEDIA_UPLOAD_NOT_SUPPORTED`,
+mapped to 400 by the routes) rather than silently downgrading.
+Source: `docs/uploads/upload-modes.mdx` (Resolving the mode yourself).
+
+### [HIGH] Expecting a media record from policy-less direct completion
+
+Wrong:
+
+```ts
+await media.direct.complete(id) // returns { key, disk, size } — no MediaRecord created
+await media.library.url('???') // nothing to look up
+```
+
+Correct:
+
+```ts
+const record = await media.completeDirectUploadToLibrary(id, {
+  ownerType: 'Lesson', ownerId: lesson.id, collection: 'videos',
+  fileName: 'original.mp4', mimeType: 'video/mp4',
+})
+```
+
+Mechanism: without a `DirectUploadPolicy`, `complete` returns the raw assembled object and
+creates NO media record — adopting it into the library is the caller's job. With a policy,
+`resolveComplete` → `attachExisting` → `onComplete` runs automatically.
+Source: `docs/uploads/direct-upload-policy.mdx` (Without a policy).
+
+### [HIGH] Trusting client-supplied keys or TUS metadata as key segments
+
+Wrong:
+
+```ts
+// routes take `key` from the request body and use it verbatim
+const key = request.input('key')
+await media.proxyUpload({ key, contents })
+```
+
+Correct:
+
+```ts
+// resolve the key server-side from authenticated context (or use a policy)
+const user = await auth.getUserOrFail()
+await media.proxyUpload({ key: `users/${user.id}/${cuid()}.mp4`, contents })
+// TUS metadata: parse + validate before use
+const meta = parseTusMetadata(request.header('upload-metadata'))
+```
+
+Mechanism: the object key is yours to resolve server-side — a client-supplied key lets one
+tenant overwrite another's objects. TUS `Upload-Metadata` is browser input: validate it and
+never use it as a key segment unsanitized.
+Source: `docs/uploads/upload-modes.mdx` (media.uploads), `docs/react/client.mdx` (Custom TUS metadata warn).
+
+See also: `media-react-uploads/SKILL.md` — the browser half that speaks these routes;
+`media-library-collections/SKILL.md` — the collection policy that re-validates adopted
+uploads.