@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/dist/packages/stack/src/plugins/media/api/operations.mjs

@@ -0,0 +1,1290 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { OperationHttpError, defineOperation } from '@btst/stack/plugins/api';
+import { z } from 'zod';
+import { mediaPermissions } from '../../../../../../plugins/media/permissions.mjs';
+import { updateAssetSchema, AssetListQuerySchema, createAssetSchema, createFolderSchema, uploadTokenRequestSchema } from '../schemas.mjs';
+import { listAssets, getAssetById, listFolders, getFolderById } from './getters.mjs';
+import { createAsset } from './mutations.mjs';
+import { serializeAsset, serializeFolder } from './serializers.mjs';
+import { isDirectAdapter, isS3Adapter, isVercelBlobAdapter } from './storage-adapter.mjs';
+
+const AssetIdOperationInputSchema = z.object({ id: z.string() });
+const UpdateAssetOperationInputSchema = z.object({
+  id: z.string(),
+  data: updateAssetSchema
+});
+const FolderIdOperationInputSchema = z.object({ id: z.string() });
+const FolderListOperationInputSchema = z.object({
+  parentId: z.string().nullable().optional()
+});
+const DirectUploadOperationInputSchema = z.object({
+  filename: z.string().min(1),
+  mimeType: z.string(),
+  size: z.number().int().min(0),
+  contentBase64: z.string(),
+  folderId: z.string().optional()
+});
+const VercelGenerateBodySchema = z.object({
+  type: z.literal("blob.generate-client-token"),
+  payload: z.object({
+    pathname: z.string(),
+    multipart: z.boolean(),
+    clientPayload: z.string().nullable(),
+    callbackUrl: z.string().optional()
+  })
+});
+const VercelCallbackBodyShape = z.object({
+  type: z.literal("blob.upload-completed"),
+  payload: z.object({
+    blob: z.object({ url: z.string(), pathname: z.string() }),
+    tokenPayload: z.string().nullable().optional()
+  })
+});
+const VercelCallbackBodySchema = z.custom(
+  (value) => VercelCallbackBodyShape.safeParse(value).success,
+  "Invalid Vercel Blob callback body"
+);
+const LegacyVercelGenerateBodySchema = z.object({
+  pathname: z.string(),
+  clientPayload: z.string().nullable().optional()
+});
+const VercelClientPayloadSchema = z.object({
+  mimeType: z.string().min(1).optional(),
+  size: z.number().int().min(0).optional(),
+  folderId: z.string().min(1).optional()
+});
+const VercelBlobOperationInputSchema = z.object({
+  body: z.union([
+    VercelGenerateBodySchema,
+    VercelCallbackBodySchema,
+    LegacyVercelGenerateBodySchema
+  ])
+});
+class MediaOperationError extends OperationHttpError {
+  constructor(statusCode, message, code) {
+    super(statusCode, message, code);
+    this.name = "MediaOperationError";
+  }
+}
+function assetSnapshot(asset) {
+  return {
+    id: asset.id,
+    filename: asset.filename,
+    originalName: asset.originalName,
+    mimeType: asset.mimeType,
+    size: asset.size,
+    url: asset.url,
+    ...asset.folderId ? { folderId: asset.folderId } : {},
+    ...asset.alt ? { alt: asset.alt } : {},
+    ...asset.tenantId ? { tenantId: asset.tenantId } : {},
+    createdAt: asset.createdAt,
+    ...asset.updatedAt ? { updatedAt: asset.updatedAt } : {}
+  };
+}
+function folderSnapshot(folder) {
+  return {
+    id: folder.id,
+    name: folder.name,
+    ...folder.parentId ? { parentId: folder.parentId } : {},
+    ...folder.tenantId ? { tenantId: folder.tenantId } : {},
+    createdAt: folder.createdAt,
+    ...folder.updatedAt ? { updatedAt: folder.updatedAt } : {}
+  };
+}
+function sameDate(left, right) {
+  return left?.getTime() === right?.getTime();
+}
+function sameAsset(asset, expected) {
+  return asset !== null && asset.id === expected.id && asset.filename === expected.filename && asset.originalName === expected.originalName && asset.mimeType === expected.mimeType && asset.size === expected.size && asset.url === expected.url && (asset.folderId || void 0) === expected.folderId && (asset.alt || void 0) === expected.alt && (asset.tenantId || void 0) === expected.tenantId && sameDate(asset.createdAt, expected.createdAt) && sameDate(asset.updatedAt, expected.updatedAt);
+}
+function sameFolder(folder, expected) {
+  return folder !== null && folder.id === expected.id && folder.name === expected.name && (folder.parentId || void 0) === expected.parentId && (folder.tenantId || void 0) === expected.tenantId && sameDate(folder.createdAt, expected.createdAt) && sameDate(folder.updatedAt, expected.updatedAt);
+}
+function nextVersion(previous) {
+  return new Date(Math.max(Date.now(), previous.getTime() + 1));
+}
+const AFFECTED_ROW_KEYS = [
+  "rowCount",
+  "affectedRows",
+  "rowsAffected",
+  "changes",
+  "numUpdatedRows"
+];
+function positive(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 || typeof value === "bigint" && value > 0n;
+}
+function didAffectRow(result, id) {
+  if (typeof result === "number" || typeof result === "bigint")
+    return positive(result);
+  if (!result || typeof result !== "object") return false;
+  const record = result;
+  if ("count" in record) return positive(record.count);
+  if (Array.isArray(result))
+    return result.length > 0 && didAffectRow(result[0], id);
+  for (const key of AFFECTED_ROW_KEYS) {
+    if (key in record) return positive(record[key]);
+  }
+  if ("meta" in record) {
+    const meta = record.meta;
+    return Boolean(
+      meta && typeof meta === "object" && "changes" in meta && positive(meta.changes)
+    );
+  }
+  return record.id === id;
+}
+function assetWhere(snapshot) {
+  return [
+    { field: "id", value: snapshot.id, operator: "eq" },
+    { field: "filename", value: snapshot.filename, operator: "eq" },
+    {
+      field: "originalName",
+      value: snapshot.originalName,
+      operator: "eq"
+    },
+    { field: "mimeType", value: snapshot.mimeType, operator: "eq" },
+    { field: "size", value: snapshot.size, operator: "eq" },
+    { field: "url", value: snapshot.url, operator: "eq" },
+    {
+      field: "folderId",
+      value: snapshot.folderId ?? null,
+      operator: "eq"
+    },
+    { field: "alt", value: snapshot.alt ?? null, operator: "eq" },
+    {
+      field: "tenantId",
+      value: snapshot.tenantId ?? null,
+      operator: "eq"
+    },
+    { field: "createdAt", value: snapshot.createdAt, operator: "eq" },
+    ...snapshot.updatedAt ? [
+      {
+        field: "updatedAt",
+        value: snapshot.updatedAt,
+        operator: "eq"
+      }
+    ] : []
+  ];
+}
+function folderWhere(snapshot) {
+  return [
+    { field: "id", value: snapshot.id, operator: "eq" },
+    { field: "name", value: snapshot.name, operator: "eq" },
+    {
+      field: "parentId",
+      value: snapshot.parentId ?? null,
+      operator: "eq"
+    },
+    {
+      field: "tenantId",
+      value: snapshot.tenantId ?? null,
+      operator: "eq"
+    },
+    { field: "createdAt", value: snapshot.createdAt, operator: "eq" },
+    ...snapshot.updatedAt ? [
+      {
+        field: "updatedAt",
+        value: snapshot.updatedAt,
+        operator: "eq"
+      }
+    ] : []
+  ];
+}
+function staleStateError() {
+  return new MediaOperationError(
+    409,
+    "Media state changed while authorization was being evaluated. Retry the operation.",
+    "MEDIA_STATE_CHANGED"
+  );
+}
+function notFound(entity) {
+  return new MediaOperationError(
+    404,
+    `${entity} not found`,
+    `${entity.toUpperCase()}_NOT_FOUND`
+  );
+}
+function normalizeError(error, fallback) {
+  return error instanceof Error ? error : new Error(typeof error === "string" ? error : fallback, { cause: error });
+}
+async function runDomainHook(run, code) {
+  try {
+    return await run();
+  } catch (error) {
+    throw new MediaOperationError(
+      403,
+      normalizeError(error, "Media operation rejected").message,
+      code
+    );
+  }
+}
+function hookContext(context, legacy = {}) {
+  return Object.freeze({
+    ...context,
+    ...context.request ? { request: context.request, headers: context.request.headers } : {},
+    ...legacy
+  });
+}
+async function notifyError(hook, error, context, legacy = {}) {
+  try {
+    await hook?.(
+      normalizeError(error, "Media operation failed"),
+      hookContext(context, legacy)
+    );
+  } catch {
+  }
+}
+function matchesUrlPrefix(url, prefix) {
+  const trimmed = prefix.trim();
+  if (!trimmed) return false;
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(trimmed)) {
+    if (trimmed.endsWith("://")) return url.startsWith(trimmed);
+    const normalized = trimmed.replace(/\/+$/, "");
+    return url === normalized || url.startsWith(`${normalized}/`);
+  }
+  return url.startsWith(`${trimmed.replace(/\/+$/, "")}/`);
+}
+function sanitizeS3KeySegment(value) {
+  return value.replace(/[/\\]/g, "-").replace(/\.\./g, "_").trim() || "unknown";
+}
+function validateMimeType(mimeType, allowed) {
+  if (!allowed?.length) return;
+  const accepted = allowed.some(
+    (pattern) => pattern.endsWith("/*") ? mimeType.startsWith(pattern.slice(0, -1)) : mimeType === pattern
+  );
+  if (!accepted) {
+    throw new MediaOperationError(
+      415,
+      `MIME type '${mimeType}' is not allowed. Allowed: ${allowed.join(", ")}`,
+      "MIME_TYPE_NOT_ALLOWED"
+    );
+  }
+}
+function validateSize(size, maximum) {
+  if (size > maximum) {
+    throw new MediaOperationError(
+      413,
+      `File size ${size} bytes exceeds the limit of ${maximum} bytes`,
+      "FILE_TOO_LARGE"
+    );
+  }
+}
+function validateAssetUrl(url, storageAdapter, allowedUrlPrefixes) {
+  let allowed = true;
+  let message = "";
+  if (allowedUrlPrefixes?.length) {
+    allowed = allowedUrlPrefixes.some(
+      (prefix) => matchesUrlPrefix(url, prefix)
+    );
+    message = `URL must start with one of: ${allowedUrlPrefixes.join(", ")}`;
+  } else if (isDirectAdapter(storageAdapter)) {
+    allowed = false;
+    message = "Client-supplied asset URLs are not allowed with localAdapter. Use POST /media/upload instead, or configure allowedUrlPrefixes to explicitly allow trusted URL prefixes.";
+  } else if (isS3Adapter(storageAdapter)) {
+    allowed = matchesUrlPrefix(url, storageAdapter.urlPrefix);
+    message = `URL must start with the configured S3 publicBaseUrl: ${storageAdapter.urlPrefix}`;
+  } else if (isVercelBlobAdapter(storageAdapter)) {
+    try {
+      allowed = new URL(url).hostname.endsWith(
+        storageAdapter.urlHostnameSuffix
+      );
+    } catch {
+      allowed = false;
+    }
+    message = `URL hostname must end with ${storageAdapter.urlHostnameSuffix}`;
+  }
+  if (!allowed)
+    throw new MediaOperationError(400, message, "ASSET_URL_NOT_ALLOWED");
+}
+function assetFacts(snapshot) {
+  return {
+    assetId: snapshot.id,
+    ...snapshot.folderId ? { folderId: snapshot.folderId } : {},
+    mimeType: snapshot.mimeType,
+    ...snapshot.tenantId ? { tenantId: snapshot.tenantId } : {}
+  };
+}
+function folderFacts(snapshot) {
+  return {
+    folderId: snapshot.id,
+    ...snapshot.parentId ? { parentId: snapshot.parentId } : {},
+    ...snapshot.tenantId ? { tenantId: snapshot.tenantId } : {}
+  };
+}
+function withoutTenant(value) {
+  const { tenantId: _tenantId, ...safe } = value;
+  return safe;
+}
+function plainStorageResult(value) {
+  if (value === void 0) return null;
+  let serialized;
+  try {
+    serialized = JSON.stringify(value);
+  } catch (error) {
+    throw new TypeError(
+      "Storage adapter returned a non-serializable response.",
+      { cause: error }
+    );
+  }
+  if (serialized === void 0) return null;
+  return JSON.parse(serialized);
+}
+function operationAsset(asset) {
+  return serializeAsset(asset);
+}
+function operationFolder(folder) {
+  return serializeFolder(folder);
+}
+function operationUploadToken(token) {
+  return token;
+}
+const memoryRollbackMarkers = /* @__PURE__ */ new WeakMap();
+function markMemoryRollback(adapter, error) {
+  memoryRollbackMarkers.get(adapter)?.(error);
+}
+function serializeMemoryOperations(adapter) {
+  if (adapter.id !== "memory" || memoryRollbackMarkers.has(adapter)) {
+    return adapter;
+  }
+  const source = { ...adapter };
+  const lockContext = new AsyncLocalStorage();
+  let tail = Promise.resolve();
+  let activeOwner;
+  const withLock = async (run) => {
+    const inherited = lockContext.getStore();
+    if (inherited && inherited.owner === activeOwner) {
+      return run(inherited.adapter);
+    }
+    let release = () => {
+    };
+    const previous = tail;
+    tail = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    const owner = {};
+    activeOwner = owner;
+    try {
+      return await lockContext.run(
+        { owner, adapter: source },
+        () => run(source)
+      );
+    } finally {
+      if (activeOwner === owner) activeOwner = void 0;
+      release();
+    }
+  };
+  const serialized = {
+    ...source,
+    create: ((input) => withLock((active) => active.create(input))),
+    findOne: ((input) => withLock((active) => active.findOne(input))),
+    findMany: ((input) => withLock((active) => active.findMany(input))),
+    count: (input) => withLock((active) => active.count(input)),
+    update: ((input) => withLock((active) => active.update(input))),
+    updateMany: (input) => withLock((active) => active.updateMany(input)),
+    delete: ((input) => withLock((active) => active.delete(input))),
+    deleteMany: (input) => withLock((active) => active.deleteMany(input)),
+    consumeOne: ((input) => withLock((active) => active.consumeOne(input))),
+    transaction: ((callback) => withLock((active) => {
+      const context = lockContext.getStore();
+      if (!context) throw new TypeError("Missing memory lock context.");
+      if (context.inTransaction) {
+        return callback(active).catch((error) => {
+          context.rollbackOnly = true;
+          context.rollbackError = error;
+          throw error;
+        });
+      }
+      if (!active.transaction) {
+        throw new TypeError("Missing memory transaction adapter.");
+      }
+      return active.transaction(
+        (tx) => lockContext.run(
+          { owner: context.owner, adapter: tx, inTransaction: true },
+          async () => {
+            const transactionContext = lockContext.getStore();
+            const result = await callback(tx);
+            if (transactionContext?.rollbackOnly) {
+              throw transactionContext.rollbackError;
+            }
+            return result;
+          }
+        )
+      );
+    }))
+  };
+  Object.assign(adapter, serialized);
+  memoryRollbackMarkers.set(adapter, (error) => {
+    const context = lockContext.getStore();
+    if (!context || context.owner !== activeOwner || !context.inTransaction) {
+      return;
+    }
+    context.rollbackOnly = true;
+    context.rollbackError = error;
+  });
+  return adapter;
+}
+function requireAtomicTransactions(adapter) {
+  if (adapter.id !== "memory" && typeof adapter.options?.adapterConfig.transaction !== "function") {
+    throw new MediaOperationError(
+      500,
+      "Media writes require an adapter with isolated transaction support.",
+      "ATOMIC_TRANSACTION_REQUIRED"
+    );
+  }
+}
+async function claimAsset(adapter, snapshot) {
+  const claimedAt = nextVersion(snapshot.updatedAt ?? snapshot.createdAt);
+  const result = await adapter.updateMany({
+    model: "mediaAsset",
+    where: assetWhere(snapshot),
+    update: { updatedAt: claimedAt }
+  });
+  if (!didAffectRow(result, snapshot.id)) throw staleStateError();
+  return claimedAt;
+}
+async function claimFolder(adapter, snapshot) {
+  const claimedAt = nextVersion(snapshot.updatedAt ?? snapshot.createdAt);
+  const result = await adapter.updateMany({
+    model: "mediaFolder",
+    where: folderWhere(snapshot),
+    update: { updatedAt: claimedAt }
+  });
+  if (!didAffectRow(result, snapshot.id)) throw staleStateError();
+  return claimedAt;
+}
+async function restoreFolder(adapter, snapshot, claimedAt) {
+  const result = await adapter.updateMany({
+    model: "mediaFolder",
+    where: folderWhere({ ...snapshot, updatedAt: claimedAt }),
+    update: { updatedAt: snapshot.updatedAt ?? snapshot.createdAt }
+  });
+  if (!didAffectRow(result, snapshot.id)) throw staleStateError();
+}
+async function collectFolderSubtree(adapter, root) {
+  const subtree = [root];
+  const seen = /* @__PURE__ */ new Set([root.id]);
+  for (let index = 0; index < subtree.length; index++) {
+    const children = await adapter.findMany({
+      model: "mediaFolder",
+      where: [{ field: "parentId", value: subtree[index].id }]
+    });
+    for (const child of children) {
+      if (seen.has(child.id)) throw staleStateError();
+      if ((child.tenantId || void 0) !== root.tenantId) {
+        throw staleStateError();
+      }
+      seen.add(child.id);
+      subtree.push(folderSnapshot(child));
+    }
+  }
+  return subtree;
+}
+async function verifyClaimedFolderSubtree(adapter, subtree, claims) {
+  const root = subtree[0];
+  if (!root) throw staleStateError();
+  const currentSubtree = await collectFolderSubtree(adapter, {
+    ...root,
+    updatedAt: claims.get(root.id)
+  });
+  if (currentSubtree.length !== subtree.length) throw staleStateError();
+  const expectedById = new Map(
+    subtree.map((folder) => [folder.id, folder])
+  );
+  for (const current of currentSubtree) {
+    const expected = expectedById.get(current.id);
+    if (!expected || !sameFolder(current, {
+      ...expected,
+      updatedAt: claims.get(expected.id)
+    })) {
+      throw staleStateError();
+    }
+  }
+  let totalAssets = 0;
+  for (const folder of subtree) {
+    totalAssets += await adapter.count({
+      model: "mediaAsset",
+      where: [{ field: "folderId", value: folder.id }]
+    });
+  }
+  if (totalAssets > 0) {
+    throw new MediaOperationError(
+      409,
+      `Cannot delete folder: it or one of its subfolders contains ${totalAssets} asset(s). Move or delete them first.`,
+      "FOLDER_NOT_EMPTY"
+    );
+  }
+}
+function parseVercelInitialize(body) {
+  const record = body;
+  const payload = record.payload && typeof record.payload === "object" && !Array.isArray(record.payload) ? record.payload : record;
+  const pathname = typeof payload.pathname === "string" ? payload.pathname : "asset";
+  const clientPayload = typeof payload.clientPayload === "string" ? payload.clientPayload : null;
+  let parsed = {};
+  try {
+    parsed = VercelClientPayloadSchema.parse(
+      clientPayload ? JSON.parse(clientPayload) : {}
+    );
+  } catch {
+    throw new MediaOperationError(
+      400,
+      "Invalid Vercel Blob client upload metadata.",
+      "INVALID_UPLOAD_BODY"
+    );
+  }
+  return {
+    pathname,
+    filename: pathname.split("/").pop() ?? pathname,
+    mimeType: parsed.mimeType ?? "application/octet-stream",
+    size: parsed.size,
+    folderId: parsed.folderId
+  };
+}
+function createMediaOperations(sourceAdapter, config) {
+  const adapter = serializeMemoryOperations(sourceAdapter);
+  const {
+    storageAdapter,
+    maxFileSizeBytes = 10 * 1024 * 1024,
+    allowedMimeTypes,
+    allowedUrlPrefixes,
+    hooks,
+    resolveTenantId
+  } = config;
+  const tenants = /* @__PURE__ */ new WeakMap();
+  const assetLists = /* @__PURE__ */ new WeakMap();
+  const assets = /* @__PURE__ */ new WeakMap();
+  const folders = /* @__PURE__ */ new WeakMap();
+  const targetFolders = /* @__PURE__ */ new WeakMap();
+  const folderSubtrees = /* @__PURE__ */ new WeakMap();
+  const vercelContexts = /* @__PURE__ */ new WeakMap();
+  const resolveTenant = async (input, request, legacy) => {
+    const tenantId = request && resolveTenantId ? await resolveTenantId({
+      input,
+      request,
+      headers: request.headers,
+      ...legacy
+    }) ?? void 0 : void 0;
+    tenants.set(input, tenantId);
+    return tenantId;
+  };
+  const loadFolder = async (id, tenantId) => {
+    if (!id) return void 0;
+    const folder = await getFolderById(adapter, id);
+    if (!folder || tenantId !== void 0 && folder.tenantId !== tenantId) {
+      throw notFound("Folder");
+    }
+    return folderSnapshot(folder);
+  };
+  const bindFolderTenant = (input, resolvedTenantId, folder) => {
+    const tenantId = resolvedTenantId ?? folder?.tenantId;
+    tenants.set(input, tenantId);
+    return tenantId;
+  };
+  const verifyFolder = async (reader, snapshot) => {
+    if (!snapshot) return;
+    const current = await reader.findOne({
+      model: "mediaFolder",
+      where: [{ field: "id", value: snapshot.id }]
+    }) ?? null;
+    if (!sameFolder(current, snapshot)) throw staleStateError();
+  };
+  const listAssetsOperation = defineOperation({
+    input: AssetListQuerySchema,
+    permission: mediaPermissions.library.read,
+    facts: async ({ input, request }) => {
+      await resolveTenant(input, request, { query: input });
+      return void 0;
+    },
+    additionalPermissions: async ({ input }) => {
+      const result = await listAssets(adapter, {
+        ...input,
+        tenantId: tenants.get(input)
+      });
+      assetLists.set(input, result);
+      return result.items.map(
+        (asset) => mediaPermissions.asset.read(assetFacts(assetSnapshot(asset)))
+      );
+    },
+    execute: async (context) => {
+      await runDomainHook(
+        () => hooks?.onBeforeListAssets?.(
+          { ...context.input },
+          hookContext(context, { query: context.input })
+        ),
+        "LIST_ASSETS_REJECTED"
+      );
+      const result = assetLists.get(context.input);
+      assetLists.delete(context.input);
+      if (!result) {
+        throw new MediaOperationError(
+          500,
+          "Asset-list authorization snapshot is unavailable.",
+          "AUTHORIZATION_SNAPSHOT_MISSING"
+        );
+      }
+      return {
+        items: result.items.map(
+          (asset) => withoutTenant(serializeAsset(asset))
+        ),
+        total: result.total,
+        ...result.limit !== void 0 ? { limit: result.limit } : {},
+        ...result.offset !== void 0 ? { offset: result.offset } : {}
+      };
+    },
+    onError: ({ error, ...context }) => notifyError(hooks?.onError, error, context, {
+      query: context.input
+    })
+  });
+  const createAssetOperation = defineOperation({
+    input: createAssetSchema,
+    permission: mediaPermissions.asset.upload,
+    facts: async ({ input, request }) => {
+      const tenantId = await resolveTenant(input, request, {
+        body: input
+      });
+      const folder = await loadFolder(input.folderId, tenantId);
+      const effectiveTenantId = bindFolderTenant(
+        input,
+        tenantId,
+        folder
+      );
+      folders.set(input, folder);
+      return {
+        phase: "finalize",
+        ...folder ? { folderId: folder.id } : {},
+        mimeType: input.mimeType,
+        ...effectiveTenantId ? { tenantId: effectiveTenantId } : {}
+      };
+    },
+    execute: (context) => {
+      requireAtomicTransactions(adapter);
+      return adapter.transaction(async (tx) => {
+        const folder = folders.get(context.input);
+        await verifyFolder(tx, folder);
+        const folderClaim = folder ? await claimFolder(tx, folder) : void 0;
+        await runDomainHook(
+          () => hooks?.onBeforeUpload?.(
+            {
+              filename: context.input.filename,
+              mimeType: context.input.mimeType,
+              size: context.input.size
+            },
+            hookContext(context, { body: context.input })
+          ),
+          "UPLOAD_REJECTED"
+        );
+        validateMimeType(context.input.mimeType, allowedMimeTypes);
+        validateSize(context.input.size, maxFileSizeBytes);
+        validateAssetUrl(context.input.url, storageAdapter, allowedUrlPrefixes);
+        const asset = await createAsset(tx, {
+          ...context.input,
+          tenantId: tenants.get(context.input)
+        });
+        if (folder && folderClaim) await restoreFolder(tx, folder, folderClaim);
+        return operationAsset(asset);
+      });
+    },
+    after: ((context) => hooks?.onAfterUpload?.(
+      context.result,
+      hookContext(context, { body: context.input })
+    )),
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onError, error, context, {
+        body: context.input
+      });
+    }
+  });
+  const updateAssetOperation = defineOperation({
+    input: UpdateAssetOperationInputSchema,
+    permission: mediaPermissions.asset.update,
+    facts: async ({ input, request }) => {
+      const tenantId = await resolveTenant(input, request, {
+        body: input.data,
+        params: { id: input.id }
+      });
+      const asset = await getAssetById(adapter, input.id);
+      if (!asset || tenantId !== void 0 && asset.tenantId !== tenantId) {
+        throw notFound("Asset");
+      }
+      const snapshot = assetSnapshot(asset);
+      assets.set(input, snapshot);
+      const changesFolder = Object.hasOwn(input.data, "folderId");
+      const target = typeof input.data.folderId === "string" ? await loadFolder(input.data.folderId, tenantId) : void 0;
+      if (target && target.tenantId !== snapshot.tenantId) {
+        throw notFound("Folder");
+      }
+      targetFolders.set(input, target);
+      return {
+        ...assetFacts(snapshot),
+        ...changesFolder ? { targetFolderId: target?.id ?? null } : {}
+      };
+    },
+    execute: (context) => {
+      requireAtomicTransactions(adapter);
+      return adapter.transaction(async (tx) => {
+        const snapshot = assets.get(context.input);
+        if (!snapshot) throw staleStateError();
+        const current = await tx.findOne({
+          model: "mediaAsset",
+          where: [{ field: "id", value: snapshot.id }]
+        }) ?? null;
+        if (!sameAsset(current, snapshot)) throw staleStateError();
+        const target = targetFolders.get(context.input);
+        await verifyFolder(tx, target);
+        const targetClaim = target ? await claimFolder(tx, target) : void 0;
+        const claimedAt = await claimAsset(tx, snapshot);
+        await runDomainHook(
+          () => hooks?.onBeforeUpdateAsset?.(
+            operationAsset(current),
+            { ...context.input.data },
+            hookContext(context, {
+              body: context.input.data,
+              params: { id: context.input.id }
+            })
+          ),
+          "UPDATE_ASSET_REJECTED"
+        );
+        const update = {
+          ...context.input.data.alt !== void 0 ? { alt: context.input.data.alt } : {},
+          ...Object.hasOwn(context.input.data, "folderId") ? { folderId: context.input.data.folderId } : {},
+          updatedAt: nextVersion(claimedAt)
+        };
+        const matched = await tx.updateMany({
+          model: "mediaAsset",
+          where: assetWhere({ ...snapshot, updatedAt: claimedAt }),
+          update
+        });
+        if (!didAffectRow(matched, snapshot.id)) throw staleStateError();
+        if (target && targetClaim) await restoreFolder(tx, target, targetClaim);
+        const updated = await getAssetById(tx, snapshot.id);
+        if (!updated) throw notFound("Asset");
+        return operationAsset(updated);
+      });
+    },
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onError, error, context, {
+        body: context.input.data,
+        params: { id: context.input.id }
+      });
+    }
+  });
+  const deleteAssetOperation = defineOperation({
+    input: AssetIdOperationInputSchema,
+    permission: mediaPermissions.asset.delete,
+    facts: async ({ input, request }) => {
+      const tenantId = await resolveTenant(input, request, {
+        params: { id: input.id }
+      });
+      const asset = await getAssetById(adapter, input.id);
+      if (!asset || tenantId !== void 0 && asset.tenantId !== tenantId) {
+        throw notFound("Asset");
+      }
+      const snapshot = assetSnapshot(asset);
+      assets.set(input, snapshot);
+      return assetFacts(snapshot);
+    },
+    execute: (context) => {
+      requireAtomicTransactions(adapter);
+      return adapter.transaction(async (tx) => {
+        const snapshot = assets.get(context.input);
+        if (!snapshot) throw staleStateError();
+        const current = await getAssetById(tx, snapshot.id);
+        if (!sameAsset(current, snapshot)) throw staleStateError();
+        const claimedAt = await claimAsset(tx, snapshot);
+        await runDomainHook(
+          () => hooks?.onBeforeDeleteAsset?.(
+            operationAsset(current),
+            hookContext(context, { params: { id: context.input.id } })
+          ),
+          "DELETE_ASSET_REJECTED"
+        );
+        try {
+          await storageAdapter.delete(snapshot.url);
+        } catch (error) {
+          throw new MediaOperationError(
+            500,
+            "Failed to delete file from storage",
+            "STORAGE_DELETE_FAILED"
+          );
+        }
+        const deleted = await tx.deleteMany({
+          model: "mediaAsset",
+          where: assetWhere({ ...snapshot, updatedAt: claimedAt })
+        });
+        if (!didAffectRow(deleted, snapshot.id)) throw staleStateError();
+        return { success: true };
+      });
+    },
+    after: (context) => hooks?.onAfterDeleteAsset?.(
+      context.input.id,
+      hookContext(context, { params: { id: context.input.id } })
+    ),
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onError, error, context, {
+        params: { id: context.input.id }
+      });
+    }
+  });
+  const listFoldersOperation = defineOperation({
+    input: FolderListOperationInputSchema,
+    permission: mediaPermissions.library.read,
+    facts: async ({ input, request }) => {
+      await resolveTenant(input, request, { query: input });
+      return void 0;
+    },
+    execute: async (context) => {
+      const filter = { parentId: context.input.parentId };
+      await runDomainHook(
+        () => hooks?.onBeforeListFolders?.(
+          filter,
+          hookContext(context, { query: context.input })
+        ),
+        "LIST_FOLDERS_REJECTED"
+      );
+      const result = await listFolders(adapter, {
+        ...filter,
+        tenantId: tenants.get(context.input)
+      });
+      return result.map((folder) => withoutTenant(serializeFolder(folder)));
+    },
+    onError: ({ error, ...context }) => notifyError(hooks?.onError, error, context, {
+      query: context.input
+    })
+  });
+  const createFolderOperation = defineOperation({
+    input: createFolderSchema,
+    permission: mediaPermissions.folder.create,
+    facts: async ({ input, request }) => {
+      const tenantId = await resolveTenant(input, request, {
+        body: input
+      });
+      const parent = await loadFolder(input.parentId, tenantId);
+      const effectiveTenantId = bindFolderTenant(
+        input,
+        tenantId,
+        parent
+      );
+      folders.set(input, parent);
+      return {
+        ...parent ? { parentId: parent.id } : {},
+        ...effectiveTenantId ? { tenantId: effectiveTenantId } : {}
+      };
+    },
+    execute: (context) => {
+      requireAtomicTransactions(adapter);
+      return adapter.transaction(async (tx) => {
+        const parent = folders.get(context.input);
+        await verifyFolder(tx, parent);
+        const parentClaim = parent ? await claimFolder(tx, parent) : void 0;
+        await runDomainHook(
+          () => hooks?.onBeforeCreateFolder?.(
+            { ...context.input },
+            hookContext(context, { body: context.input })
+          ),
+          "CREATE_FOLDER_REJECTED"
+        );
+        const now = /* @__PURE__ */ new Date();
+        const folder = await tx.create({
+          model: "mediaFolder",
+          data: {
+            ...context.input,
+            tenantId: tenants.get(context.input),
+            createdAt: now,
+            updatedAt: now
+          }
+        });
+        if (parent && parentClaim) await restoreFolder(tx, parent, parentClaim);
+        return operationFolder(folder);
+      });
+    },
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onError, error, context, {
+        body: context.input
+      });
+    }
+  });
+  const deleteFolderOperation = defineOperation({
+    input: FolderIdOperationInputSchema,
+    permission: mediaPermissions.folder.delete,
+    facts: async ({ input, request }) => {
+      const tenantId = await resolveTenant(input, request, {
+        params: { id: input.id }
+      });
+      const folder = await loadFolder(input.id, tenantId);
+      if (!folder) throw notFound("Folder");
+      folders.set(input, folder);
+      return folderFacts(folder);
+    },
+    additionalPermissions: async ({ input }) => {
+      const root = folders.get(input);
+      if (!root) throw staleStateError();
+      const subtree = await collectFolderSubtree(adapter, root);
+      folderSubtrees.set(input, subtree);
+      return subtree.slice(1).map((folder) => mediaPermissions.folder.delete(folderFacts(folder)));
+    },
+    execute: (context) => {
+      requireAtomicTransactions(adapter);
+      return adapter.transaction(async (tx) => {
+        const subtree = folderSubtrees.get(context.input);
+        folderSubtrees.delete(context.input);
+        if (!subtree?.length) throw staleStateError();
+        const snapshot = subtree[0];
+        const claims = /* @__PURE__ */ new Map();
+        for (const folder of subtree) {
+          claims.set(folder.id, await claimFolder(tx, folder));
+        }
+        await verifyClaimedFolderSubtree(tx, subtree, claims);
+        await runDomainHook(
+          () => hooks?.onBeforeDeleteFolder?.(
+            operationFolder({
+              ...snapshot,
+              updatedAt: snapshot.updatedAt
+            }),
+            hookContext(context, { params: { id: context.input.id } })
+          ),
+          "DELETE_FOLDER_REJECTED"
+        );
+        await verifyClaimedFolderSubtree(tx, subtree, claims);
+        for (const folder of [...subtree].reverse()) {
+          const deleted = await tx.deleteMany({
+            model: "mediaFolder",
+            where: folderWhere({
+              ...folder,
+              updatedAt: claims.get(folder.id)
+            })
+          });
+          if (!didAffectRow(deleted, folder.id)) throw staleStateError();
+        }
+        return { success: true };
+      });
+    },
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onError, error, context, {
+        params: { id: context.input.id }
+      });
+    }
+  });
+  const uploadDirectOperation = defineOperation({
+    input: DirectUploadOperationInputSchema,
+    permission: mediaPermissions.asset.upload,
+    facts: async ({ input, request }) => {
+      const tenantId = await resolveTenant(input, request, {
+        body: input
+      });
+      const folder = await loadFolder(input.folderId, tenantId);
+      const effectiveTenantId = bindFolderTenant(
+        input,
+        tenantId,
+        folder
+      );
+      folders.set(input, folder);
+      return {
+        phase: "direct",
+        ...folder ? { folderId: folder.id } : {},
+        mimeType: input.mimeType,
+        ...effectiveTenantId ? { tenantId: effectiveTenantId } : {}
+      };
+    },
+    execute: async (context) => {
+      requireAtomicTransactions(adapter);
+      if (!isDirectAdapter(storageAdapter)) {
+        throw new MediaOperationError(
+          400,
+          "Direct upload is only supported with the local storage adapter",
+          "DIRECT_UPLOAD_UNSUPPORTED"
+        );
+      }
+      let uploadedUrl;
+      try {
+        return await adapter.transaction(async (tx) => {
+          const folder = folders.get(context.input);
+          await verifyFolder(tx, folder);
+          const folderClaim = folder ? await claimFolder(tx, folder) : void 0;
+          await runDomainHook(
+            () => hooks?.onBeforeUpload?.(
+              {
+                filename: context.input.filename,
+                mimeType: context.input.mimeType,
+                size: context.input.size
+              },
+              hookContext(context, { body: context.input })
+            ),
+            "UPLOAD_REJECTED"
+          );
+          validateMimeType(context.input.mimeType, allowedMimeTypes);
+          validateSize(context.input.size, maxFileSizeBytes);
+          const buffer = Buffer.from(context.input.contentBase64, "base64");
+          if (buffer.byteLength !== context.input.size) {
+            throw new MediaOperationError(
+              400,
+              "Uploaded file size does not match its bytes",
+              "INVALID_UPLOAD_SIZE"
+            );
+          }
+          const { url } = await storageAdapter.upload(buffer, {
+            filename: context.input.filename,
+            mimeType: context.input.mimeType,
+            size: context.input.size,
+            ...folder ? { folderId: folder.id } : {}
+          });
+          uploadedUrl = url;
+          const asset = await createAsset(tx, {
+            filename: url.split("/").pop() ?? context.input.filename,
+            originalName: context.input.filename,
+            mimeType: context.input.mimeType,
+            size: context.input.size,
+            url,
+            ...folder ? { folderId: folder.id } : {},
+            tenantId: tenants.get(context.input)
+          });
+          if (folder && folderClaim)
+            await restoreFolder(tx, folder, folderClaim);
+          return operationAsset(asset);
+        });
+      } catch (error) {
+        if (uploadedUrl) {
+          try {
+            await storageAdapter.delete(uploadedUrl);
+          } catch (cleanupError) {
+            console.error(
+              `[btst/media] Failed to clean up orphaned storage file after operation failure: ${uploadedUrl}`,
+              cleanupError
+            );
+          }
+        }
+        throw error;
+      }
+    },
+    after: ((context) => hooks?.onAfterUpload?.(
+      context.result,
+      hookContext(context, { body: context.input })
+    )),
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onError, error, context, {
+        body: context.input
+      });
+    }
+  });
+  const uploadTokenOperation = defineOperation({
+    input: uploadTokenRequestSchema,
+    permission: mediaPermissions.asset.upload,
+    facts: async ({ input, request }) => {
+      const tenantId = await resolveTenant(input, request, {
+        body: input
+      });
+      const folder = await loadFolder(input.folderId, tenantId);
+      const effectiveTenantId = bindFolderTenant(
+        input,
+        tenantId,
+        folder
+      );
+      folders.set(input, folder);
+      return {
+        phase: "initialize",
+        ...folder ? { folderId: folder.id } : {},
+        mimeType: input.mimeType,
+        ...effectiveTenantId ? { tenantId: effectiveTenantId } : {}
+      };
+    },
+    execute: async (context) => {
+      if (!isS3Adapter(storageAdapter)) {
+        throw new MediaOperationError(
+          400,
+          "Upload token endpoint is only supported with the S3 storage adapter",
+          "UPLOAD_TOKEN_UNSUPPORTED"
+        );
+      }
+      const folder = folders.get(context.input);
+      const issueToken = async () => {
+        await runDomainHook(
+          () => hooks?.onBeforeUpload?.(
+            {
+              filename: context.input.filename,
+              mimeType: context.input.mimeType,
+              size: context.input.size
+            },
+            hookContext(context, { body: context.input })
+          ),
+          "UPLOAD_REJECTED"
+        );
+        validateMimeType(context.input.mimeType, allowedMimeTypes);
+        validateSize(context.input.size, maxFileSizeBytes);
+        return operationUploadToken(
+          await storageAdapter.generateUploadToken({
+            filename: sanitizeS3KeySegment(context.input.filename),
+            mimeType: context.input.mimeType,
+            size: context.input.size,
+            ...folder ? { folderId: folder.id } : {}
+          })
+        );
+      };
+      if (!folder) return issueToken();
+      requireAtomicTransactions(adapter);
+      return adapter.transaction(async (tx) => {
+        await verifyFolder(tx, folder);
+        const claimedAt = await claimFolder(tx, folder);
+        const token = await issueToken();
+        await restoreFolder(tx, folder, claimedAt);
+        return token;
+      });
+    },
+    onError: ({ error, ...context }) => notifyError(hooks?.onError, error, context, {
+      body: context.input
+    })
+  });
+  const uploadVercelBlobOperation = defineOperation({
+    input: VercelBlobOperationInputSchema,
+    permission: mediaPermissions.asset.upload,
+    facts: async ({ input, request }) => {
+      if (!isVercelBlobAdapter(storageAdapter)) {
+        throw new MediaOperationError(
+          400,
+          "Vercel Blob endpoint is only supported with the vercelBlobAdapter",
+          "VERCEL_BLOB_UNSUPPORTED"
+        );
+      }
+      if ("type" in input.body && input.body.type === "blob.upload-completed") {
+        if (!request)
+          throw new TypeError("Vercel Blob callbacks require a request.");
+        let verified;
+        try {
+          verified = await storageAdapter.verifyCallback(
+            request,
+            input.body
+          );
+        } catch {
+          throw new MediaOperationError(
+            401,
+            "Invalid Vercel Blob provider callback.",
+            "INVALID_PROVIDER_CALLBACK"
+          );
+        }
+        const context2 = {
+          phase: "callback",
+          filename: verified.pathname.split("/").pop() ?? verified.pathname,
+          ...verified
+        };
+        vercelContexts.set(input, context2);
+        return {
+          phase: "callback",
+          ...verified.folderId ? { folderId: verified.folderId } : {},
+          mimeType: verified.mimeType,
+          ...verified.tenantId ? { tenantId: verified.tenantId } : {}
+        };
+      }
+      const normalized = parseVercelInitialize(input.body);
+      const tenantId = await resolveTenant(input, request, {
+        body: input.body
+      });
+      const folder = await loadFolder(normalized.folderId, tenantId);
+      const effectiveTenantId = bindFolderTenant(
+        input,
+        tenantId,
+        folder
+      );
+      folders.set(input, folder);
+      const context = {
+        phase: "initialize",
+        ...normalized,
+        ...folder ? { folderId: folder.id } : {},
+        ...effectiveTenantId ? { tenantId: effectiveTenantId } : {}
+      };
+      vercelContexts.set(input, context);
+      return {
+        phase: "initialize",
+        ...folder ? { folderId: folder.id } : {},
+        mimeType: normalized.mimeType,
+        ...effectiveTenantId ? { tenantId: effectiveTenantId } : {}
+      };
+    },
+    execute: async (context) => {
+      if (!isVercelBlobAdapter(storageAdapter) || !context.request) {
+        throw new TypeError(
+          "Vercel Blob execution requires its configured adapter and request."
+        );
+      }
+      const request = context.request;
+      const upload = vercelContexts.get(context.input);
+      if (!upload) throw staleStateError();
+      const handleProviderRequest = async () => {
+        if (upload.phase === "initialize") {
+          await runDomainHook(
+            () => hooks?.onBeforeUpload?.(
+              {
+                filename: upload.filename,
+                mimeType: upload.mimeType,
+                size: upload.size
+              },
+              hookContext(context, { body: context.input.body })
+            ),
+            "UPLOAD_REJECTED"
+          );
+          validateMimeType(upload.mimeType, allowedMimeTypes);
+          if (upload.size !== void 0)
+            validateSize(upload.size, maxFileSizeBytes);
+        }
+        const response = await storageAdapter.handleRequest(
+          request,
+          context.input.body,
+          {
+            onBeforeGenerateToken: async (pathname) => {
+              if (upload.phase !== "initialize" || pathname !== upload.pathname) {
+                throw staleStateError();
+              }
+              return {
+                addRandomSuffix: true,
+                allowedContentTypes: allowedMimeTypes?.length ? allowedMimeTypes : void 0,
+                maximumSizeInBytes: maxFileSizeBytes,
+                tokenPayload: JSON.stringify({
+                  version: 1,
+                  pathname: upload.pathname,
+                  mimeType: upload.mimeType,
+                  ...upload.size !== void 0 ? { size: upload.size } : {},
+                  ...upload.folderId ? { folderId: upload.folderId } : {},
+                  ...upload.tenantId ? { tenantId: upload.tenantId } : {}
+                })
+              };
+            }
+          }
+        );
+        return plainStorageResult(response);
+      };
+      if (upload.phase === "initialize") {
+        const folder = folders.get(context.input);
+        if (folder) {
+          requireAtomicTransactions(adapter);
+          return adapter.transaction(async (tx) => {
+            await verifyFolder(tx, folder);
+            const claimedAt = await claimFolder(tx, folder);
+            const response = await handleProviderRequest();
+            await restoreFolder(tx, folder, claimedAt);
+            return response;
+          });
+        }
+      }
+      return handleProviderRequest();
+    },
+    onError: ({ error, ...context }) => notifyError(hooks?.onError, error, context, {
+      body: context.input.body
+    })
+  });
+  return {
+    listAssets: listAssetsOperation,
+    createAsset: createAssetOperation,
+    updateAsset: updateAssetOperation,
+    deleteAsset: deleteAssetOperation,
+    listFolders: listFoldersOperation,
+    createFolder: createFolderOperation,
+    deleteFolder: deleteFolderOperation,
+    uploadDirect: uploadDirectOperation,
+    uploadToken: uploadTokenOperation,
+    uploadVercelBlob: uploadVercelBlobOperation
+  };
+}
+
+export { AssetIdOperationInputSchema, DirectUploadOperationInputSchema, FolderIdOperationInputSchema, FolderListOperationInputSchema, MediaOperationError, UpdateAssetOperationInputSchema, VercelBlobOperationInputSchema, createMediaOperations };