@usehenri/uploads 0.0.0 → 1.2.0

package/src/download.js

@@ -0,0 +1,126 @@
+/**
+ * The route that verifies henri's own signed urls and streams the file.
+ *
+ * It exists only for a storage that cannot sign its own -- the local disk --
+ * and only when `uploads.urls` says so. An object store signs a url the
+ * client fetches from the store itself, and nothing here ever runs for it.
+ *
+ * **Why it is a middleware and not a route of `config/routes.js`.** The same
+ * reason the parser is: the uploads module is at runlevel 3 and the router
+ * is at 5, so there is no route table yet to add to. That is not a
+ * workaround, it is the right place -- this url carries its own
+ * authorization in its signature, so it wants no session, no CSRF token and
+ * no policy. The rate limit and helmet are mounted at runlevel 2, before
+ * this, so a signed url is rate limited and gets the same headers as
+ * everything else.
+ *
+ * **Why it fails through `next(error)`.** `res.boom` does not exist yet at
+ * this point in the chain either; core's error handler negotiates an
+ * `UploadError` into the JSON body a client expects or the page a browser
+ * does, and the code (`HENRI_UPLOAD_URL_INVALID`, `HENRI_UPLOAD_URL_EXPIRED`)
+ * reaches both. The parser refuses the same way, for the same reason.
+ */
+const debug = require('debug')('henri:uploads');
+
+const { UploadError } = require('./errors');
+
+/** The methods a signed url answers: reading, and asking about reading */
+const METHODS = new Set(['GET', 'HEAD']);
+
+/**
+ * The storage key a request names, or null when the path is not one of ours
+ *
+ * @param {string} pathname the path of the request
+ * @param {string} prefix where the route is mounted
+ * @returns {?string} the key
+ */
+function keyIn(pathname, prefix) {
+  if (!pathname.startsWith(`${prefix}/`)) {
+    return null;
+  }
+
+  try {
+    return decodeURIComponent(pathname.slice(prefix.length + 1));
+  } catch (error) {
+    debug('undecodable path %s: %s', pathname, error.message);
+
+    return null;
+  }
+}
+
+/**
+ * The middleware the module mounts next to the parser.
+ *
+ * Like the parser, it reads the settings and the signer off the module on
+ * every request rather than closing over them: a reload changes what it
+ * does, never whether it is there.
+ *
+ * @param {object} module the uploads module (`henri.uploads`)
+ * @returns {function} express middleware
+ */
+function downloads(module) {
+  return function uploadDownload(req, res, next) {
+    const { settings, signer, storage } = module;
+
+    if (!module.enabled || !signer || !settings.urls || !storage) {
+      return next();
+    }
+
+    if (!METHODS.has(req.method)) {
+      return next();
+    }
+
+    const [pathname, search] = String(req.originalUrl || req.url).split('?');
+    const key = keyIn(pathname, settings.urls.path);
+
+    if (key === null) {
+      return next();
+    }
+
+    const verdict = signer.verify(key, new URLSearchParams(search || ''));
+
+    if (!verdict.ok) {
+      return next(
+        verdict.reason === 'expired'
+          ? new UploadError(
+              'URL_EXPIRED',
+              'this link has expired; ask the application for another one',
+              {
+                expires: Number(
+                  new URLSearchParams(search || '').get('expires')
+                ),
+              }
+            )
+          : new UploadError('URL_INVALID', 'this link is not valid')
+      );
+    }
+
+    // Everything below is about a link henri really signed. An object that
+    // is no longer there answers what an invalid link answers, rather than
+    // a 404: the two are indistinguishable to a holder of the link, and a
+    // link that is refused says nothing about what the storage holds
+    return storage
+      .stat(key)
+      .then((found) => {
+        if (!found) {
+          return next(
+            new UploadError('URL_INVALID', 'this file is no longer there')
+          );
+        }
+
+        return module.send(
+          res,
+          {
+            key,
+            name: verdict.claims.filename || 'file',
+            size: found.size,
+            type: verdict.claims.type,
+          },
+          { disposition: verdict.claims.disposition }
+        );
+      })
+      .catch(next);
+  };
+}
+
+module.exports = { METHODS, downloads, keyIn };

package/src/errors.js

@@ -0,0 +1,92 @@
+/**
+ * What a refused upload is.
+ *
+ * Every refusal is an `UploadError` carrying an HTTP status and a code, and
+ * it reaches the client through `next(error)` -- core's error handler
+ * negotiates it into the JSON shape a client expects or the page a browser
+ * does, and its own logging quotes the request id. Nothing here writes a
+ * response itself: an upload is refused in a middleware, and the middleware
+ * that owns the answer is the one at the end of the chain.
+ */
+
+/** The codes a refusal carries, and the status each one answers with */
+const CODES = {
+  FIELD_NAME_TOO_LONG: 413,
+  FILE_TOO_LARGE: 413,
+  MALFORMED_MULTIPART: 400,
+  TOO_MANY_FIELDS: 413,
+  TOO_MANY_FILES: 413,
+  TOTAL_TOO_LARGE: 413,
+  TYPE_NOT_ALLOWED: 415,
+  URL_EXPIRED: 403,
+  URL_INVALID: 403,
+  VALUE_TOO_LARGE: 413,
+};
+
+/**
+ * The catalogue code a refusal also carries, where there is one.
+ *
+ * `error.code` is the short name a client reads next to the status, and
+ * core's `coded()` looks at `henriCode` when `code` is not one of the
+ * catalogue's -- the same arrangement an `ENOENT` gets. So a refusal can
+ * keep the name it always had and still reach the JSON body, the log line
+ * and `henri mcp` as `HENRI_UPLOAD_*`.
+ */
+const HENRI = {
+  URL_EXPIRED: 'HENRI_UPLOAD_URL_EXPIRED',
+  URL_INVALID: 'HENRI_UPLOAD_URL_INVALID',
+};
+
+/**
+ * A refused upload
+ *
+ * @class UploadError
+ * @extends {Error}
+ */
+class UploadError extends Error {
+  /**
+   * Creates an instance of UploadError.
+   *
+   * @param {string} code one of `CODES`
+   * @param {string} message what to tell the client
+   * @param {object} [data={}] what to add to the answer (a field name, a limit)
+   * @memberof UploadError
+   */
+  constructor(code, message, data = {}) {
+    super(message);
+
+    this.name = 'UploadError';
+    this.code = code;
+    this.status = CODES[code] || 400;
+    this.statusCode = this.status;
+    this.data = data;
+
+    if (HENRI[code]) {
+      this.henriCode = HENRI[code];
+    }
+  }
+}
+
+/**
+ * A failure carrying one of the catalogue's codes and nothing else.
+ *
+ * The three lines a package that only peer-depends on core writes for
+ * itself, the way `@usehenri/webhooks` and `@usehenri/s3` do: a code is a
+ * string, so raising one imports nothing.
+ *
+ * @param {string} code a henri error code, from core's own catalogue
+ * @param {string} message what went wrong
+ * @param {object} [rest={}] `cause` and anything to carry on the error
+ * @returns {Error} the error
+ */
+function coded(code, message, rest = {}) {
+  const { cause, ...extra } = rest;
+  const error = new Error(message, cause ? { cause } : undefined);
+
+  error.code = code;
+  Object.assign(error, extra);
+
+  return error;
+}
+
+module.exports = { CODES, HENRI, UploadError, coded };

package/src/file.js

@@ -0,0 +1,204 @@
+/**
+ * One file that arrived.
+ *
+ * It exists on disk from the moment the parser finished reading it until the
+ * end of the request, and it is temporary for the whole of that time: an
+ * upload is not kept because it arrived, it is kept because a controller
+ * said so with `store()`. Everything else is swept when the response closes,
+ * whether the request was answered, refused, timed out or abandoned
+ * half-way.
+ *
+ * What `store()` resolves with is the record: the plain object a controller
+ * writes to a model. It holds the key, the cleaned original name, the type
+ * the *bytes* were recognized as, the size and a sha256 of the content --
+ * everything needed to hand the file back later, and nothing that would let
+ * the row alone reconstruct where on the machine it sits.
+ */
+const fsp = require('node:fs/promises');
+const debug = require('debug')('henri:uploads');
+
+const { extensionFor } = require('./sniff');
+const { keyFor, safeName } = require('./names');
+
+/**
+ * A file the parser read and put somewhere private
+ *
+ * @class UploadedFile
+ */
+class UploadedFile {
+  /**
+   * Creates an instance of UploadedFile.
+   *
+   * @param {object} options what the parser found out
+   * @param {string} options.field the form field it arrived in
+   * @param {string} options.name the cleaned original name
+   * @param {string} options.declaredType what the client called it
+   * @param {string} options.type what the bytes say it is
+   * @param {boolean} options.sniffed whether henri recognized those bytes
+   * @param {number} options.size how many bytes arrived
+   * @param {string} options.checksum sha256 of the content, hex
+   * @param {string} options.path where it is, until the response closes
+   * @param {object} options.storage the storage that will keep it
+   * @param {number} [options.order=0] which part of the body it was, so that
+   *   `req.files.photos[0]` is the first photo the form sent whatever order
+   *   the reads happened to finish in
+   * @memberof UploadedFile
+   */
+  constructor({
+    checksum,
+    declaredType,
+    field,
+    name,
+    order = 0,
+    path: temporary,
+    size,
+    sniffed,
+    storage,
+    type,
+  }) {
+    this.order = order;
+    this.field = field;
+    this.name = name;
+    this.declaredType = declaredType;
+    this.type = type;
+    this.sniffed = sniffed;
+    this.size = size;
+    this.checksum = checksum;
+    this.path = temporary;
+    this.storage = storage;
+
+    /** The record `store()` resolved with, once it has */
+    this.stored = null;
+
+    /** True once the temporary file is gone, however it went */
+    this.released = false;
+  }
+
+  /**
+   * Did the client say one thing and the bytes another?
+   *
+   * @returns {boolean} true when the declared type is not the real one
+   * @memberof UploadedFile
+   */
+  get mistyped() {
+    return (
+      this.sniffed &&
+      Boolean(this.declaredType) &&
+      this.declaredType !== this.type
+    );
+  }
+
+  /**
+   * Keeps the file, and answers the record to write to a model
+   *
+   * @async
+   * @param {object} [options={}] the options
+   * @param {string} [options.prefix] a directory to file it under
+   * @param {object} [options.storage] another storage than the default one
+   * @returns {Promise<object>} `{ checksum, key, name, size, storage, type, uploadedAt }`
+   * @throws when there is nothing left to store, or the storage refuses
+   * @memberof UploadedFile
+   */
+  async store(options = {}) {
+    if (this.stored) {
+      return this.stored;
+    }
+
+    if (this.released) {
+      throw new Error(
+        `the upload "${this.name}" was already released; store() has to be called before the response closes`
+      );
+    }
+
+    const storage = options.storage || this.storage;
+    // What the parser already knows travels with the file: a backend that
+    // keeps metadata of its own (an object store keeps a `Content-Type` and
+    // wants the digest it is signing) would otherwise read the bytes again
+    // to learn what was measured on the way in
+    const key = await storage.put(
+      this.path,
+      keyFor({
+        extension: extensionFor(this.type),
+        prefix: options.prefix || null,
+      }),
+      {
+        checksum: this.checksum,
+        name: this.name,
+        size: this.size,
+        type: this.type,
+      }
+    );
+
+    this.released = true;
+    this.stored = {
+      checksum: this.checksum,
+      key,
+      name: this.name,
+      size: this.size,
+      storage: storage.name,
+      type: this.type,
+      uploadedAt: new Date().toISOString(),
+    };
+
+    return this.stored;
+  }
+
+  /**
+   * Throws the file away now, rather than at the end of the request
+   *
+   * @async
+   * @returns {Promise<boolean>} true when something was removed
+   * @memberof UploadedFile
+   */
+  async discard() {
+    if (this.released) {
+      return false;
+    }
+
+    this.released = true;
+
+    try {
+      await fsp.unlink(this.path);
+
+      return true;
+    } catch (error) {
+      debug('unable to remove %s: %s', this.path, error.message);
+
+      return false;
+    }
+  }
+
+  /**
+   * What a view or a JSON answer gets: the record when it was stored, the
+   * facts without the temporary path when it was not
+   *
+   * @returns {object} a plain object
+   * @memberof UploadedFile
+   */
+  toJSON() {
+    return (
+      this.stored || {
+        checksum: this.checksum,
+        field: this.field,
+        name: this.name,
+        size: this.size,
+        type: this.type,
+      }
+    );
+  }
+}
+
+/**
+ * An UploadedFile, with its name cleaned and its type decided
+ *
+ * @param {object} options see the constructor, plus `maxFilenameLength`
+ * @returns {UploadedFile} the file
+ */
+const fileOf = (options) =>
+  new UploadedFile(
+    Object.assign({}, options, {
+      name: safeName(options.name, options.maxFilenameLength),
+    })
+  );
+
+module.exports = { UploadedFile, fileOf };