@12-apps/storage 1.0.0

package/src/server/remote-url.ts

@@ -0,0 +1,57 @@
+import { StorageNotConfiguredError } from '../problems';
+
+/**
+ * The public URL of an object in an S3-compatible bucket.
+ *
+ * Pure, and in `./server` rather than in `./s3`, for two reasons: a host that
+ * serves display URLs from a CDN needs the same builder without the SDK, and
+ * every branch below is a real deployment that got this wrong once.
+ */
+export interface RemoteObjectUrlConfig {
+  bucket: string;
+  /** AWS region — the only thing needed for an AWS-hosted bucket. */
+  region?: string;
+  /** Endpoint of a non-AWS S3-compatible store (Spaces, MinIO, R2…). */
+  endpoint?: string;
+  /** Path-style addressing, for stores that cannot do virtual-hosted. */
+  forcePathStyle?: boolean;
+  /** A CDN in front of the bucket. Wins over everything else. */
+  publicBaseUrl?: string;
+}
+
+/**
+ * Config that cannot produce a URL at all.
+ *
+ * Raised at MOUNT time rather than at render time: a driver that returned the
+ * bare key here would put a relative path in an `<img src>`, which resolves
+ * against the app's own origin and 404s — a broken image with no error anywhere,
+ * for every product in the catalog.
+ */
+export function assertRemoteUrlConfig(config: RemoteObjectUrlConfig): void {
+  if (!config.bucket) {
+    throw new StorageNotConfiguredError('An S3-compatible driver needs a bucket.');
+  }
+  if (!config.region && !config.endpoint && !config.publicBaseUrl) {
+    throw new StorageNotConfiguredError(
+      'An S3-compatible driver needs a region, an endpoint or a publicBaseUrl to build display URLs.',
+    );
+  }
+}
+
+export function remoteObjectUrl(config: RemoteObjectUrlConfig, key: string): string {
+  if (config.publicBaseUrl) {
+    return `${config.publicBaseUrl.replace(/\/$/, '')}/${key}`;
+  }
+  if (config.endpoint) {
+    const base = config.endpoint.replace(/\/$/, '');
+    if (config.forcePathStyle) {
+      // Path-style, matching how such a store addresses objects. The endpoint's
+      // own scheme is kept: a local http://localhost:9000 must not be rewritten
+      // to https.
+      return `${base}/${config.bucket}/${key}`;
+    }
+    // Virtual-hosted style on the S3-compatible endpoint (Spaces and friends).
+    return `https://${config.bucket}.${base.replace(/^https?:\/\//i, '')}/${key}`;
+  }
+  return `https://${config.bucket}.s3.${config.region}.amazonaws.com/${key}`;
+}

package/src/server/routes.ts

@@ -0,0 +1,189 @@
+import { CONTENT_TYPE_BY_EXTENSION, acceptedContentTypeOf } from '../content-types';
+import { parseObjectMemberKey } from '../keys';
+import { STORAGE_PATHS } from '../paths';
+import { isStorageProblem, type StorageMessages } from '../problems';
+import type { StorageDriver } from './driver';
+import { readBodyCapped } from './read-body';
+import { storeImage, type StoreImageDeps } from './store-image';
+
+/**
+ * The endpoints, as framework-neutral descriptors. There are exactly two, and
+ * neither hands a caller an address to upload to.
+ *
+ *   POST <mount>/uploads/image      the ONE way a browser stores bytes
+ *   GET  <mount>/uploads/local/…    how an object is read back
+ *
+ * ## Why one POST, and why never a presigned URL
+ *
+ * An earlier contract had the browser ask for an ADDRESS and then PUT to it. Two
+ * requests — and the key had to be minted at the first, before anybody had seen
+ * the bytes, which means PREDICTING whether crops will exist. The prediction
+ * needed flags and special cases to stay true and a 422 for when it did not.
+ *
+ * The obvious form of that second hop is a presigned bucket URL, and it is the
+ * one thing this package must never offer. A `PUT` with a `Content-Type` is never
+ * a "simple" request, so the browser sends an `OPTIONS` preflight; a freshly
+ * created bucket answers it with 403 and no `Access-Control-Allow-*`, and the
+ * upload is never sent. THE SERVER SEES NOTHING — no request, no log line, no
+ * error rate. The browser cannot say why, because a blocked cross-origin fetch is
+ * deliberately indistinguishable from an offline network. And the person who sees
+ * the message is a store owner, about a bucket only an operator can configure.
+ *
+ * One same-origin POST removes the second hop, the prediction and the CORS class
+ * together. It is also the only shape that CAN work now: a stored photo is a set
+ * of objects the server derives from the bytes, so an upload the server never
+ * sees cannot produce one.
+ */
+
+/**
+ * Who is calling — resolved by the HOST and never computed here.
+ *
+ * `mayUpload` is one boolean on purpose. Two independent questions feed it —
+ * "may this person store objects?" (roles, memberships, plan) and "may this
+ * SESSION change anything?" (a read-only impersonation, a maintenance mode) — and
+ * both are the host's, answered before it delegates. A package that tried to
+ * compute either would be wrong for every host but the first.
+ */
+export interface StorageActor {
+  /** The tenant whose objects this call may touch — the key's scope segment. */
+  scope: string;
+  mayUpload: boolean;
+}
+
+export interface StorageRouteContext {
+  actor: StorageActor | null;
+  params: Record<string, string | undefined>;
+  request: Request;
+}
+
+/** A JSON answer, an object's bytes, or a redirect to where the object lives. */
+export type StorageRouteResponse =
+  | { status: number; body: unknown }
+  | { status: number; bytes: Uint8Array; headers: Record<string, string> }
+  | { status: number; redirect: string };
+
+export interface StorageRoute {
+  method: 'GET' | 'POST';
+  /** Path suffix, relative to the mount. */
+  path: string;
+  /** `actor` routes answer 401 before the handler runs; `public` ones do not. */
+  auth: 'actor' | 'public';
+  /**
+   * The path ends in a catch-all whose whole remainder is the `key` param. An
+   * adapter spells that its own way; the descriptor says only that it is there.
+   */
+  wildcardParam?: 'key';
+  handle(context: StorageRouteContext): Promise<StorageRouteResponse>;
+}
+
+interface RoutesDeps extends StoreImageDeps {
+  driver: StorageDriver;
+  messages: StorageMessages;
+}
+
+/** Keys are content-addressed (a uuid), so an object may be cached forever. */
+const IMMUTABLE = 'public, max-age=31536000, immutable';
+
+async function handleUpload(
+  deps: RoutesDeps,
+  context: StorageRouteContext,
+): Promise<StorageRouteResponse> {
+  const actor = context.actor;
+  if (!actor?.mayUpload) {
+    // Stays a CODE, unlike the refusals below, and deliberately: `mayUpload` is the
+    // host's own boolean, so the package cannot phrase WHY without asserting a role
+    // model it does not have. The browser half owns that sentence and lets the host
+    // override it (`WebStorageMessages.forbidden`).
+    return { status: 403, body: { error: 'forbidden' } };
+  }
+  const contentType = acceptedContentTypeOf(context.request.headers.get('content-type'));
+  if (!contentType) {
+    return { status: 400, body: { error: deps.messages.unsupported_content_type } };
+  }
+  // Capped WHILE STREAMING, so an oversize body is refused without ever being
+  // held whole in memory.
+  const bytes = await readBodyCapped(context.request, deps.maxBytes);
+  if (bytes === null) {
+    // The configured SENTENCE, not the code `file_too_large`. These two refusals
+    // are decided before the write path runs, so they used to be the only ones the
+    // endpoint stated as a bare code — and the browser then re-derived the number
+    // from its OWN default. A mount capped at 4 MB refusing a 6 MB file produced
+    // "o limite é 8 MB": a ceiling nothing enforced, in the one package whose
+    // headline claim is that there is exactly ONE number. The sentence is built
+    // from this mount's `maxBytes` and carries this mount's `messages` overrides.
+    return { status: 413, body: { error: deps.messages.file_too_large } };
+  }
+  try {
+    // No byte check here: `storeImage` owns it, so the endpoint and a host write
+    // holding raw bytes cannot disagree about whether it ran (see store-image.ts).
+    const imageKey = await storeImage(deps, { bytes, contentType, scope: actor.scope });
+    return { status: 200, body: { data: { imageKey } } };
+  } catch (error) {
+    // The write path speaks in StorageProblemError precisely so both entrances
+    // answer with the same status and the same sentence.
+    if (isStorageProblem(error)) {
+      return { status: error.status, body: { error: error.message } };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Serve a stored object, or send the caller where it actually lives.
+ *
+ * Which of the two applies is read off the DRIVER — a driver that holds its own
+ * bytes implements `read`, a bucket-backed one does not. That used to be an
+ * environment flag consulted inside the route, i.e. the same fact recorded in a
+ * second place where it could disagree with the driver in use.
+ *
+ * The redirect is not a nicety: a consumer may still be asking for this route
+ * after a switch to a bucket — a cached page, a storefront bundle mid-deploy that
+ * fell back to the bare key — and a 404 there is a catalog full of broken images.
+ */
+async function handleServe(
+  deps: RoutesDeps,
+  context: StorageRouteContext,
+): Promise<StorageRouteResponse> {
+  const key = context.params.key ?? '';
+  const member = parseObjectMemberKey(key, deps.keyPrefix);
+  if (!member || !(member.extension in CONTENT_TYPE_BY_EXTENSION)) {
+    return { status: 400, body: { error: 'invalid_key' } };
+  }
+  if (!deps.driver.read) {
+    const url = deps.driver.publicUrl(key);
+    // `publicUrl` may answer a relative path on a misconfigured driver, and a
+    // redirect to one loops back here forever. 404 instead — the same answer the
+    // object being absent gives.
+    return /^https?:\/\//i.test(url)
+      ? { status: 302, redirect: url }
+      : { status: 404, body: { error: 'not_found' } };
+  }
+  const object = await deps.driver.read(key);
+  if (!object) return { status: 404, body: { error: 'not_found' } };
+  return {
+    status: 200,
+    bytes: object.bytes,
+    headers: { 'content-type': object.contentType, 'cache-control': IMMUTABLE },
+  };
+}
+
+export function storageRoutes(deps: RoutesDeps): readonly StorageRoute[] {
+  return [
+    {
+      method: 'POST',
+      path: STORAGE_PATHS.upload,
+      auth: 'actor',
+      handle: (context) => handleUpload(deps, context),
+    },
+    {
+      method: 'GET',
+      path: STORAGE_PATHS.serve,
+      // Objects are world-readable by design — a store's logo is printed in its
+      // own storefront HTML — and the key is an unguessable uuid path. Gating the
+      // read would mean every `<img>` in a public storefront carried a session.
+      auth: 'public',
+      wildcardParam: 'key',
+      handle: (context) => handleServe(deps, context),
+    },
+  ];
+}

package/src/server/store-image.ts

@@ -0,0 +1,168 @@
+import { mintObjectKey, mintObjectSetKey, renditionKey } from '../keys';
+import { decodeImagePayload, verifyImageBytes } from '../payload';
+import {
+  StorageNotConfiguredError,
+  StorageProblemError,
+  type StorageMessages,
+} from '../problems';
+import { RENDITION_CONTENT_TYPE, type RenditionSpec } from '../renditions';
+import type { InlineImage } from '../wire';
+import type { StorageDriver } from './driver';
+import type { ImagePipeline } from './pipeline/port';
+
+/**
+ * THE writer. Every stored photo is stored here, and nothing else decides what a
+ * stored photo is made of.
+ *
+ * That single-owner rule is the point, and it was learned the hard way. An
+ * earlier design had the answer in three places: the inline path minted a key
+ * from what it had actually produced, the presign path GUESSED the same key's
+ * shape from a content type and a config flag before a single byte existed, and
+ * both then looped over the rendition list storing objects. Two of the three
+ * could disagree — and did, structurally: a key minted on a guess promises crops
+ * the bytes may turn out not to support, which is why that design needed a
+ * `purpose` flag, an animation special case, a direct-upload special case, and a
+ * 422 to break the promise afterwards. None of that is here. The key is minted
+ * from FINISHED work, so it cannot promise anything that is not already stored.
+ *
+ * The two ways bytes arrive keep their own TRANSPORT and share this LOGIC:
+ *
+ *   - an AGENT sends them base64 inside the write that uses them, because a tool
+ *     call is JSON and it cannot make an HTTP request of its own;
+ *   - a BROWSER POSTs them to the upload endpoint and saves the key it gets back,
+ *     which is what lets a draft reference a photo picked before the row exists.
+ *
+ * The order matters:
+ *
+ *   1. process the uncropped object — the whole picture, which is what a zoom
+ *      shows;
+ *   2. cut the crops from the ORIGINAL bytes, not from step 1's output;
+ *   3. mint the key from the RESULT — the extension from the type the object was
+ *      actually stored as, and the SHAPE from whether step 2 produced anything.
+ */
+
+export interface StoreImageDeps {
+  driver: StorageDriver;
+  pipeline: ImagePipeline;
+  messages: StorageMessages;
+  maxBytes: number;
+  specs: readonly RenditionSpec[];
+  keyPrefix: string;
+}
+
+interface StoreImageInput {
+  bytes: Uint8Array;
+  /** The type the caller declares. Corroborated against the bytes themselves. */
+  contentType: string;
+  /** The tenant the object belongs to — the key's scope segment. */
+  scope: string;
+}
+
+function refuse(deps: StoreImageDeps, problem: keyof StorageMessages): never {
+  throw new StorageProblemError(problem, deps.messages[problem]);
+}
+
+/**
+ * Refuse bytes that are not really an image of `contentType`.
+ *
+ * Called by {@link storeImage} ITSELF, which is the only arrangement that holds.
+ * It used to be each entrance's job — the endpoint called it before delegating,
+ * and the base64 path got it as part of decoding — and the public `storeImage` a
+ * host calls with raw bytes in hand was then the one that forgot. An adversarial
+ * probe stored `<html><script>alert(1)</script></html>` under a `full.png` key,
+ * served as `image/png`, straight through that gap.
+ *
+ * The gap was reachable with the REAL pipeline and not only with a stub: a
+ * re-encode that is not SMALLER deliberately keeps the original bytes and the
+ * DECLARED type (see `sharp.ts`), and libvips decodes plenty of formats this
+ * allowlist excludes — so `process` had no reason to object either.
+ *
+ * `payload.ts` already said this check must run on both entrances "because
+ * neither may be the one that forgets". The fix is to stop asking entrances: the
+ * writer verifies once, and no path to storage goes around it.
+ */
+function assertImageBytes(
+  deps: StoreImageDeps,
+  bytes: Uint8Array,
+  contentType: string,
+): void {
+  const problem = verifyImageBytes(bytes, contentType);
+  if (problem) refuse(deps, problem);
+}
+
+/** Write the crops first, then the object the row will name. */
+async function writeSet(
+  deps: StoreImageDeps,
+  key: string,
+  full: { bytes: Uint8Array; contentType: string },
+  renditions: readonly { spec: RenditionSpec; bytes: Uint8Array }[],
+): Promise<void> {
+  try {
+    // The uncropped object goes LAST, after every crop its key implies is already
+    // in place. A request that dies partway then leaves objects nothing points at
+    // — which a bucket forgets — rather than a row pointing at a photo whose card
+    // crop 404s in every grid that draws it.
+    await Promise.all(
+      renditions.map((rendition) =>
+        // Non-null: `renditions` is only non-empty for a set key.
+        deps.driver.put(
+          renditionKey(key, rendition.spec.name, deps.keyPrefix) as string,
+          rendition.bytes,
+          RENDITION_CONTENT_TYPE,
+        ),
+      ),
+    );
+    await deps.driver.put(key, full.bytes, full.contentType);
+  } catch (error) {
+    if (error instanceof StorageNotConfiguredError) refuse(deps, 'storage_not_configured');
+    refuse(deps, 'storage_unavailable');
+  }
+}
+
+/**
+ * Store `bytes` and return the key to save on the row.
+ *
+ * Throws {@link StorageProblemError} for anything the caller can fix, so a bad
+ * image fails the whole write with a usable status instead of creating a row with
+ * a silently missing photo.
+ */
+export async function storeImage(
+  deps: StoreImageDeps,
+  input: StoreImageInput,
+): Promise<string> {
+  // FIRST, and before a decoder sees anything: bytes that are not really an image
+  // of the declared type never reach the pipeline at all.
+  assertImageBytes(deps, input.bytes, input.contentType);
+  const [processed, renditions] = await Promise.all([
+    deps.pipeline.process(input.bytes, input.contentType),
+    deps.pipeline.cut(input.bytes, deps.specs),
+  ]);
+  if (!processed.ok) refuse(deps, processed.problem);
+
+  const { contentType } = processed.image;
+  const mint = { scope: input.scope, contentType, prefix: deps.keyPrefix };
+  // An empty rendition list is the animated case and the pipeline-declined case,
+  // and both want the flat key: it is what tells every later reader that this
+  // photo has no crops to ask for. Decided from the RESULT, never a prediction.
+  const key = renditions.length > 0 ? mintObjectSetKey(mint) : mintObjectKey(mint);
+
+  await writeSet(deps, key, processed.image, renditions);
+  return key;
+}
+
+/**
+ * {@link storeImage} for bytes that arrived base64-encoded inside a write body.
+ *
+ * The decode is the only thing this adds. Everything that happens to the bytes
+ * afterwards is the same code a browser's upload runs, so a photo is the same set
+ * of objects however it arrived.
+ */
+export async function storeInlineImage(
+  deps: StoreImageDeps,
+  image: InlineImage,
+  scope: string,
+): Promise<string> {
+  const decoded = decodeImagePayload(image.contentBase64, image.contentType, deps.maxBytes);
+  if (!decoded.ok) refuse(deps, decoded.problem);
+  return storeImage(deps, { bytes: decoded.bytes, contentType: image.contentType, scope });
+}

package/src/urls.ts

@@ -0,0 +1,118 @@
+import { hasRenditions, renditionKey } from './keys';
+import {
+  CATALOG_RENDITIONS,
+  renditionFamilies,
+  type RenditionFamily,
+  type RenditionSpec,
+} from './renditions';
+
+/**
+ * Turning a stored KEY back into URLs a browser can load.
+ *
+ * The key, never the URL, is what lands in the host's database. Display code
+ * resolves it through the ACTIVE driver, so the same row renders correctly
+ * whether the object lives on a dev machine's disk or in a bucket behind a CDN —
+ * and only the server knows which of those is running, which is why these run
+ * server-side and the client receives finished `src`/`srcSet` pairs.
+ */
+
+/** How a key becomes a loadable URL. A driver's `publicUrl`, in practice. */
+export type PublicUrlResolver = (key: string) => string;
+
+/** One `srcset` family, ready to hand an `<img>`. */
+export interface ImageRenditionSet {
+  /**
+   * What a browser without `srcset` support falls back to — a real member of
+   * the family rather than the uncropped object, because a fallback that changed
+   * the framing would make one card in a grid taller than the rest.
+   */
+  src: string;
+  /** `w`-descriptor srcset — the widths are the canvases the crops were cut at. */
+  srcSet: string;
+}
+
+/**
+ * The derived crops of one photo, by the shape they are drawn in. `null` for a
+ * photo stored without them — an animated source, a passthrough pipeline, or
+ * anything uploaded before renditions existed — which every consumer reads as
+ * "draw the uncropped object the way it has always been drawn".
+ */
+export type ImageSources = Readonly<Record<RenditionFamily, ImageRenditionSet>>;
+
+/** Resolve a stored key, or an already-absolute URL, to something loadable. */
+export function objectUrl(key: string | null, resolve: PublicUrlResolver): string | null {
+  if (!key) return null;
+  // A value that is already a URL is returned unchanged: a host migrating off
+  // an older column may still hold absolute URLs beside real keys.
+  if (/^https?:\/\//i.test(key)) return key;
+  return resolve(key);
+}
+
+function familySet(
+  key: string,
+  family: RenditionFamily,
+  specs: readonly RenditionSpec[],
+  resolve: PublicUrlResolver,
+  prefix: string | undefined,
+): ImageRenditionSet {
+  const members = specs.filter((spec) => spec.family === family);
+  // Non-null throughout: `hasRenditions(key)` is the caller's precondition, and
+  // `family` came from this same spec list.
+  const url = (spec: RenditionSpec): string =>
+    resolve(renditionKey(key, spec.name, prefix) as string);
+  const first = members[0] as RenditionSpec;
+  return {
+    // The SMALLEST of the family: `src` is only reached without srcset support,
+    // and over-fetching is the worse of the two ways to be wrong there.
+    src: url(first),
+    srcSet: members.map((spec) => `${url(spec)} ${spec.width}w`).join(', '),
+  };
+}
+
+export interface ImageSourcesOptions {
+  specs?: readonly RenditionSpec[];
+  prefix?: string;
+}
+
+/**
+ * The crop families stored beside `key`, or `null` when it has none.
+ *
+ * Derived from the key's SHAPE alone — see `keys.ts` for why that is a truthful
+ * answer and not a guess.
+ */
+export function imageSources(
+  key: string | null,
+  resolve: PublicUrlResolver,
+  options: ImageSourcesOptions = {},
+): ImageSources | null {
+  const specs = options.specs ?? CATALOG_RENDITIONS;
+  if (!key || !hasRenditions(key, options.prefix)) return null;
+  return Object.fromEntries(
+    renditionFamilies(specs).map((family) => [
+      family,
+      familySet(key, family, specs, resolve, options.prefix),
+    ]),
+  ) as ImageSources;
+}
+
+/**
+ * {@link objectUrl} with a cache-busting stamp appended.
+ *
+ * Exists for an app icon, where a stable URL is a bug rather than a nicety: a
+ * manifest and its icons are cached hard, and an ALREADY-INSTALLED home-screen
+ * icon is the last asset a device re-fetches — so a store that replaces its icon
+ * keeps showing the old one on precisely the devices that matter, with nothing
+ * on screen to explain it.
+ *
+ * The separator is chosen rather than assumed: a CDN base may legitimately carry
+ * query parameters of its own, and a blind `?` would produce a URL with two.
+ */
+export function versionedObjectUrl(
+  key: string | null,
+  version: string | null,
+  resolve: PublicUrlResolver,
+): string | null {
+  const url = objectUrl(key, resolve);
+  if (!url || !version) return url;
+  return `${url}${url.includes('?') ? '&' : '?'}v=${encodeURIComponent(version)}`;
+}

package/src/wire.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+
+import { ACCEPTED_CONTENT_TYPES } from './content-types';
+import { DEFAULT_KEY_PREFIX, isObjectKey } from './keys';
+import { maxBase64Length } from './limits';
+
+/**
+ * The wire shapes, as zod — including the one a TOOL schema is built from.
+ *
+ * `inlineImageSchema(maxBytes)` is a factory rather than a constant because its
+ * ceiling IS the mount's ceiling. That is the whole anti-drift point of the
+ * extraction: a host builds its agent-facing tool schema from
+ * `createApiStorage(…).schemas.inlineImage`, so the schema cannot advertise a
+ * limit the endpoint does not enforce, and raising one raises the other.
+ */
+
+/** An image supplied by VALUE, base64-encoded because a tool call is JSON. */
+export function inlineImageSchema(
+  maxBytes: number,
+): z.ZodObject<{ contentType: z.ZodEnum<Record<string, string>>; contentBase64: z.ZodString }> {
+  return z.object({
+    contentType: z.enum(
+      Object.fromEntries(ACCEPTED_CONTENT_TYPES.map((type) => [type, type])),
+    ),
+    /** The file's bytes, base64-encoded. A `data:` URL prefix is accepted. */
+    contentBase64: z.string().min(1).max(maxBase64Length(maxBytes)),
+  });
+}
+
+/** An image supplied by value: `{ contentType, contentBase64 }`. */
+export interface InlineImage {
+  contentType: string;
+  contentBase64: string;
+}
+
+/**
+ * A key this scheme actually minted — the schema an `imageKey` FIELD should use.
+ *
+ * Ships beside {@link inlineImageSchema} because the pair is what a host's write
+ * body is made of, and because `z.string()` is the wrong answer in a way that is
+ * not obvious. An `imageKey` is not free text: it is a key the server minted, it is
+ * rendered straight into an `<img src>` by `objectUrl`, and `objectUrl`
+ * deliberately returns an ALREADY-ABSOLUTE value unchanged (a documented migration
+ * affordance for a host moving off a URL column).
+ *
+ * Compose those two and a recipe that accepts any string accepts
+ * `imageKey: 'https://tracker.example/p.png'` from anyone who may edit the row —
+ * after which every buyer loading that storefront page sends their IP and
+ * user-agent to a third party. No upload, no bucket and no driver is involved, so
+ * nothing on the storage path can catch it; the only place to refuse it is where
+ * the value arrives.
+ *
+ * The cross-tenant variant (`products/<otherTenant>/<uuid>/full.webp`) parses here
+ * and is refused later by the reclaim's `keyInScope` — but a host that wants it
+ * refused on the WRITE should pair this with `keyInScope(key, scope, …)`, which
+ * this schema cannot do because it does not know the caller.
+ *
+ * A `javascript:`-shaped value is already inert: `objectUrl` only passes through
+ * `^https?://`, so `javascript:alert(1)` is handed to the driver and comes back as
+ * a path under the mount. Inert is not the same as valid, and it is refused here too.
+ */
+export function objectKeySchema(prefix: string = DEFAULT_KEY_PREFIX): z.ZodString {
+  return z.string().refine((key) => isObjectKey(key, prefix), {
+    message: 'Not an object key minted by this storage mount.',
+  });
+}
+
+/** The pair of fields an image-bearing write body carries. */
+export interface ImageFields {
+  imageKey?: string | null;
+  image?: InlineImage;
+}
+
+/**
+ * Reject a body stating BOTH an existing key and new bytes.
+ *
+ * Silently preferring one makes the other's presence a no-op the caller cannot
+ * see, and the two mean opposite things — "keep pointing at this object" versus
+ * "store these bytes and point at the result". An explicit refusal is the only
+ * reading that cannot quietly discard an upload.
+ */
+export function refineImageInput(
+  value: ImageFields,
+  ctx: z.RefinementCtx,
+  path: readonly (string | number)[] = [],
+): void {
+  if (value.image && value.imageKey) {
+    ctx.addIssue({
+      code: 'custom',
+      path: [...path, 'image'],
+      message:
+        'Send either imageKey (an object already stored) or image (the bytes to store), not both.',
+    });
+  }
+}
+
+/** What `POST <mount>/uploads/image` answers on success. */
+export const uploadAcceptedSchema = z.object({
+  data: z.object({ imageKey: z.string() }),
+});
+
+/** The success body of an upload, as the browser half parses it. */
+export type UploadAccepted = z.infer<typeof uploadAcceptedSchema>;