@blamejs/core 0.7.0 → 0.7.4

package/lib/file-upload.js

@@ -0,0 +1,933 @@
+"use strict";
+/**
+ * b.fileUpload — chunked file upload primitive.
+ *
+ *   var uploads = b.fileUpload.create({
+ *     stagingDir:                 "/var/lib/myapp/uploads",
+ *     maxFileBytes:               C.BYTES.gib(2),
+ *     maxChunkBytes:              C.BYTES.mib(8),
+ *     maxStreamReassemblyBytes:   C.BYTES.mib(64),  // > this → stream onFinalize
+ *     maxStagingBytes:            C.BYTES.gib(50),
+ *     maxActiveUploadsPerActor:   5,
+ *     maxChunks:                  16384,
+ *     incompleteTtlMs:            C.TIME.hours(24),
+ *     maxIdleMs:                  C.TIME.minutes(30),
+ *     allowedFileTypes:           ["image/jpeg", "image/png", "application/pdf"],
+ *     audit:                      b.audit,
+ *     observability:              b.observability,
+ *     permissions:                b.permissions,                // optional
+ *     fileType:                   b.fileType,                    // optional — needed for allowedFileTypes
+ *     onChunk:        async function (info) { ... },             // optional per-chunk hook
+ *     onFinalize:     async function (info) { ... },             // operator decides final storage
+ *   });
+ *
+ *   // Lifecycle:
+ *   var initRv = await uploads.init({ uploadId, metadata, actor });
+ *   await uploads.acceptChunk({ uploadId, index, body, sha3, actor });
+ *   var rv = await uploads.finalize({ uploadId, manifest, actor });
+ *
+ *   // Operator dashboards:
+ *   var st = uploads.status(uploadId, { actor });            // { received, totalBytesAccepted, createdAt, ... }
+ *   var active = uploads.list({ actor });                    // active uploads for this actor
+ *   await uploads.cancelUpload(uploadId, { actor });         // operator-cancel
+ *
+ *   // Periodic cleanup (wire to b.scheduler):
+ *   await uploads.purgeIncomplete();   // → { purged, ids }
+ *
+ * Surface (returned by create):
+ *
+ *   init(opts)            → { uploadId, expiresAt, ... }
+ *                           Allocates staging dir, stores metadata + actor +
+ *                           createdAt. Required before acceptChunk. Permission-
+ *                           checked: action "fileUpload.init".
+ *
+ *   acceptChunk(opts)     → { received, totalBytesAccepted, status }
+ *                           Validates body length + per-chunk SHA3-512.
+ *                           Per-chunk hook (onChunk) runs before write.
+ *                           Permission-checked: action "fileUpload.accept".
+ *                           Idempotent on re-PUT of same (uploadId, index)
+ *                           with matching body.
+ *
+ *   finalize(opts)        → result of onFinalize (or framework default)
+ *                           Walks chunks in manifest order, verifies per-chunk
+ *                           + total SHA3-512, sniffs MIME (when fileType
+ *                           wired) and gates against allowedFileTypes, hands
+ *                           assembled buffer (or readable stream when size >
+ *                           maxStreamReassemblyBytes) to onFinalize. Removes
+ *                           staging dir on success. Permission-checked:
+ *                           action "fileUpload.finalize".
+ *
+ *   status(uploadId, opts) → { received, totalBytesAccepted, createdAt,
+ *                              lastChunkAt, metadata, expiresAt } | null
+ *                           Permission-checked: action "fileUpload.status".
+ *                           Returns null if upload not found.
+ *
+ *   list(opts)            → [{ uploadId, metadata, createdAt, lastChunkAt,
+ *                              totalBytesAccepted, actor }]
+ *                           Operator dashboards. Permission-checked: action
+ *                           "fileUpload.list". Filter by actor + since.
+ *
+ *   cancelUpload(id,opts) → { ok, uploadId }
+ *                           Force-removes staging. Permission-checked:
+ *                           action "fileUpload.cancel".
+ *
+ *   purgeIncomplete()     → { purged: N, ids: [string] }
+ *                           Reclaims staging dirs that exceeded
+ *                           incompleteTtlMs (since createdAt) OR maxIdleMs
+ *                           (since lastChunkAt). Operator wires to
+ *                           b.scheduler or triggers on-demand.
+ *
+ *   close()               → void
+ *                           Lifecycle parity with other framework primitives.
+ *
+ * Design posture:
+ *
+ *   - **init() before any chunk**: explicit lifecycle. Init records
+ *     createdAt + actor + metadata + signing key in a per-upload sidecar
+ *     so subsequent acceptChunk / finalize / status calls can authenticate
+ *     and audit consistently.
+ *
+ *   - **Framework owns chunk lifecycle**, not final storage. Operator
+ *     decides via `onFinalize` what to do with the assembled buffer
+ *     OR streamed chunks. Framework doesn't dictate the storage layer.
+ *
+ *   - **SHA3-512** is the hash. PQC-first; SHA-256 is not offered.
+ *     Per-chunk hash + total hash both verified.
+ *
+ *   - **Stream reassembly above maxStreamReassemblyBytes**: in-memory
+ *     Buffer.concat of a 2 GiB upload would OOM the process. When the
+ *     upload exceeds the threshold, finalize calls onFinalize with a
+ *     readable stream reading the chunk files in order; the body
+ *     parameter is null. Operator pipes to disk / S3 / etc.
+ *
+ *   - **MIME / file-type gate**: when allowedFileTypes is set and the
+ *     fileType primitive is wired, finalize sniffs the assembled bytes
+ *     (or first chunk for streamed uploads) and rejects if the magic
+ *     bytes don't classify into one of the allowed types. Defense
+ *     against `.exe disguised as .jpg` and similar mismatches.
+ *
+ *   - **Per-actor + total staging quotas**: maxActiveUploadsPerActor
+ *     prevents one actor from holding open dozens of uploads;
+ *     maxStagingBytes prevents the staging dir from filling the disk
+ *     across all actors. Both checked at init() time before any
+ *     filesystem allocation.
+ *
+ *   - **Permissions integration**: when `permissions` opt is wired,
+ *     every operator-facing call checks the action via
+ *     `permissions.check(actor, "fileUpload.<op>")` before acting.
+ *     Action names: init / accept / finalize / status / list / cancel.
+ *
+ *   - **Tombstone cleanup**: purgeIncomplete() walks staging entries
+ *     and reclaims those exceeding incompleteTtlMs (since createdAt)
+ *     OR maxIdleMs (since lastChunkAt — for in-flight uploads
+ *     abandoned mid-stream). Audit emission on every purge.
+ *
+ *   - **Validation errors are permanent**: chunk-hash mismatch,
+ *     oversized chunk, oversized total file, manifest verification
+ *     failure, MIME-type rejection, quota exhaustion all throw
+ *     `FileUploadError` with `permanent: true` — no retry will
+ *     succeed.
+ *
+ * Security defaults:
+ *
+ *   - Per-chunk SHA3-512 mandatory.
+ *   - Upload ID format: 1-128 chars from [A-Za-z0-9._-]; hostile
+ *     values (`..`, `/`, `\`, `\0`, glob chars) refused.
+ *   - Staging dir mode 0o700.
+ *   - allowedFileTypes default empty (no whitelist; operator opts in).
+ *     When set without fileType primitive wired, finalize throws at
+ *     create() — fail-fast on misconfig.
+ *
+ * What this primitive intentionally does NOT do:
+ *
+ *   - Resumable uploads via Range header — operator builds on top by
+ *     reading status()'s `received` indices and resuming at index N+1
+ *     client-side.
+ *   - Direct browser → S3 presigned-PUT bypass — operators with that
+ *     requirement use b.objectStore.presignedUploadUrl directly.
+ *   - Background virus scanning — onChunk hook is the integration
+ *     point. Operator wires their scanner of choice.
+ */
+
+var fs = require("node:fs");
+var path = require("node:path");
+var stream = require("node:stream");
+var atomicFile = require("./atomic-file");
+var C = require("./constants");
+var crypto = require("./crypto");
+var numericBounds = require("./numeric-bounds");
+var requestHelpers = require("./request-helpers");
+var safeBuffer = require("./safe-buffer");
+var safeJson = require("./safe-json");
+var validateOpts = require("./validate-opts");
+var { FileUploadError } = require("./framework-error");
+
+var _err = FileUploadError.factory;
+
+var DEFAULTS = Object.freeze({
+  maxFileBytes:               C.BYTES.gib(2),
+  maxChunkBytes:              C.BYTES.mib(8),
+  maxStreamReassemblyBytes:   C.BYTES.mib(64),
+  maxStagingBytes:            C.BYTES.gib(50),
+  maxActiveUploadsPerActor:   0x10,
+  maxChunks:                  0x4000,
+  incompleteTtlMs:            C.TIME.hours(24),
+  maxIdleMs:                  C.TIME.minutes(30),
+  // Empty array = no MIME allowlist gate (any type accepted).
+  allowedFileTypes:           Object.freeze([]),
+});
+
+// SHA3-512 produces 64 bytes; named here so the chunk + manifest
+// hash-shape checks read intentionally instead of as a raw 128.
+var SHA3_512_HEX_LENGTH = C.BYTES.bytes(128);
+// Cap on the bytes the per-upload sidecar files can grow to.
+var SIDECAR_MAX_BYTES = C.BYTES.kib(256);
+// Metadata cap — operators stash filename / mimeType / app-bag here.
+// 64 KiB is generous for normal use and refuses payloads that look
+// like the operator is trying to use the upload sidecar as a row store.
+var METADATA_MAX_BYTES = C.BYTES.kib(64);
+
+var UPLOAD_ID_RE = /^[A-Za-z0-9._-]+$/;
+var UPLOAD_ID_MAX_LENGTH = C.BYTES.bytes(128);
+
+function _validateUploadId(id) {
+  if (typeof id !== "string" ||
+      id.length === 0 ||
+      id.length > UPLOAD_ID_MAX_LENGTH ||
+      !UPLOAD_ID_RE.test(id)) {
+    var ID_PREVIEW_CHARS = C.BYTES.bytes(64);
+    throw _err("BAD_UPLOAD_ID",
+      "fileUpload: uploadId must be 1-128 chars matching " + UPLOAD_ID_RE +
+      " (path-traversal-hostile inputs refused before any filesystem op), got " +
+      JSON.stringify(typeof id === "string" ? id.slice(0, ID_PREVIEW_CHARS) : id));
+  }
+  return id;
+}
+
+function _validateCreateOpts(opts) {
+  validateOpts.requireObject(opts, "fileUpload.create", FileUploadError);
+  validateOpts.requireNonEmptyString(opts.stagingDir, "fileUpload.create: stagingDir", FileUploadError);
+  if (!path.isAbsolute(opts.stagingDir)) {
+    throw _err("BAD_OPT", "fileUpload.create: stagingDir must be an absolute path, got " +
+      JSON.stringify(opts.stagingDir));
+  }
+  validateOpts.optionalFunction(opts.onFinalize, "fileUpload.create: onFinalize", FileUploadError);
+  validateOpts.optionalFunction(opts.onChunk, "fileUpload.create: onChunk", FileUploadError);
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxFileBytes,
+    "fileUpload.create: maxFileBytes", FileUploadError, "BAD_OPT");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxChunkBytes,
+    "fileUpload.create: maxChunkBytes", FileUploadError, "BAD_OPT");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxStreamReassemblyBytes,
+    "fileUpload.create: maxStreamReassemblyBytes", FileUploadError, "BAD_OPT");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxStagingBytes,
+    "fileUpload.create: maxStagingBytes", FileUploadError, "BAD_OPT");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxActiveUploadsPerActor,
+    "fileUpload.create: maxActiveUploadsPerActor", FileUploadError, "BAD_OPT");
+  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.incompleteTtlMs,
+    "fileUpload.create: incompleteTtlMs", FileUploadError, "BAD_OPT");
+  numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxIdleMs,
+    "fileUpload.create: maxIdleMs", FileUploadError, "BAD_OPT");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxChunks,
+    "fileUpload.create: maxChunks", FileUploadError, "BAD_OPT");
+  validateOpts.auditShape(opts.audit, "fileUpload.create", FileUploadError);
+  validateOpts.observabilityShape(opts.observability, "fileUpload.create", FileUploadError);
+  validateOpts.optionalFunction(opts.clock, "fileUpload.create: clock", FileUploadError);
+  // allowedFileTypes — operator's MIME allowlist. Empty / undefined
+  // disables the gate. Setting it without wiring a fileType primitive
+  // is a misconfig — the gate would have nothing to enforce against.
+  validateOpts.optionalNonEmptyStringArray(opts.allowedFileTypes,
+    "fileUpload.create: allowedFileTypes", FileUploadError, "BAD_OPT");
+  if (Array.isArray(opts.allowedFileTypes) && opts.allowedFileTypes.length > 0 &&
+      (!opts.fileType || typeof opts.fileType.detect !== "function")) {
+    throw _err("BAD_OPT",
+      "fileUpload.create: allowedFileTypes is set but fileType primitive is not wired " +
+      "(pass fileType: b.fileType so the framework can sniff magic bytes at finalize)");
+  }
+  // permissions — when set, must expose check(actor, scope) → boolean.
+  validateOpts.optionalObjectWithMethod(opts.permissions, "check",
+    "fileUpload.create: permissions", FileUploadError, "BAD_OPT",
+    "must be a b.permissions instance (check fn)");
+}
+
+function create(opts) {
+  _validateCreateOpts(opts);
+  var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
+  var stagingDir              = opts.stagingDir;
+  var onFinalize              = opts.onFinalize || null;
+  var onChunk                 = opts.onChunk || null;
+  var fileType                = opts.fileType || null;
+  var permissions             = opts.permissions || null;
+  var maxFileBytes            = cfg.maxFileBytes;
+  var maxChunkBytes           = cfg.maxChunkBytes;
+  var maxStreamReassemblyBytes = cfg.maxStreamReassemblyBytes;
+  var maxStagingBytes         = cfg.maxStagingBytes;
+  var maxActiveUploadsPerActor = cfg.maxActiveUploadsPerActor;
+  var maxChunks               = cfg.maxChunks;
+  var incompleteTtlMs         = cfg.incompleteTtlMs;
+  var maxIdleMs               = cfg.maxIdleMs;
+  var allowedFileTypes        = cfg.allowedFileTypes;
+  var audit                   = opts.audit || null;
+  var clock                   = opts.clock || function () { return Date.now(); };
+
+  var _emitAudit = validateOpts.makeAuditEmitter(audit);
+  function _emitObs(name, value, labels) {
+    if (opts.observability) opts.observability.safeEvent(name, value, labels || {});
+  }
+
+  // Staging dir mode 0o700 — only the framework process reads its own
+  // staging files.
+  atomicFile.ensureDir(stagingDir, 0o700);
+
+  function _uploadDir(uploadId) { return path.join(stagingDir, uploadId); }
+  function _chunkPath(uploadId, index) { return path.join(_uploadDir(uploadId), String(index)); }
+  function _receivedPath(uploadId) { return path.join(_uploadDir(uploadId), "_received.json"); }
+  function _metaPath(uploadId) { return path.join(_uploadDir(uploadId), "_meta.json"); }
+
+  function _checkPermission(action, actor) {
+    if (!permissions) return;
+    var allowed;
+    try { allowed = permissions.check(actor, "fileUpload." + action); }
+    catch (_e) { allowed = false; }
+    if (!allowed) {
+      _emitObs("fileUpload.permission_denied", 1, { action: action });
+      throw _err("PERMISSION_DENIED",
+        "fileUpload." + action + ": actor lacks permission scope 'fileUpload." + action + "'");
+    }
+  }
+
+  function _readReceivedIndices(uploadId) {
+    var p = _receivedPath(uploadId);
+    if (!fs.existsSync(p)) return [];
+    try {
+      var raw = atomicFile.readSync(p, { maxBytes: SIDECAR_MAX_BYTES });
+      var parsed = safeJson.parse(raw.toString("utf8"));
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (_e) { return []; }
+  }
+  function _writeReceivedIndices(uploadId, indices) {
+    atomicFile.writeSync(_receivedPath(uploadId), JSON.stringify(indices), { mode: 0o600 });
+  }
+
+  function _readMeta(uploadId) {
+    var p = _metaPath(uploadId);
+    if (!fs.existsSync(p)) return null;
+    try {
+      var raw = atomicFile.readSync(p, { maxBytes: SIDECAR_MAX_BYTES });
+      return safeJson.parse(raw.toString("utf8"));
+    } catch (_e) { return null; }
+  }
+  function _writeMeta(uploadId, meta) {
+    atomicFile.writeSync(_metaPath(uploadId), JSON.stringify(meta), { mode: 0o600 });
+  }
+
+  function _actorKey(actor) {
+    // Actor identity for quota grouping. id field if present; otherwise
+    // anonymous bucket. Operators with un-id'd actors share quota.
+    return (actor && (actor.id || actor.userId)) || "_anonymous";
+  }
+
+  function _enumerateUploads() {
+    if (!fs.existsSync(stagingDir)) return [];
+    var entries;
+    try { entries = atomicFile.listDir(stagingDir, { includeStat: true }); }
+    catch (_e) { return []; }
+    var uploads = [];
+    for (var i = 0; i < entries.length; i++) {
+      var e = entries[i];
+      if (!e.isDirectory) continue;
+      var meta = _readMeta(e.name);
+      uploads.push({
+        uploadId:    e.name,
+        meta:        meta,
+        mtimeMs:     e.mtimeMs,
+      });
+    }
+    return uploads;
+  }
+
+  function _stagingTotalBytes() {
+    var uploads = _enumerateUploads();
+    var total = 0;
+    for (var i = 0; i < uploads.length; i++) {
+      total += (uploads[i].meta && uploads[i].meta.totalBytesAccepted) || 0;
+    }
+    return total;
+  }
+
+  function _activeUploadsForActor(actorId) {
+    var uploads = _enumerateUploads();
+    var count = 0;
+    for (var i = 0; i < uploads.length; i++) {
+      if (uploads[i].meta && uploads[i].meta.actorId === actorId) count += 1;
+    }
+    return count;
+  }
+
+  // ---- init ----
+
+  async function init(callerOpts) {
+    validateOpts.requireObject(callerOpts, "fileUpload.init", FileUploadError);
+    var uploadId = _validateUploadId(callerOpts.uploadId);
+    var actor    = callerOpts.actor || null;
+    var metadata = callerOpts.metadata !== undefined ? callerOpts.metadata : {};
+
+    _checkPermission("init", actor);
+
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+      throw _err("BAD_METADATA",
+        "fileUpload.init: metadata must be a plain object (operator app-bag)");
+    }
+    var metadataJson = JSON.stringify(metadata);
+    if (Buffer.byteLength(metadataJson, "utf8") > METADATA_MAX_BYTES) {
+      throw _err("METADATA_TOO_LARGE",
+        "fileUpload.init: metadata exceeds " + METADATA_MAX_BYTES + " bytes");
+    }
+
+    // Refuse re-init of an existing upload (caller-side bug).
+    if (fs.existsSync(_uploadDir(uploadId))) {
+      throw _err("UPLOAD_EXISTS",
+        "fileUpload.init: upload '" + uploadId + "' already exists; cancel or finalize first");
+    }
+
+    var actorId = _actorKey(actor);
+    if (_activeUploadsForActor(actorId) >= maxActiveUploadsPerActor) {
+      _emitObs("fileUpload.actor_quota_exceeded", 1);
+      throw _err("ACTOR_QUOTA_EXCEEDED",
+        "fileUpload.init: actor '" + actorId + "' has " + maxActiveUploadsPerActor +
+        " active uploads (cap maxActiveUploadsPerActor)");
+    }
+    if (_stagingTotalBytes() >= maxStagingBytes) {
+      _emitObs("fileUpload.staging_quota_exceeded", 1);
+      throw _err("STAGING_QUOTA_EXCEEDED",
+        "fileUpload.init: total staging exceeds " + maxStagingBytes + " bytes (maxStagingBytes)");
+    }
+
+    atomicFile.ensureDir(_uploadDir(uploadId), 0o700);
+    var now = clock();
+    var meta = {
+      uploadId:             uploadId,
+      actorId:              actorId,
+      metadata:             metadata,
+      createdAt:            now,
+      lastChunkAt:          now,
+      totalBytesAccepted:   0,
+    };
+    _writeMeta(uploadId, meta);
+    _writeReceivedIndices(uploadId, []);
+
+    _emitObs("fileUpload.init", 1);
+    _emitAudit("fileUpload.init", {
+      actor:    requestHelpers.extractActorContext(actor),
+      resource: { kind: "fileUpload", id: uploadId },
+      outcome:  "success",
+      metadata: { metadata: metadata },
+    });
+
+    return {
+      uploadId:  uploadId,
+      createdAt: now,
+      expiresAt: now + incompleteTtlMs,
+    };
+  }
+
+  // ---- acceptChunk ----
+
+  async function acceptChunk(callerOpts) {
+    validateOpts.requireObject(callerOpts, "fileUpload.acceptChunk", FileUploadError);
+    var uploadId = _validateUploadId(callerOpts.uploadId);
+    var index    = callerOpts.index;
+    var body     = callerOpts.body;
+    var sha3Hex  = callerOpts.sha3;
+    var actor    = callerOpts.actor;
+
+    _checkPermission("accept", actor);
+
+    var meta = _readMeta(uploadId);
+    if (!meta) {
+      throw _err("UNKNOWN_UPLOAD",
+        "fileUpload.acceptChunk: no init() seen for '" + uploadId + "'; call init() first");
+    }
+    if (clock() - meta.lastChunkAt > maxIdleMs) {
+      // Idle-timed-out — too much time since init or last chunk.
+      throw _err("UPLOAD_IDLE_EXPIRED",
+        "fileUpload.acceptChunk: upload '" + uploadId + "' exceeded maxIdleMs (" + maxIdleMs +
+        " ms since last chunk or init)");
+    }
+
+    if (!Number.isInteger(index) || index < 0 || index >= maxChunks) {
+      throw _err("BAD_INDEX",
+        "fileUpload.acceptChunk: index must be a non-negative integer < " + maxChunks +
+        ", got " + numericBounds.shape(index));
+    }
+    if (!Buffer.isBuffer(body)) {
+      throw _err("BAD_BODY",
+        "fileUpload.acceptChunk: body must be a Buffer, got " + typeof body);
+    }
+    if (body.length === 0) {
+      throw _err("EMPTY_CHUNK",
+        "fileUpload.acceptChunk: body is empty (0 bytes)");
+    }
+    if (body.length > maxChunkBytes) {
+      _emitObs("fileUpload.chunk_too_large", 1);
+      throw _err("CHUNK_TOO_LARGE",
+        "fileUpload.acceptChunk: chunk body is " + body.length +
+        " bytes, exceeds maxChunkBytes (" + maxChunkBytes + ")");
+    }
+    if (!safeBuffer.isHex(sha3Hex) || sha3Hex.length !== SHA3_512_HEX_LENGTH) {
+      throw _err("BAD_CHUNK_HASH",
+        "fileUpload.acceptChunk: sha3 must be a SHA3-512 hex string (" +
+        SHA3_512_HEX_LENGTH + " chars); got " +
+        (typeof sha3Hex === "string" ? sha3Hex.length + " chars" : typeof sha3Hex));
+    }
+
+    // Verify chunk hash matches the supplied header.
+    var actualHex = crypto.sha3Hash(body);
+    if (!crypto.timingSafeEqual(actualHex, sha3Hex)) {
+      _emitObs("fileUpload.chunk_hash_mismatch", 1);
+      _emitAudit("fileUpload.chunk_received", {
+        actor:    requestHelpers.extractActorContext(actor),
+        resource: { kind: "fileUpload", id: uploadId },
+        outcome:  "failure",
+        reason:   "chunk-hash-mismatch",
+        metadata: { index: index, size: body.length },
+      });
+      throw _err("CHUNK_HASH_MISMATCH",
+        "fileUpload.acceptChunk: chunk SHA3-512 mismatch — supplied does not equal computed");
+    }
+
+    // Per-chunk operator hook (e.g. virus scan, schema check). May
+    // throw to refuse the chunk.
+    if (onChunk) {
+      try {
+        await onChunk({
+          uploadId: uploadId,
+          index:    index,
+          body:     body,
+          sha3:     actualHex,
+          actor:    actor,
+          metadata: meta.metadata,
+        });
+      } catch (e) {
+        _emitObs("fileUpload.onchunk_rejected", 1);
+        _emitAudit("fileUpload.chunk_received", {
+          actor:    requestHelpers.extractActorContext(actor),
+          resource: { kind: "fileUpload", id: uploadId },
+          outcome:  "failure",
+          reason:   "onchunk-rejected",
+          metadata: { index: index, size: body.length,
+                      error: (e && e.message) || String(e) },
+        });
+        throw e;
+      }
+    }
+
+    // Idempotent re-PUT: if this index is already received with a
+    // matching body, no-op. Different body = caller bug.
+    var p = _chunkPath(uploadId, index);
+    if (fs.existsSync(p)) {
+      var existing = atomicFile.readSync(p, { maxBytes: maxChunkBytes });
+      if (crypto.timingSafeEqual(crypto.sha3Hash(existing), sha3Hex)) {
+        return {
+          received:           _readReceivedIndices(uploadId).length,
+          totalBytesAccepted: meta.totalBytesAccepted,
+          status:             "in-progress",
+          duplicate:          true,
+        };
+      }
+      throw _err("CHUNK_REUSE_MISMATCH",
+        "fileUpload.acceptChunk: chunk " + index +
+        " already received with a different body (caller-side bug; refusing overwrite)");
+    }
+
+    atomicFile.writeSync(p, body, { mode: 0o600 });
+    var receivedIndices = _readReceivedIndices(uploadId);
+    if (receivedIndices.indexOf(index) === -1) {
+      receivedIndices.push(index);
+      _writeReceivedIndices(uploadId, receivedIndices);
+    }
+
+    // Update meta.
+    meta.lastChunkAt = clock();
+    meta.totalBytesAccepted = (meta.totalBytesAccepted || 0) + body.length;
+    if (meta.totalBytesAccepted > maxFileBytes) {
+      // Reclaim staging — the upload exceeded the cap mid-stream.
+      try { fs.rmSync(_uploadDir(uploadId), { recursive: true, force: true }); }
+      catch (_e) { /* purgeIncomplete will reclaim */ }
+      _emitObs("fileUpload.file_too_large", 1);
+      throw _err("FILE_TOO_LARGE",
+        "fileUpload.acceptChunk: cumulative upload exceeded maxFileBytes (" + maxFileBytes +
+        "); upload reclaimed");
+    }
+    _writeMeta(uploadId, meta);
+
+    _emitObs("fileUpload.chunks_received", 1);
+    _emitObs("fileUpload.bytes_received", body.length);
+    _emitAudit("fileUpload.chunk_received", {
+      actor:    requestHelpers.extractActorContext(actor),
+      resource: { kind: "fileUpload", id: uploadId },
+      outcome:  "success",
+      metadata: { index: index, size: body.length },
+    });
+
+    return {
+      received:           receivedIndices.length,
+      totalBytesAccepted: meta.totalBytesAccepted,
+      status:             "in-progress",
+    };
+  }
+
+  // ---- finalize ----
+
+  function _validateManifest(manifest) {
+    validateOpts.requireObject(manifest, "fileUpload.finalize: manifest", FileUploadError);
+    if (!Array.isArray(manifest.chunks) || manifest.chunks.length === 0) {
+      throw _err("BAD_MANIFEST",
+        "fileUpload.finalize: manifest.chunks must be a non-empty array");
+    }
+    if (manifest.chunks.length > maxChunks) {
+      throw _err("TOO_MANY_CHUNKS",
+        "fileUpload.finalize: manifest declares " + manifest.chunks.length +
+        " chunks, exceeds maxChunks (" + maxChunks + ")");
+    }
+    if (!Number.isInteger(manifest.totalBytes) || manifest.totalBytes <= 0) {
+      throw _err("BAD_MANIFEST",
+        "fileUpload.finalize: manifest.totalBytes must be a positive integer");
+    }
+    if (manifest.totalBytes > maxFileBytes) {
+      throw _err("FILE_TOO_LARGE",
+        "fileUpload.finalize: manifest.totalBytes (" + manifest.totalBytes +
+        ") exceeds maxFileBytes (" + maxFileBytes + ")");
+    }
+    if (!safeBuffer.isHex(manifest.sha3) || manifest.sha3.length !== SHA3_512_HEX_LENGTH) {
+      throw _err("BAD_MANIFEST",
+        "fileUpload.finalize: manifest.sha3 must be a SHA3-512 hex string (" +
+        SHA3_512_HEX_LENGTH + " chars)");
+    }
+  }
+
+  function _verifyChunksOnDisk(uploadId, manifest) {
+    // Returns sorted chunk paths + verifies per-chunk + total hash.
+    // For small uploads we walk + concat; for large we just walk and
+    // verify, returning paths so the streaming path can read on
+    // demand.
+    var sortedChunks = manifest.chunks.slice().sort(function (a, b) {
+      return a.index - b.index;
+    });
+    var paths = [];
+    var hasher = require("node:crypto").createHash("sha3-512");
+    var totalBytes = 0;
+
+    for (var i = 0; i < sortedChunks.length; i++) {
+      var ck = sortedChunks[i];
+      if (!Number.isInteger(ck.index) || ck.index !== i) {
+        throw _err("MANIFEST_INDEX_GAP",
+          "fileUpload.finalize: chunk " + i + " in manifest has index " + ck.index +
+          " (expected " + i + " — chunk indices must be 0..N-1 contiguous)");
+      }
+      if (!safeBuffer.isHex(ck.sha3) || ck.sha3.length !== SHA3_512_HEX_LENGTH) {
+        throw _err("BAD_MANIFEST",
+          "fileUpload.finalize: chunk " + i + ".sha3 must be a SHA3-512 hex string (" +
+          SHA3_512_HEX_LENGTH + " chars)");
+      }
+      var chunkPath = _chunkPath(uploadId, ck.index);
+      if (!fs.existsSync(chunkPath)) {
+        throw _err("MISSING_CHUNK",
+          "fileUpload.finalize: chunk " + ck.index + " missing from staging");
+      }
+      var chunkBody = atomicFile.readSync(chunkPath, { maxBytes: maxChunkBytes });
+      var actualChunkHex = crypto.sha3Hash(chunkBody);
+      if (!crypto.timingSafeEqual(actualChunkHex, ck.sha3)) {
+        throw _err("CHUNK_HASH_MISMATCH",
+          "fileUpload.finalize: chunk " + ck.index +
+          " on-disk SHA3-512 doesn't match manifest");
+      }
+      paths.push(chunkPath);
+      totalBytes += chunkBody.length;
+      if (totalBytes > maxFileBytes) {
+        throw _err("FILE_TOO_LARGE",
+          "fileUpload.finalize: reassembly exceeds maxFileBytes mid-walk");
+      }
+      hasher.update(chunkBody);
+    }
+    if (totalBytes !== manifest.totalBytes) {
+      throw _err("MANIFEST_SIZE_MISMATCH",
+        "fileUpload.finalize: reassembled " + totalBytes +
+        " bytes, manifest declares " + manifest.totalBytes);
+    }
+    var totalHashHex = hasher.digest("hex");
+    if (!crypto.timingSafeEqual(totalHashHex, manifest.sha3)) {
+      throw _err("MANIFEST_HASH_MISMATCH",
+        "fileUpload.finalize: reassembled SHA3-512 doesn't match manifest.sha3");
+    }
+    return { paths: paths, totalBytes: totalBytes, totalHashHex: totalHashHex };
+  }
+
+  function _checkAllowedFileType(firstChunkBody) {
+    if (!allowedFileTypes || allowedFileTypes.length === 0) return;
+    if (!fileType) return;   // create() guards this; defensive
+    var detected = fileType.detect(firstChunkBody);
+    var detectedMime = detected && detected.mime;
+    if (!detectedMime) {
+      throw _err("MIME_NOT_DETECTED",
+        "fileUpload.finalize: could not classify magic bytes against allowedFileTypes");
+    }
+    var ok = false;
+    for (var i = 0; i < allowedFileTypes.length; i++) {
+      var allowed = allowedFileTypes[i];
+      if (allowed === detectedMime) { ok = true; break; }
+      // Wildcard support: "image/*" matches "image/png".
+      if (allowed.endsWith("/*")) {
+        var prefix = allowed.slice(0, -1);  // "image/"
+        if (detectedMime.indexOf(prefix) === 0) { ok = true; break; }
+      }
+    }
+    if (!ok) {
+      throw _err("MIME_NOT_ALLOWED",
+        "fileUpload.finalize: detected MIME '" + detectedMime +
+        "' not in allowedFileTypes (" + allowedFileTypes.join(", ") + ")");
+    }
+  }
+
+  function _streamFromChunkPaths(paths /* totalBytes */) {
+    // Sequential ReadableStream over chunk files. Operator's
+    // onFinalize reads through to wherever they're piping.
+    async function* generate() {
+      for (var i = 0; i < paths.length; i += 1) {
+        var fh = fs.createReadStream(paths[i]);
+        for await (var chunk of fh) {
+          yield chunk;
+        }
+      }
+    }
+    return stream.Readable.from(generate(), { objectMode: false });
+  }
+
+  async function finalize(callerOpts) {
+    validateOpts.requireObject(callerOpts, "fileUpload.finalize", FileUploadError);
+    var uploadId = _validateUploadId(callerOpts.uploadId);
+    var manifest = callerOpts.manifest;
+    var actor    = callerOpts.actor;
+
+    _checkPermission("finalize", actor);
+
+    var meta = _readMeta(uploadId);
+    if (!meta) {
+      throw _err("UNKNOWN_UPLOAD",
+        "fileUpload.finalize: no init() seen for '" + uploadId + "'");
+    }
+
+    _validateManifest(manifest);
+
+    var verified = _verifyChunksOnDisk(uploadId, manifest);
+
+    // Decide buffer-vs-stream based on size.
+    var useStream = verified.totalBytes > maxStreamReassemblyBytes;
+    var bodyBuffer = null;
+    var bodyStream = null;
+    var firstChunk = null;
+
+    if (useStream) {
+      // Read just the first chunk for the MIME sniff; the operator
+      // gets the stream for the actual data.
+      firstChunk = atomicFile.readSync(verified.paths[0], { maxBytes: maxChunkBytes });
+      bodyStream = _streamFromChunkPaths(verified.paths, verified.totalBytes);
+    } else {
+      // Small enough to assemble in memory. Buffer.concat.
+      var pieces = [];
+      for (var i = 0; i < verified.paths.length; i++) {
+        pieces.push(atomicFile.readSync(verified.paths[i], { maxBytes: maxChunkBytes }));
+      }
+      bodyBuffer = Buffer.concat(pieces, verified.totalBytes);
+      firstChunk = pieces[0];
+    }
+
+    // MIME allowlist gate (if configured).
+    try { _checkAllowedFileType(firstChunk); }
+    catch (e) {
+      _emitObs("fileUpload.mime_rejected", 1);
+      _emitAudit("fileUpload.finalize", {
+        actor:    requestHelpers.extractActorContext(actor),
+        resource: { kind: "fileUpload", id: uploadId },
+        outcome:  "failure",
+        reason:   "mime-not-allowed",
+        metadata: { size: verified.totalBytes,
+                    error: (e && e.message) || String(e) },
+      });
+      throw e;
+    }
+
+    // Hand to operator's onFinalize.
+    var rv;
+    try {
+      if (onFinalize) {
+        rv = await onFinalize({
+          uploadId: uploadId,
+          body:     bodyBuffer,
+          stream:   bodyStream,
+          sha3:     verified.totalHashHex,
+          size:     verified.totalBytes,
+          actor:    actor,
+          metadata: meta.metadata,
+        });
+      } else {
+        rv = { ok: true, sha3: verified.totalHashHex, size: verified.totalBytes };
+      }
+    } catch (e) {
+      _emitObs("fileUpload.finalize_failure", 1);
+      _emitAudit("fileUpload.finalize", {
+        actor:    requestHelpers.extractActorContext(actor),
+        resource: { kind: "fileUpload", id: uploadId },
+        outcome:  "failure",
+        reason:   "onfinalize-threw",
+        metadata: { size: verified.totalBytes, sha3: verified.totalHashHex,
+                    error: (e && e.message) || String(e) },
+      });
+      throw e;
+    }
+
+    // Cleanup staging on success.
+    try { fs.rmSync(_uploadDir(uploadId), { recursive: true, force: true }); }
+    catch (_e) { /* best-effort */ }
+
+    _emitObs("fileUpload.finalize_success", 1);
+    _emitObs("fileUpload.finalize_bytes", verified.totalBytes);
+    _emitAudit("fileUpload.finalize", {
+      actor:    requestHelpers.extractActorContext(actor),
+      resource: { kind: "fileUpload", id: uploadId },
+      outcome:  "success",
+      metadata: { size: verified.totalBytes, sha3: verified.totalHashHex,
+                  mode: useStream ? "stream" : "buffer" },
+    });
+
+    return rv;
+  }
+
+  // ---- status / list / cancel ----
+
+  function status(uploadId, callerOpts) {
+    callerOpts = callerOpts || {};
+    _validateUploadId(uploadId);
+    _checkPermission("status", callerOpts.actor);
+    var meta = _readMeta(uploadId);
+    if (!meta) return null;
+    var indices = _readReceivedIndices(uploadId).slice().sort(function (a, b) { return a - b; });
+    return {
+      uploadId:           uploadId,
+      received:           indices,
+      totalBytesAccepted: meta.totalBytesAccepted || 0,
+      createdAt:          meta.createdAt,
+      lastChunkAt:        meta.lastChunkAt,
+      metadata:           meta.metadata || {},
+      expiresAt:          meta.createdAt + incompleteTtlMs,
+    };
+  }
+
+  function list(callerOpts) {
+    callerOpts = callerOpts || {};
+    _checkPermission("list", callerOpts.actor);
+    var actorFilter = callerOpts.actor && (callerOpts.actor.id || callerOpts.actor.userId);
+    var sinceMs     = (typeof callerOpts.since === "number") ? callerOpts.since : 0;
+    var uploads     = _enumerateUploads();
+    var out = [];
+    for (var i = 0; i < uploads.length; i++) {
+      var u = uploads[i];
+      if (!u.meta) continue;
+      if (sinceMs && u.meta.createdAt < sinceMs) continue;
+      if (actorFilter && callerOpts.scopeToActor !== false && u.meta.actorId !== actorFilter) continue;
+      out.push({
+        uploadId:           u.meta.uploadId,
+        actorId:            u.meta.actorId,
+        metadata:           u.meta.metadata || {},
+        createdAt:          u.meta.createdAt,
+        lastChunkAt:        u.meta.lastChunkAt,
+        totalBytesAccepted: u.meta.totalBytesAccepted || 0,
+      });
+    }
+    return out;
+  }
+
+  async function cancelUpload(uploadId, callerOpts) {
+    callerOpts = callerOpts || {};
+    _validateUploadId(uploadId);
+    _checkPermission("cancel", callerOpts.actor);
+    var meta = _readMeta(uploadId);
+    if (!meta) return { ok: false, uploadId: uploadId, reason: "not-found" };
+    try { fs.rmSync(_uploadDir(uploadId), { recursive: true, force: true }); }
+    catch (_e) { /* best-effort */ }
+    _emitObs("fileUpload.cancelled", 1);
+    _emitAudit("fileUpload.cancelled", {
+      actor:    requestHelpers.extractActorContext(callerOpts.actor),
+      resource: { kind: "fileUpload", id: uploadId },
+      outcome:  "success",
+      metadata: { totalBytesAccepted: meta.totalBytesAccepted || 0 },
+    });
+    return { ok: true, uploadId: uploadId };
+  }
+
+  // ---- purgeIncomplete ----
+
+  function purgeIncomplete() {
+    if (!fs.existsSync(stagingDir)) return { purged: 0, ids: [] };
+    var now = clock();
+    var entries;
+    try { entries = atomicFile.listDir(stagingDir, { includeStat: true }); }
+    catch (_e) { return { purged: 0, ids: [] }; }
+    var purged = [];
+    for (var i = 0; i < entries.length; i++) {
+      var e = entries[i];
+      if (!e.isDirectory) continue;
+      var meta = _readMeta(e.name);
+      var purgeReason = null;
+      if (meta) {
+        if (now - meta.createdAt > incompleteTtlMs) purgeReason = "ttl-exceeded";
+        else if (now - meta.lastChunkAt > maxIdleMs) purgeReason = "idle-exceeded";
+      } else {
+        // No meta sidecar → orphaned dir from a prior version or
+        // failed init. Reclaim by mtime.
+        if (now - e.mtimeMs > incompleteTtlMs) purgeReason = "orphan";
+      }
+      if (!purgeReason) continue;
+      try {
+        fs.rmSync(e.fullPath, { recursive: true, force: true });
+        purged.push({ id: e.name, reason: purgeReason });
+      } catch (_e2) { /* best-effort; will retry */ }
+    }
+    if (purged.length > 0) {
+      _emitObs("fileUpload.purged_incomplete", purged.length);
+      _emitAudit("fileUpload.purged", {
+        actor:    { kind: "framework" },
+        resource: { kind: "fileUpload", id: stagingDir },
+        outcome:  "success",
+        metadata: { purgedIds: purged.map(function (p) { return p.id; }),
+                    count: purged.length },
+      });
+    }
+    return {
+      purged: purged.length,
+      ids:    purged.map(function (p) { return p.id; }),
+      reasons: purged,
+    };
+  }
+
+  function close() {
+    // Lifecycle parity. No timers / connections to release.
+  }
+
+  return {
+    init:             init,
+    acceptChunk:      acceptChunk,
+    finalize:         finalize,
+    status:           status,
+    list:             list,
+    cancelUpload:     cancelUpload,
+    purgeIncomplete:  purgeIncomplete,
+    close:            close,
+  };
+}
+
+module.exports = {
+  create:           create,
+  FileUploadError:  FileUploadError,
+  DEFAULTS:         DEFAULTS,
+  UPLOAD_ID_RE:     UPLOAD_ID_RE,
+};