@ultimat3/storage 1.1.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,169 @@
+# @ultimat3/storage — agent notes
+
+Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
+
+- May import: `@ultimat3/core`, `@ultimat3/schema`. Nothing else. No npm dependencies.
+- Must NOT know about HTTP, entities, actions, render — a route calls `acceptSignedUpload()`,
+  this package never owns one. Consumers: `http`, `seo`, `admin`, `cli`.
+- **The line is a `Request`/`Response`/status, not a URL string.** `accept.ts` takes a url, bytes
+  and a content-type string and answers with a `StorageObject` or throws; the caller turns that
+  into a response, because `@ultimat3/http`'s `error-map.ts` is the only place a code becomes a
+  status. A handler here would be a second status table.
+- **Tier 1 is why there is no `uploadAction()`.** `action` is tier 3, so this package cannot
+  return one — `llm()` works only because `@ultimat3/ai` sits *above* `action`. The shape that
+  fits the table is `@ultimat3/auth`'s: ship the server function (`grantUpload`), let the app
+  wrap it in its own `action()` with its own policy. See `docs/architecture/17-uploads.md`.
+
+| Rule | |
+|---|---|
+| Errors | `StorageError` + one factory per code in `errors.ts`; never `throw new Error` |
+| New code | add to `STORAGE_ERROR_CODES` **and** `STORAGE_ERROR_TITLES` |
+| Keys | every driver method starts with `assertSafeKey()`. No exceptions, no sanitising. `META_DIR` (`.meta`) is a reserved first segment on every driver — see below |
+| Time | take a `Clock`; never `Date.now()` |
+| Bytes | `Uint8Array \| ReadableStream \| Blob`. Never a base64 string, never unbounded — `toBytes(body, limit)` |
+| Exports | explicit in `src/index.ts`; no `export *` |
+
+| File | Owns |
+|---|---|
+| `driver.ts` | `StorageDriver` contract (8 methods) + bounded `toBytes`/`sha256Base64`/`etagOf` |
+| `driver-local.ts` | dev default over `Bun.file`, `.meta/` sidecars, `Bun.Glob` listing |
+| `driver-s3.ts` | `Bun.S3Client`, built lazily (import must never open a socket) |
+| `path.ts` | key validation + `META_DIR` + `scopedKey`/`isWithinOrg`/`isTenantScoped` tenant boundary |
+| `signed-url.ts` | HMAC over the constraint tuple, constant-time verify |
+| `upload.ts` | magic-byte sniff + size/allowlist/checksum policy |
+| `image.ts` | deterministic variant keys; byte path over core's pipeline (png/jpeg encode only) |
+| | `variantKey` is the cache identity `@ultimat3/cli`'s `/media/*` route looks a variant up by — derived, never stored, so a request that misses transforms once and every later one is a disk read |
+| `storage.ts` | `defineStorage` + module-level `storage()` / `disk()` |
+| `grant.ts` | `grantUpload` — the ONE way a presigned PUT is minted; the client never names a key |
+| `accept.ts` | `acceptSignedUpload` / `readSignedObject` — the two decisions a `/_storage` route is made of |
+| `attachment.ts` | `pending/` → row promotion, the `quarantine/` segment, and `sweepOrphans` |
+| `upload-client.ts` | the browser half: grant → PUT with progress → key. No `Bun.*`, no `node:` |
+
+```bash
+bun test                      # from packages/storage
+bun run typecheck
+```
+
+Gotchas:
+- **A driver's semantics are pinned in ONE test with the other driver beside them.**
+  `driver-parity.test.ts` drives `localDriver` over a temp dir and `s3Driver` over `FakeS3Client`
+  in a single `test()` per claim, so neither disk can move alone. Where the two genuinely cannot
+  agree it pins the DIVERGENCE, with the reason — that is the honest form, and it still fails the
+  day either half changes.
+- **`list()` is idempotent for an EMPTY disk and for nothing else** (`As of 2026-08`) — exactly
+  `delete()`'s rule, one call to the left, and both drivers broke it in opposite directions. The
+  local one caught EVERYTHING and answered `{ objects: [], truncated: false }`, so `EACCES` on the
+  root read as "this disk is empty"; the s3 one let a bare `S3Error` escape uncoded, with nothing
+  for the http error map to render but a 500. `sweepOrphans` walks `list()`, so the local swallow
+  was a false-erasure report a layer up. `ENOENT` (a root nobody has written to) is still an empty
+  page; everything else is `X_STORAGE_LIST_FAILED`, whose `fix` the DRIVER supplies.
+- **`head()` NEVER reads an object's bytes, and `list()` is why** (`As of 2026-08`). It hashed a
+  sidecar-less object to invent an etag, under a comment saying "`list()` must not read every file
+  it lists" — which is what `list()` then did, one whole buffered object per listed row,
+  sequentially, and `copy()` inherited it, so a copy documented as never routing bytes through the
+  heap buffered the entire source. A listing that cannot know an etag reports `''`, which is what
+  the s3 listing already answers. `get()` hashes out of bytes it already holds; `copy()` passes
+  `hash: true`, because the sidecar it writes at the destination would otherwise carry `etag: ''`
+  as a durable lie.
+- **`put({ metadata })` / `put({ cacheControl })` is the one `PutOptions` pair the disks disagree
+  about, and it is pinned rather than resolved.** Bun's `S3File.write` exposes `type`, `acl` and
+  `storageClass` and no header hook for `x-amz-meta-*` or `Cache-Control`, so `s3Driver` refuses
+  (`X_NOT_IMPLEMENTED`, with the out-of-band `aws s3 cp` in the fix) while `localDriver` stores both
+  in its sidecar and reads them back. **Do not "fix" this by making the local disk refuse too** —
+  that deletes a working capability and the two `StorageListEntry` fields that carry it, to buy
+  symmetry with a limitation that is Bun's and temporary. The day the hook lands, the s3 half of
+  `driver-parity.test.ts` fails and the resolution is to make s3 store them.
+- **`signedUrl({ maxBytes })` is signed on `local` and unenforceable on `s3`, and the s3 driver may
+  NOT refuse it.** `grantUpload` passes `maxBytes: policy.maxBytes` on every grant, so a refusal
+  would break every s3 upload an app mints. S3 has no request header for a size and Bun's `presign`
+  covers method, expiry and type — so on the production disk the client PUTs straight into the
+  bucket and nothing between the grant and the object holds the ceiling. That belongs to a bucket
+  rule or a post-upload `object.size` check, neither of which is a driver's; `SignedUrlOptions`
+  says so and `driver-parity.test.ts` pins both halves.
+- **`delete()` is idempotent for an ABSENT key and for nothing else.** Both drivers used to end in
+  `.catch(() => undefined)`, so a denied `s3:DeleteObject`, a `SlowDown`, an expired credential and
+  a read-only mount all resolved as success — and `sweepOrphans` returned them as deleted, which
+  is a GDPR erasure report certifying data that is still in the bucket. The s3 driver classifies
+  structurally (`code` in `NoSuchKey`/`NotFound`/`ENOENT`, or a 404 `statusCode`/`status`; an
+  `S3Error` is a plain `Error` with those fields and every read of one can throw), the local
+  driver on `ENOENT`. Everything else is `X_STORAGE_DELETE_FAILED`, whose `fix` the DRIVER
+  supplies — the command that reproduces the refusal differs per disk.
+- **`toBytes` takes a `ByteLimit`, and there is no unbounded variant.** `put()` buffers, so the
+  ceiling is what keeps a route piping a 4GB body into `disk.put()` from being an OOM kill rather
+  than a refusal. `Uint8Array`/`Blob` are refused on their declared length; a `ReadableStream` is
+  read chunk-by-chunk and **cancelled** past the line, so at most one chunk over is ever held.
+  Default `maxPutBytes` is `DEFAULT_MAX_UPLOAD_BYTES` — one constant, imported by both drivers
+  from `upload.ts`, because the server-side ceiling and the upload ceiling are the same fact.
+- **`serverSideEncryption` is declared and refused by BOTH drivers.** Bun exposes `acl`,
+  `storageClass` and `type` and nothing for `x-amz-server-side-encryption*`, and a POSIX file is
+  not encrypted at all. Refusing on the dev disk too is deliberate: a `put()` that works in `x dev`
+  and throws in production is two rules. Lifecycle, storage classes and replication stay out
+  entirely — bucket-side, terraform's, axiom 7.
+- **Quarantine is `pending/quarantine/`, INSIDE the pending prefix.** So `sweepOrphans` collects a
+  never-scanned upload with no second prefix to walk, and `isPendingKey` stays true for it.
+  `promoteAttachment` refuses a quarantined key (`X_STORAGE_QUARANTINED`); `releaseQuarantine` is
+  the app's scan verdict, and returns the ordinary pending key promotion accepts. Ultimate ships
+  no scanner — axiom 8, and `application/zip` is an accepted OOXML container by design.
+- **`StorageListEntry` vs `StorageObject`.** A listing's `contentType` is optional; a `get()`'s is
+  not. `ListObjectsV2` returns no Content-Type, and the s3 driver used to invent
+  `application/octet-stream` while the local driver read the truth from its sidecar — two drivers
+  disagreeing about one object. The local `list()` now omits it too when there is no sidecar.
+- **`META_DIR` lives in `path.ts`, not in `driver-local.ts`.** The sidecar namespace overlapped the
+  object namespace: `put('a/b', png)` writes `<root>/.meta/a/b.json`, and `.meta/a/b.json` was
+  itself a legal key, so an uploader could rewrite another object's recorded `contentType` to
+  `text/html` and have a route serve attacker HTML from the app's origin. Reserved in
+  `assertSafeKey`, so it holds for S3 too — a key valid on one driver and refused on another is two
+  key rules. The `list()` skip stays as a second line of defence.
+- **`localDriver` refuses to construct outside development without a usable signing secret**
+  (`X_ENV_MISSING`, borrowed from core). Usable means neither the `signingSecret` option nor
+  `STORAGE_SIGNING_SECRET` is missing, empty **or** the published `DEV_SIGNING_SECRET` — pasting
+  the literal into `app.config.ts` configures nothing, so it is refused exactly as its absence is.
+  `DEV_SIGNING_SECRET` is published in this repo, and `acceptSignedUpload` trusts a signed URL's
+  constraints over the app's `uploadPolicy` — so the fallback is a universal grant to mint any
+  `PUT`. Refused at construction, not at the first `signedUrl()`: a process that cannot sign safely
+  must not finish booting. The cause names the environment `resolveEnvironment()` resolved, which
+  may be `NODE_ENV`'s, never a variable the process did not set. `usesDevStorageSecret()` is the
+  `x doctor` predicate, mirroring core's `usesDevCursorSecret()`; it reads the env var, so a disk
+  handed an explicit `signingSecret` is outside its question.
+- **The mounted read half is `@ultimat3/cli`'s `dev-storage.ts`, not this package.** `GET
+  /_storage/:disk/*key` gates on `@ultimat3/policy`'s `evaluate()` (`storage:read`), which is tier
+  2 and unreachable from here — so a "serve this object" helper in this package could only ever be
+  a second authz path. This package's contribution to that route is `assertSafeKey`,
+  `isTenantScoped`/`isWithinOrg` and the driver's own `contentType`/`etag`; the `Response` is the
+  host's, exactly as `accept.ts`'s header says.
+- `acceptSignedUpload` still has no mounted route: the signing secret is closed over inside
+  `localDriver` and no `StorageDriver` method exposes it, so a host cannot verify a signed PUT
+  through the `Storage` seam it is handed. Serving reads needed none of it (policy decides, not a
+  signature); mounting the write half needs that seam question answered first.
+- `X_NOT_IMPLEMENTED` is core's — it belongs in `STORAGE_BORROWED_ERROR_CODES` (codes, no title)
+  and never in the registration call. A `hasErrorCode()` guard there would suppress the
+  `X_ERROR_CODE_DUPLICATE` two owners of one code are supposed to get. Tests need `resetStorage()`
+  in `beforeEach`.
+- `image.ts` owns no pixels: core's `transformImageBytes`/`blurDataUrl` are the only scaler.
+  Its image failures (`X_IMAGE_UNSUPPORTED`, `X_IMAGE_DECODE_FAILED`) surface unwrapped —
+  wrapping them in a `StorageError` would give one failure two codes.
+- `transformImage()` must encode at exactly `fitDimensions()`'s size, and passes `format`
+  explicitly (`?? 'webp'`, which then rejects): bytes that disagree with the `variantKey`
+  extension, or with the `width`/`height` `@ultimat3/seo` inlined, are the layout shift the
+  whole path exists to prevent. That is why it derives the box itself and asks core for
+  `fit: 'cover'` — core's `contain` letterboxes to the requested box, this API fits inside it.
+- Bun's S3 flag is `virtualHostedStyle`; our `forcePathStyle` is its inverse.
+- The signature check runs BEFORE the expiry check. Do not reorder.
+- `timingSafeEqual` is `@ultimat3/core`'s (`signed-url.ts` imports and re-exports it) — the same
+  implementation `@ultimat3/auth` uses, not a second copy. Add new secret comparisons through it.
+- `verifySignedUrl` never throws, and `parseConstraints` is where that is kept: the key is decoded
+  through the guarded `decodeSegment`, so a `%ZZ` in the path is `'malformed'` rather than the bare
+  `URIError` `decodeURIComponent` raises. Same shape as `@ultimat3/auth`'s `decodeCookieValue`.
+- `acceptSignedUpload` refuses a URL signed with **no** content type (`unconstrained`). `grantUpload`
+  always sets one, so such a URL is hand-rolled, and trusting the uploader's header instead is the
+  only other option.
+- `orgId` is required on both halves of `accept.ts` and is the ACTOR's, never a request field. A
+  signed URL is a capability; a leaked capability must still not cross a tenant.
+- `X_STORAGE_ORG_MISMATCH` maps to **404**, not 403 (`@ultimat3/http`'s `error-map.ts`). 403 would
+  confirm a key exists to the one caller who must not learn it.
+- The local driver reports the **filesystem's** `lastModified`, not the injected `Clock`, so
+  `sweepOrphans` cannot be tested against it with a frozen clock — `attachment.test.ts` uses a
+  stub driver with authored timestamps, and `driver-local.test.ts` proves the disk half.
+- `upload-client.ts` defaults to `XMLHttpRequest`, not `fetch`: `fetch` reports no upload
+  progress in any shipping browser, and a bar that jumps 0 → 100 is a bar that is lying.
+- `exactOptionalPropertyTypes` is on — declare optional fields as `x?: T | undefined`.

package/README.md

@@ -25,30 +25,93 @@ Swapping `local` for `s3` in `app.config.ts` changes no call site. `x dev` needs
 | `localDriver` | `Bun.file`/`Bun.write`, one root dir | dev, tests, single-node | HMAC + dev route |
 | `s3Driver` | `Bun.s3` | prod: MinIO, R2, AWS | provider presign |
 
+`copy(from, to)` is on the contract so a promotion is not a download-and-reupload:
+`promoteAttachment` used to `get()` the whole object into the app and `put()` it back, a gigabyte
+through the pod to rename a 500MB attachment. `localDriver` does a real file copy; `s3Driver`
+hands the source `S3File` to `write()` — Bun exposes no `CopyObject`, so the bytes still cross the
+network, but never this process's heap. Both arguments go through `assertSafeKey`.
+
 One S3 driver covers all three backends — the difference is `endpoint` + `forcePathStyle`.
 Credentials are **env var NAMES** (`accessKeyIdEnv`, default `S3_ACCESS_KEY_ID`), never
 literals: a key in `app.config.ts` is a key in git. Missing ones throw `X_ENV_MISSING`.
-`localDriver` keeps content type and etag in a `<root>/.meta/` sidecar so `get()` round-trips
-`put()`; sidecars never appear in `list()`.
+`localDriver` keeps content type, etag, `cacheControl` and `metadata` in a `<root>/.meta/`
+sidecar so `get()`/`list()` round-trip everything `put()` was handed; sidecars never appear in
+`list()`. `s3Driver` cannot: it refuses `cacheControl`/`metadata` on `put()` (`X_NOT_IMPLEMENTED`,
+Bun exposes no header hook yet).
+
+**`StorageListEntry.contentType` is optional; `StorageObject.contentType` is not.** S3's
+`ListObjectsV2` returns no Content-Type, so a listed s3 object simply has none — reading the real
+value would cost one `HeadObject` per row, which is what `list()` exists to avoid. It used to
+report `application/octet-stream`, indistinguishable from an object that really is one, while the
+local driver read the truth out of its sidecar: a caller filtering a listing by content type got
+everything on `local` and nothing on `s3`. `get()` always answers a full `StorageObject`.
+
+The etag follows the same rule: a listed object with no sidecar reports `etag: ''`, because
+answering otherwise means reading and hashing the whole object — which is what the local `list()`
+used to do, once per sidecar-less row, sequentially. `get()` hashes out of bytes it already holds.
+
+## `put()` is for objects that fit in memory
+
+`put()` buffers the whole body — size and checksum have to be known before the object exists —
+so every disk enforces a ceiling, `maxPutBytes`, defaulting to `DEFAULT_MAX_UPLOAD_BYTES` (10MB).
+Past it is `X_STORAGE_TOO_LARGE`, raised **before** the bytes are resident: a `Uint8Array` and a
+`Blob` already know their length, and a `ReadableStream` is cancelled the moment the running total
+crosses the line. Without it a route piping a 4GB request body into `disk.put(key, req.body)` grew
+the heap by 4GB and the kubelet killed the pod.
+
+**User uploads never go through `put()`.** They go direct to the disk through `grantUpload`, which
+is the architecture and not an optimisation — see the round trip below. Raise `maxPutBytes` only
+for a disk that really does write large objects server-side, and remember S3 caps a single PUT at
+5GB whatever you set.
+
+## Server-side encryption, storage classes, lifecycle
+
+`PutOptions.serverSideEncryption` exists so the gap is visible **at the type level**, and every
+shipped driver refuses it (`X_NOT_IMPLEMENTED`) with the out-of-band command in the `fix`.
+`Bun.S3Client` exposes `acl`, `storageClass` and `type` and nothing for
+`x-amz-server-side-encryption*`; a local disk writes plain files. A typed refusal an engineer
+meets at the call site beats a silent absence discovered during a security review.
+
+Encryption at rest is therefore a **bucket default**, and so are lifecycle rules, storage classes
+and cross-region replication: all four are bucket-side configuration and belong to terraform, not
+to the framework (axiom 7 — zero platform primitives). Ultimate half-building any of them would
+be a second place to look for the same setting.
 
 ## Keys
 
 `assertSafeKey()` runs on every key before it reaches a driver. Rejected: `..` segments,
 absolute keys, backslashes, NUL/control bytes, percent-encoded separators (`%2e`, `%2f`),
-empty segments, over 1024 chars. No sanitising — a key that needed fixing was built wrong.
+empty segments, over 1024 chars, and a first segment of `.meta` (`META_DIR`) — the local driver's
+sidecar namespace, reserved on **every** driver so one key rule covers disk and S3 alike. Without
+it, `put('.meta/a/b.json', …)` overwrote the recorded content type of `a/b` and a route serving
+that object answered attacker HTML from the app's own origin. No sanitising — a key that needed
+fixing was built wrong.
 `scopedKey('org-1', 'avatars', 'a.png')` is `org/org-1/avatars/a.png`; guard every
-client-supplied key with `isWithinOrg(key, ctx.actor.orgId)`.
+client-supplied key with `isWithinOrg(key, ctx.actor.orgId)`. A surface that serves objects pairs
+it with `isTenantScoped(key)`: only a key already inside `org/` is another tenant's to refuse, so
+`disk().put('brand/logo.png', …)` stays reachable while `org/org-2/…` never is.
 
 ## Signed URLs
 
 The HMAC covers the **constraints**, not just the key —
 `v1 \n METHOD \n key \n expiresAt \n maxBytes \n contentType`.
 A client that edits `?x-max=` invalidates the signature — it cannot widen what it was granted.
+
+The HMAC key is `signingSecret`, else `STORAGE_SIGNING_SECRET`, else the shipped
+`DEV_SIGNING_SECRET` — and **only in `development` or `test`**. Anywhere else `localDriver` refuses
+to construct (`X_ENV_MISSING`) unless one of those two is set to something that is not the shipped
+literal: the dev literal is published in this repo, so signing with it lets anyone mint a `PUT` for
+any key with a `maxBytes` and `contentType` of their choosing, which `acceptSignedUpload` then
+trusts over the app's own `uploadPolicy`. Setting `STORAGE_SIGNING_SECRET=$DEV_SIGNING_SECRET`, or
+pasting the literal into `signingSecret`, is refused exactly as an unset variable is. `usesDevStorageSecret()` is the
+`x doctor` probe for it, the twin of core's `usesDevCursorSecret()`.
 Verification is constant-time, checks the signature *before* the expiry (a forged URL never
 learns it was merely late), takes a `Clock` so tests freeze time, and returns
 `{ ok: false, reason }` rather than throwing — `malformed | unsafe-key | signature-mismatch |
 expired`. S3 presign covers method, expiry and content type but **not** `maxBytes`: S3 has no
-header for it, so size stays a server-side `validateUpload()` check.
+header for it, so a bucket-backed disk's ceiling is a bucket rule or a post-upload `object.size`
+check, never the signature. `s3Driver` does not refuse `maxBytes` either — `grantUpload` supplies
+it on every grant, so refusing would break every s3 upload an app mints.
 
 ## Uploads sniff the content type
 
@@ -60,6 +123,84 @@ allowlist → sniff → checksum.
 
 `validateUpload({ key, declaredContentType, bytes }, uploadPolicy({ maxBytes: 5e6 }))`
 
+## The direct-upload round trip
+
+Three calls, one per hop. The **client never names the key** — it asks for a grant and is told
+one — so it cannot aim an upload at another tenant, at a row it does not own, or at a size the
+policy never allowed.
+
+```ts
+// 1. server, inside an action's handle: mint the grant
+const grant = await grantUpload({
+  disk: disk('uploads'),
+  orgId: ctx.actor.orgId,            // the ACTOR's org, never one read off the request
+  request: { filename, contentType, size },
+  policy: uploadPolicy({ maxBytes: 5e6 }),
+  // target: { entity: 'post', id, field: 'cover' } — omit it and the key lands under `pending/`
+});
+
+// 2. browser: PUT at it, with real progress, and get the key back
+const { key } = await uploadFile({ file, grant: (request) => api.requestUpload(request), onProgress });
+
+// 3. server, in the route mounted at `/_storage`: take it back, or refuse
+const object = await acceptSignedUpload({
+  url: request.url, secret, baseUrl: '/_storage/local',
+  disk: disk('uploads'), orgId: ctx.actor.orgId,
+  bytes, declaredContentType: request.headers.get('content-type') ?? undefined,
+  policy: uploadPolicy({ maxBytes: 5e6 }),
+});
+```
+
+`acceptSignedUpload` refuses on any of: a signature that does not verify, an expired grant, a
+`PUT` grant replayed as a `GET`, a key outside the actor's org, more bytes than the signature
+granted, a `Content-Type` the signature does not cover, or magic bytes that contradict it.
+`readSignedObject` is the GET half and applies the same verification and the same org check.
+Neither owns a `Request`, a `Response` or a status number — mounting is the host's job, and
+`@ultimat3/http` is the only layer that turns an `X_*` code into a status.
+
+## Attachments and orphans
+
+An upload happens **before** the row it belongs to exists, so it lands at
+`org/<orgId>/pending/<uploadId><ext>` and is promoted once there is an id:
+
+| Call | Key |
+|---|---|
+| `pendingKey(orgId, uploadName(id, filename))` | `org/o1/pending/u-1.png` |
+| `quarantineKey(orgId, name)` | `org/o1/pending/quarantine/u-1.png` |
+| `attachmentKey(orgId, { entity, id, field }, name)` | `org/o1/post/p-1/cover/u-1.png` |
+| `promoteAttachment({ disk, key, orgId, target })` | `copy` then `delete` — never the reverse |
+| `releaseQuarantine({ disk, key, orgId })` | quarantine → pending; returns the released key |
+| `sweepOrphans({ disk, orgId, olderThanMs })` | `{ deleted, failed }` for stale `pending/` keys |
+
+The filename contributes nothing but its extension, and only if it matches `.[a-z0-9]{1,12}`.
+`sweepOrphans` can only reach the `pending/` prefix of one org — a sweep that could touch an
+attached key is a job that deletes production data the first time an app forgets to promote.
+
+**Two lists, because one cannot be wrong.** `sweepOrphans` answers `{ deleted, failed }`: a
+refused delete goes in `failed` with the disk's own words and the sweep keeps going. A single
+array of "deleted" keys put every refusal in it, so an erasure sweep over a bucket whose policy
+had lost `s3:DeleteObject` reported 200 objects gone that were all still there.
+
+### Quarantine is the mechanism; the scanner is your app's
+
+Magic-byte sniffing closes stored XSS. It is **not** malware scanning, and `application/zip` is
+accepted on purpose as the OOXML container, so a macro-laden `.docx` passes `validateUpload`
+exactly as a clean one does. A scanner is a business decision with a vendor, a licence and a
+latency budget (axiom 8), so what ships is the place to put one — one more segment in a
+convention that already existed:
+
+```ts
+const grant = await grantUpload({ disk, orgId, request, quarantine: true });
+// → org/<orgId>/pending/quarantine/<uploadId><ext>
+
+// promoteAttachment on that key throws X_STORAGE_QUARANTINED. Your scan job decides:
+const released = await releaseQuarantine({ disk, key, orgId });   // clean
+await promoteAttachment({ disk, key: released, orgId, target });
+```
+
+Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan, so
+`sweepOrphans` collects it with no second prefix to walk.
+
 ## Errors
 
 | Code | Fires when |
@@ -67,10 +208,18 @@ allowlist → sniff → checksum.
 | `X_STORAGE_DISK_UNKNOWN` | `disk(name)` is not in `storage.disks`; cause lists the real ones |
 | `X_STORAGE_NOT_FOUND` | `get`/`stream` on a key that does not exist |
 | `X_STORAGE_PATH_UNSAFE` | traversal, absolute key, backslash, NUL, `%2e`, empty segment |
-| `X_STORAGE_TOO_LARGE` | payload over the policy `maxBytes` |
+| `X_STORAGE_TOO_LARGE` | payload over the policy `maxBytes`, or over a disk's `maxPutBytes` |
 | `X_STORAGE_TYPE_REJECTED` | declared type off the allowlist, or contradicted by magic bytes |
 | `X_STORAGE_CHECKSUM_MISMATCH` | supplied base64 SHA-256 does not describe the bytes |
-| `X_NOT_IMPLEMENTED` | S3 user metadata |
+| `X_STORAGE_URL_INVALID` | a signed request that does not match what was signed — edited constraint, wrong base, wrong method, contradicting `Content-Type` |
+| `X_STORAGE_URL_EXPIRED` | the grant's window closed; the signature was fine |
+| `X_STORAGE_ORG_MISMATCH` | the key is well-formed and unforged, and belongs to another org |
+| `X_STORAGE_UPLOAD_FAILED` | client half: the presigned `PUT` answered non-2xx or never landed |
+| `X_STORAGE_DELETE_FAILED` | the disk REFUSED a delete — denied `s3:DeleteObject`, a throttle, an expired credential, a read-only mount. An **absent** key is still not an error |
+| `X_STORAGE_LIST_FAILED` | the disk REFUSED a listing — denied `s3:ListBucket`, a throttle, an unreadable root. An **empty** disk is still not an error |
+| `X_STORAGE_QUARANTINED` | `promoteAttachment` on a key nothing has released from `pending/quarantine/` |
+| `X_NOT_IMPLEMENTED` | S3 user metadata / cache-control; `serverSideEncryption` on either driver |
+| `X_ENV_MISSING` | core's: S3 credential env vars, or a `localDriver` built outside development where neither `signingSecret` nor `STORAGE_SIGNING_SECRET` holds a secret other than the published `DEV_SIGNING_SECRET` |
 | `X_IMAGE_UNSUPPORTED` | core's: an `avif`/`webp` encode, or a source no built-in decoder reads |
 | `X_IMAGE_DECODE_FAILED` | core's: truncated or corrupt image bytes |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.1.0"
+    "@ultimat3/core": "2.0.0"
   }
 }

package/src/accept.ts

@@ -0,0 +1,125 @@
+// Single responsibility: the two server-side decisions a mounted `/_storage` route is made of —
+// "may these bytes be written at that key?" and "may this actor read that key?". Transport-free
+// on purpose: this package owns no `Request`, no `Response` and no status number (statuses are
+// `@ultimat3/http`'s alone), so a route is a handler around these two calls and nothing else.
+//
+// Every step fails CLOSED and throws — a forged, expired, oversized, cross-tenant or
+// wrong-typed request never reaches `disk.put`, and no path returns a "warning".
+
+import type { Clock } from '@ultimat3/core';
+import type { SignedUrlMethod, StorageDriver, StorageObject, StorageRead } from './driver';
+import { orgMismatch, signedUrlExpired, signedUrlRejected, tooLarge } from './errors';
+import { isWithinOrg } from './path';
+import type { SignedUrlConstraints } from './signed-url';
+import { verifySignedUrl } from './signed-url';
+import type { UploadPolicy } from './upload';
+import { normalizeContentType, uploadPolicy, validateUpload } from './upload';
+
+export interface SignedRequestInput {
+  /** Absolute or route-relative — `verifySignedUrl` parses both. */
+  readonly url: string;
+  readonly secret: string;
+  readonly baseUrl?: string | undefined;
+  readonly disk: StorageDriver;
+  /**
+   * The ACTOR's org. Required, and checked against the key: a signed URL is a capability, and a
+   * capability that leaks must still not read another tenant's object. Unreachable, not unguessable.
+   */
+  readonly orgId: string;
+  readonly clock?: Clock | undefined;
+}
+
+export interface AcceptSignedUploadInput extends SignedRequestInput {
+  readonly bytes: Uint8Array;
+  /** The transport's `Content-Type`. Refused unless it equals the type the grant signed. */
+  readonly declaredContentType?: string | undefined;
+  readonly policy?: UploadPolicy | undefined;
+}
+
+/**
+ * The signature check runs first and the expiry second — `verifySignedUrl` owns that order, and
+ * the reason it exists is that a forged URL must never learn "the signature was fine, just late".
+ * The org check runs on the verified key, so an attacker cannot probe org names with a fake one.
+ */
+async function constraintsFor(
+  input: SignedRequestInput,
+  method: SignedUrlMethod,
+): Promise<SignedUrlConstraints> {
+  const result = await verifySignedUrl({
+    url: input.url,
+    secret: input.secret,
+    ...(input.baseUrl === undefined ? {} : { baseUrl: input.baseUrl }),
+    ...(input.clock === undefined ? {} : { clock: input.clock }),
+  });
+  if (!result.ok) {
+    throw result.reason === 'expired'
+      ? signedUrlExpired(input.url, result.detail)
+      : signedUrlRejected(result.reason, result.detail);
+  }
+  const constraints = result.constraints;
+  if (constraints.method !== method) {
+    throw signedUrlRejected(
+      'method-mismatch',
+      `the URL is signed for ${constraints.method}, and this is a ${method}`,
+    );
+  }
+  if (!isWithinOrg(constraints.key, input.orgId)) {
+    throw orgMismatch(constraints.key, input.orgId);
+  }
+  return constraints;
+}
+
+/**
+ * Take a presigned PUT and write it, or refuse. Four gates the client cannot move because all
+ * four are inside the signature or inside the bytes: the signature itself, the expiry, the byte
+ * count against the signed ceiling, and the declared type against both the signature and the
+ * magic bytes. `validateUpload` runs last because it is the only one that reads the whole body.
+ */
+export async function acceptSignedUpload(input: AcceptSignedUploadInput): Promise<StorageObject> {
+  const constraints = await constraintsFor(input, 'PUT');
+  const key = constraints.key;
+
+  // A PUT signed with no content type bounds nothing — any bytes, any type, at that key. The
+  // grant always sets one, so this is a hand-rolled URL, and refusing is the only fail-closed
+  // answer: the alternative is trusting whatever header the uploader sends.
+  const signed = constraints.contentType;
+  if (signed === undefined) {
+    throw signedUrlRejected(
+      'unconstrained',
+      `"${key}" was signed with no content type, so nothing bounds what may be stored there`,
+    );
+  }
+  const declaredHeader = input.declaredContentType;
+  const declared = declaredHeader === undefined ? signed : normalizeContentType(declaredHeader);
+  if (declared !== signed) {
+    throw signedUrlRejected(
+      'content-type-mismatch',
+      `the request declares ${declared} and the signature covers ${signed}`,
+    );
+  }
+
+  // The signed ceiling, checked before the policy's: the two can differ once a policy is edited
+  // between the grant and the upload, and the narrower one is the one that was granted.
+  const maxBytes = constraints.maxBytes;
+  const size = input.bytes.byteLength;
+  if (maxBytes !== undefined && size > maxBytes) throw tooLarge(key, size, maxBytes);
+
+  const policy = input.policy ?? uploadPolicy();
+  const validated = validateUpload(
+    { key, declaredContentType: signed, bytes: input.bytes },
+    policy,
+  );
+  return input.disk.put(validated.key, validated.bytes, {
+    contentType: validated.contentType,
+    checksum: validated.checksum,
+  });
+}
+
+/**
+ * The GET half. Same verification, same tenant boundary — a download URL that skipped either
+ * would make every object readable by anyone who ever saw one link.
+ */
+export async function readSignedObject(input: SignedRequestInput): Promise<StorageRead> {
+  const constraints = await constraintsFor(input, 'GET');
+  return input.disk.get(constraints.key);
+}