@jini-ai/cms 0.3.5 → 0.3.7

package/dist/media/html-attributes.js

@@ -0,0 +1,161 @@
+/**
+ * @file Server-side allowlist for `MediaRecord.htmlAttributes` (2026-09-07) — the enforcement half
+ * of a validator that ALSO has a browser-side copy in the consuming product's admin
+ * (`apps/admin/src/features/media/rules.ts`, `parseMediaHtmlAttributes` and friends).
+ *
+ * Deliberately duplicated, not shared via one imported module, for the same reason this codebase
+ * already hand-copies `DEFAULT_ALLOWED_MIME_TYPES` into that admin's `FILE_HANDLER_ALLOWED_MIME_TYPES`/
+ * `IMPORTABLE_CONTENT_TYPES`: `@jini-ai/cms/media`'s barrel (`index.ts`) re-exports files that
+ * import real Node built-ins (`node:crypto` in `media-service.ts`, `node:fs` in
+ * `blob-store.fs.ts`, native `sharp` bindings in `image-transformer.sharp.ts`) — importing this
+ * subpath from a browser-bundled Vite app (that product's `apps/admin`) risks pulling those into the admin
+ * SPA's bundle even if only this one pure function is actually used, and this admin's own copy
+ * already exists, tested, with no such risk. This file is the copy every Node-side consumer
+ * (`media-service.ts`'s own `updateMediaMetadata`, and that product's `apps/website` render path, both pure
+ * backend code) can safely import from `@jini-ai/cms/media` instead of re-deriving the rules a
+ * third time.
+ *
+ * THE RULES THEMSELVES ARE NOT REDESIGNED HERE — this is a verbatim port of the admin copy's logic
+ * (allowlist membership, `on*`/`javascript:` precedence, the tokenizer, the four rejection reasons).
+ * Extend `MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES` in BOTH copies together if a new attribute is ever
+ * needed — that is the one piece of drift risk this duplication accepts, the same risk every other
+ * hand-copied list in this codebase already accepts.
+ *
+ * This is a SECURITY boundary, not a syntax convenience: media metadata is authored in the consuming product's admin
+ * but rendered on the public site, so a free-text HTML-attribute passthrough is a stored-XSS vector
+ * (`onerror`, `onclick`, `style`, `href="javascript:"`, any `on*` handler) the moment it reaches a
+ * public page. A client-side-only check is not a control, since the API accepts whatever a caller
+ * sends — this file is what makes the write path (`updateMediaMetadata`) and the render path (a
+ * host's own tag-building code) actually enforce it, not just the admin form.
+ */
+/**
+ * Exact-match attribute names the allowlist accepts beyond the open-ended `data-`/`aria-` prefix
+ * families (checked separately in {@link isAllowedMediaHtmlAttributeName}). Picked for the owner's
+ * stated near-term uses (animations, custom WebMCP hooks) plus the standard `<img>`/`<video>`
+ * attributes those uses actually need; extend this list, not the parser, when a new one is needed —
+ * and keep it in sync with the identical constant in that admin's copy (see this file's header).
+ */
+export const MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES = [
+    "loading",
+    "decoding",
+    "playsinline",
+    "muted",
+    "loop",
+    "autoplay",
+    "poster",
+];
+/**
+ * The shape EVERY accepted attribute name must have, checked before allowlist membership
+ * (2026-09-07 stored-XSS fix; keep identical in the admin copy).
+ *
+ * The `data-`/`aria-` families below are open-ended by design — no fixed suffix list — so the
+ * prefix check alone accepted whatever characters {@link HTML_ATTRIBUTE_TOKEN}'s name class
+ * (`[^\s="']+`, which excludes only whitespace, `=` and quotes) let through. `<`, `>` and `/` are
+ * all legal in that class, and a renderer templating a name into ` name="value"` escapes only the
+ * VALUE — so a stored `data-x><svg/onload=alert(1)` closed the `<img>` and opened a live
+ * `<svg onload>` on the public page. Constraining the NAME to the characters a real HTML attribute
+ * name can contain is what makes "the value is escaped" sufficient: no accepted name can carry a
+ * character that terminates a tag or starts an attribute.
+ *
+ * Deliberately narrower than the HTML spec's own name production (which permits far more): this
+ * field exists for `data-*`/`aria-*` hooks and a short list of standard `<img>`/`<video>`
+ * attributes, every one of which fits `[a-z][a-z0-9-]*`. Widening this is a deliberate decision,
+ * not something a new allowlist entry should need.
+ */
+const MEDIA_HTML_ATTRIBUTE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Whether `name` is on the allowlist — a well-formed attribute name
+ *  ({@link MEDIA_HTML_ATTRIBUTE_NAME_PATTERN}) that is either an exact match against
+ *  {@link MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES} or carries a `data-`/`aria-` prefix (both open-ended
+ *  families with no fixed suffix list). Case-insensitive: HTML attribute names are themselves
+ *  case-insensitive, and an operator typing `DATA-FOO` should not slip past a lowercase-only check.
+ *
+ * @complexity O(n) in the name's length (one anchored regex test), then O(1) — one prefix check,
+ * one fixed-length array lookup.
+ */
+export function isAllowedMediaHtmlAttributeName(name) {
+    const lower = name.toLowerCase();
+    if (!MEDIA_HTML_ATTRIBUTE_NAME_PATTERN.test(lower))
+        return false;
+    if (lower.startsWith("data-") || lower.startsWith("aria-"))
+        return true;
+    return MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES.includes(lower);
+}
+/** Matches one `name`, or one `name="value"`/`name='value'`/`name=value` pair — the same loose
+ *  shape real HTML attribute syntax allows, since that is the syntax an operator typing this field
+ *  would naturally reach for. */
+const HTML_ATTRIBUTE_TOKEN = /([^\s="']+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s"']+)))?/g;
+/** Classifies one already-tokenized `name`/`value` pair. Split out of {@link parseMediaHtmlAttributes}
+ *  so each rejection reason is its own directly testable branch.
+ *
+ * Order matters: `on*`/`javascript:` are checked BEFORE allowlist membership, so a rejected
+ * `onerror="..."` always reports as `event-handler` (the more specific, more actionable reason)
+ * rather than the generic `disallowed-name`.
+ *
+ * @complexity O(1) — three fixed checks against one already-extracted token.
+ */
+function classifyMediaHtmlAttributeToken(name, value) {
+    if (name.startsWith("on"))
+        return { reason: "event-handler", attribute: name };
+    if (value.trim().toLowerCase().startsWith("javascript:"))
+        return { reason: "javascript-url", attribute: name };
+    if (!isAllowedMediaHtmlAttributeName(name))
+        return { reason: "disallowed-name", attribute: name };
+    return null;
+}
+/**
+ * Parses the `htmlAttributes` field's free text (`name="value" name2="value2"`, or a bare boolean
+ * `name`) into a validated attribute map, rejecting anything not on the allowlist. Nothing here
+ * tries to sanitize or escape an otherwise-disallowed name into something safe — it is rejected
+ * outright, and the caller must show the reason (not silently drop it) so an operator can tell a
+ * typo from a hard "no".
+ *
+ * @complexity Time O(n) in `text`'s length (one regex pass over it), space O(k) for k parsed
+ *   attributes.
+ */
+export function parseMediaHtmlAttributes(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return { attributes: {}, error: null };
+    const attributes = {};
+    HTML_ATTRIBUTE_TOKEN.lastIndex = 0;
+    let consumed = 0;
+    let match;
+    while ((match = HTML_ATTRIBUTE_TOKEN.exec(trimmed)) !== null) {
+        // Non-whitespace text between the previous match and this one is a fragment the token pattern
+        // could not parse as a name (e.g. a stray quote) — reported once, at the first gap, rather
+        // than silently skipped.
+        const skipped = trimmed.slice(consumed, match.index);
+        if (skipped.trim() !== "")
+            return { attributes: {}, error: { reason: "malformed", attribute: skipped.trim() } };
+        consumed = match.index + match[0].length;
+        const name = match[1].toLowerCase();
+        const value = match[2] ?? match[3] ?? match[4] ?? "";
+        const rejection = classifyMediaHtmlAttributeToken(name, value);
+        if (rejection)
+            return { attributes: {}, error: rejection };
+        attributes[name] = value;
+    }
+    const trailing = trimmed.slice(consumed);
+    if (trailing.trim() !== "")
+        return { attributes: {}, error: { reason: "malformed", attribute: trailing.trim() } };
+    return { attributes, error: null };
+}
+/** Formats a {@link MediaHtmlAttributeError} into a plain-English message naming the rejected
+ *  attribute (owner requirement) — the server-side, non-localized counterpart to the admin's own
+ *  `describeMediaHtmlAttributeError` (which additionally runs the message through `MEDIA_DICT` for
+ *  the operator's locale). Domain errors elsewhere in this file (`MediaValidationError`'s other
+ *  messages) are likewise always plain English, so this matches that existing convention rather
+ *  than inventing a localized-error contract this service has never had.
+ *
+ * @complexity O(1).
+ */
+export function describeMediaHtmlAttributeError(error) {
+    if (error.reason === "event-handler")
+        return `event handler attributes like '${error.attribute}' are not allowed`;
+    if (error.reason === "javascript-url")
+        return `'${error.attribute}' cannot use a javascript: value`;
+    if (error.reason === "malformed")
+        return `could not parse HTML attributes near '${error.attribute}'`;
+    return `'${error.attribute}' is not an allowed HTML attribute`;
+}
+//# sourceMappingURL=html-attributes.js.map

package/dist/media/image-transformer.sharp.d.ts

@@ -24,8 +24,42 @@ export declare class ImageSourceCorruptError extends Error {
  * `params.format` (via `sharp().toFormat(...)`, always — re-encode is
  * unconditional).
  *
+ * Animated sources (multi-frame GIF/WebP/APNG): loaded with `{ animated: true }` whenever the
+ * target format can carry animation (`ANIMATION_CAPABLE_FORMATS`), so `.resize()` and `.toFormat()`
+ * operate on every frame instead of silently decoding only frame 0. This is safe to request
+ * unconditionally for a genuinely single-frame source too — verified empirically against this
+ * package's pinned `sharp@0.35.3`: a static image loaded with `{ animated: true }` produces
+ * byte-identical dimensions/output to loading it without the option (sharp resolves `nPages` to 1
+ * from the format's own page count, there is no multi-page metadata to read all of).
+ *
+ * When the target format CANNOT carry animation (jpeg/png), `{ animated: true }` is deliberately
+ * NOT passed — verified empirically that doing so anyway is worse than a plain flatten: sharp
+ * writes the whole multi-frame "toilet roll" (all frames stacked vertically) out as one tall,
+ * visibly-corrupted static image rather than either a clean single frame or a real animated
+ * output. Loading without the option keeps sharp's default single-page decode, which already
+ * yields a normal frame-0 still — a deliberate, now-documented flatten instead of an accident.
+ *
+ * Multi-frame resize correctness: `sharp`'s native pipeline is already page-height-aware — the
+ * `width`/`height` passed to `.resize()` are resolved against the PER-FRAME `pageHeight`, not the
+ * full multi-frame canvas, and the crop/scale math is applied identically per frame (verified with
+ * a 4-frame fixture and an aggressive mismatched-aspect crop — each frame's content stayed inside
+ * its own frame boundary). No special-cased width-only or manual `pageHeight` recomputation is
+ * needed here; adding one would be redundant with (and could conflict with) sharp's own handling.
+ *
+ * Resource bounds: sharp's default `limitInputPixels` (~268M px, unconditional, not raised by
+ * `{ animated: true }`) is checked against the FULL decoded canvas — for a multi-page load that
+ * means `width * (pageHeight * pages)`, i.e. total pixels across all frames combined, not per
+ * frame. Turning on `{ animated: true }` therefore does not remove or widen that ceiling. It does
+ * mean legitimate large animated files now do proportionally more decode/re-encode work than the
+ * previous (buggy) frame-0-only path — expected, since fully processing an animated file is the
+ * point of this fix — bounded on the input side by `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB compressed)
+ * before any of these bytes ever reach this transformer.
+ *
  * @complexity O(pixels) — dominated by `sharp`'s native resize/encode work,
- * outside this function's control. Runs IN-PROCESS in this build (the
+ * outside this function's control. For an animated source this now scales with total pixels across
+ * ALL frames combined (previously just frame 0) — see "Resource bounds" above for why this widened
+ * cost is bounded by the same pre-existing `limitInputPixels`/upload-size caps rather than being an
+ * unbounded new surface. Runs IN-PROCESS in this build (the
  * out-of-process worker the original design calls for to protect the host from
  * `sharp` OOMing is explicitly out of scope for this task — see
  * `rendition-service.ts`'s file header).

package/dist/media/image-transformer.sharp.js

@@ -49,6 +49,13 @@ export class ImageTransformUnavailableError extends Error {
  */
 export class ImageSourceCorruptError extends Error {
 }
+/**
+ * {@link TransformFormat} values that can actually carry multiple frames on output. GIF and WebP
+ * both support animated re-encoding; JPEG and PNG do not (this build's plain libvips PNG writer
+ * does not emit APNG). Gates the `{ animated: true }` load option below — see that call site's
+ * comment for why loading animated but encoding to a non-animated format must NOT happen.
+ */
+const ANIMATION_CAPABLE_FORMATS = new Set(["webp", "gif"]);
 /**
  * Lazily resolves the `sharp` module. See file header for why this is a
  * deferred, untyped `require()` (via `createRequire`) rather than a
@@ -75,8 +82,42 @@ function loadSharpFactory() {
  * `params.format` (via `sharp().toFormat(...)`, always — re-encode is
  * unconditional).
  *
+ * Animated sources (multi-frame GIF/WebP/APNG): loaded with `{ animated: true }` whenever the
+ * target format can carry animation (`ANIMATION_CAPABLE_FORMATS`), so `.resize()` and `.toFormat()`
+ * operate on every frame instead of silently decoding only frame 0. This is safe to request
+ * unconditionally for a genuinely single-frame source too — verified empirically against this
+ * package's pinned `sharp@0.35.3`: a static image loaded with `{ animated: true }` produces
+ * byte-identical dimensions/output to loading it without the option (sharp resolves `nPages` to 1
+ * from the format's own page count, there is no multi-page metadata to read all of).
+ *
+ * When the target format CANNOT carry animation (jpeg/png), `{ animated: true }` is deliberately
+ * NOT passed — verified empirically that doing so anyway is worse than a plain flatten: sharp
+ * writes the whole multi-frame "toilet roll" (all frames stacked vertically) out as one tall,
+ * visibly-corrupted static image rather than either a clean single frame or a real animated
+ * output. Loading without the option keeps sharp's default single-page decode, which already
+ * yields a normal frame-0 still — a deliberate, now-documented flatten instead of an accident.
+ *
+ * Multi-frame resize correctness: `sharp`'s native pipeline is already page-height-aware — the
+ * `width`/`height` passed to `.resize()` are resolved against the PER-FRAME `pageHeight`, not the
+ * full multi-frame canvas, and the crop/scale math is applied identically per frame (verified with
+ * a 4-frame fixture and an aggressive mismatched-aspect crop — each frame's content stayed inside
+ * its own frame boundary). No special-cased width-only or manual `pageHeight` recomputation is
+ * needed here; adding one would be redundant with (and could conflict with) sharp's own handling.
+ *
+ * Resource bounds: sharp's default `limitInputPixels` (~268M px, unconditional, not raised by
+ * `{ animated: true }`) is checked against the FULL decoded canvas — for a multi-page load that
+ * means `width * (pageHeight * pages)`, i.e. total pixels across all frames combined, not per
+ * frame. Turning on `{ animated: true }` therefore does not remove or widen that ceiling. It does
+ * mean legitimate large animated files now do proportionally more decode/re-encode work than the
+ * previous (buggy) frame-0-only path — expected, since fully processing an animated file is the
+ * point of this fix — bounded on the input side by `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB compressed)
+ * before any of these bytes ever reach this transformer.
+ *
  * @complexity O(pixels) — dominated by `sharp`'s native resize/encode work,
- * outside this function's control. Runs IN-PROCESS in this build (the
+ * outside this function's control. For an animated source this now scales with total pixels across
+ * ALL frames combined (previously just frame 0) — see "Resource bounds" above for why this widened
+ * cost is bounded by the same pre-existing `limitInputPixels`/upload-size caps rather than being an
+ * unbounded new surface. Runs IN-PROCESS in this build (the
  * out-of-process worker the original design calls for to protect the host from
  * `sharp` OOMing is explicitly out of scope for this task — see
  * `rendition-service.ts`'s file header).
@@ -90,6 +131,7 @@ function loadSharpFactory() {
 export class SharpImageTransformer {
     async transform(input) {
         const sharpFactory = loadSharpFactory();
+        const preserveAnimation = ANIMATION_CAPABLE_FORMATS.has(input.params.format);
         // Pipeline construction through `toBuffer()` all live in one try/catch: any of these steps can
         // reject on bad SOURCE bytes (`sharp`'s decode is lazy — a malformed file often only surfaces
         // once a downstream operation like `toBuffer()` actually reads it), and every such rejection
@@ -97,7 +139,7 @@ export class SharpImageTransformer {
         // call in the chain actually threw. See {@link ImageSourceCorruptError}'s own doc for why this is
         // named/rethrown rather than left as an undifferentiated `sharp` error.
         try {
-            let pipeline = sharpFactory(Buffer.from(input.bytes));
+            let pipeline = sharpFactory(Buffer.from(input.bytes), preserveAnimation ? { animated: true } : undefined);
             if (input.params.width !== undefined || input.params.height !== undefined) {
                 pipeline = pipeline.resize(input.params.width, input.params.height, {
                     fit: input.params.fit ?? "cover",

package/dist/media/index.d.ts

@@ -15,12 +15,13 @@ export type { MediaStatus, MediaSource, MediaRecord, AssetBlobStatus, AssetBlobR
 export { MediaNotFoundError, MediaValidationError, MediaConflictError, MediaSourceImmutableError, MediaStillReferencedError, } from "./types.js";
 export type { MediaRepoPort, AssetBlobRepoPort, AssetRenditionRepoPort, BlobStorePort, BlobGcJournalRepoPort, PutBlobInput, TransformDefinitionRepoPort, } from "./ports.js";
 export { computeBlobStorageKey } from "./blob-key.js";
+export { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES, isAllowedMediaHtmlAttributeName, parseMediaHtmlAttributes, describeMediaHtmlAttributeError, type MediaHtmlAttributeRejectionReason, type MediaHtmlAttributeError, type ParsedMediaHtmlAttributes, } from "./html-attributes.js";
 export { InMemoryMediaRepo, InMemoryAssetBlobRepo, InMemoryAssetRenditionRepo, InMemoryBlobGcJournalRepo, InMemoryTransformDefinitionRepo, } from "./repo.memory.js";
 export { withSha256Lock } from "./blob-gc-lock.js";
 export { DEFAULT_GC_GRACE_MS, resolveGcGraceMs, isBlobUnreferenced, tombstoneBlobIfUnreferenced, runBlobGcDeletePass, runBlobGcUnlinkPass, runBlobGcCycle, runMonthlyOrphanSweepStub, } from "./blob-gc.js";
 export { InMemoryBlobStore } from "./blob-store.memory.js";
 export { LocalFsBlobStore, type LocalFsBlobStoreDeps } from "./blob-store.fs.js";
-export { DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_ALLOWED_MIME_TYPES, resolveWriteOnceSource, uploadMedia, listMedia, getMediaById, updateMediaMetadata, trashMedia, purgeMedia, type UploadMediaInput, type UploadMediaDeps, type UpdateMediaMetadataInput, } from "./media-service.js";
+export { DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_ALLOWED_MIME_TYPES, resolveWriteOnceSource, uploadMedia, listMedia, getMediaById, findMediaByIdOrSlug, updateMediaMetadata, trashMedia, purgeMedia, isValidMediaSlugFormat, type UploadMediaInput, type UploadMediaDeps, type UpdateMediaMetadataInput, type FindMediaByIdOrSlugRequired, } from "./media-service.js";
 export type { TransformFit, TransformFormat, TransformParams, TransformDefinitionRecord, } from "./transform-types.js";
 export { TransformValidationError, mimeForTransformFormat, MAX_TRANSFORM_DIMENSION_PX } from "./transform-types.js";
 export { withRenditionLock, withTransformRegistryLock } from "./transform-lock.js";

package/dist/media/index.js

@@ -1,11 +1,12 @@
 export { MediaNotFoundError, MediaValidationError, MediaConflictError, MediaSourceImmutableError, MediaStillReferencedError, } from "./types.js";
 export { computeBlobStorageKey } from "./blob-key.js";
+export { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES, isAllowedMediaHtmlAttributeName, parseMediaHtmlAttributes, describeMediaHtmlAttributeError, } from "./html-attributes.js";
 export { InMemoryMediaRepo, InMemoryAssetBlobRepo, InMemoryAssetRenditionRepo, InMemoryBlobGcJournalRepo, InMemoryTransformDefinitionRepo, } from "./repo.memory.js";
 export { withSha256Lock } from "./blob-gc-lock.js";
 export { DEFAULT_GC_GRACE_MS, resolveGcGraceMs, isBlobUnreferenced, tombstoneBlobIfUnreferenced, runBlobGcDeletePass, runBlobGcUnlinkPass, runBlobGcCycle, runMonthlyOrphanSweepStub, } from "./blob-gc.js";
 export { InMemoryBlobStore } from "./blob-store.memory.js";
 export { LocalFsBlobStore } from "./blob-store.fs.js";
-export { DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_ALLOWED_MIME_TYPES, resolveWriteOnceSource, uploadMedia, listMedia, getMediaById, updateMediaMetadata, trashMedia, purgeMedia, } from "./media-service.js";
+export { DEFAULT_MAX_UPLOAD_BYTES, DEFAULT_ALLOWED_MIME_TYPES, resolveWriteOnceSource, uploadMedia, listMedia, getMediaById, findMediaByIdOrSlug, updateMediaMetadata, trashMedia, purgeMedia, isValidMediaSlugFormat, } from "./media-service.js";
 export { TransformValidationError, mimeForTransformFormat, MAX_TRANSFORM_DIMENSION_PX } from "./transform-types.js";
 export { withRenditionLock, withTransformRegistryLock } from "./transform-lock.js";
 export { registerTransform, getLatestTransformDefinition, isLatestTransformVersion, isReferencedByPublishedContent, } from "./transform-registry.js";

package/dist/media/media-service.d.ts

@@ -10,12 +10,20 @@ export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
  * that sanitizer is not built in this pass, so SVG upload is rejected rather
  * than accepted unsanitized.
  *
+ * `image/avif` (owner-directed, 2026-09-06): a fifth still-image type, on the
+ * same footing as the four above — `content-type-sniffer.ts` identifies it by
+ * ISO-BMFF brand and the installed `sharp`/libvips build decodes it, so it
+ * flows through the ordinary transform/rendition pipeline and is re-encoded
+ * like any other image. Adding it required a matching sniffer fix, not just
+ * this line: AVIF shares MP4's `ftyp` container tag, so before that fix an
+ * AVIF was sniffed as `video/mp4` and served as an unplayable video.
+ *
  * `video/mp4`/`video/webm` (owner-directed, 2026-08-24): the two formats
  * `content-type-sniffer.ts` already recognizes by magic bytes. Unlike the four
  * image types above, an accepted video is never re-encoded — there is no
  * `TransformFormat` for video (`transform-types.ts`'s union is image-only), so
  * a video asset's public URL bypasses the transform/rendition pipeline
- * entirely and serves the original bytes as-is (host concern; see Tovu's
+ * entirely and serves the original bytes as-is (host concern; see the host's
  * `routes/site/media-rendition.ts`). This widens the SAME advisory,
  * client-declared-string check item 4 above already discloses as untrusted —
  * no new ingress hardening was added for video.
@@ -41,6 +49,7 @@ export declare function resolveWriteOnceSource(required: {
     existing: MediaSource | undefined;
     requestedSha256: string;
 }, _optional?: Record<string, never>): MediaSource;
+export declare function isValidMediaSlugFormat(slug: string): boolean;
 export interface UploadMediaInput {
     workspaceId: UUID;
     bytes: Uint8Array;
@@ -86,7 +95,8 @@ export interface UploadMediaOptional {
  *
  * @complexity O(1) — one hash, one blob lookup, at most one blob write, one
  * media write, one rendition write (the lock itself adds O(1) scheduling
- * overhead, not a scan).
+ * overhead, not a scan) — plus {@link deriveUniqueMediaSlug}'s own O(n) in the number of prior
+ * same-base-slug collisions (see that function's doc).
  * @overallScore 100
  */
 export declare function uploadMedia(required: UploadMediaRequired, optional?: UploadMediaOptional): Promise<{
@@ -131,6 +141,39 @@ export interface GetMediaByIdRequired {
 export declare function getMediaById(required: GetMediaByIdRequired, _optional?: Record<string, never>): Promise<{
     media: MediaRecord;
 }>;
+export interface FindMediaByIdOrSlugRequired {
+    deps: {
+        mediaRepo: MediaRepoPort;
+    };
+    input: {
+        workspaceId: UUID;
+        idOrSlug: string;
+    };
+}
+/**
+ * Resolves a media asset by either its id or its slug — ID FIRST, slug second. The slug is the
+ * handle a human typed into an embed marker or a hand-authored `<img>`/`<video>` tag; the id is the
+ * opaque UUID every existing reference already uses, and every URL a host's renderer emits.
+ *
+ * THE ORDER IS A SECURITY PROPERTY, not a preference (2026-09-07). This resolved slug-first, on the
+ * documented assumption that "an id never collides with a slug in practice since slugs pass through
+ * {@link isValidMediaSlugFormat}". That assumption was false: a lowercase UUID matched the old slug
+ * pattern `[a-z0-9-]+` exactly, so setting asset B's slug to asset A's id made every `/m/{A.id}/…`
+ * URL — the ones a renderer emitted for A, already live in published pages — resolve to B instead.
+ * An id is minted by the system and is never a value a human chooses, so it must always win; the
+ * write path additionally refuses UUID-shaped slugs now (see
+ * {@link MEDIA_SLUG_UUID_SHAPE_PATTERN}), but ordering is what protects rows written before that
+ * rule existed. Id-first costs nothing on the slug path: a real slug simply misses the id lookup and
+ * falls through.
+ *
+ * Never throws (unlike {@link getMediaById}): every call site that needs this (an embed resolver, a
+ * public rendition route) already has its own REQ-27-style non-throwing-miss contract, so this
+ * returns `null` on failure and lets the caller apply its own not-found handling rather than forcing
+ * one shape on every caller.
+ *
+ * @complexity O(1) — at most two indexed repo lookups, short-circuited on the first hit.
+ */
+export declare function findMediaByIdOrSlug(required: FindMediaByIdOrSlugRequired, _optional?: Record<string, never>): Promise<MediaRecord | null>;
 export interface UpdateMediaMetadataInput {
     workspaceId: UUID;
     id: UUID;
@@ -152,6 +195,23 @@ export interface UpdateMediaMetadataInput {
      *  a string that trims to empty is stored as `null` (equivalent to clearing it), matching the
      *  "empty means unset" convention `title`/`alt`/etc. already follow via `.trim()`. */
     cssClass?: string | null | undefined;
+    /**
+     * Explicit slug edit (2026-09-07). `undefined` (key omitted) leaves the stored slug unchanged —
+     * in particular, changing `title` on the SAME call never touches `slug`; they are independent
+     * fields by design (see `MediaRecord.slug`'s doc). Unlike `title`/`cssClass`, `slug` has no
+     * "empty means unset" fallback: a media asset's slug is never null once assigned, so a caller
+     * cannot clear it back to absent, only replace it with a different valid slug.
+     */
+    slug?: string | undefined;
+    /**
+     * Same undefined/null/value contract as `cssClass` above (2026-09-07). A provided non-empty string
+     * is validated against `html-attributes.ts`'s allowlist BEFORE it is trimmed and stored — an `on*`
+     * handler, a `javascript:` value, or any disallowed name throws `MediaValidationError` naming the
+     * exact rejected attribute, and NOTHING is written (this field included) when that happens. A
+     * string that validates but trims to empty is stored as `null`, matching `cssClass`'s identical
+     * "empty means unset" convention.
+     */
+    htmlAttributes?: string | null | undefined;
 }
 export interface UpdateMediaMetadataDeps {
     clock: ClockPort;