kempo-media 0.2.3

package/tests/module-graph.node-test.js

@@ -0,0 +1,86 @@
+import { readdir } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+/*
+  Every server-side module must at least load.
+
+  This extension resolves imports out of the host `kempo` package, so it breaks in two ways
+  nothing else notices until a request comes in: a relative import that climbs the wrong number of
+  directories, or the host moving something this package reaches into. Importing the whole surface
+  turns both into a build failure.
+
+  admin/* and public/components/* are excluded — those are browser modules importing absolute
+  /kempo-ui/... URLs, not something Node can import directly.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const ROUTE_METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+
+const walk = async dir => {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for(const entry of entries){
+    const full = path.join(dir, entry.name);
+    if(entry.isDirectory()){
+      files.push(...await walk(full));
+    } else if(entry.name.endsWith('.js')){
+      files.push(full);
+    }
+  }
+  return files;
+};
+
+const dirs = ['server', 'hooks', 'public/api'];
+const singles = ['install.js', 'update.js', 'sdk.js'];
+
+const files = [
+  ...(await Promise.all(dirs.map(d => walk(path.join(root, d))))).flat(),
+  ...singles.map(f => path.join(root, f)),
+];
+
+const isRouteHandler = file => {
+  const name = path.basename(file, '.js');
+  return file.replace(/\\/g, '/').includes('/api/') && ROUTE_METHODS.includes(name);
+};
+
+const tests = {
+  /*
+    Starts low because this extension is still being scaffolded (see the implementation plan) —
+    raise this as server/utils and public/api fill in, so it stays a meaningful check that the
+    surface list itself isn't broken, rather than a number nobody revisits.
+  */
+  'module surface is discoverable': async ({ pass, fail }) => {
+    if(files.length < 4){
+      return fail(`only found ${files.length} modules — the surface list is probably wrong, so this suite would pass without checking anything`);
+    }
+    pass();
+  }
+};
+
+for(const file of files){
+  const rel = path.relative(root, file).replace(/\\/g, '/');
+
+  tests[`imports ${rel}`] = async ({ pass, fail }) => {
+    let module;
+    try {
+      module = await import(pathToFileURL(file).href);
+    } catch(e) {
+      return fail(`${e.code || e.constructor.name}: ${e.message.split('\n')[0]}`);
+    }
+
+    if(isRouteHandler(file) && typeof module.default !== 'function'){
+      return fail(`route handler has no default export function (got ${typeof module.default})`);
+    }
+
+    pass();
+  };
+}
+
+export default tests;

package/tests/package-invariants.node-test.js

@@ -0,0 +1,247 @@
+import { readFile, readdir } from 'fs/promises';
+import { existsSync, readdirSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { builtinModules } from 'module';
+
+/*
+  Static checks for the packaging mistakes that do not surface until something else breaks.
+
+  Each of these corresponds to a bug that actually shipped in kempo-blog, the extension this
+  package is modeled on: a package depending on itself, a dependency imported everywhere but never
+  declared, a file: specifier committed into a manifest, and relative imports climbing the wrong
+  number of directories.
+
+  The module-graph suite catches an unresolvable import only for modules it can load, which
+  excludes every browser module and the standalone scripts. These run over the source text
+  instead, so public/components and admin/ are covered too.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/*
+  public/ and admin/ ship inside this package and are served in place by the host, so their imports
+  are checked here as well.
+*/
+const SOURCE_DIRS = ['server', 'hooks', 'public', 'admin', 'scripts', 'tests'];
+
+const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+
+const DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+  'optionalDependencies',
+];
+
+const declared = new Set(
+  DEPENDENCY_FIELDS.flatMap(field => Object.keys(pkg[field] || {}))
+);
+
+const builtins = new Set(builtinModules);
+
+/*
+  How the absolute URLs the browser requests map back onto files. These mirror the host's
+  customRoutes plus this package's own public-scope mount. Longest prefix first, so
+  /kempo-ui/icons/ wins over /kempo-ui/. /admin/** is intentionally absent: those are links into
+  the host's admin portal, which does not exist in this checkout.
+*/
+const BROWSER_ROUTES = [
+  ['/kempo-ui/icons/', ['node_modules/kempo-ui/icons']],
+  ['/kempo-ui/', ['node_modules/kempo-ui/dist']],
+  ['/kempo-css/', ['node_modules/kempo-css/dist']],
+  ['/kempo/', ['node_modules/kempo/dist/kempo']],
+  // This package is mounted at its public-scope, so /kempo-media/** is its own public/ directory
+  ['/kempo-media/', ['public']],
+];
+
+const walk = async (dir, extensions = ['.js']) => {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for(const entry of entries){
+    const full = path.join(dir, entry.name);
+    if(entry.isDirectory()){
+      files.push(...await walk(full, extensions));
+    } else if(extensions.some(ext => entry.name.endsWith(ext))){
+      files.push(full);
+    }
+  }
+  return files;
+};
+
+const files = (await Promise.all(SOURCE_DIRS.map(d => walk(path.join(root, d))))).flat();
+
+// Commented-out imports are still imports as far as a regex is concerned
+const stripComments = source => source
+  .replace(/\/\*[\s\S]*?\*\//g, '')
+  .replace(/^[ \t]*\/\/.*$/gm, '');
+
+/*
+  Matches `from '…'`, `import '…'` and `import('…')`. The lookbehind keeps method calls that happen
+  to end in those words — Buffer.from('…') above all — from being read as imports.
+*/
+const SPECIFIER = /(?<![.\w])(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g;
+
+const specifiersFor = source => [...stripComments(source).matchAll(SPECIFIER)].map(m => m[1]);
+
+const packageNameOf = specifier => {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+};
+
+const sources = new Map(
+  await Promise.all(files.map(async f => [f, await readFile(f, 'utf8')]))
+);
+
+const rel = file => path.relative(root, file).replace(/\\/g, '/');
+
+/*
+  Walks a relative specifier one segment at a time, checking each against the real directory
+  listing. existsSync cannot do this on Windows or macOS: their filesystems are case-insensitive,
+  so an import of TcExportCSV.js happily resolves to TcExportCsv.js locally and then 404s on Linux.
+  Returns null when the specifier is fine, or a description of what is wrong.
+*/
+const resolveCaseExact = (fromDir, specifier) => {
+  let dir = fromDir;
+  const segments = specifier.split('/').filter(s => s !== '' && s !== '.');
+  for(const [i, segment] of segments.entries()){
+    if(segment === '..'){
+      dir = path.dirname(dir);
+      continue;
+    }
+    const last = i === segments.length - 1;
+    let listing;
+    try {
+      listing = readdirSync(dir);
+    } catch {
+      return `${dir} is not a directory`;
+    }
+    // Extensionless imports may resolve to name.js or name/index.js
+    const candidates = last ? [segment, `${segment}.js`] : [segment];
+    const match = candidates.find(c => listing.includes(c));
+    if(!match){
+      const insensitive = listing.filter(n => candidates.some(c => n.toLowerCase() === c.toLowerCase()));
+      return insensitive.length
+        ? `case mismatch — on disk it is ${insensitive.join(', ')}`
+        : `${segment} does not exist`;
+    }
+    dir = path.join(dir, match);
+  }
+  return null;
+};
+
+export default {
+  'no dependency is declared with a file: or link: specifier': async ({ pass, fail }) => {
+    const offenders = [];
+    for(const field of DEPENDENCY_FIELDS){
+      for(const [name, spec] of Object.entries(pkg[field] || {})){
+        if(typeof spec === 'string' && /^(file|link):/.test(spec)){
+          offenders.push(`${field}.${name} = "${spec}"`);
+        }
+      }
+    }
+    if(offenders.length){
+      return fail(`a local path was committed into package.json, which encodes one machine's directory layout and leaves every other checkout with a dangling symlink — use \`npm run link:local\` instead:\n    ${offenders.join('\n    ')}`);
+    }
+    pass();
+  },
+
+  'the package does not depend on itself': async ({ pass, fail }) => {
+    const offenders = DEPENDENCY_FIELDS
+      .filter(field => pkg[field]?.[pkg.name])
+      .map(field => `${field}.${pkg.name} = "${pkg[field][pkg.name]}"`);
+    if(offenders.length){
+      return fail(`${pkg.name} lists itself as a dependency:\n    ${offenders.join('\n    ')}`);
+    }
+    pass();
+  },
+
+  'every imported package is declared in package.json': async ({ pass, fail }) => {
+    const missing = new Map();
+    for(const [file, source] of sources){
+      for(const specifier of specifiersFor(source)){
+        // Relative paths, absolute browser URLs and remote modules are not package imports
+        if(/^[./]/.test(specifier) || /^[a-z]+:/i.test(specifier)) continue;
+        const name = packageNameOf(specifier);
+        if(builtins.has(name) || declared.has(name)) continue;
+        if(!missing.has(name)) missing.set(name, new Set());
+        missing.get(name).add(rel(file));
+      }
+    }
+    if(missing.size){
+      const detail = [...missing].map(([name, users]) =>
+        `${name} — imported by ${[...users].slice(0, 3).join(', ')}${users.size > 3 ? ` (+${users.size - 3} more)` : ''}`
+      );
+      return fail(`imported but not declared, so it only resolves by luck of hoisting:\n    ${detail.join('\n    ')}`);
+    }
+    pass();
+  },
+
+  'every relative import resolves, matching case exactly': async ({ pass, fail }) => {
+    const broken = [];
+    for(const [file, source] of sources){
+      for(const specifier of specifiersFor(source)){
+        if(!specifier.startsWith('.')) continue;
+        const problem = resolveCaseExact(path.dirname(file), specifier);
+        if(problem) broken.push(`${rel(file)}\n      -> ${specifier}   (${problem})`);
+      }
+    }
+    if(broken.length){
+      return fail(`relative imports that do not resolve (wrong number of ../ segments, or a case mismatch that only fails on a case-sensitive filesystem):\n    ${broken.join('\n    ')}`);
+    }
+    pass();
+  },
+
+  'every absolute browser URL resolves to a file that ships': async ({ pass, fail }) => {
+    if(!existsSync(path.join(root, 'node_modules', 'kempo-ui', 'dist'))){
+      return fail('kempo-ui is not installed, so /kempo-ui/** cannot be checked — run npm install');
+    }
+
+    const htmlFiles = (await Promise.all(
+      SOURCE_DIRS.map(d => walk(path.join(root, d), ['.html']))
+    )).flat();
+
+    const references = [];
+
+    for(const [file, source] of sources){
+      for(const specifier of specifiersFor(source)){
+        if(specifier.startsWith('/')) references.push([file, specifier]);
+      }
+    }
+
+    // The outage this guards was almost entirely <script src>, not JS imports
+    for(const file of htmlFiles){
+      const source = await readFile(file, 'utf8');
+      for(const m of source.matchAll(/(?:src|href)="(\/[^"]+)"/g)){
+        references.push([file, m[1]]);
+      }
+    }
+
+    const broken = [];
+    for(const [file, specifier] of references){
+      const url = specifier.split(/[?#]/)[0];
+      /*
+        Only static assets are checked. Links like /admin/extension/<name>/ are navigation to a
+        dynamic route, not a file on disk, and are recognised by having no extension.
+      */
+      if(!path.basename(url).includes('.')) continue;
+      const route = BROWSER_ROUTES.find(([prefix]) => url.startsWith(prefix));
+      // Unmapped prefixes are the consumer's own public/ files, which do not exist in this repo
+      if(!route) continue;
+      const [prefix, roots] = route;
+      const rest = url.slice(prefix.length);
+      if(roots.some(r => existsSync(path.join(root, r, rest)))) continue;
+      broken.push(`${rel(file)}\n      -> ${url}   (looked in ${roots.join(', ')})`);
+    }
+
+    if(broken.length){
+      return fail(`absolute browser URLs that 404 at runtime. These fail silently — a module that does not load never defines its custom element, so the component simply renders nothing:\n    ${[...new Set(broken)].join('\n    ')}`);
+    }
+    pass();
+  },
+};

package/tests/permission-name-consistency.node-test.js

@@ -0,0 +1,102 @@
+import { readFile, readdir } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/*
+  kempo-blog ships this exact bug today: kempo-config.json declares an unprefixed permission
+  ("posts:create"), the server-side check uses the same unprefixed name, but both
+  public/index.page.html and admin/index.page.html gate their "New Post" button with
+  <k-permission has="kempo-blog:posts:create"> — a string that was never registered, so the gate
+  silently evaluates false for every user, including admins.
+
+  This statically cross-checks every permission literal referenced anywhere in this package against
+  the set actually declared in kempo-config.json, so the same class of bug fails CI instead of
+  shipping silently.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const kempoConfig = JSON.parse(await readFile(path.join(root, 'kempo-config.json'), 'utf8'));
+
+const declared = new Set((kempoConfig.permissions || []).map(p => p.name));
+
+const walk = async (dir, extensions) => {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for(const entry of entries){
+    const full = path.join(dir, entry.name);
+    if(entry.isDirectory()){
+      files.push(...await walk(full, extensions));
+    } else if(extensions.some(ext => entry.name.endsWith(ext))){
+      files.push(full);
+    }
+  }
+  return files;
+};
+
+const rel = file => path.relative(root, file).replace(/\\/g, '/');
+
+// currentUserHasPermission(token, 'name') — the server-side check every route uses
+const SERVER_CHECK = /currentUserHasPermission\(\s*[^,]+,\s*['"]([^'"]+)['"]\s*\)/g;
+
+// <k-permission has="name"> / all="a,b" / some="a,b"> — the admin/public UI gate
+const UI_GATE = /<k-permission\s+(?:has|all|some)="([^"]+)"/g;
+
+export default {
+  'every permission referenced in code or markup is declared in kempo-config.json': async ({ pass, fail }) => {
+    const jsFiles = await walk(path.join(root, 'public'), ['.js']);
+    jsFiles.push(...await walk(path.join(root, 'admin'), ['.js']));
+    jsFiles.push(...await walk(path.join(root, 'server'), ['.js']));
+
+    const htmlFiles = await walk(path.join(root, 'public'), ['.html']);
+    htmlFiles.push(...await walk(path.join(root, 'admin'), ['.html']));
+
+    const referenced = new Map(); // permission name -> Set of files referencing it
+
+    const record = (name, file) => {
+      if(!referenced.has(name)) referenced.set(name, new Set());
+      referenced.get(name).add(rel(file));
+    };
+
+    for(const file of jsFiles){
+      const source = await readFile(file, 'utf8');
+      for(const m of source.matchAll(SERVER_CHECK)) record(m[1], file);
+    }
+
+    for(const file of htmlFiles){
+      const source = await readFile(file, 'utf8');
+      for(const m of source.matchAll(UI_GATE)){
+        for(const name of m[1].split(',').map(s => s.trim())) record(name, file);
+      }
+    }
+
+    const undeclared = [...referenced].filter(([name]) => !declared.has(name));
+
+    if(undeclared.length){
+      const detail = undeclared.map(([name, files]) =>
+        `"${name}" — referenced in ${[...files].join(', ')} but not declared in kempo-config.json's permissions[]`
+      );
+      return fail(`permission name mismatches, which silently deny everyone regardless of role:\n    ${detail.join('\n    ')}`);
+    }
+
+    pass(`${referenced.size} referenced permission name(s), all declared`);
+  },
+
+  'every group permission is declared in kempo-config.json': async ({ pass, fail }) => {
+    const undeclared = [];
+    for(const group of kempoConfig.groups || []){
+      for(const name of group.permissions || []){
+        if(!declared.has(name)) undeclared.push(`group "${group.name}" grants "${name}", which is not declared in permissions[]`);
+      }
+    }
+    if(undeclared.length){
+      return fail(undeclared.join('\n    '));
+    }
+    pass();
+  },
+};

package/tests/uploads.node-test.js

@@ -0,0 +1,255 @@
+import { mkdtemp, rm, readFile, stat } from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import parseMultipart, { extractBoundary } from '../server/utils/uploads/parseMultipart.js';
+import storeUpload from '../server/utils/uploads/storeUpload.js';
+import generateThumbnail from '../server/utils/uploads/generateThumbnail.js';
+import { typeForFilename } from '../server/utils/uploads/fileTypes.js';
+
+/*
+  The upload path is the one place this extension handles attacker-supplied bytes and
+  attacker-supplied filenames, so these lean on the two things that actually go wrong: content
+  being corrupted on the way in, and a filename being trusted to build a path.
+*/
+
+const BOUNDARY = '----kempoMediaTestBoundary';
+
+// Bytes that are not valid UTF-8 — a PNG signature, a JPEG marker, and a lone 0xFF
+const BINARY = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+  0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0xff, 0xfe, 0xfd, 0x80
+]);
+
+const buildBody = parts => {
+  const chunks = [];
+  for(const part of parts){
+    const disposition = part.filename
+      ? `form-data; name="${part.name}"; filename="${part.filename}"`
+      : `form-data; name="${part.name}"`;
+    const headers = [`Content-Disposition: ${disposition}`];
+    if(part.contentType) headers.push(`Content-Type: ${part.contentType}`);
+    chunks.push(Buffer.from(`--${BOUNDARY}\r\n${headers.join('\r\n')}\r\n\r\n`));
+    chunks.push(Buffer.isBuffer(part.data) ? part.data : Buffer.from(part.data));
+    chunks.push(Buffer.from('\r\n'));
+  }
+  chunks.push(Buffer.from(`--${BOUNDARY}--\r\n`));
+  return Buffer.concat(chunks);
+};
+
+const withTempRoot = async fn => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'kempo-media-'));
+  try {
+    return await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+};
+
+const makePng = async () => {
+  const { default: sharp } = await import('sharp');
+  return sharp({ create: { width: 200, height: 120, channels: 3, background: { r: 200, g: 40, b: 40 } } })
+    .png()
+    .toBuffer();
+};
+
+export default {
+  'extractBoundary reads the boundary, quoted or not': async ({ pass, fail }) => {
+    if(extractBoundary(`multipart/form-data; boundary=${BOUNDARY}`) !== BOUNDARY) return fail('plain boundary');
+    if(extractBoundary(`multipart/form-data; boundary="${BOUNDARY}"`) !== BOUNDARY) return fail('quoted boundary');
+    if(extractBoundary('application/json') !== null) return fail('should reject a non-multipart content type');
+    if(extractBoundary(undefined) !== null) return fail('should tolerate a missing content type');
+    pass();
+  },
+
+  'a file part and a text field are both parsed': async ({ pass, fail }) => {
+    const body = buildBody([
+      { name: 'file', filename: 'photo.png', contentType: 'image/png', data: BINARY },
+      { name: 'alt', data: 'A red square' }
+    ]);
+    const parts = parseMultipart(body, BOUNDARY);
+    if(parts.length !== 2) return fail(`expected 2 parts, got ${parts.length}`);
+
+    const file = parts.find(p => p.name === 'file');
+    if(file?.filename !== 'photo.png') return fail(`filename wrong: ${file?.filename}`);
+    if(file?.contentType !== 'image/png') return fail(`content type wrong: ${file?.contentType}`);
+
+    const alt = parts.find(p => p.name === 'alt');
+    if(alt?.data.toString('utf8') !== 'A red square') return fail(`text field wrong: ${alt?.data}`);
+    if(alt?.filename !== null) return fail('a text field should have no filename');
+    pass();
+  },
+
+  'binary file content survives parsing byte for byte': async ({ pass, fail }) => {
+    const body = buildBody([{ name: 'file', filename: 'x.png', contentType: 'image/png', data: BINARY }]);
+    const [file] = parseMultipart(body, BOUNDARY);
+    if(!Buffer.isBuffer(file.data)) return fail(`part data is ${typeof file.data}, expected a Buffer`);
+    if(!file.data.equals(BINARY)){
+      return fail(`bytes changed\n      sent:     ${BINARY.toString('hex')}\n      received: ${file.data.toString('hex')}`);
+    }
+    pass();
+  },
+
+  'content containing CRLF is not truncated': async ({ pass, fail }) => {
+    // A naive line-based parser cuts the part short at the first CRLF inside the content
+    const data = Buffer.from('line one\r\nline two\r\n\r\nline three');
+    const body = buildBody([{ name: 'file', filename: 'a.zip', contentType: 'application/zip', data }]);
+    const [file] = parseMultipart(body, BOUNDARY);
+    if(!file.data.equals(data)) return fail(`got ${JSON.stringify(file.data.toString())}`);
+    pass();
+  },
+
+  'a body with no boundary yields nothing rather than throwing': async ({ pass, fail }) => {
+    if(parseMultipart(Buffer.from('not multipart at all'), BOUNDARY).length !== 0) return fail('expected no parts');
+    if(parseMultipart(Buffer.from(''), BOUNDARY).length !== 0) return fail('expected no parts for an empty body');
+    if(parseMultipart(Buffer.from('x'), null).length !== 0) return fail('expected no parts without a boundary');
+    pass();
+  },
+
+  'only allowed file types are accepted': async ({ pass, fail }) => {
+    for(const name of ['a.png', 'b.JPG', 'c.mp4', 'd.glb', 'e.zip', 'f.mp3']){
+      if(!typeForFilename(name)) return fail(`${name} should be allowed`);
+    }
+    for(const name of ['evil.svg', 'run.exe', 'shell.sh', 'page.html', 'noextension', 'trailing.']){
+      if(typeForFilename(name)) return fail(`${name} should be rejected`);
+    }
+    // SVG is excluded on purpose: it is served as inline unsanitised markup, so it is stored XSS
+    if(typeForFilename('logo.svg')) return fail('svg must stay rejected');
+    pass();
+  },
+
+  'an upload is written under a generated name, never the one supplied': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      const [error, asset] = await storeUpload({
+        rootDir,
+        // A filename doing its best to escape the upload directory
+        filename: '../../../../etc/passwd.png',
+        data: BINARY,
+        uploadedBy: 'user-1',
+        altText: 'traversal attempt'
+      });
+      if(error) return fail(`unexpected error: ${error.msg}`);
+
+      if(!/^media\/uploads\/[0-9a-f]{16}\.png$/.test(asset.path)){
+        return fail(`stored path is not a generated name: ${asset.path}`);
+      }
+      if(asset.originalName !== '../../../../etc/passwd.png'){
+        return fail('the original name should still be recorded for display');
+      }
+
+      const onDisk = await readFile(path.join(rootDir, asset.path));
+      if(!onDisk.equals(BINARY)) return fail('file on disk does not match the uploaded bytes');
+
+      // Nothing should exist outside the upload directory
+      const escaped = path.join(rootDir, '..', 'etc');
+      const leaked = await stat(escaped).then(() => true).catch(() => false);
+      if(leaked) return fail('a file was written outside the upload directory');
+      pass();
+    });
+  },
+
+  'an unsupported type is rejected before anything is written': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      const [error, asset] = await storeUpload({ rootDir, filename: 'payload.svg', data: BINARY, uploadedBy: 'u' });
+      if(!error) return fail('svg should have been rejected');
+      if(error.code !== 415) return fail(`expected 415, got ${error.code}`);
+      if(asset) return fail('no asset should be returned');
+
+      const uploads = path.join(rootDir, 'media', 'uploads');
+      const written = await stat(uploads).then(() => true).catch(() => false);
+      if(written) return fail('the upload directory should not have been created for a rejected type');
+      pass();
+    });
+  },
+
+  'the size limit is enforced': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      const [error] = await storeUpload({
+        rootDir,
+        filename: 'big.png',
+        data: Buffer.alloc(2048, 0x41),
+        uploadedBy: 'u',
+        maxBytes: 1024
+      });
+      if(!error) return fail('an oversized upload should be rejected');
+      if(error.code !== 413) return fail(`expected 413, got ${error.code}`);
+
+      const [okError] = await storeUpload({
+        rootDir,
+        filename: 'small.png',
+        data: Buffer.alloc(512, 0x41),
+        uploadedBy: 'u',
+        maxBytes: 1024
+      });
+      if(okError) return fail(`an upload within the limit was rejected: ${okError.msg}`);
+      pass();
+    });
+  },
+
+  'an empty upload is rejected': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      const [error] = await storeUpload({ rootDir, filename: 'x.png', data: Buffer.alloc(0), uploadedBy: 'u' });
+      if(!error) return fail('an empty file should be rejected');
+      if(error.code !== 400) return fail(`expected 400, got ${error.code}`);
+      pass();
+    });
+  },
+
+  'an image gets a thumbnail and its dimensions recorded': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      const png = await makePng();
+      const [error, asset] = await storeUpload({
+        rootDir,
+        filename: 'square.png',
+        data: png,
+        uploadedBy: 'u',
+        thumbnailMaxDimension: 64
+      });
+      if(error) return fail(`unexpected error: ${error.msg}`);
+
+      if(asset.width !== 200 || asset.height !== 120){
+        return fail(`expected the source dimensions 200x120, got ${asset.width}x${asset.height}`);
+      }
+      if(!asset.thumbnailPath) return fail('no thumbnail was recorded');
+
+      const thumb = await readFile(path.join(rootDir, asset.thumbnailPath));
+      const { default: sharp } = await import('sharp');
+      const meta = await sharp(thumb).metadata();
+      if(meta.format !== 'webp') return fail(`thumbnail is ${meta.format}, expected webp`);
+      if(meta.width > 64 || meta.height > 64) return fail(`thumbnail was not resized: ${meta.width}x${meta.height}`);
+      pass();
+    });
+  },
+
+  'a non-image kind gets no thumbnail and no sharp call': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      const [error, asset] = await storeUpload({ rootDir, filename: 'clip.mp4', data: BINARY, uploadedBy: 'u' });
+      if(error) return fail(`unexpected error: ${error.msg}`);
+      if(asset.kind !== 'video') return fail(`expected kind video, got ${asset.kind}`);
+      if(asset.thumbnailPath !== null) return fail('a video should not get a generated thumbnail');
+      if(asset.width !== null || asset.height !== null) return fail('a video should not report image dimensions');
+      pass();
+    });
+  },
+
+  'bytes that are not a real image still upload, just without a preview': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      // Named .png but not remotely a PNG — the upload must survive, the thumbnail need not
+      const [error, asset] = await storeUpload({ rootDir, filename: 'fake.png', data: BINARY, uploadedBy: 'u' });
+      if(error) return fail(`the upload should not fail because a thumbnail could not be made: ${error.msg}`);
+      if(asset.thumbnailPath !== null) return fail('undecodable bytes should not produce a thumbnail');
+
+      const onDisk = await readFile(path.join(rootDir, asset.path));
+      if(!onDisk.equals(BINARY)) return fail('the original file should still be stored intact');
+      pass();
+    });
+  },
+
+  'generateThumbnail reports a failure rather than throwing': async ({ pass, fail }) => {
+    await withTempRoot(async (rootDir) => {
+      const [error, data] = await generateThumbnail({ rootDir, data: BINARY, id: 'deadbeefdeadbeef' });
+      if(!error) return fail('expected an error tuple for undecodable input');
+      if(data) return fail('no data should accompany an error');
+      pass();
+    });
+  }
+};