@12-apps/storage 1.0.0

package/ADOPTING.md

@@ -0,0 +1,281 @@
+# Adopting @12-apps/storage
+
+This package is a **plug-and-play upload plugin** (12-20): one library, reusable
+across repositories, exposing standardized surfaces. A host only *points* at
+those surfaces — when the library updates, every host updates with **no app
+changes**. The contract is the one `@12-apps/report-builder`, `@12-apps/rbac` and
+`@12-apps/payments-*` established.
+
+## The standardized plugin surfaces
+
+| Surface | Export | What the host does |
+|---|---|---|
+| **Core** | `@12-apps/storage` | Nothing to wire — the format allowlist, the ceiling, the object-key grammar, the rendition set, the refusal taxonomy, the URL builders and the wire schemas. Isomorphic: the browser half reads the same constants the server enforces. |
+| **Server** | `@12-apps/storage/server` | Call `createApiStorage(config)` and mount the `routes` it returns. Parsing, the streaming cap, the magic-number check, key minting, the rendition write order, status codes and the envelope are all inside. The same object also hands back the write path, the URL builders and the reclaim, so every OTHER host surface stores and resolves through one wiring. |
+| **Hono** | `@12-apps/storage/hono` | `const storage = storageRouter({ …config, resolveActor }); app.route('/api', storage.router)`. A one-call mount; `hono` is an OPTIONAL peer, so importing the root or `/server` never resolves it. |
+| **S3** | `@12-apps/storage/s3` | `createS3Driver({ bucket, region \| endpoint, … })`. `@aws-sdk/client-s3` is an OPTIONAL peer resolved ONLY here, so a host on local disk never installs it. |
+| **React** | `@12-apps/storage/react` | Call `createWebStorage({ apiBase })` and render `page`, drop `ImageField` into a form, or build your own affordance on `useUpload`. |
+| **Prisma** | — none | This package owns **no models**. See "Why there is no Prisma partial" below. |
+
+## The five values you must decide, and why none of them defaults
+
+`createApiStorage` requires `driver`, `maxBytes`, `imagePipeline`, `unscopedKeys`
+and `references`. The reason is the same for all five and it is not tidiness:
+**each one fails quietly when it is wrong.** A loud wrong default gets fixed on
+the first deploy. These produce a green deploy, successful uploads, and a
+consequence weeks later that no log line explains — so the only place the
+decision can be made correctly is the host, in the open, once.
+
+| Config | What a default would cost you, specifically |
+|---|---|
+| `driver` | Uploads succeed onto a container's ephemeral disk. One container holds the object, the others 404, the next deploy discards it. `writeFile` returned success every time, so nothing is logged. |
+| `maxBytes` | Your tool schemas advertise one ceiling and the endpoint enforces another; an agent's upload is refused for a size its own schema accepted. |
+| `imagePipeline` | Whether crops exist at all. Discovered from the shape of a key, in production, by a card that renders the uncropped photo. |
+| `unscopedKeys` | Whether one tenant's reclaim can reach another tenant's bytes. Wrong in either direction and silent in both. |
+| `references` | Whether a restored row still has its photo. `[]` is not "no opinion" — it means *reclaim everything immediately*. |
+
+`logger` is the one that legitimately defaults: a reclaim may only report, never
+raise, so the worst a defaulted logger costs is silence. Pass yours anyway.
+
+## Host wiring rules (the ones that bite)
+
+1. **The host resolves WHO and WHERE; the package decides WHAT HAPPENS TO THE
+   BYTES.** `resolveActor` answers `{ scope, mayUpload }`. `scope` is the tenant
+   the objects belong to — it becomes the key's scope segment, so it must be
+   stable for the lifetime of an object (an id, not a renameable slug, unless
+   slugs are immutable in your host). `mayUpload` is ONE boolean because two
+   independent host questions feed it: "may this person store objects?" (roles,
+   memberships, plan) and "may this SESSION change anything?" (a read-only
+   impersonation, a maintenance mode). Both are answered before delegating. A
+   package that computed either would be wrong for every host but the first.
+2. **`unscopedKeys` is a migration decision, and you must make it.** A host with
+   existing rows minted before the scope segment passes `'accept'`: such a key
+   carries no tenant, so the structural cross-tenant guard cannot apply to it and
+   only `references` stands between one tenant and another's objects. A fresh
+   host passes `'reject'`, and then every key it will ever touch is scoped.
+   There is no default because the wrong one is silent in both directions.
+3. **`references` are YOUR tables, and the parameter is REQUIRED.** A key can
+   outlive the row that pointed at it, and some of those states are ones a person
+   is about to act on — a duplicated row sharing one object, a soft-deleted row
+   whose "restore" is expected to bring the photo back, a draft or a pending
+   approval holding a key waiting to be published. Deleting the object would break
+   the very next thing they do. Each of those is a probe:
+
+   ```ts
+   references: [
+     { name: 'live-rows', referenced: (scope, key) => rowPointsAt(scope, key) },
+     { name: 'pending',   referenced: (scope, key) => draftOrRequestHolds(scope, key) },
+   ]
+   ```
+
+   Scope each probe to the state that is genuinely PENDING (an `OPEN` draft, a
+   `PENDING` request, a `DELETED` bin entry). A probe that matches every row ever
+   written quietly restores "nothing is ever reclaimed", one abandoned edit at a
+   time. And think hard before adding **version history** as a probe: versioning
+   is usually on by default, so counting a version as a reference pins the object
+   for the whole retention window and "replace a photo" reclaims nothing, ever.
+
+   `references: []` is a legal answer and you must write it out. It says "nothing
+   in this host copies a key", and it is the value that made this parameter
+   required: it used to be the DEFAULT, so a host that had never thought about the
+   question got *reclaim everything immediately* — and found out weeks later, when
+   a store owner restored a product and the row came back without its photo.
+
+   **WHEN to call the reclaim: after commit, and after any copy-on-write path has
+   landed.** The probes are read OUTSIDE your transaction, and `deleteIfOrphaned`
+   is read-validate-write with no claim-once — it consults every probe, then
+   deletes. So there is a window, and it is real:
+
+   1. user B replaces product P's photo; the reclaim probes key `K`, nothing holds it;
+   2. concurrently user A duplicates P from a stale tab, and the duplicate row is
+      written with `imageKey: K`;
+   3. the purge runs. `K` and its five crops are gone, and A's new row points at
+      six objects that do not exist.
+
+   Closing that window needs refcounting, which would live in your tables beside
+   the keys — it is not something the package can do for you. What you can do is
+   order the call so the window is empty: **commit first, then reclaim**, and never
+   reclaim from inside a transaction or before a duplicate/restore path has
+   written. The package makes the failure discoverable rather than silent: if a
+   probe claims the key immediately after the purge, it logs through your `logger`
+   naming the probe — which is the only warning you will get, and the reason rule 4
+   matters.
+4. **`logger` is how you hear about a bucket that stopped accepting deletes.**
+   The reclaim runs after the write it follows and can only report, never raise —
+   a store owner who successfully changed a photo must not see an error because a
+   delete timed out. Pass your feature logger. The default drops everything, and
+   note that a bare `console.error` is invisible to some server-side error
+   reporters.
+5. **`publicPathPrefix` must be the mount plus `STORAGE_PATHS.serve`.** The local
+   driver builds display URLs from it, and the serve route answers them. Compose
+   it rather than retyping the path, or a deployment writes objects at one path
+   and serves them from another.
+6. **Static imports only.** This package publishes TypeScript source. A dynamic
+   non-literal `import()` of a subpath crashes a bundled server.
+7. **Do not add a presigned-URL path in the host either.** The endpoint is
+   deliberately the only way bytes arrive from a browser; the reasons are in the
+   README and they apply to a host that reintroduces the hop by hand.
+
+## Why there is no Prisma partial
+
+The other plugins in this series own tables. This one owns none, and that is a
+finding rather than an omission: everything storage persists is an object in a
+bucket or on a disk. The columns that hold a key — `menu_items.image_key`,
+`client_branding.logo_key` — are columns on **host** models, and a package that
+declared them would be declaring the host's catalog.
+
+The consequence is rule 3: the "is this object still needed?" question cannot be
+answered inside the package, so it arrives as predicates over the host's own
+tables. There is nothing to sync, no migration to replay, and no
+`prisma:sync-*:check` for this package.
+
+## A worked mount (Hono + local disk + sharp)
+
+This is a **fresh host**: no rows predate the scope segment, so `unscopedKeys` is
+`'reject'`. See the note after it if that is not you.
+
+Read the `root` line before you copy it. There is **no `??`** on it deliberately:
+`process.env.UPLOADS_DIR ?? \`${process.cwd()}/.uploads\`` in this position is
+precisely the fail-open default the table above refuses to have, and it is the one
+mistake this document used to hand you ready-made.
+
+```ts
+import sharp from 'sharp';
+import { DEFAULT_MAX_UPLOAD_BYTES, STORAGE_PATHS } from '@12-apps/storage';
+import { createLocalDiskDriver, createSharpImagePipeline } from '@12-apps/storage/server';
+import { storageRouter } from '@12-apps/storage/hono';
+
+/**
+ * Fail at BOOT for a missing value, not at the next deploy.
+ *
+ * `UPLOADS_DIR` must be a MOUNTED VOLUME. A container path "works" in every test
+ * you will run and loses every object the first time the app is redeployed.
+ */
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is required (a mounted volume, not a container path)`);
+  return value;
+}
+
+const storage = storageRouter({
+  driver: createLocalDiskDriver({
+    root: requireEnv('UPLOADS_DIR'),
+    publicPathPrefix: `/api${STORAGE_PATHS.serve}`,
+  }),
+  maxBytes: DEFAULT_MAX_UPLOAD_BYTES,
+  imagePipeline: createSharpImagePipeline({ sharp }),
+  // A fresh host: every key it will ever mint is scoped, so a key WITHOUT a scope
+  // can only be someone else's or nobody's. See rule 2 before changing this.
+  unscopedKeys: 'reject',
+  // Your tables. `[]` only if you have checked that nothing here copies a key.
+  references: [
+    { name: 'live-rows', referenced: liveRowHoldsKey },
+    { name: 'pending-state', referenced: pendingStateHoldsKey },
+  ],
+  logger: createFeatureLogger('uploads'),
+  resolveActor: async (c) => {
+    const actor = await resolveEffectiveActor(c.req.raw);
+    if (!actor.tenantId) return null;
+    return { scope: actor.tenantId, mayUpload: await mayUpload(actor) };
+  },
+});
+
+app.route('/api', storage.router);
+```
+
+**If your host already has image keys**, they were minted before the scope segment
+existed, so they carry no tenant and `'reject'` would refuse to touch every one of
+them. Pass `unscopedKeys: 'accept'` instead — and understand what you are taking
+on: for those legacy keys the tenant boundary on reclaim is your `references`
+probes ALONE, because there is no scope in the key for the structural guard to
+check. That makes rule 3 sharper for you than for a greenfield host, not looser.
+
+**In development**, and only there, the `??` is fine — a lost object on a laptop
+costs nothing:
+
+```ts
+// DEV ONLY. Never in the mount above.
+root: process.env.UPLOADS_DIR ?? `${process.cwd()}/.uploads`,
+```
+
+Switching to a bucket is a driver swap and nothing else:
+
+```ts
+import { createS3Driver } from '@12-apps/storage/s3';
+
+driver: createS3Driver({
+  bucket: process.env.S3_BUCKET ?? '',
+  region: process.env.S3_REGION,
+  endpoint: process.env.S3_ENDPOINT,          // Spaces, MinIO, R2…
+  forcePathStyle: process.env.S3_FORCE_PATH_STYLE === '1',
+  publicBaseUrl: process.env.STORAGE_PUBLIC_BASE_URL,   // a CDN in front
+}),
+```
+
+## Feeding a tool schema without drifting
+
+A host that lets an agent send bytes inside a write needs the same ceiling in
+its tool schema. Read **both** fields off the mount, not off a constant:
+
+```ts
+const body = z.object({
+  imageKey: storage.schemas.objectKey.nullish(),   // grammar === this mount's keyPrefix
+  image: storage.schemas.inlineImage.optional(),   // ceiling  === this mount's maxBytes
+}).superRefine(refineImageInput);
+```
+
+`refineImageInput` refuses a body stating BOTH an existing key and new bytes.
+They mean opposite things — "keep pointing at this object" versus "store these
+bytes and point at the result" — so silently preferring one discards an upload
+the caller cannot see was discarded.
+
+### `imageKey` is not a string field, and this recipe used to say it was
+
+It said `imageKey: z.string().nullish()`, which accepts **any** string. Combine
+that with `objectUrl`, which deliberately returns an already-absolute value
+unchanged (a documented affordance for a host migrating off a URL column), and an
+adopter following this page ends up accepting an arbitrary URL on a write and
+rendering it into an `<img src>`:
+
+```ts
+updateProduct({ imageKey: 'https://tracker.example/p.png' })
+```
+
+Any actor who may edit a product can then make every buyer loading that
+storefront page send 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.
+`storage.schemas.objectKey` is that refusal, and it is built from the mount's own
+`keyPrefix` so it cannot drift from what the mount actually mints.
+
+Two things it does not do, and you may want both:
+
+- **It does not check the tenant.** `products/<otherTenant>/<uuid>/full.webp` is a
+  well-formed key, so it parses. The reclaim refuses to delete it (`keyInScope`),
+  but it is still a key you never minted sitting in your own catalog, and it makes
+  one store display another's photo. Pair the schema with
+  `keyInScope(key, scope, unscopedKeys)` in the handler, which the schema cannot do
+  because it does not know who is calling.
+- **It does not verify the object EXISTS.** A well-formed key for an object that was
+  never stored passes; the `<img>` 404s. That is a cheap `driver` read if you care.
+
+For the record, a `javascript:`-shaped value is already inert without the schema —
+`objectUrl` only passes through `^https?://`, so it is handed to the driver and
+comes back as a path under your mount rather than as an executable href. Inert is
+not the same as valid; the schema refuses it too.
+
+## What the host keeps
+
+Config, and nothing else: who is calling, which tenant they act for, where bytes
+live, which of its tables can pin an object, the ceiling, and the choice of
+pipeline. Everything else — the endpoint, the cap, the byte check, the key
+grammar, the crop set, the URLs, the reclaim, the picker, the browser-side
+re-encode and every pt-BR sentence — is the package's.
+
+## Not in scope for this package
+
+- **Publishing setup.** A brand-new package's first npm publish and its trusted
+  publisher are a manual step for a maintainer.
+- **`base-app` adoption.** Mounting this behind an OFF-by-default feature flag in
+  `12-apps/base-app` is tracked with the ticket; that repository is not part of
+  this change.

package/README.md

@@ -0,0 +1,229 @@
+# @12-apps/storage
+
+Image uploads that land at **your own origin**, never at the bucket.
+
+One backend factory, one frontend factory, a driver port with two
+implementations, and an image-pipeline port so a native dependency stays the
+host's choice.
+
+> **Adopting this?** This README is the API reference; **[`ADOPTING.md`](./ADOPTING.md)**
+> is the step-by-step wiring, including the five required config values and why
+> each of them has no default.
+
+## The rule the whole package is built around
+
+**The browser POSTs its bytes to the app server. There is no presigned-URL
+mode, and there must never be one.**
+
+A presigned bucket URL makes a working upload depend on the bucket's **CORS
+rules** — configuration that lives in neither this repository nor any deploy it
+runs. A `PUT` carrying a `Content-Type` is never a "simple" request, so the
+browser sends an `OPTIONS` preflight first; a freshly created bucket answers it
+with `403` and no `Access-Control-Allow-*` headers, and the upload is never
+sent. What makes that failure mode particularly bad:
+
+- **The server sees nothing.** No request ever arrives — no log line, no error
+  rate, no 5xx.
+- **The browser will not say why.** A blocked cross-origin fetch is deliberately
+  indistinguishable from an offline network at the `fetch` layer.
+- **The person who sees it cannot fix it.** The message reaches a store owner,
+  about a bucket only an operator can configure.
+
+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.
+
+## Subpath exports
+
+| Import | Contents |
+| --- | --- |
+| `@12-apps/storage` | Isomorphic core: format allowlist, upload ceiling, object-key grammar, rendition set, refusal taxonomy, URL builders, wire schemas. |
+| `@12-apps/storage/server` | `createApiStorage(config)`, the driver port, the local-disk driver, the image-pipeline port with both implementations, the reclaim. |
+| `@12-apps/storage/hono` | `storageRouter({ …config, resolveActor })` — a one-call mount. `hono` is an OPTIONAL peer. |
+| `@12-apps/storage/s3` | `createS3Driver(config)` for every S3-compatible vendor. `@aws-sdk/client-s3` is an OPTIONAL peer, resolved only here. |
+| `@12-apps/storage/react` | `createWebStorage({ apiBase })` — the bound picker, the preview, the upload hook, the browser-side re-encode. |
+
+The exports map points at `./src` directly — no build step is required at
+runtime.
+
+## The two endpoints
+
+```
+POST <mount>/uploads/image      raw bytes in, { data: { imageKey } } out
+GET  <mount>/uploads/local/…    the object back, or a redirect to where it lives
+```
+
+The serve route has two behaviours and the **driver** decides which: a driver
+that keeps its own bytes implements `read` and the route streams them; a
+bucket-backed driver does not, and the route redirects to `publicUrl`. That used
+to be an environment flag read inside the route — the same fact in a second
+place, free to disagree with the driver actually in use.
+
+## What a stored photo is
+
+```
+products/<scope>/<uuid>/full.webp        the whole picture — the zoom
+products/<scope>/<uuid>/card-320.webp    4:3, a card on a phone
+products/<scope>/<uuid>/card-640.webp    4:3, a retina card / a phone hero
+products/<scope>/<uuid>/card-1280.webp   4:3, a retina hero on a desktop
+products/<scope>/<uuid>/thumb-128.webp   1:1, a 64px row thumbnail
+products/<scope>/<uuid>/thumb-256.webp   1:1, the same row at 2×
+```
+
+The key saved on the row names the uncropped member, and **the key's shape is
+what says the crops exist**: `…/<uuid>/full.<ext>` has them, the flat
+`…/<uuid>.<ext>` does not. Nothing else records it — no column, and therefore
+nothing to keep in step across the draft, the change request, the recycle-bin
+snapshot and the version history a row is copied into.
+
+`<scope>` is the tenant. It is what makes cross-tenant reclaim a parse rather
+than a query: a reclaim refuses a key whose scope is not the caller's *before*
+consulting any reference probe. A scheme without it can only answer "may this
+tenant delete this object?" by proving no row of **theirs** points at it — which
+is true of every other tenant's objects too.
+
+## The five values with no default
+
+`createApiStorage` requires `driver`, `maxBytes`, `imagePipeline`,
+`unscopedKeys` and `references`. Each safe value is host-specific, so a default
+would be a decision made by whoever typed the first host and silently inherited
+by every one after it — and each of these fails **quietly**, which is the actual
+argument. A loud wrong default gets fixed on the first deploy; these do not:
+
+| Config | What a default would cost |
+| --- | --- |
+| `driver` | A container's ephemeral disk in production, reporting every upload as a success and losing the objects at the next deploy. |
+| `maxBytes` | Whatever number this file happens to carry, in a host whose tool schemas advertise something else. |
+| `imagePipeline` | Whether crops exist at all — discovered from the shape of a key in production. |
+| `unscopedKeys` | Whether one tenant's reclaim can reach another tenant's bytes. |
+| `references` | Whether a restored row still has its photo. `[]` is not neutral: it means *reclaim everything immediately*. |
+
+`logger` still defaults, and it is the one that legitimately can: a reclaim may
+only report, never raise, so the worst a defaulted logger costs is silence.
+`references` defaulted too, until it didn't — because its default **destroys**.
+
+## Backend, in full
+
+**Note the absence of `??`.** Every value below either comes from the
+environment and must be there, or is written out. That is deliberate: a
+`process.env.UPLOADS_DIR ?? \`${process.cwd()}/.uploads\`` in this position is
+exactly the fail-open default the table above refuses to have. `UPLOADS_DIR`
+unset in production means uploads succeed, one container holds the object, the
+other 404s half the `<img>` requests, and the next deploy discards both — with
+nothing in any log, because `writeFile` succeeded every time.
+
+```ts
+import { createApiStorage } from '@12-apps/storage/server';
+import { createLocalDiskDriver, passthroughImagePipeline } from '@12-apps/storage/server';
+import { DEFAULT_MAX_UPLOAD_BYTES, STORAGE_PATHS } from '@12-apps/storage';
+
+/** Fail at BOOT for a missing value, rather than at the next deploy. */
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is required — it must be a MOUNTED VOLUME, not a container path.`);
+  return value;
+}
+
+const storage = createApiStorage({
+  driver: createLocalDiskDriver({
+    root: requireEnv('UPLOADS_DIR'),
+    publicPathPrefix: `/api${STORAGE_PATHS.serve}`,
+  }),
+  maxBytes: DEFAULT_MAX_UPLOAD_BYTES,
+  imagePipeline: passthroughImagePipeline(),
+  // 'reject' because this host is fresh: every key it will ever mint is scoped, so
+  // a key without a scope can only be someone else's or nobody's. A host with rows
+  // that predate the scope segment passes 'accept' — see ADOPTING.md rule 2.
+  unscopedKeys: 'reject',
+  // Which of YOUR tables can still need an object after the row stopped pointing at
+  // it. `[]` says "nothing here copies a key" — write it only if you have checked.
+  references: [
+    { name: 'live-rows', referenced: (scope, key) => rowPointsAt(scope, key) },
+  ],
+});
+```
+
+For **development** the `??` is fine, and only here, because a lost object on a
+laptop costs nothing:
+
+```ts
+// DEV ONLY. Never in the block above.
+root: process.env.UPLOADS_DIR ?? `${process.cwd()}/.uploads`,
+```
+
+`storage` carries everything else a host needs:
+
+| Member | Use |
+| --- | --- |
+| `routes` | Framework-neutral descriptors. `@12-apps/storage/hono` mounts them. |
+| `limits` | What this mount enforces — feed a tool schema from it, never from a constant of your own. |
+| `schemas.inlineImage` | A zod schema whose base64 ceiling **is** `maxBytes`. |
+| `schemas.objectKey` | The schema for an `imageKey` field. **Not `z.string()`** — see below. |
+| `storeImage` / `storeInlineImage` | The write path for a host write that carries bytes (an agent's only option). |
+| `urls.objectUrl` / `urls.imageSources` / `urls.versionedObjectUrl` | Key → URL, through the active driver. |
+| `reclaim.*` | Reclaiming a replaced object, a superseded set, or keys a failed write just minted. |
+
+### An `imageKey` field is not a string field
+
+`objectUrl` returns an already-absolute value **unchanged** — a deliberate
+affordance for a host migrating off a URL column. So a write body that accepts
+`imageKey: z.string()` accepts `https://tracker.example/p.png`, and every buyer
+loading that storefront page then 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. Use the mount's own schema:
+
+```ts
+const body = z.object({
+  imageKey: storage.schemas.objectKey.nullish(),
+  image: storage.schemas.inlineImage.optional(),
+}).superRefine(refineImageInput);
+```
+
+## Frontend, in full
+
+```ts
+import { createWebStorage } from '@12-apps/storage/react';
+
+const storage = createWebStorage({ apiBase: '/api' });
+// storage.page        a standalone upload surface
+// storage.ImageField  the field a form drops in — a key comes out
+// storage.useUpload   the primitive, for a bespoke affordance
+```
+
+## The image pipeline is a port
+
+Image processing means a native module, and a native module is build surface
+every consumer would pay for on every deploy whether or not it wants crops. So
+`sharp` is neither a dependency nor a peer here: a host that has it passes the
+module in.
+
+```ts
+import sharp from 'sharp';
+import { createSharpImagePipeline } from '@12-apps/storage/server';
+
+imagePipeline: createSharpImagePipeline({ sharp });
+```
+
+`passthroughImagePipeline()` is the other choice: the bytes are stored as they
+arrived, no crops, flat keys — which is exactly what every catalog image was
+before crops existed.
+
+**The magic-number check is not the pipeline's job**, and this README used to say
+it was. It belongs to the WRITER: `storeImage` verifies the bytes against the
+declared type as its first statement, before any pipeline sees them. That
+placement is deliberate, because the two implementations cannot both be trusted
+with it — `passthrough` verifies as part of doing nothing, while `sharp` cannot:
+"did libvips decode this" and "is this the format that was declared" are
+different questions, and libvips decodes plenty of formats this allowlist
+excludes. Putting the check in the writer means no path to storage goes around
+it, whichever pipeline a host injected and whether the bytes arrived at the
+endpoint, base64 inside a write, or through a direct `storeImage` call.
+
+## A second vendor is a config entry
+
+`createS3Driver` covers every S3-compatible store. AWS needs a `region`;
+DigitalOcean Spaces, MinIO, R2 and the rest need an `endpoint`, plus
+`forcePathStyle` for the ones that cannot do virtual-hosted addressing. No
+branch in the upload path changes, and no host code is written.
+
+Nothing in this package reads `process.env`.

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@12-apps/storage",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Image uploads that land at YOUR OWN ORIGIN, never at the bucket (12-20). Isomorphic core (format allowlist, upload ceiling, object-key grammar, rendition set, refusal taxonomy, wire schemas), host-mounted backend surface (./server: createApiStorage, the local-disk driver, the image-pipeline port, the orphan reclaim), Hono adapter (./hono), the S3-compatible driver behind its own subpath (./s3) and the bound picker + upload hook (./react). Standardized adoption contract in ADOPTING.md.",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./react": "./src/react/index.ts",
+    "./hono": "./src/hono/index.ts",
+    "./s3": "./src/s3/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules coverage",
+    "test": "node ../../scripts/vitest-with-teardown.mjs run",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.700.0",
+    "hono": ">=4.0.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@12-apps/ui": "^4.0.1",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@12-apps/eslint-config": "^1.20.0",
+    "@12-apps/typescript-config": "^1.20.0",
+    "@aws-sdk/client-s3": "^3.703.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "eslint": "^9.39.1",
+    "eslint-plugin-test-flakiness": "^1.4.0",
+    "hono": "^4.6.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/12-apps/shared-packages.git",
+    "directory": "packages/storage"
+  },
+  "files": [
+    "src",
+    "*.js",
+    "*.mjs",
+    "*.md",
+    "!eslint.config.js",
+    "!**/__tests__/**",
+    "!**/tests/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.stories.*",
+    "!**/*.test-story.*",
+    "!**/test-helpers.*"
+  ]
+}

package/src/content-types.ts

@@ -0,0 +1,47 @@
+/**
+ * The image formats an upload surface accepts, and the extension each is
+ * stored under.
+ *
+ * One map, because three separate places read it and none of them may
+ * disagree: the endpoint validates the declared `Content-Type` against it, the
+ * key is minted with the extension it names, and the serve path answers with
+ * the type that extension maps back to. A format added on one of those three
+ * paths only is a file that uploads and then cannot be read, or reads as the
+ * wrong type.
+ */
+
+/** Image MIME types an upload accepts, mapped to their file extension. */
+export const EXTENSION_BY_CONTENT_TYPE: Readonly<Record<string, string>> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+};
+
+/** Inverse lookup: extension → MIME type (for `Content-Type` response headers). */
+export const CONTENT_TYPE_BY_EXTENSION: Readonly<Record<string, string>> = Object.fromEntries(
+  Object.entries(EXTENSION_BY_CONTENT_TYPE).map(([contentType, extension]) => [
+    extension,
+    contentType,
+  ]),
+);
+
+/** The accepted types, as a list — the browser half's `accept` attribute. */
+export const ACCEPTED_CONTENT_TYPES: readonly string[] = Object.keys(EXTENSION_BY_CONTENT_TYPE);
+
+/** Is `contentType` one of the formats this surface stores? */
+export function isAcceptedContentType(contentType: string): boolean {
+  return contentType in EXTENSION_BY_CONTENT_TYPE;
+}
+
+/**
+ * `image/png; charset=…` → `image/png`, lowercased; `undefined` for anything
+ * outside the allowlist.
+ *
+ * Parsing and allowlisting in one step on purpose: a caller that got the type
+ * back but had to check it itself is a caller that can forget to.
+ */
+export function acceptedContentTypeOf(header: string | null | undefined): string | undefined {
+  const raw = header?.split(';')[0]?.trim().toLowerCase();
+  return raw && isAcceptedContentType(raw) ? raw : undefined;
+}