@12-apps/storage 1.0.0

package/src/hono/index.ts

@@ -0,0 +1,96 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+
+import {
+  createApiStorage,
+  type ApiStorage,
+  type ApiStorageConfig,
+} from '../server/create-api-storage';
+import type { StorageActor, StorageRouteResponse } from '../server/routes';
+
+/**
+ * `@12-apps/storage/hono` — the upload surface as a mountable router.
+ *
+ * The framework-neutral descriptors in `/server` are the contract; this is the
+ * adapter for the framework we happen to use, behind its own subpath with `hono`
+ * as an OPTIONAL peer — a host on Express, or one that only wants the React half,
+ * never resolves it.
+ *
+ * A host writes:
+ *
+ *   const storage = storageRouter({ …config, resolveActor });
+ *   app.route('/api', storage.router);
+ *
+ * and keeps what is genuinely its own: who the caller is, and which tenant they
+ * are acting for. The wildcard the serve route needs is spelled here (`:key{.+}`)
+ * rather than in the descriptor, because the syntax is this framework's.
+ */
+
+/**
+ * Resolve the caller. `null` is unauthenticated and answers 401 before any
+ * handler runs — which is also where a host's own gates belong (a read-only
+ * impersonation, a plan that does not include uploads): answered before
+ * delegating, never inside the package.
+ */
+export type ResolveStorageActor = (
+  c: Context,
+) => Promise<StorageActor | null> | StorageActor | null;
+
+export interface StorageHonoConfig extends ApiStorageConfig {
+  resolveActor: ResolveStorageActor;
+  /** 401 body message. pt-BR by default, like every other refusal here. */
+  unauthenticatedMessage?: string;
+}
+
+export interface StorageHono extends ApiStorage {
+  router: Hono;
+}
+
+/** A response the descriptors chose, rendered in this framework's terms. */
+function send(c: Context, response: StorageRouteResponse): Response {
+  if ('redirect' in response) return c.redirect(response.redirect, 302);
+  if ('bytes' in response) {
+    // The bytes as their own ArrayBuffer: a Uint8Array over a pooled buffer would
+    // hand the client whatever else shares that allocation.
+    const body = response.bytes.slice().buffer as ArrayBuffer;
+    return c.body(body, response.status as 200, {
+      ...response.headers,
+      'content-length': String(response.bytes.byteLength),
+    });
+  }
+  // The status travels with the body the handler chose; this adapter never
+  // reinterprets either, or the two halves of the contract would drift — which is
+  // the whole reason the handlers live in the package.
+  return c.json(response.body as Record<string, unknown>, response.status as 200);
+}
+
+export function storageRouter(config: StorageHonoConfig): StorageHono {
+  const { resolveActor, unauthenticatedMessage, ...apiConfig } = config;
+  const api = createApiStorage(apiConfig);
+  const unauthenticated = unauthenticatedMessage ?? 'Não autenticado.';
+  const router = new Hono();
+
+  for (const route of api.routes) {
+    const handler = async (c: Context): Promise<Response> => {
+      const actor = route.auth === 'public' ? null : await resolveActor(c);
+      if (route.auth === 'actor' && !actor) {
+        return c.json({ error: unauthenticated }, 401);
+      }
+      const response = await route.handle({
+        actor,
+        params: c.req.param() as Record<string, string | undefined>,
+        request: c.req.raw,
+      });
+      return send(c, response);
+    };
+
+    // `:key{.+}` and not `*`: the whole remainder is one parameter, which is what
+    // makes a nested key (`products/<scope>/<uuid>/card-320.webp`) arrive intact
+    // instead of as a path Hono has already split.
+    const path = route.wildcardParam ? `${route.path}/:${route.wildcardParam}{.+}` : route.path;
+    if (route.method === 'GET') router.get(path, handler);
+    else router.post(path, handler);
+  }
+
+  return { ...api, router };
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * `@12-apps/storage` — uploads that land at YOUR OWN ORIGIN.
+ *
+ * The root entry is the isomorphic half: the format allowlist, the upload
+ * ceiling, the object-key grammar, the rendition list, the refusal taxonomy and
+ * the wire schemas. Both other halves are built on it, which is what keeps the
+ * browser and the server agreeing about what an upload is.
+ *
+ * The design decision this package exists to preserve: **the browser PUTs at our
+ * own origin, never at the bucket.** A presigned URL makes a working upload
+ * depend on the bucket's CORS rules — configuration that lives in neither the
+ * host repository nor any deploy it runs. When it is missing, the preflight is
+ * refused, THE SERVER SEES NOTHING (no request arrives, no log line, no error
+ * rate), the browser cannot say why (a blocked cross-origin fetch is
+ * deliberately indistinguishable from an offline network), and the message
+ * reaches a store owner about a bucket only an operator can configure. There is
+ * therefore no "just presign it" mode here, and adding one would reintroduce all
+ * three symptoms at once.
+ *
+ * A second reason it cannot come back: a stored photo is a SET of objects the
+ * server derives from the bytes, so an upload the server never sees cannot
+ * produce one.
+ */
+
+export {
+  ACCEPTED_CONTENT_TYPES,
+  CONTENT_TYPE_BY_EXTENSION,
+  EXTENSION_BY_CONTENT_TYPE,
+  acceptedContentTypeOf,
+  isAcceptedContentType,
+} from './content-types';
+
+export { DEFAULT_MAX_UPLOAD_BYTES, maxBase64Length, megabytes } from './limits';
+
+export { STORAGE_PATHS } from './paths';
+
+export {
+  DEFAULT_KEY_PREFIX,
+  hasRenditions,
+  isLegalScope,
+  isObjectKey,
+  keyInScope,
+  mintObjectKey,
+  mintObjectSetKey,
+  parseObjectKey,
+  parseObjectMemberKey,
+  renditionKey,
+  type MintKeyInput,
+  type ObjectKey,
+  type ObjectMemberKey,
+} from './keys';
+
+export {
+  CATALOG_RENDITIONS,
+  RENDITION_CONTENT_TYPE,
+  renditionFamilies,
+  type RenditionFamily,
+  type RenditionOutput,
+  type RenditionSpec,
+} from './renditions';
+
+export {
+  decodeImagePayload,
+  sniffImageContentType,
+  verifyImageBytes,
+  type DecodedPayload,
+} from './payload';
+
+export {
+  STORAGE_PROBLEM_STATUS,
+  StorageNotConfiguredError,
+  StorageProblemError,
+  defaultStorageMessages,
+  isStorageProblem,
+  type StorageMessageContext,
+  type StorageMessages,
+  type StorageProblem,
+} from './problems';
+
+export {
+  imageSources,
+  objectUrl,
+  versionedObjectUrl,
+  type ImageRenditionSet,
+  type ImageSources,
+  type ImageSourcesOptions,
+  type PublicUrlResolver,
+} from './urls';
+
+export {
+  inlineImageSchema,
+  objectKeySchema,
+  refineImageInput,
+  uploadAcceptedSchema,
+  type ImageFields,
+  type InlineImage,
+  type UploadAccepted,
+} from './wire';

package/src/keys.ts

@@ -0,0 +1,331 @@
+import { EXTENSION_BY_CONTENT_TYPE } from './content-types';
+
+/**
+ * The object key: what it looks like, what its SHAPE promises, and which
+ * tenant it belongs to.
+ *
+ * ## Server-minted, always
+ *
+ * The key is what lands in the host's database and what a serve route resolves,
+ * and stored objects are world-readable (a store's logo is printed in its own
+ * storefront HTML). A caller that could choose its own key could therefore
+ * write over any object whose URL it can read.
+ *
+ * ## Two shapes, and the difference is a FACT about the object
+ *
+ * A photo stored WITH its derived crops is a directory of objects sharing a
+ * uuid, and the key saved on the row names the uncropped member:
+ *
+ *     products/<scope>/<uuid>/full.webp        ← the key on the row
+ *     products/<scope>/<uuid>/card-320.webp    ← its siblings
+ *     products/<scope>/<uuid>/thumb-128.webp
+ *
+ * A photo stored ALONE keeps the flat shape:
+ *
+ *     products/<scope>/<uuid>.webp
+ *
+ * So the shape is a truthful answer to "may I ask for this photo's 4:3 card
+ * crop?" ({@link ObjectKey.hasRenditions}) — and that is deliberately the ONLY
+ * place that question is answered. The alternative is a column recording which
+ * derivatives exist, on the row and on every draft, change request, recycle-bin
+ * snapshot and version the row is copied into, kept in step with the bucket by
+ * nothing. A key that describes its own storage cannot fall out of step, and a
+ * consumer handed a key with no set simply asks for no crops.
+ *
+ * ## The SCOPE segment is the tenant boundary
+ *
+ * `<scope>` is the tenant the object belongs to, and it is what makes
+ * cross-tenant reclaim a parse rather than a query: `deleteIfOrphaned` refuses
+ * a key whose scope is not the caller's before it consults any reference probe.
+ * A scheme without it leaves "may this tenant delete this object?" answerable
+ * only by proving no row of THEIRS points at it — which is true of every other
+ * tenant's objects too.
+ *
+ * UNSCOPED keys parse as well, with `scope: null`, because an adopting host has
+ * a table full of them. They are the reason `unscopedKeys` is a required
+ * choice rather than a default (see `create-api-storage.ts`): for such a key
+ * the structural guarantee above does not exist, and only the host's probes
+ * stand between one tenant and another's bytes.
+ *
+ * The four shapes stay mutually unambiguous even when a scope is itself
+ * uuid-shaped (a tenant id): a set key's leaf stem is always `full`, and a flat
+ * key's leaf stem is always the object uuid, which is never the word `full`.
+ */
+
+/** Default top-level segment every key starts with. */
+export const DEFAULT_KEY_PREFIX = 'products';
+
+/** The member of a rendition set that holds the uncropped picture. */
+const FULL_STEM = 'full';
+
+/**
+ * A legal scope segment.
+ *
+ * Deliberately narrower than "a tenant slug": the local-disk driver turns a key
+ * into a filesystem path, so a segment that can carry `.`, `/` or whitespace is
+ * a traversal waiting for a caller who assembles a key by hand. A host whose
+ * tenant identifiers do not fit passes their id instead of their slug.
+ */
+const SCOPE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** A parsed object key. */
+export interface ObjectKey {
+  prefix: string;
+  /** The tenant the object belongs to; `null` for a legacy unscoped key. */
+  scope: string | null;
+  /** The object's own uuid — shared by every member of a rendition set. */
+  uuid: string;
+  /** Extension of the uncropped object, which is not always `webp`. */
+  extension: string;
+  /** Was this photo stored with the crops a storefront draws? */
+  hasRenditions: boolean;
+}
+
+/** Is `scope` usable as a key segment? Checked at mint time, not assumed. */
+export function isLegalScope(scope: string): boolean {
+  return SCOPE.test(scope);
+}
+
+/**
+ * The four shapes, as anchored regexes built once per prefix.
+ *
+ * Regexes rather than a segment walk because the four are MUTUALLY EXCLUSIVE by
+ * construction and that is the property worth making obvious: a set key's leaf
+ * stem is the literal `full`, a flat key's is the object uuid, and a uuid is never
+ * the word `full`. So the three-segment shapes — `<prefix>/<scope>/<uuid>.ext` and
+ * `<prefix>/<uuid>/full.ext` — cannot both match one key, whether or not the scope
+ * happens to be uuid-shaped itself.
+ *
+ * The scope group is always present and simply matches nothing on the unscoped
+ * shapes, so a caller reads it the same way every time.
+ */
+interface KeyShape {
+  re: RegExp;
+  hasRenditions: boolean;
+}
+
+const UUID_SOURCE = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const SCOPE_SOURCE = '[A-Za-z0-9][A-Za-z0-9_-]{0,63}';
+const EXT_SOURCE = '[A-Za-z0-9]{2,4}';
+const STEM_SOURCE = '[A-Za-z0-9][A-Za-z0-9_-]*';
+
+function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Built per prefix and cached: a key is parsed on every read of every row. */
+const SHAPES = new Map<string, readonly KeyShape[]>();
+const MEMBER_SHAPES = new Map<string, readonly RegExp[]>();
+
+function shapesFor(prefix: string): readonly KeyShape[] {
+  const cached = SHAPES.get(prefix);
+  if (cached) return cached;
+  const p = escapeRegExp(prefix);
+  const shapes: readonly KeyShape[] = [
+    // scoped set, scoped flat, unscoped set, unscoped flat
+    { re: key(`${p}/(${SCOPE_SOURCE})/(${UUID_SOURCE})/${FULL_STEM}`), hasRenditions: true },
+    { re: key(`${p}/(${SCOPE_SOURCE})/(${UUID_SOURCE})`), hasRenditions: false },
+    { re: key(`${p}/()(${UUID_SOURCE})/${FULL_STEM}`), hasRenditions: true },
+    { re: key(`${p}/()(${UUID_SOURCE})`), hasRenditions: false },
+  ];
+  SHAPES.set(prefix, shapes);
+  return shapes;
+}
+
+/** `<body>.<ext>`, anchored and case-insensitive. */
+function key(body: string): RegExp {
+  return new RegExp(`^${body}\\.(${EXT_SOURCE})$`, 'i');
+}
+
+/**
+ * The MEMBER shapes: a crop's leaf stem is `card-320`, which is deliberately not a
+ * key any row may name.
+ */
+function memberShapesFor(prefix: string): readonly RegExp[] {
+  const cached = MEMBER_SHAPES.get(prefix);
+  if (cached) return cached;
+  const p = escapeRegExp(prefix);
+  const shapes: readonly RegExp[] = [
+    new RegExp(
+      `^${p}/(${SCOPE_SOURCE})/(${UUID_SOURCE})/(${STEM_SOURCE})\\.(${EXT_SOURCE})$`,
+      'i',
+    ),
+    new RegExp(`^${p}/()(${UUID_SOURCE})/(${STEM_SOURCE})\\.(${EXT_SOURCE})$`, 'i'),
+  ];
+  MEMBER_SHAPES.set(prefix, shapes);
+  return shapes;
+}
+
+/** A capture group, which the shapes above always define. */
+function group(match: RegExpExecArray, index: number): string {
+  return match[index] ?? '';
+}
+
+/**
+ * Parse `key`, or `null` for anything this scheme did not mint.
+ *
+ * Total: every accepted key is one of the four shapes documented above, so a near
+ * miss reads as "not ours" rather than as a photo whose crops five URLs promise and
+ * no object backs.
+ */
+export function parseObjectKey(key: string, prefix = DEFAULT_KEY_PREFIX): ObjectKey | null {
+  for (const shape of shapesFor(prefix)) {
+    const match = shape.re.exec(key);
+    if (match) {
+      return {
+        prefix,
+        // Empty on the unscoped shapes, where the group matches nothing.
+        scope: group(match, 1) || null,
+        uuid: group(match, 2),
+        extension: group(match, 3).toLowerCase(),
+        hasRenditions: shape.hasRenditions,
+      };
+    }
+  }
+  return null;
+}
+
+/** Is `key` one this scheme minted — any of the four shapes? */
+export function isObjectKey(key: string, prefix = DEFAULT_KEY_PREFIX): boolean {
+  return parseObjectKey(key, prefix) !== null;
+}
+
+/** Does `key` name a photo that was stored with its derived crops? */
+export function hasRenditions(key: string, prefix = DEFAULT_KEY_PREFIX): boolean {
+  return parseObjectKey(key, prefix)?.hasRenditions ?? false;
+}
+
+/** How a key is minted: the tenant it belongs to and the stored format. */
+export interface MintKeyInput {
+  /** The tenant the object belongs to. */
+  scope: string;
+  /**
+   * The type the object is ACTUALLY stored as — on a re-encoding pipeline that is
+   * the produced type, not the one the caller declared. The extension here is what
+   * the object is later served with, so minting from the declared type would label
+   * a downscaled WebP `.png`.
+   */
+  contentType: string;
+  prefix?: string;
+  /** A caller-supplied uuid. Tests only; production mints one per upload. */
+  uuid?: string;
+}
+
+function extensionFor(contentType: string): string {
+  const extension = EXTENSION_BY_CONTENT_TYPE[contentType];
+  if (!extension) {
+    throw new Error(`Refusing to mint a key for an unsupported type: ${contentType}`);
+  }
+  return extension;
+}
+
+function assertScope(scope: string): void {
+  if (!isLegalScope(scope)) {
+    throw new Error(`Refusing to mint a key with an unsafe scope segment: ${scope}`);
+  }
+}
+
+/**
+ * Mint a STANDALONE object key: `<prefix>/<scope>/<uuid>.<ext>`.
+ *
+ * The shape for everything that is one picture and nothing more — a logo, an app
+ * icon, and a photo whose source cannot be cropped frame by frame.
+ */
+export function mintObjectKey(input: MintKeyInput): string {
+  assertScope(input.scope);
+  const prefix = input.prefix ?? DEFAULT_KEY_PREFIX;
+  return `${prefix}/${input.scope}/${input.uuid ?? crypto.randomUUID()}.${extensionFor(
+    input.contentType,
+  )}`;
+}
+
+/**
+ * Mint the key for the uncropped member of a rendition SET:
+ * `<prefix>/<scope>/<uuid>/full.<ext>`. Siblings are named from it by
+ * {@link renditionKey}.
+ */
+export function mintObjectSetKey(input: MintKeyInput): string {
+  assertScope(input.scope);
+  const prefix = input.prefix ?? DEFAULT_KEY_PREFIX;
+  const uuid = input.uuid ?? crypto.randomUUID();
+  return `${prefix}/${input.scope}/${uuid}/${FULL_STEM}.${extensionFor(input.contentType)}`;
+}
+
+/**
+ * The key of one sibling in `key`'s rendition set, or `null` for a key with no set.
+ *
+ * Null rather than a plausible-looking string: constructing a key for an object
+ * nobody ever wrote is how a card ends up drawing the broken-image glyph.
+ */
+export function renditionKey(
+  key: string,
+  name: string,
+  prefix = DEFAULT_KEY_PREFIX,
+): string | null {
+  if (!hasRenditions(key, prefix)) return null;
+  return `${key.slice(0, key.lastIndexOf('/'))}/${name}.webp`;
+}
+
+/** One member of a stored photo — the uncropped object or any of its crops. */
+export interface ObjectMemberKey {
+  scope: string | null;
+  uuid: string;
+  /** `full`, `card-320`, or the uuid itself for a flat key. */
+  stem: string;
+  extension: string;
+}
+
+/**
+ * Parse any MEMBER of a stored photo, crops included.
+ *
+ * The serve route needs this and {@link parseObjectKey} will not do: the two
+ * questions are different — "is this a key I could have saved?" versus "is this an
+ * object I could have written?" — and answering the second with the first would
+ * 400 every crop in the catalog.
+ */
+export function parseObjectMemberKey(
+  key: string,
+  prefix = DEFAULT_KEY_PREFIX,
+): ObjectMemberKey | null {
+  const direct = parseObjectKey(key, prefix);
+  if (direct) {
+    return {
+      scope: direct.scope,
+      uuid: direct.uuid,
+      stem: direct.hasRenditions ? FULL_STEM : direct.uuid,
+      extension: direct.extension,
+    };
+  }
+  for (const re of memberShapesFor(prefix)) {
+    const match = re.exec(key);
+    if (match) {
+      return {
+        scope: group(match, 1) || null,
+        uuid: group(match, 2),
+        stem: group(match, 3),
+        extension: group(match, 4).toLowerCase(),
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Does `key` belong to `scope`?
+ *
+ * `unscopedKeys` decides the legacy case and has no safe default, which is why
+ * the mount requires the host to choose it. `'accept'` means a key with no
+ * scope segment is treated as in-scope — correct for a host whose existing rows
+ * predate the scope segment, and the reason such a host still needs reference
+ * probes. `'reject'` means only a key carrying this scope is ever touched.
+ */
+export function keyInScope(
+  key: string,
+  scope: string,
+  unscopedKeys: 'accept' | 'reject',
+  prefix = DEFAULT_KEY_PREFIX,
+): boolean {
+  const parsed = parseObjectKey(key, prefix);
+  if (!parsed) return false;
+  if (parsed.scope === null) return unscopedKeys === 'accept';
+  return parsed.scope === scope;
+}

package/src/limits.ts

@@ -0,0 +1,37 @@
+/**
+ * The upload ceiling, and the one rule about it: there is exactly ONE number.
+ *
+ * A cap that differed by entrance would mean a file the app accepts from a
+ * browser and refuses from an agent, for no reason the person uploading could
+ * see. So this module owns the number and everything derived from it, and
+ * {@link createApiStorage} takes `maxBytes` as a REQUIRED config value rather
+ * than defaulting quietly — a permissive default is the failure that cannot be
+ * noticed from inside the host that has it.
+ *
+ * {@link DEFAULT_MAX_UPLOAD_BYTES} is the recommended value, exported so a host
+ * can hand the SAME constant to its upload mount and to any tool schema that
+ * advertises the ceiling. That is the anti-drift seam the extraction exists for:
+ * `createApiStorage(…).limits` echoes back what the mount actually enforces, so
+ * a schema built from it cannot describe a limit the endpoint does not have.
+ */
+
+/** The recommended upload cap: 8 MiB. */
+export const DEFAULT_MAX_UPLOAD_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Ceiling for a base64-encoded field carrying `maxBytes` of file.
+ *
+ * 4 characters carry 3 bytes, plus room for a `data:` URL wrapper and for line
+ * wrapping. Used as a schema `max`, so an oversize payload is refused by
+ * validation before a handler ever allocates it.
+ */
+export function maxBase64Length(maxBytes: number): number {
+  return Math.ceil(maxBytes / 3) * 4 + 1024;
+}
+
+/** `8 MB`, `1,5 MB` — pt-BR decimal comma, for a message a store owner reads. */
+export function megabytes(bytes: number): string {
+  const mb = bytes / 1024 / 1024;
+  const rendered = Number.isInteger(mb) ? String(mb) : mb.toFixed(1).replace('.', ',');
+  return `${rendered} MB`;
+}

package/src/paths.ts

@@ -0,0 +1,14 @@
+/**
+ * Where the two endpoints live, relative to wherever the router is mounted.
+ *
+ * Its own module, and part of the ISOMORPHIC entry, because both halves need it
+ * and neither may spell it itself: the browser posts to `upload`, the local driver
+ * builds display URLs from `serve`, and a host composes its driver's
+ * `publicPathPrefix` as `<mount base> + STORAGE_PATHS.serve`. A string retyped in
+ * three places is three chances to have written objects at one path and served
+ * them from another.
+ */
+export const STORAGE_PATHS = {
+  upload: '/uploads/image',
+  serve: '/uploads/local',
+} as const;