@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/lib/durable.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+/**
+ * Writes that survive a power cut.
+ *
+ * `fs.writeFile` returns once the bytes are in the page cache. On a capture
+ * station — a machine that loses mains power as a matter of routine — that is
+ * not the same as "the file exists". Both facts a bind depends on, the private
+ * key and the config that points at it, must be on stable storage before
+ * anything is allowed to destroy their predecessor.
+ *
+ * The failure this exists to prevent is specific and unrecoverable. The
+ * migration tool used to be the wrong way round: the only `fsync` in the whole
+ * SDK forced the *zero-fill of the plaintext PEM*, while the DPAPI blob that
+ * replaced it and the config that pointed at it were both left to the lazy
+ * writer. A power cut seconds after a successful migration could therefore make
+ * the destruction durable and the creation not — losing the one secret in the
+ * system that cannot be regenerated, and leaving the user no repair but a
+ * manual re-bind in the web console.
+ *
+ * Directory entries need their own flush: on most filesystems the metadata that
+ * makes a name point at an inode is journalled on a different schedule than the
+ * data, so a file can be durable while the directory still does not list it.
+ * That flush is best-effort — on Windows a directory cannot be opened for
+ * fsync at all, and there the rename is already ordered by the NTFS log.
+ */
+
+/** Creates a file, refusing to overwrite, and returns only once it is durable. */
+async function writeFileDurable(filePath, contents, { mode = 0o600, flag = 'wx' } = {}) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  let handle;
+  try {
+    handle = await fsp.open(filePath, flag, mode);
+    await handle.write(contents, 0, contents.length, 0);
+    await handle.sync();
+  } finally {
+    if (handle) await handle.close();
+  }
+  await syncDirectory(path.dirname(filePath));
+}
+
+/**
+ * Atomically replaces `targetPath`, durably.
+ *
+ * The temp file is flushed *before* the rename, not after: a rename that lands
+ * before its own payload does is exactly how an atomic replace turns into a
+ * zero-length file.
+ */
+async function replaceFileDurable(targetPath, contents, temporaryPath, { mode = 0o600 } = {}) {
+  await fsp.mkdir(path.dirname(targetPath), { recursive: true });
+  let handle;
+  try {
+    handle = await fsp.open(temporaryPath, 'wx', mode);
+    await handle.write(contents, 0, contents.length, 0);
+    await handle.sync();
+  } finally {
+    if (handle) await handle.close();
+  }
+  await fsp.rename(temporaryPath, targetPath);
+  await syncDirectory(path.dirname(targetPath));
+}
+
+/** Best-effort; see the module comment for why it cannot be required. */
+async function syncDirectory(directoryPath) {
+  let handle;
+  try {
+    handle = await fsp.open(directoryPath, 'r');
+    await handle.sync();
+  } catch (_) {
+    /* not supported on this platform or filesystem */
+  } finally {
+    if (handle) {
+      try {
+        await handle.close();
+      } catch (_) {
+        /* best effort */
+      }
+    }
+  }
+}
+
+module.exports = { writeFileDurable, replaceFileDurable, syncDirectory };

package/lib/errors.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * The only error type this SDK throws.
+ *
+ * `kind` is the stable programmatic discriminator; `message` is for humans and
+ * is never assembled from credential material. Anything that could carry a
+ * secret (assertion JWT, access token, private key bytes, DPoP proof) is
+ * deliberately absent from every field here — callers routinely log this object
+ * wholesale, and a single interpolated token would turn a log file into a
+ * credential store.
+ */
+class MeteorCloudError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'MeteorCloudError';
+    /**
+     * validation | io | transport | device_api | auth | keystore | cancelled
+     */
+    this.kind = options.kind || 'validation';
+    this.httpStatus = options.httpStatus;
+    /** Device API stable business code (`code` in the CommonResult envelope). */
+    this.apiCode = options.apiCode;
+    /** RFC 6749 `error` value when the failure came from the token endpoint. */
+    this.oauthError = options.oauthError;
+    this.retryable = Boolean(options.retryable);
+    this.retryAfterSeconds = options.retryAfterSeconds;
+    this.action = options.action;
+    /**
+     * Where a completed-but-unenriched bind left its config, so a caller can
+     * recover programmatically.
+     *
+     * Deliberately absent from both `message` and `toSafeObject()`: an
+     * absolute path carries the local account name, `message` is the string
+     * callers log most reliably, and `toSafeObject()` is documented as safe
+     * to write into evidence files. Read it off the error instead.
+     */
+    this.configPath = options.configPath;
+    if (options.cause !== undefined) this.cause = options.cause;
+  }
+
+  /**
+   * A plain object safe to log or serialise into evidence files. `cause` is
+   * intentionally dropped: it is frequently a transport error whose `message`
+   * embeds the full request URL, and query strings are outside our control.
+   */
+  toSafeObject() {
+    return {
+      name: this.name,
+      kind: this.kind,
+      httpStatus: this.httpStatus,
+      apiCode: this.apiCode,
+      oauthError: this.oauthError,
+      retryable: this.retryable,
+      retryAfterSeconds: this.retryAfterSeconds,
+      action: this.action,
+      message: this.message
+    };
+  }
+}
+
+function fail(message, options) {
+  throw new MeteorCloudError(message, options);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+module.exports = { MeteorCloudError, fail, isObject };

package/lib/http.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const { Readable } = require('node:stream');
+
+const { MeteorCloudError, fail, isObject } = require('./errors');
+
+const MAX_CONTROL_BODY = 2 * 1024 * 1024;
+const RETRYABLE_HTTP = new Set([408, 429, 500, 502, 503, 504]);
+
+function headerValue(headers, name) {
+  if (!headers) return undefined;
+  if (typeof headers.get === 'function') return headers.get(name) || undefined;
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === wanted && value !== undefined && value !== null) return String(value);
+  }
+  return undefined;
+}
+
+function retryAfterSeconds(headers) {
+  const raw = headerValue(headers, 'retry-after');
+  if (!raw) return undefined;
+  if (/^[0-9]+$/.test(raw.trim())) return Math.min(Number(raw.trim()), 3600);
+  const date = Date.parse(raw);
+  if (!Number.isFinite(date)) return undefined;
+  return Math.max(0, Math.min(Math.ceil((date - Date.now()) / 1000), 3600));
+}
+
+async function readLimitedResponse(response, limit) {
+  if (!response.body || typeof response.body.getReader !== 'function') {
+    const body = Buffer.from(await response.arrayBuffer());
+    if (body.length > limit) fail('response body exceeds the accepted limit', { kind: 'transport' });
+    return body;
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const item = await reader.read();
+    if (item.done) break;
+    total += item.value.byteLength;
+    if (total > limit) {
+      await reader.cancel();
+      fail('response body exceeds the accepted limit', { kind: 'transport' });
+    }
+    chunks.push(Buffer.from(item.value));
+  }
+  return Buffer.concat(chunks, total);
+}
+
+/**
+ * The one place this SDK touches the network.
+ *
+ * `request.bodyStream` is a *factory*, not a stream: a chunk PUT that has to be
+ * retried needs fresh bytes from the same file offset, and a consumed stream
+ * cannot supply them. `Content-Length` is always set by the caller because the
+ * chunked data plane rejects a body whose length it cannot pin down in advance.
+ */
+async function defaultTransport(request) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), request.timeoutMs);
+  // Held so the file handle can be closed when `fetch` never consumes it.
+  // `Readable.toWeb` does not adopt the fd's lifetime: if the request fails
+  // before the body is read — connection refused, TLS failure, or the abort
+  // above firing, which a 32 MiB chunk on a slow link can hit — the
+  // ReadStream is simply dropped, and an fs.ReadStream has no finalizer. Five
+  // chunk attempts per artifact per event turns that into EMFILE on an
+  // unattended station within a day, and every leaked handle pins the media
+  // file's inode, so rotating the recording never reclaims the disk either.
+  let bodySource = null;
+  try {
+    const init = {
+      method: request.method,
+      headers: request.headers,
+      redirect: 'manual',
+      signal: controller.signal
+    };
+    if (typeof request.bodyStream === 'function') {
+      bodySource = request.bodyStream();
+      init.body = Readable.toWeb(bodySource);
+      init.duplex = 'half';
+    } else if (request.method !== 'GET' && request.body !== undefined) {
+      init.body = request.body;
+    }
+    const response = await fetch(request.url, init);
+    const body = await readLimitedResponse(response, request.maxResponseBytes || MAX_CONTROL_BODY);
+    bodySource = null;
+    return { status: response.status, headers: response.headers, body };
+  } catch (cause) {
+    if (cause instanceof MeteorCloudError) throw cause;
+    throw new MeteorCloudError('HTTP transport failed', {
+      kind: 'transport',
+      retryable: true,
+      cause
+    });
+  } finally {
+    clearTimeout(timer);
+    // Idempotent and safe on an already-consumed stream; only the failure paths
+    // above leave `bodySource` set.
+    if (bodySource) bodySource.destroy();
+  }
+}
+
+/**
+ * Full jitter exponential backoff, capped at 8s, with `Retry-After` taking
+ * precedence when the server bothered to state a figure.
+ */
+function backoffSeconds(attempt, retryAfter, random) {
+  if (Number.isFinite(retryAfter)) return Math.min(Math.max(retryAfter, 0), 3600);
+  return Math.min(0.5 * 2 ** (attempt - 1) + random() * 0.25, 8);
+}
+
+/**
+ * Decodes the yudao `CommonResult` envelope shared by every Device API endpoint.
+ * A 2xx with a non-zero `code` is still a failure — the envelope, not the status
+ * line, is the authority.
+ */
+function decodeEnvelope(response, expectedStatuses) {
+  const responseBody = Buffer.isBuffer(response.body) ? response.body : Buffer.from(response.body || '');
+  if (responseBody.length > MAX_CONTROL_BODY) {
+    fail('Device API response exceeds 2 MiB', { kind: 'transport' });
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(responseBody.toString('utf8'));
+  } catch (cause) {
+    throw new MeteorCloudError('Device API returned invalid JSON', {
+      kind: 'device_api',
+      httpStatus: response.status,
+      retryable: RETRYABLE_HTTP.has(response.status),
+      retryAfterSeconds: retryAfterSeconds(response.headers),
+      cause
+    });
+  }
+  // Valid JSON is not necessarily an envelope. A literal `null`, a bare string
+  // or a number all parse, and reaching into them for `.msg` throws a raw
+  // TypeError — which escapes the contract that MeteorCloudError is the only
+  // error this SDK throws, and which `isFatalChunkError` then treats as
+  // retryable because it is not a MeteorCloudError.
+  if (!isObject(decoded)) {
+    throw new MeteorCloudError('Device API returned a non-envelope body', {
+      kind: 'device_api',
+      httpStatus: response.status,
+      retryable: RETRYABLE_HTTP.has(response.status)
+    });
+  }
+  const apiCode = Number.isInteger(decoded.code) ? decoded.code : undefined;
+  if (!expectedStatuses.has(response.status) || apiCode !== 0) {
+    const deletionAction = decoded.action || (isObject(decoded.data) && decoded.data.action);
+    const deletionStop = new Set(['capability_unavailable', 'RESOURCE_DISABLED', 'RESOURCE_DELETED', 'RESOURCE_RECREATION_REQUIRED',
+      'UPLOAD_GENERATION_STALE', 'DELETION_SCOPE_REQUIRED', 'DELETION_PREVIEW_STALE', 'IDEMPOTENCY_CONFLICT']);
+    const retryable = RETRYABLE_HTTP.has(response.status) && !deletionStop.has(deletionAction);
+    throw new MeteorCloudError(
+      typeof decoded.msg === 'string' && decoded.msg ? decoded.msg : 'Device API rejected the request',
+      {
+        kind: 'device_api',
+        httpStatus: response.status,
+        apiCode,
+        retryable,
+        retryAfterSeconds: retryAfterSeconds(response.headers),
+        action:
+          typeof decoded.action === 'string'
+            ? decoded.action
+            : isObject(decoded.data) && typeof decoded.data.action === 'string'
+              ? decoded.data.action
+              : undefined
+      }
+    );
+  }
+  if (!isObject(decoded.data) && typeof decoded.data !== 'boolean') {
+    fail('Device API success envelope omitted data', {
+      kind: 'device_api',
+      httpStatus: response.status
+    });
+  }
+  return decoded.data;
+}
+
+module.exports = {
+  MAX_CONTROL_BODY,
+  RETRYABLE_HTTP,
+  headerValue,
+  retryAfterSeconds,
+  readLimitedResponse,
+  defaultTransport,
+  backoffSeconds,
+  decodeEnvelope
+};

package/lib/jobs.js

@@ -0,0 +1,54 @@
+"use strict";
+
+const { fail, isObject } = require('./errors');
+
+const MIN_POLL = 10;
+const MAX_POLL = 300;
+const compatible = (version) => typeof version === 'string' && /^mlc\.device-job-status\/2(?:\.[0-9]+)*$/.test(version);
+
+// Capability failure stops polling, never an otherwise valid upload.
+function jobCapability(data) {
+  const source = data?.capabilities?.jobQuery;
+  const minimum = source?.minimumPollSeconds;
+  const supported = isObject(source) && source.supported === true;
+  return Object.freeze({
+    observed: true, supported,
+    compatible: supported && compatible(source.contractVersion) &&
+      Number.isInteger(minimum) && minimum >= MIN_POLL && minimum <= MAX_POLL,
+    contractVersion: typeof source?.contractVersion === 'string' ? source.contractVersion : '',
+    minimumPollSeconds: Number.isInteger(minimum) ? minimum : MIN_POLL
+  });
+}
+
+function parseJob(data, jobUid, pollFloor = MIN_POLL) {
+  const invalid = () => fail('job response violates mlc.device-job-status/2', {
+    kind: 'device_api', httpStatus: 200, action: 'contract_invalid'
+  });
+  if (!isObject(data) || !compatible(data.contractVersion) || data.jobUid !== jobUid) invalid();
+  for (const key of ['uploadUid', 'submissionStatus', 'jobStatus', 'resultStatus', 'updatedAt']) {
+    if (typeof data[key] !== 'string' || !data[key]) invalid();
+  }
+  if (typeof data.terminal !== 'boolean' || typeof data.resultFinal !== 'boolean' ||
+      data.terminal !== data.resultFinal) invalid();
+  const next = data.nextPollAfterSeconds;
+  if (data.resultFinal ? next != null : !Number.isInteger(next) || next < pollFloor || next > MAX_POLL) invalid();
+  for (const key of ['attemptCount', 'requeueCount']) {
+    if (data[key] != null && (!Number.isSafeInteger(data[key]) || data[key] < 0)) invalid();
+  }
+  for (const key of ['reasonCode', 'reasonMessage', 'pipelineEventId', 'solutionKind', 'solverName']) {
+    if (data[key] != null && typeof data[key] !== 'string') invalid();
+  }
+  if (data.accepted != null && typeof data.accepted !== 'boolean') invalid();
+  if (data.result != null && !isObject(data.result)) invalid();
+  return data;
+}
+
+function jobErrorAction(error) {
+  return ({
+    1030002006: 'rate_limited', 1030003018: 'job_query_not_enabled',
+    1030004000: 'job_unavailable', 1030004002: 'job_expired',
+    1030004003: 'job_request_invalid'
+  })[error.apiCode] || (error.retryable ? 'retry' : error.httpStatus === 200 ? 'contract_invalid' : undefined);
+}
+
+module.exports = { jobCapability, parseJob, jobErrorAction };

package/lib/jose.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+const { fail, isObject } = require('./errors');
+
+const ES256 = 'ES256';
+const P256_CRV = 'P-256';
+
+function base64UrlEncode(input) {
+  return Buffer.from(input).toString('base64url');
+}
+
+function base64UrlEncodeJson(value) {
+  return base64UrlEncode(Buffer.from(JSON.stringify(value), 'utf8'));
+}
+
+function base64UrlDecode(value) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]*$/.test(value)) {
+    fail('value is not base64url');
+  }
+  return Buffer.from(value, 'base64url');
+}
+
+/**
+ * A cryptographically random base64url token. 32 bytes is the floor for PKCE
+ * verifiers (RFC 7636 §7.1) and is reused for `state` and every `jti`.
+ */
+function randomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+/**
+ * RFC 7636 S256: challenge = base64url(SHA-256(ASCII(verifier))).
+ */
+function pkceChallengeS256(verifier) {
+  if (typeof verifier !== 'string' || !/^[A-Za-z0-9\-._~]{43,128}$/.test(verifier)) {
+    fail('PKCE verifier must be 43-128 unreserved characters');
+  }
+  return crypto.createHash('sha256').update(verifier, 'ascii').digest('base64url');
+}
+
+function createPkcePair(randomBytes = crypto.randomBytes) {
+  const verifier = Buffer.from(randomBytes(32)).toString('base64url');
+  return { verifier, challenge: pkceChallengeS256(verifier), method: 'S256' };
+}
+
+/**
+ * The public half of a P-256 key as a JWK whose members are in the exact
+ * lexicographic order RFC 7638 requires. Node's own `export({format:'jwk'})`
+ * emits `{kty,x,y,crv}`, which hashes to the wrong thumbprint, so the object is
+ * rebuilt here rather than reordered downstream.
+ */
+function p256PublicJwk(key) {
+  const publicKey = key.type === 'public' ? key : crypto.createPublicKey(key);
+  const jwk = publicKey.export({ format: 'jwk' });
+  if (jwk.kty !== 'EC' || jwk.crv !== P256_CRV || !jwk.x || !jwk.y) {
+    fail('key is not a P-256 public key');
+  }
+  return { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y };
+}
+
+/**
+ * RFC 7638 JWK thumbprint, base64url SHA-256 — the same value Nimbus computes
+ * for `cnf.jkt` on the server, so DPoP binding compares equal byte for byte.
+ */
+function jwkThumbprint(jwk) {
+  if (!isObject(jwk) || jwk.kty !== 'EC') fail('thumbprint requires an EC JWK');
+  const canonical = JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y });
+  return crypto.createHash('sha256').update(canonical, 'utf8').digest('base64url');
+}
+
+/**
+ * Assembles a compact JWS. `sign` receives the exact signing input bytes and
+ * must return the 64-byte raw (IEEE P1363) ECDSA signature — never a key.
+ * Keeping the signature callback abstract is what lets a future CNG/TPM backend
+ * drop in without the private key ever entering the JS heap.
+ */
+async function signCompactJws(header, claims, sign) {
+  const signingInput = `${base64UrlEncodeJson(header)}.${base64UrlEncodeJson(claims)}`;
+  const signature = await sign(Buffer.from(signingInput, 'ascii'));
+  if (!Buffer.isBuffer(signature) || signature.length !== 64) {
+    fail('ES256 signer must return a 64-byte IEEE P1363 signature', { kind: 'keystore' });
+  }
+  return `${signingInput}.${signature.toString('base64url')}`;
+}
+
+/**
+ * RFC 7523 client assertion for `private_key_jwt`.
+ *
+ * `aud` is the absolute token endpoint URL; the server chains SAS's own
+ * validator (iss/sub/aud/exp) with a max-age check of `exp - iat`, so the 60
+ * second window below is a contract value, not a preference.
+ */
+function buildAssertionClaims({ installationUid, tokenEndpoint, now, lifetimeSeconds, jti }) {
+  return {
+    iss: installationUid,
+    sub: installationUid,
+    aud: tokenEndpoint,
+    exp: now + lifetimeSeconds,
+    iat: now,
+    jti
+  };
+}
+
+/**
+ * RFC 9449 DPoP proof. `ath` is present only for resource requests: the token
+ * endpoint has no access token to hash yet, and sending a bogus one there would
+ * be a spec violation rather than harmless noise.
+ */
+function buildDpopClaims({ method, url, now, jti, accessToken }) {
+  const claims = { htm: method.toUpperCase(), htu: dpopHtu(url), iat: now, jti };
+  if (accessToken) {
+    claims.ath = crypto.createHash('sha256').update(accessToken, 'ascii').digest('base64url');
+  }
+  return claims;
+}
+
+/**
+ * RFC 9449 §4.2: `htu` is the request URI with query and fragment removed.
+ * `URL` also normalises the default port away, which matters because the server
+ * compares against its own reconstruction of the request URI.
+ */
+function dpopHtu(url) {
+  const parsed = new URL(url);
+  parsed.search = '';
+  parsed.hash = '';
+  return parsed.toString();
+}
+
+module.exports = {
+  ES256,
+  P256_CRV,
+  base64UrlEncode,
+  base64UrlEncodeJson,
+  base64UrlDecode,
+  randomToken,
+  pkceChallengeS256,
+  createPkcePair,
+  p256PublicJwk,
+  jwkThumbprint,
+  signCompactJws,
+  buildAssertionClaims,
+  buildDpopClaims,
+  dpopHtu
+};

package/lib/journal.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const { MeteorCloudError, fail, isObject } = require('./errors');
+const { assertNoSecrets } = require('./config');
+
+const JOURNAL_VERSION = 2;
+const MAX_JOURNAL_SIZE = 1024 * 1024;
+
+/**
+ * Crash-resume bookkeeping for one upload session.
+ *
+ * v2 drops the COS multipart model (UploadId + per-part ETags) for a single
+ * `offset` per artifact, because the local plane's resume unit is a byte count
+ * rather than a part list.
+ *
+ * The offset here is a **hint, not an authority**. The server's `receivedBytes`
+ * is the only value allowed to decide where the next chunk starts; this file
+ * exists so a restart can skip the status round trip for artifacts that were
+ * plainly finished, and so a human debugging a stuck upload can see what the
+ * client believed. Where the two disagree, the server wins, always.
+ *
+ * Nothing credential-shaped may be written here — `assertNoSecrets` runs on
+ * every save, so a future field carrying a token fails the write rather than
+ * quietly persisting one next to the data it protects.
+ */
+class UploadJournal {
+  constructor(journalPath, sessionUid) {
+    this.path = journalPath;
+    this.sessionUid = sessionUid;
+    this.state = { version: JOURNAL_VERSION, sessionUid, files: {} };
+  }
+
+  async load() {
+    try {
+      const stat = await fsp.lstat(this.path);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_JOURNAL_SIZE) {
+        fail('upload journal is unsafe');
+      }
+      const loaded = JSON.parse(await fsp.readFile(this.path, 'utf8'));
+      if (
+        !isObject(loaded) ||
+        loaded.version !== JOURNAL_VERSION ||
+        loaded.sessionUid !== this.sessionUid ||
+        !isObject(loaded.files)
+      ) {
+        // A journal from a different session (or a v1 COS journal) is not an
+        // error worth failing the upload over: discard it and re-derive
+        // everything from the server. Reusing it would be the dangerous choice.
+        this.state = { version: JOURNAL_VERSION, sessionUid: this.sessionUid, files: {} };
+        return this;
+      }
+      this.state = loaded;
+    } catch (error) {
+      if (error && error.code === 'ENOENT') return this;
+      if (error instanceof MeteorCloudError) throw error;
+      throw new MeteorCloudError('upload journal is invalid', { kind: 'io', cause: error });
+    }
+    return this;
+  }
+
+  /**
+   * Per-artifact state keyed by role — the addressing unit of the chunked PUT
+   * plane. `key` is the relative upload target path (the local plane has no COS
+   * object key), `size`/`sha256` pin the identity of the bytes so a changed file
+   * invalidates the offset instead of resuming into a different artifact.
+   */
+  fileState(role) {
+    if (!isObject(this.state.files[role])) {
+      this.state.files[role] = { key: '', size: 0, sha256: '', offset: 0 };
+    }
+    return this.state.files[role];
+  }
+
+  /** Resets the recorded offset when the artifact identity no longer matches. */
+  reconcile(role, identity) {
+    const state = this.fileState(role);
+    if (state.key !== identity.key || state.size !== identity.size || state.sha256 !== identity.sha256) {
+      state.key = identity.key;
+      state.size = identity.size;
+      state.sha256 = identity.sha256;
+      state.offset = 0;
+    }
+    return state;
+  }
+
+  async save() {
+    const encoded = `${JSON.stringify(this.state)}\n`;
+    if (Buffer.byteLength(encoded) > MAX_JOURNAL_SIZE) fail('upload journal exceeds 1 MiB');
+    assertNoSecrets(encoded, 'upload journal');
+    const temporary = `${this.path}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    try {
+      // Inside the try: mkdir fails for exactly the same reasons the write does
+      // (ENOSPC, EACCES, EROFS), and leaving it outside let a raw fs error
+      // escape as itself — breaking the promise that MeteorCloudError is the
+      // only error this SDK throws, and defeating every `kind === 'io'` check
+      // downstream, including the one that keeps a full disk from killing an
+      // upload that needs no disk.
+      await fsp.mkdir(path.dirname(this.path), { recursive: true });
+      await fsp.writeFile(temporary, encoded, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      await fsp.rename(temporary, this.path);
+    } catch (cause) {
+      try {
+        await fsp.rm(temporary, { force: true });
+      } catch (_) {
+        /* best effort */
+      }
+      throw new MeteorCloudError('cannot save upload journal', { kind: 'io', cause });
+    }
+  }
+}
+
+module.exports = { UploadJournal, JOURNAL_VERSION, MAX_JOURNAL_SIZE };