@usehenri/uploads 0.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# @usehenri/uploads
+
+## 1.2.0
+
+### Minor Changes
+
+- [#372](https://github.com/usehenri/henri/pull/372) [`1a86acb`](https://github.com/usehenri/henri/commit/1a86acbf15e4a43e5fb81277bb22e101c06e77a4) Thanks [@reel](https://github.com/reel)! - File uploads, in a new package: `@usehenri/uploads`.
+  
+  An application installs it and gets `henri.uploads`, `req.files`,
+  `req.file(field)` and `req.permitFiles(...fields)` — `req.permit()` for files,
+  which removes what a controller did not ask for on the spot. `store()` moves a
+  file into the storage and answers the record to write to a model
+  (`{ key, name, type, size, checksum, storage, uploadedAt }`), and
+  `henri.uploads.send(res, record)` streams it back as a download.
+  
+  The parser is busboy, and every bound is enforced as it reads rather than
+  checked afterwards: `maxTotalSize` (25mb, checked against `Content-Length`
+  first and counted again as the bytes arrive), `maxFileSize` (10mb), `maxFiles`
+  (10), `maxFields` (100), `maxFieldNameSize` (100 bytes) and `maxFieldSize`,
+  which defaults to `config.bodyLimit`. The type of a file is decided from its
+  first bytes, never from the `Content-Type` or the extension the client sent,
+  and `uploads.allow` matches that. The stored name is generated, so no name a
+  client sends ever reaches a path. Files land in `storage/uploads` (`0700`,
+  objects `0600`), outside everything the application serves, and nothing is kept
+  unless a controller calls `store()` — a request that is refused, times out or is
+  abandoned leaves no temporary file behind.
+  
+  The local disk is one implementation of a documented `HenriStorage` contract;
+  an object store is another, named by module id in `config.uploads.storage` and
+  resolved from the application. henri ships no S3 client.
+  
+  `@usehenri/core` gains the `uploads` configuration key (validated whether or
+  not the package is installed), the `req.files`/`req.file`/`req.permitFiles`
+  declarations, and `res.boom.payloadTooLarge()` and
+  `res.boom.unsupportedMediaType()`.
+  
+  `henri audit` gains three checks: `uploads.limits-disabled` (V12.1.1),
+  `uploads.type-check-disabled` (V12.2.1) and `uploads.root-served` (V12.4.1).
+
+- [#407](https://github.com/usehenri/henri/pull/407) [`de1c1e0`](https://github.com/usehenri/henri/commit/de1c1e02ed83d13dcfeb8e44012f309eb663f03e) Thanks [@reel](https://github.com/reel)! - Uploads that survive a second machine: an object store, signed urls and variants
+  
+  `@usehenri/uploads` shipped one backend — the local disk — and said `url()`
+  was allowed to answer `null` forever. Two application processes on two
+  machines therefore did not share uploads at all, a link to a stored file
+  meant writing a controller and a route for every one of them, and a
+  thumbnail meant leaving the framework entirely. All three are closed here.
+  
+  **`@usehenri/s3`, a new package.** `config.uploads.storage` takes an object
+  now (`{ "adapter": "s3", "bucket": "…", "region": "…" }`, the shape
+  `config.shared` and a store already have) and `s3` resolves the package from
+  the application. One backend speaks to S3, R2, Spaces, MinIO and GCS's
+  interoperability mode; what tells them apart is an endpoint and a region. It
+  carries no dependency but `debug` — AWS Signature Version 4 is two hundred
+  lines of `node:crypto`, checked against the vectors AWS publishes. Every
+  safety property survives the move: the key is generated and refused if it is
+  not, the type still comes from the bytes and becomes the object's
+  `Content-Type`, the original name is metadata, and a part still lands on a
+  private local file that only `store()` promotes.
+  
+  **Signed urls.** `henri.uploads.url(record, { expiresIn, disposition,
+  filename, type })` is one call whatever the backend: the provider's own
+  signature on an object store, henri's own (an HMAC over the key, the expiry,
+  the disposition, the name and the type, verified by a route it mounts) on
+  the local disk. Neither can be edited to name another object, widened, or
+  replayed past its expiry. Until then a signed url **is** a bearer
+  capability, so `config.uploads.urls` is off by default and `url()` refuses
+  with `HENRI_UPLOAD_URLS_DISABLED` rather than answering `null`.
+  `uploads.urls.cdn` puts a cache in front of henri's own, whose signature
+  deliberately does not cover the host.
+  
+  **Variants.** `config.uploads.variants` declares them by name and
+  `henri.uploads.variant(record, 'thumb')` answers a record like any other.
+  The key is the source's plus a digest of the variant's terms, so the work
+  happens once, on demand, and never in the request that uploaded. `sharp` is
+  an **optional peer dependency** resolved from the application: without it
+  `variant()` refuses with `HENRI_UPLOAD_NO_IMAGE_LIBRARY` and the install
+  line rather than quietly answering the original, and `henri doctor` reports
+  it. A name never comes from a request, an SVG is refused, a source is
+  bounded at fifty megapixels and one frame, no metadata is carried forward,
+  and what the resize produced is sniffed before it is stored.
+  
+  New configuration: `uploads.storage` in its object form, `uploads.urls`
+  (`expiresIn`, `path`, `cdn`) and `uploads.variants`. New codes:
+  `HENRI_UPLOAD_NO_IMAGE_LIBRARY`, `HENRI_UPLOAD_STORAGE_FAILED`,
+  `HENRI_UPLOAD_STORAGE_MISCONFIGURED`, `HENRI_UPLOAD_URLS_DISABLED`,
+  `HENRI_UPLOAD_URL_EXPIRED`, `HENRI_UPLOAD_URL_INVALID`,
+  `HENRI_UPLOAD_VARIANT_FAILED`, `HENRI_UPLOAD_VARIANT_UNKNOWN`,
+  `HENRI_UPLOAD_VARIANT_UNSUPPORTED`. `henri doctor` asks for
+  `@usehenri/s3` and `sharp` when the configuration names them.
+
+### Patch Changes
+
+- [#384](https://github.com/usehenri/henri/pull/384) [`68fe3af`](https://github.com/usehenri/henri/commit/68fe3afa8bdaa6d9a95d0e60858fd4abe28028b2) Thanks [@reel](https://github.com/reel)! - Test factories: a valid record with the fields the test does not care about already filled in.
+  
+  A factory lives in `test/factories/<name>.js` and is read the first time a test asks for one. It is a plain object -- `{ attributes, traits, model, after }` -- and `@usehenri/testing` now exports `create`, `build`, `createList`, `defineFactory` and `resetFactories`:
+  
+  ```js
+  // test/factories/proposal.js
+  module.exports = {
+    attributes: {
+      eventId: async ({ create }) => (await create('event')).id,
+      speakerId: async ({ create }) => (await create('user')).id,
+      title: ({ sequence }) => `A proposal ${sequence}`,
+    },
+    traits: { submitted: { state: 'submitted', submittedAt: () => new Date() } },
+  };
+  
+  await create('proposal', 'submitted', { speakerId: me.id });
+  ```
+  
+  Three rules hold it together. What the caller gives is never made, so an override of an association creates no second record. A value is a literal or a function of the build context (`attrs`, `build`, `create`, `sequence`, `traits`, `uid`), so there is no separate vocabulary for associations, sequences or computed fields. Fields resolve on demand rather than in the order they are written, so `await attrs.eventId` from another field's function keeps two of them on one parent whatever order the keys sit in. A trait is an override object with a name, kept next to the model because a state is rarely one field.
+  
+  A factory writes through the model, so the password is still hashed, the timestamps are still stamped and a `paranoid` model still soft-deletes; `after(record, context)` covers what the model refuses to mass assign. Failures carry the new `HENRI_FACTORY_*` codes.
+  
+  `@usehenri/uploads`: the local storage sweeps only the parts older than an hour when it starts. It could not tell a part a dead process left behind from one another process is streaming into right now, so a second application process -- or a second test file -- booting mid-upload failed that upload.
+- Updated dependencies [[`792a15a`](https://github.com/usehenri/henri/commit/792a15ade614cf8b920d9197586f9866700d458e), [`1e23664`](https://github.com/usehenri/henri/commit/1e23664829bd1a356de28f404cfb21c9ae211388), [`5b627ad`](https://github.com/usehenri/henri/commit/5b627adfa37e9f16bc75af96cc8ff5308a91f688), [`4dff51e`](https://github.com/usehenri/henri/commit/4dff51edc050e29398c793a5aedb48776b7b7119), [`60dbf33`](https://github.com/usehenri/henri/commit/60dbf33c2a4f14e328a0df1cb44be061e15431e5), [`1b316c6`](https://github.com/usehenri/henri/commit/1b316c6f3c5d5eb5752c70b534092d1052956cc6), [`d074e8b`](https://github.com/usehenri/henri/commit/d074e8b482582e25f80d8a14b4735e69a2b7821e), [`7fd13f6`](https://github.com/usehenri/henri/commit/7fd13f631b75f7aa152b73046b50c6902ae3ca93), [`b559fb7`](https://github.com/usehenri/henri/commit/b559fb72b391eeb21a3f6a0cda1515e01ecbfafc), [`1c0dfe8`](https://github.com/usehenri/henri/commit/1c0dfe84a98eff2122512256c4f42ec7ccde4212), [`93060a8`](https://github.com/usehenri/henri/commit/93060a86df795dbbd99bf1895beb0cf14c4b86de), [`e031900`](https://github.com/usehenri/henri/commit/e031900082f28aec72af4cda9cd959f932e2ebc7), [`9173000`](https://github.com/usehenri/henri/commit/91730005efa88f073bfaaf67078c3ec0e137b459), [`62fac46`](https://github.com/usehenri/henri/commit/62fac46fd6cae5581979b73daf99700fd246e0ea), [`b7f33e2`](https://github.com/usehenri/henri/commit/b7f33e28a5e4844391befd75d08e42c4cf6212ed), [`3d6f3fc`](https://github.com/usehenri/henri/commit/3d6f3fc048d05db41be86069608d342e437408cb), [`b278119`](https://github.com/usehenri/henri/commit/b2781190de436eb5838e866446c9a0c8210bb6ca), [`b161e1b`](https://github.com/usehenri/henri/commit/b161e1b8fad94af2d2afc351dc1bc07dabbb1379), [`7cb0b04`](https://github.com/usehenri/henri/commit/7cb0b04b29b61dedaa82fcd1972646fb3765acfc), [`1616e34`](https://github.com/usehenri/henri/commit/1616e343a612be2bffffcfa5b23bfa8ad191bbe3), [`c8f5367`](https://github.com/usehenri/henri/commit/c8f53678b33341d086b467f801e959314afc7860), [`bcf4ce2`](https://github.com/usehenri/henri/commit/bcf4ce22bcd294844504164fac1fa4aef1ffec41), [`ab5a8e4`](https://github.com/usehenri/henri/commit/ab5a8e4a88c80cca070a2b8ad398c80babdaff11), [`43d267f`](https://github.com/usehenri/henri/commit/43d267f0f9d192b2c01e89c3925b7daf5000041b), [`9f868f3`](https://github.com/usehenri/henri/commit/9f868f3d9162fa218e34304110210e6949f97d5c), [`d88bf7f`](https://github.com/usehenri/henri/commit/d88bf7fe038a6b58e7bed02ff4c90755f6c0e65e), [`49398a6`](https://github.com/usehenri/henri/commit/49398a6308f0760f01c6ff2ec98aaa35f484474d), [`89dda62`](https://github.com/usehenri/henri/commit/89dda62da456a0a55600e79cfb65ce89f11258e2), [`62fac46`](https://github.com/usehenri/henri/commit/62fac46fd6cae5581979b73daf99700fd246e0ea), [`a93d6cc`](https://github.com/usehenri/henri/commit/a93d6cc39b33b261089e91f3e757b54fefc9fe15), [`d9f3be4`](https://github.com/usehenri/henri/commit/d9f3be49c5929d929a220220bf6e72fdcb135595), [`c44f025`](https://github.com/usehenri/henri/commit/c44f025acec3d5bbbb57e2310d02184a1053a10d), [`67cfb20`](https://github.com/usehenri/henri/commit/67cfb200ea0e0b31bacf2af183db6467b0fa011d), [`e661f98`](https://github.com/usehenri/henri/commit/e661f98fe8f8acce15aa10ce2dc320c5a2cb006f), [`43a0e1a`](https://github.com/usehenri/henri/commit/43a0e1a6a320baa43298391e1c1e0334d6cd28d5), [`cee57b9`](https://github.com/usehenri/henri/commit/cee57b9d3521a4a70c715222eae1f18ff4a6c128), [`61bf75c`](https://github.com/usehenri/henri/commit/61bf75cbaccda1aecff34408a175b2d85447d7a8), [`2c8a826`](https://github.com/usehenri/henri/commit/2c8a8265262dbf6ea5c3e73e8e7892a230d4d0f0), [`46d5dbc`](https://github.com/usehenri/henri/commit/46d5dbcc983c03e96ae5a87d7288c5d8a5adbc24), [`ba97ea9`](https://github.com/usehenri/henri/commit/ba97ea968f0b34cd67b7a3e803ecd34543b8aaaf), [`5ccd537`](https://github.com/usehenri/henri/commit/5ccd537b3621b54d11e7f24ccca39643ae7d5cf7), [`d88bf7f`](https://github.com/usehenri/henri/commit/d88bf7fe038a6b58e7bed02ff4c90755f6c0e65e), [`9895cbf`](https://github.com/usehenri/henri/commit/9895cbf4be85b476e341a5be915e3049e5a027de), [`61bf75c`](https://github.com/usehenri/henri/commit/61bf75cbaccda1aecff34408a175b2d85447d7a8), [`5a150d5`](https://github.com/usehenri/henri/commit/5a150d576208571c32b9cd12827d035e31ed4313), [`3c1c5b8`](https://github.com/usehenri/henri/commit/3c1c5b83ea135b000ddd6ffbfd05457b000f2f7c), [`2625067`](https://github.com/usehenri/henri/commit/26250673d91ab70ad024739d02b647754f75267d), [`aa3f90b`](https://github.com/usehenri/henri/commit/aa3f90bd6f42bb05431c33f3e4bf2202cb6bb7c6), [`a1c6769`](https://github.com/usehenri/henri/commit/a1c6769099e3dc28b22b5338a2a57b13bdf69f7a), [`0a8bb41`](https://github.com/usehenri/henri/commit/0a8bb415d352cd75b12d07e591c8ec7c16774a99), [`ec1c8c4`](https://github.com/usehenri/henri/commit/ec1c8c419f4d9063a7617472b2970fdb8a929fa1), [`dd2731d`](https://github.com/usehenri/henri/commit/dd2731d6a20fd96aa1be1aeb5e6ec0155001326b), [`ab52e18`](https://github.com/usehenri/henri/commit/ab52e187c420dfe381f03ed51c5c141fda525acb), [`b7b56e1`](https://github.com/usehenri/henri/commit/b7b56e190ae774abc0096fe2aebaf91f823115af), [`b7038ce`](https://github.com/usehenri/henri/commit/b7038ceaa430f4a0b9eaf7e983fc2844421bf636), [`1ea0f85`](https://github.com/usehenri/henri/commit/1ea0f85066b86fba31f58937cc10abb6359e6a26), [`762062a`](https://github.com/usehenri/henri/commit/762062aadc450d49b1a2d15524f9d579ab4f60e7), [`01a561a`](https://github.com/usehenri/henri/commit/01a561aa58650ec15df1c2659795a5e4c5bbfd53), [`bd1b630`](https://github.com/usehenri/henri/commit/bd1b63083b3817b8c47b8a187de76027458a1b32), [`27b5513`](https://github.com/usehenri/henri/commit/27b5513d1cae8aba734fe27da0ace2a82423e2f4), [`e31a3f7`](https://github.com/usehenri/henri/commit/e31a3f73e7e8facf3cedf7460f115e57995f32c3), [`2689779`](https://github.com/usehenri/henri/commit/26897798b840fd28a4bc091c050a83457b36905d), [`72cd1d3`](https://github.com/usehenri/henri/commit/72cd1d35ffb99311bbca815c1f6ab41ee3682f64), [`a2e1ec2`](https://github.com/usehenri/henri/commit/a2e1ec29df52462f12ebaae9bfbc1ad4f427b27f), [`afead74`](https://github.com/usehenri/henri/commit/afead7489498ed42e1893a25123ea772cac2ca09), [`a4ecba5`](https://github.com/usehenri/henri/commit/a4ecba50c663f4d5c741adbb6cd9bc0eefe0e5cc), [`baec3fd`](https://github.com/usehenri/henri/commit/baec3fd22be92bf8ffbaeb251b0b6c2771f8347a), [`1103628`](https://github.com/usehenri/henri/commit/110362808f8ec6d73a75ff7fc89a77f3e943d773), [`e865d94`](https://github.com/usehenri/henri/commit/e865d945d65419ac676f5a2fe3ba3b6114a1e53d), [`4274567`](https://github.com/usehenri/henri/commit/4274567e20a980657f07df9ec7db25296c7d55f5), [`aea429c`](https://github.com/usehenri/henri/commit/aea429ca99338a62370ab3e3d94bdc6b8c227601), [`8a8e3b3`](https://github.com/usehenri/henri/commit/8a8e3b33d7967b81f66633aa25c3075318f01d60), [`18715f9`](https://github.com/usehenri/henri/commit/18715f90ea8958dc57da1bb029b8209c36b84cc6), [`0d2ebc3`](https://github.com/usehenri/henri/commit/0d2ebc344bfcd80533ef900638083e4c105407bb), [`49398a6`](https://github.com/usehenri/henri/commit/49398a6308f0760f01c6ff2ec98aaa35f484474d), [`ec64e44`](https://github.com/usehenri/henri/commit/ec64e44e7b79a02da5fc587a72a9a6c900836982), [`831aa5c`](https://github.com/usehenri/henri/commit/831aa5c011f3432630c68b8d26755d2582f82f74), [`16824e8`](https://github.com/usehenri/henri/commit/16824e8fe9ccc6a04dab5d9b2481c29ff4f6b64b), [`fda9366`](https://github.com/usehenri/henri/commit/fda9366e9ed2b072764a995c5aa60205ca7a4725), [`1a86acb`](https://github.com/usehenri/henri/commit/1a86acbf15e4a43e5fb81277bb22e101c06e77a4), [`808d824`](https://github.com/usehenri/henri/commit/808d82471d59e64ccc735f617bab293eb572c46b), [`0b32fbd`](https://github.com/usehenri/henri/commit/0b32fbde19c95da8fe07fab76933840a4242c71c), [`c0c16e8`](https://github.com/usehenri/henri/commit/c0c16e873ba440aee9832160553cbb12ab81bd2c), [`41470bf`](https://github.com/usehenri/henri/commit/41470bf378d83ca3d35d00e8c31796fea5eb15e0), [`8e44e7e`](https://github.com/usehenri/henri/commit/8e44e7e882dd8741b3ac632651b453389d76bf2c), [`de1c1e0`](https://github.com/usehenri/henri/commit/de1c1e02ed83d13dcfeb8e44012f309eb663f03e), [`4b4677d`](https://github.com/usehenri/henri/commit/4b4677d4a09d39fe50b1fa4af577600342578daf)]:
+  - @usehenri/core@1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016-present, Félix-Antoine Paradis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
+<!-- generated by scripts/prepublish.js -->
+
 # @usehenri/uploads
 
-Placeholder release. Install a real version: see https://usehenri.io.
+Henri file uploads: bounded multipart parsing, files typed by their bytes and a storage seam.
+
+Part of [henri](https://usehenri.io), the Rails-like React framework for
+Node.js: [documentation](https://usehenri.io),
+[source and issues](https://github.com/usehenri/henri),
+[changelog](https://github.com/usehenri/henri/blob/master/packages/uploads/CHANGELOG.md).

package/index.js

@@ -0,0 +1,42 @@
+/**
+ * `@usehenri/uploads`: bounded multipart parsing, files typed by their bytes,
+ * and a storage seam.
+ *
+ * An application installs the package and gets the module (`henri.uploads`),
+ * `req.files`, `req.file()` and `req.permitFiles()`. What is exported here is
+ * for the two things an application does beyond that: writing a storage of
+ * its own against `HenriStorage`, and reusing the name and type helpers in a
+ * validation of its own.
+ *
+ * See https://usehenri.io/guides/uploads/
+ */
+const UploadsModule = require('./src/module');
+const LocalStorage = require('./src/storage/local');
+
+const { DEFAULTS, settings } = require('./src/config');
+const { UploadError, coded } = require('./src/errors');
+const { UploadedFile } = require('./src/file');
+const { UrlSigner } = require('./src/signing');
+const { bytes, format } = require('./src/bytes');
+const { contentDisposition, isKey, keyFor, safeName } = require('./src/names');
+const { createStorage } = require('./src/storage');
+const { extensionFor, sniff } = require('./src/sniff');
+
+module.exports = UploadsModule;
+module.exports.DEFAULTS = DEFAULTS;
+module.exports.LocalStorage = LocalStorage;
+module.exports.UploadError = UploadError;
+module.exports.UploadedFile = UploadedFile;
+module.exports.UploadsModule = UploadsModule;
+module.exports.UrlSigner = UrlSigner;
+module.exports.bytes = bytes;
+module.exports.coded = coded;
+module.exports.contentDisposition = contentDisposition;
+module.exports.createStorage = createStorage;
+module.exports.extensionFor = extensionFor;
+module.exports.format = format;
+module.exports.isKey = isKey;
+module.exports.keyFor = keyFor;
+module.exports.safeName = safeName;
+module.exports.settings = settings;
+module.exports.sniff = sniff;

package/module.js

@@ -0,0 +1,8 @@
+/**
+ * The henri module this package ships.
+ *
+ * `package.json` points at this file with `"henri": { "module": "./module.js" }`,
+ * which is all core reads: an application depending on `@usehenri/uploads`
+ * has the module in its boot, as `henri.uploads`.
+ */
+module.exports = require('./src/module');

package/package.json

@@ -1,15 +1,61 @@
 {
-  "description": "Placeholder creating @usehenri/uploads on npm; the first real version is published by the henri release workflow",
-  "homepage": "https://usehenri.io",
-  "license": "MIT",
   "name": "@usehenri/uploads",
-  "publishConfig": {
-    "access": "public"
-  },
+  "version": "1.2.0",
+  "description": "henri file uploads: bounded multipart parsing, files typed by their bytes and a storage seam",
+  "license": "MIT",
+  "author": "Felix-Antoine Paradis",
+  "homepage": "https://usehenri.io",
   "repository": {
-    "directory": "packages/uploads",
     "type": "git",
-    "url": "git+https://github.com/usehenri/henri.git"
+    "url": "git+https://github.com/usehenri/henri.git",
+    "directory": "packages/uploads"
+  },
+  "bugs": {
+    "url": "https://github.com/usehenri/henri/issues"
+  },
+  "keywords": [
+    "henri",
+    "uploads",
+    "multipart",
+    "files",
+    "busboy",
+    "storage",
+    "variants"
+  ],
+  "main": "index.js",
+  "henri": {
+    "module": "./module.js"
+  },
+  "files": [
+    "index.js",
+    "module.js",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "busboy": "^1.6.0",
+    "debug": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@usehenri/core": "^1.2.0",
+    "sharp": ">=0.33"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
   },
-  "version": "0.0.0"
-}
+  "devDependencies": {
+    "@usehenri/core": "^1.2.0",
+    "express": "^5.2.1",
+    "sharp": "^0.35.4",
+    "supertest": "^7.2.2"
+  }
+}

package/src/bytes.js

@@ -0,0 +1,86 @@
+/**
+ * Sizes, the way the configuration writes them.
+ *
+ * `config.bodyLimit` is `"1mb"` or a number of bytes, and the upload limits
+ * are read the same way so that the two are comparable at a glance. This is
+ * the parser: no dependency, no unit henri does not document, and `false`
+ * kept as `false` because a limit an application removed on purpose is not
+ * the same thing as a limit it wrote badly.
+ */
+
+/** Multipliers of the suffixes a size accepts (no suffix is bytes) */
+const UNITS = { gb: 1024 * 1024 * 1024, kb: 1024, mb: 1024 * 1024 };
+
+/** A size: a number, with an optional unit */
+/**
+ * The written form: an amount, then a unit.
+ *
+ * The surrounding whitespace is trimmed before this runs rather than
+ * matched by it: `^\s*…\s*$` around an optional group is quadratic, and
+ * `'9' + ' '.repeat(100000) + '!'` took five seconds to refuse when the two
+ * star quantifiers had a run of spaces to share between them.
+ */
+const SIZE = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/iu;
+
+/**
+ * A size in bytes
+ *
+ * @param {*} value a number of bytes, a string (`'10mb'`), or `false`
+ * @param {(number|false|null)} [fallback=null] what an unreadable value becomes
+ * @returns {(number|false|null)} the size, `false` for no limit, or the fallback
+ */
+function bytes(value, fallback = null) {
+  if (value === false) {
+    return false;
+  }
+
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+  }
+
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+
+  const match = SIZE.exec(value.trim());
+
+  if (!match) {
+    return fallback;
+  }
+
+  const unit = String(match[2] || '').toLowerCase();
+  const size = Number(match[1]) * (UNITS[unit] || 1);
+
+  return size > 0 ? Math.floor(size) : fallback;
+}
+
+/**
+ * A size, printed the way the documentation writes it
+ *
+ * @param {(number|false)} value a size in bytes, or `false`
+ * @returns {string} `'10mb'`, `'512kb'`, `'900b'` or `'no limit'`
+ */
+function format(value) {
+  if (value === false || value === null) {
+    return 'no limit';
+  }
+
+  for (const unit of ['gb', 'mb', 'kb']) {
+    if (value >= UNITS[unit]) {
+      return `${Math.round((value / UNITS[unit]) * 10) / 10}${unit}`;
+    }
+  }
+
+  return `${value}b`;
+}
+
+/**
+ * A limit as busboy wants it: a number, or `Infinity` for no limit
+ *
+ * @param {(number|false|null)} value the limit
+ * @returns {number} the limit, or `Infinity`
+ */
+const orInfinity = (value) =>
+  typeof value === 'number' && value > 0 ? value : Infinity;
+
+module.exports = { UNITS, bytes, format, orInfinity };

package/src/config.js

@@ -0,0 +1,243 @@
+/**
+ * `config.uploads`, normalized.
+ *
+ * Every limit here is enforced by the parser as it reads, which is the only
+ * kind of limit worth writing: a check that runs once the file is on disk
+ * has already let the disk fill. `false` is accepted on the four that bound
+ * a request, because an application that means "no limit" should have to
+ * write it -- and `henri audit` reports it when it does.
+ *
+ * `maxFieldSize` defaults to `config.bodyLimit` rather than to a number of
+ * its own. The two bound the same thing from two directions: `bodyLimit`
+ * is what `express.json()` and `express.urlencoded()` accept for a whole
+ * body, and a multipart body is bounded by `maxTotalSize` instead, with
+ * `maxFieldSize` bounding one of its non-file parts. Giving the part the
+ * same ceiling as a whole urlencoded body keeps `"name"` costing the same
+ * whichever encoding a form was posted with.
+ */
+const { bytes } = require('./bytes');
+const { EXPIRES_IN, MAX_EXPIRES, PATH } = require('./signing');
+const { variantsOf } = require('./variants');
+
+/** The defaults, and the table the documentation prints */
+const DEFAULTS = {
+  allow: null,
+  maxFieldNameSize: 100,
+  maxFieldSize: null,
+  maxFields: 100,
+  maxFileSize: '10mb',
+  maxFilenameLength: 255,
+  maxFiles: 10,
+  maxTotalSize: '25mb',
+  paths: null,
+  root: 'storage/uploads',
+  sniff: true,
+  storage: 'local',
+  urls: false,
+  variants: null,
+};
+
+/** The methods a body is read from; anything else never carries an upload */
+const METHODS = new Set(['PATCH', 'POST', 'PUT']);
+
+/**
+ * The storage an application named, split into the backend and its settings.
+ *
+ * Two forms, the way `config.stores.<name>` and `config.shared` already
+ * work: a string is a backend with nothing to configure (`"local"`,
+ * `"./lib/storage"`), and an object is a backend with settings, whose
+ * `adapter` names it and whose other keys are the backend's own. henri
+ * reads none of the latter -- a bucket, a region and an endpoint are
+ * `@usehenri/s3`'s business, not the framework's.
+ *
+ * @param {*} value what the configuration holds under `storage`
+ * @returns {{name: string, options: object}} the backend and its settings
+ */
+const storageOf = (value) => {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return { name: value.trim(), options: {} };
+  }
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const { adapter, ...options } = value;
+
+    return {
+      name:
+        typeof adapter === 'string' && adapter.trim()
+          ? adapter.trim()
+          : DEFAULTS.storage,
+      options,
+    };
+  }
+
+  return { name: DEFAULTS.storage, options: {} };
+};
+
+/**
+ * A whole number above zero, `false`, or the fallback
+ *
+ * @param {*} value the value
+ * @param {(number|false)} fallback what an unreadable value becomes
+ * @returns {(number|false)} the count
+ */
+const count = (value, fallback) => {
+  if (value === false) {
+    return false;
+  }
+
+  const number = Number(value);
+
+  return Number.isInteger(number) && number > 0 ? number : fallback;
+};
+
+/**
+ * A plain object, or an empty one
+ *
+ * @param {*} value the value
+ * @returns {object} a plain object
+ */
+const objectOf = (value) =>
+  value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+
+/**
+ * The list of media types an application accepts, or null for every type
+ *
+ * @param {*} value what the configuration holds
+ * @returns {?Array<string>} the list, or null
+ */
+const allowList = (value) => {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+
+  const entries = value
+    .filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+    .map((entry) => entry.trim().toLowerCase());
+
+  return entries.length > 0 ? entries : null;
+};
+
+/**
+ * The path prefixes multipart is parsed under, or null for every path
+ *
+ * @param {*} value what the configuration holds
+ * @returns {?Array<string>} the prefixes, or null
+ */
+const pathList = (value) => {
+  const entries = (Array.isArray(value) ? value : [value])
+    .filter((entry) => typeof entry === 'string' && entry.startsWith('/'))
+    .map((entry) => (entry.length > 1 ? entry.replace(/\/+$/u, '') : entry));
+
+  return entries.length > 0 ? entries : null;
+};
+
+/**
+ * Signed urls: off, or the settings of the ones this application hands out.
+ *
+ * Off is the default, and it is fail-closed rather than shy. A signed url
+ * is a bearer capability -- whoever holds the link holds the file, until it
+ * expires -- and on the local disk it also mounts a route that serves bytes
+ * without asking the application anything. Neither is a thing to acquire by
+ * installing a package; both are one line of configuration.
+ *
+ * @param {*} value what the configuration holds under `urls`
+ * @returns {(false|object)} the settings, or false
+ */
+const urlsOf = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  const seconds = Number(value.expiresIn);
+  const declared = typeof value.path === 'string' && value.path.startsWith('/');
+
+  return {
+    cdn: typeof value.cdn === 'string' ? value.cdn.replace(/\/+$/u, '') : '',
+    expiresIn:
+      Number.isInteger(seconds) && seconds > 0 && seconds <= MAX_EXPIRES
+        ? seconds
+        : EXPIRES_IN,
+    path: declared ? value.path.replace(/\/+$/u, '') || PATH : PATH,
+  };
+};
+
+/**
+ * The settings of the uploads module
+ *
+ * @param {object} config henri's config module (anything with get/has)
+ * @returns {object} the settings, or `{ enabled: false }` when the
+ *   application wrote `"uploads": false`
+ */
+function settings(config) {
+  const has = (key) =>
+    Boolean(config) && typeof config.has === 'function' && config.has(key);
+  const get = (key, fallback) => (has(key) ? config.get(key) : fallback);
+  const declared = get('uploads', {});
+
+  if (declared === false) {
+    return { enabled: false };
+  }
+
+  const uploads = objectOf(declared);
+  const bodyLimit = bytes(get('bodyLimit', '1mb'), 1024 * 1024);
+  const storage = storageOf(uploads.storage);
+
+  return {
+    allow: allowList(uploads.allow),
+    enabled: true,
+    maxFieldNameSize: count(
+      uploads.maxFieldNameSize,
+      DEFAULTS.maxFieldNameSize
+    ),
+    maxFieldSize: bytes(uploads.maxFieldSize, bodyLimit),
+    maxFields: count(uploads.maxFields, DEFAULTS.maxFields),
+    maxFileSize: bytes(uploads.maxFileSize, bytes(DEFAULTS.maxFileSize)),
+    maxFilenameLength: count(
+      uploads.maxFilenameLength,
+      DEFAULTS.maxFilenameLength
+    ),
+    maxFiles: count(uploads.maxFiles, DEFAULTS.maxFiles),
+    maxTotalSize: bytes(uploads.maxTotalSize, bytes(DEFAULTS.maxTotalSize)),
+    paths: pathList(uploads.paths),
+    root: typeof uploads.root === 'string' ? uploads.root : DEFAULTS.root,
+    sniff: uploads.sniff !== false,
+    storage: storage.name,
+    storageOptions: storage.options,
+    urls: urlsOf(uploads.urls),
+    variants: variantsOf(uploads.variants),
+  };
+}
+
+/**
+ * Does this request take a body a multipart parser should read?
+ *
+ * @param {Express.Request} req the request
+ * @param {?Array<string>} paths the configured prefixes, or null
+ * @returns {boolean} true when the parser runs for it
+ */
+function covers(req, paths) {
+  if (!METHODS.has(req.method)) {
+    return false;
+  }
+
+  if (!Array.isArray(paths)) {
+    return true;
+  }
+
+  const url = (req.path || req.url || '/').split('?')[0];
+
+  return paths.some(
+    (prefix) => url === prefix || url.startsWith(`${prefix}/`) || prefix === '/'
+  );
+}
+
+module.exports = {
+  DEFAULTS,
+  METHODS,
+  allowList,
+  count,
+  covers,
+  settings,
+  storageOf,
+  urlsOf,
+};