@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/lib/artifacts.js

@@ -0,0 +1,279 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const { MeteorCloudError, fail, isObject } = require('./errors');
+
+const ROLES = Object.freeze(['manifest', 'ecsv', 'media', 'preview']);
+const REQUIRED_ROLES = Object.freeze(['manifest', 'ecsv', 'media']);
+const ROLE_SET = new Set(ROLES);
+const MAX_ARTIFACT_SIZE = 50 * 1024 * 1024 * 1024;
+const MAX_MEDIA_SIZE = 100 * 1024 * 1024;
+/**
+ * The server's per-role ceilings (`MsCloudUploadSessionServiceImpl.validateRoleSize`).
+ * Mirrored so an oversize artifact is refused before the SDK spends a
+ * full-file SHA-256 on it and gets back an opaque
+ * `upload session request is invalid` 400 that names no role and no limit.
+ * A full-resolution PNG preview clears 20 MiB easily, so this is not exotic.
+ */
+const MAX_ROLE_SIZE = Object.freeze({
+  manifest: 1024 * 1024,
+  ecsv: 2 * 1024 * 1024 * 1024,
+  preview: 20 * 1024 * 1024,
+  media: MAX_MEDIA_SIZE
+});
+/**
+ * `MsCloudUploadSessionFileReqVO.originalFilename`, mirrored verbatim:
+ * `@Size(max = 255)` plus `@Pattern("[^\\x00\\r\\n]+")`.
+ *
+ * It used to be `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`, a rule neither the server
+ * nor the C++ SDK has — `client_impl.hpp.inc` checks non-empty, `size() > 255`
+ * and `contains_crlf_or_nul`, and nothing else. The cost was not theoretical: a
+ * Chinese filename or one with a space — `流星 2026-01-01.mp4`, which is what a
+ * capture app writes by default — was refused locally by the Node SDK while the
+ * identical event package uploaded fine from the C++ one. The value is pure
+ * metadata: `path.basename()` produces it, it is sent in the authorize body, and
+ * nothing local is built from it (the PUT URL is derived from `sessionUid` and
+ * `role`, and the journal keys off that same target path). So there is nothing
+ * for a stricter local rule to protect, and plenty for it to break.
+ *
+ * One residual difference, and it lands on the server's side: `@Size` counts
+ * Java chars and `String.length` counts UTF-16 units, so these two agree
+ * exactly, while the C++ `size()` counts UTF-8 bytes and is therefore stricter
+ * for non-ASCII. A name Node accepts and C++ refuses is one the server accepts.
+ */
+const FILENAME_MAX = 255;
+const FILENAME_RE = /^[^\0\r\n]+$/;
+/**
+ * `MsCloudUploadSessionFileReqVO.contentType`: `@Size(max = 128)` and
+ * `@Pattern("[A-Za-z0-9][A-Za-z0-9!#$&^_.+\\-/;= ]*")`, anchored here because
+ * Jakarta's `@Pattern` matches the whole value.
+ *
+ * The local check used to reject only CR, LF and NUL, so `image/*` and
+ * `text/plain; charset="utf-8"` sailed past it and came back from the server as
+ * a bare 400 `upload session request is invalid` naming neither the field nor
+ * the role — after the full-file hashing pass. The C++ SDK has applied this
+ * exact pattern and this exact ceiling all along
+ * (`client_impl.hpp.inc:1786-1791`); this is the Node half catching up.
+ */
+const CONTENT_TYPE_MAX = 128;
+const CONTENT_TYPE_RE = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+\-/;= ]*$/;
+
+/**
+ * Renders a limit the way the docs and the server write it.
+ *
+ * Only exact multiples become units. Every ceiling above is round by
+ * construction so it always renders as one, while a real file size almost never
+ * is — and a rounded "20.3 MiB" would be a number the caller cannot match
+ * against anything they were told.
+ */
+function humanBytes(bytes) {
+  const units = [
+    [1024 * 1024 * 1024, 'GiB'],
+    [1024 * 1024, 'MiB'],
+    [1024, 'KiB']
+  ];
+  for (const [unit, suffix] of units) {
+    if (bytes >= unit && bytes % unit === 0) return `${bytes / unit} ${suffix}`;
+  }
+  return `${bytes} bytes`;
+}
+
+async function sha256Path(filePath, { start = 0, end } = {}) {
+  const digest = crypto.createHash('sha256');
+  try {
+    const options = end === undefined ? { start } : { start, end };
+    const stream = fs.createReadStream(filePath, options);
+    for await (const chunk of stream) digest.update(chunk);
+    return digest.digest('hex');
+  } catch (cause) {
+    throw new MeteorCloudError(`cannot hash artifact: ${filePath}`, { kind: 'io', cause });
+  }
+}
+
+/**
+ * Hashes and measures the local artifacts that will be authorized.
+ *
+ * The digests computed here are what the server records as authoritative, and
+ * `finalize` on the local plane re-derives them from the bytes it received. A
+ * file mutated between this call and the last chunk therefore fails at finalize
+ * with an object mismatch rather than being silently ingested.
+ */
+async function describeArtifacts(artifacts) {
+  if (!Array.isArray(artifacts) || ![3, 4].includes(artifacts.length)) {
+    fail('exactly three or four artifacts are required');
+  }
+  const result = [];
+  const seen = new Set();
+  for (const artifact of artifacts) {
+    if (!isObject(artifact) || !ROLE_SET.has(artifact.role)) fail('unsupported artifact role');
+    if (seen.has(artifact.role)) fail(`duplicate artifact role: ${artifact.role}`);
+    seen.add(artifact.role);
+    if (typeof artifact.path !== 'string' || !artifact.path) fail(`artifact path is invalid: ${artifact.role}`);
+    if (
+      typeof artifact.contentType !== 'string' ||
+      artifact.contentType.length > CONTENT_TYPE_MAX ||
+      !CONTENT_TYPE_RE.test(artifact.contentType)
+    ) {
+      fail(
+        `${artifact.role} artifact contentType is invalid. The server accepts at most ` +
+          `${CONTENT_TYPE_MAX} characters matching [A-Za-z0-9][A-Za-z0-9!#$&^_.+\\-/;= ]* ` +
+          '— so no quotes, commas or asterisks: write text/plain; charset=utf-8, ' +
+          'not text/plain; charset="utf-8", and name a concrete type rather than image/*'
+      );
+    }
+    const originalFilename = path.basename(artifact.path);
+    if (originalFilename.length > FILENAME_MAX || !FILENAME_RE.test(originalFilename)) {
+      fail(
+        `${artifact.role} artifact filename is invalid: the server accepts 1 to ` +
+          `${FILENAME_MAX} characters with no NUL, CR or LF`
+      );
+    }
+    let stat;
+    try {
+      stat = await fsp.lstat(artifact.path);
+    } catch (cause) {
+      throw new MeteorCloudError(`artifact does not exist: ${artifact.role}`, { kind: 'io', cause });
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) fail(`artifact must be a regular file: ${artifact.role}`);
+    if (stat.size < 1 || stat.size > MAX_ARTIFACT_SIZE) fail(`artifact size is invalid: ${artifact.role}`);
+    const roleCeiling = MAX_ROLE_SIZE[artifact.role] ?? MAX_ARTIFACT_SIZE;
+    if (stat.size > roleCeiling) {
+      // Every role phrases the ceiling in the units the guide and the server
+      // use. A raw byte count makes the reader do arithmetic to find out
+      // whether they hit the limit they were told about.
+      fail(
+        `${artifact.role} artifact is ${humanBytes(stat.size)}; ` +
+          `the server accepts at most ${humanBytes(roleCeiling)}`
+      );
+    }
+    result.push({
+      role: artifact.role,
+      originalFilename,
+      sizeBytes: stat.size,
+      sha256: await sha256Path(artifact.path),
+      contentType: artifact.contentType
+    });
+  }
+  for (const role of REQUIRED_ROLES) {
+    if (!seen.has(role)) fail('manifest, ecsv and media roles are required');
+  }
+  return result;
+}
+
+/**
+ * The manifest is the contract between client and pipeline, so it is validated
+ * locally before a session is opened: `local_event_id` must equal the idempotency
+ * key, and the bytes on disk must equal the JSON being submitted. Without the
+ * second check a client could authorize one manifest and upload another.
+ */
+async function validateManifest(request) {
+  if (typeof request.manifestJson !== 'string') fail('manifestJson must be a string');
+  let manifest;
+  try {
+    manifest = JSON.parse(request.manifestJson);
+  } catch (cause) {
+    throw new MeteorCloudError('manifestJson is invalid JSON', { kind: 'validation', cause });
+  }
+  if (
+    !isObject(manifest) ||
+    manifest.schema !== 'mlc.manifest/2' ||
+    manifest.local_event_id !== request.clientRequestKey
+  ) {
+    fail('mlc.manifest/2 local_event_id must equal clientRequestKey');
+  }
+  const manifestArtifact = request.artifacts.find((item) => item.role === 'manifest');
+  if (!manifestArtifact) fail('a manifest artifact is required');
+  const submitted = Buffer.from(request.manifestJson, 'utf8');
+  // Compare sizes before reading. `readFile` on a path the caller mislabelled
+  // as the manifest — pointing at the media file, say — used to buffer the
+  // whole thing: straight RSS on a machine that is also capturing video, and
+  // past ~2 GiB a raw ERR_FS_FILE_TOO_LARGE rather than a MeteorCloudError.
+  // Wrapped: these are the only two unguarded fs calls on the public upload
+  // path, and they run *after* describeArtifacts has hashed every artifact —
+  // minutes, on a large event. Anything that removes, replaces or exclusively
+  // locks the manifest in that window (on Windows, the capture app reopening it
+  // with FILE_SHARE_NONE gives EBUSY) used to escape as a raw fs Error, so an
+  // integrator's `catch (e) { switch (e.kind) }` saw undefined. lib/journal.js
+  // had the same hole around mkdir and it was closed for the same reason:
+  // MeteorCloudError is promised to be the only error this SDK throws.
+  let onDisk;
+  try {
+    const onDiskSize = (await fsp.stat(manifestArtifact.path)).size;
+    if (onDiskSize !== submitted.length) {
+      fail('manifest file bytes must exactly equal manifestJson');
+    }
+    onDisk = await fsp.readFile(manifestArtifact.path);
+  } catch (cause) {
+    if (cause instanceof MeteorCloudError) throw cause;
+    throw new MeteorCloudError('cannot read the manifest artifact', { kind: 'io', cause });
+  }
+  if (onDisk.length !== submitted.length || !crypto.timingSafeEqual(onDisk, submitted)) {
+    fail('manifest file bytes must exactly equal manifestJson');
+  }
+  return manifest;
+}
+
+/**
+ * Cross-checks the digests the manifest declares against the artifacts actually
+ * being submitted.
+ *
+ * The server does this too (`validateManifestDigests`) — but it answers a
+ * mismatch with **401**, which reads as a credential failure for what is a
+ * manifest content error. The digests are already computed by the time we get
+ * here, so checking locally costs nothing and turns the most confusing error on
+ * the whole plane into a plain sentence. The usual way to hit it: switching on
+ * preview generation while the manifest writer still emits `"preview"` as `"-"`.
+ */
+function validateManifestDigests(manifest, files) {
+  const declared = isObject(manifest.files) ? manifest.files : {};
+  for (const role of ['ecsv', 'media', 'preview']) {
+    const file = files.find((item) => item.role === role);
+    const entry = declared[role];
+    const claimed = isObject(entry) ? String(entry.sha256 || '') : entry === undefined ? undefined : String(entry);
+    if (!file) {
+      // Not supplied: the manifest must say so, by omission or by "-".
+      if (claimed !== undefined && claimed !== '-' && claimed !== '') {
+        fail(`manifest declares a ${role} digest but no ${role} artifact was supplied`);
+      }
+      continue;
+    }
+    if (claimed === undefined || claimed === '-' || claimed === '') {
+      fail(`manifest omits the ${role} digest, but a ${role} artifact was supplied`);
+    }
+    if (claimed.toLowerCase() !== file.sha256) {
+      fail(`manifest ${role} sha256 does not match the file being uploaded`);
+    }
+  }
+}
+
+/**
+ * The server's own normalisation (`trim().toLowerCase()`), mirrored so a client
+ * comparing its own contentType against the echoed plan agrees with the value
+ * the server actually stored.
+ */
+function normalizeContentType(value) {
+  return typeof value === 'string' ? value.trim().toLowerCase() : value;
+}
+
+module.exports = {
+  normalizeContentType,
+  validateManifestDigests,
+  FILENAME_MAX,
+  FILENAME_RE,
+  CONTENT_TYPE_MAX,
+  CONTENT_TYPE_RE,
+  MAX_ROLE_SIZE,
+  ROLES,
+  REQUIRED_ROLES,
+  ROLE_SET,
+  MAX_ARTIFACT_SIZE,
+  MAX_MEDIA_SIZE,
+  humanBytes,
+  sha256Path,
+  describeArtifacts,
+  validateManifest
+};

package/lib/camera.js

@@ -0,0 +1,316 @@
+'use strict';
+
+const { fail, isObject } = require('./errors');
+
+/**
+ * Machine-position declaration: local validation of the `camera` block.
+ *
+ * From v0.5.0 every upload names where it came from, and the host application
+ * no longer pre-registers anything. It passes either a `camera` block (its own
+ * stable key plus the station's coordinates) or a `cameraUid` it happens to
+ * already know; the server registers on first sight and returns the uids purely
+ * as information. The SDK holds no camera list, no station list and no
+ * key-to-uid map — see contract §1.2, §7.9 and plan §0.2.
+ *
+ * This module exists because of one sentence in contract §7.6: a missing or
+ * malformed declaration is a *caller argument* error and must be caught
+ * "before reading and hashing large files". `uploadEvent` otherwise spends a
+ * full SHA-256 pass over a multi-gigabyte capture — minutes of disk on an
+ * unattended station — before the server answers 400 CAMERA_REQUIRED. So
+ * everything here is synchronous, allocation-only, and touches no file, no
+ * socket and no clock: it is safe to call as the very first statement of
+ * `uploadEvent`, ahead of `_prepareFiles`.
+ */
+
+/**
+ * Server-minted camera identifier, the same literal `index.js` uses. Duplicated
+ * rather than imported because this module must stay loadable without pulling
+ * in the client (and its keystore/transport); the integration point owns the
+ * dedupe.
+ */
+const CAMERA_RE = /^cam_[0-9a-f]{32}$/;
+
+/**
+ * The host application's own stable key for one channel (contract §7.9: "1-64
+ * safe ASCII ... no PII").
+ *
+ * Deliberately the same character class as `EVENT_RE` in `index.js`, one
+ * length-cap shorter, because it lands in the same kind of place: a database
+ * unique index, log lines, and eventually a URL path segment. Restricting it
+ * this way is what enforces the prose rules for free — no control characters
+ * (charset), no leading or trailing whitespace (whitespace is not in the
+ * charset at all), and no `@`, so the single most likely PII smuggle, an email
+ * address, cannot even be spelled.
+ *
+ * A channel name works as a key when it is ASCII; a non-ASCII one ("北向广角")
+ * does not, and the caller should keep the display string in `camera.name` and
+ * generate the key with `newCameraKey()`. Changing the key means a new camera,
+ * so it must be something the host persists, never something it re-derives.
+ */
+const CAMERA_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+
+/**
+ * Shape gate for an IANA zone id, applied *before* the runtime check below.
+ *
+ * `Intl` also accepts fixed offsets — `+08:00`, `-0500` — and those are exactly
+ * what must not reach the server: an offset has no DST rule, so every local
+ * timestamp this station reports across a transition is silently an hour wrong,
+ * and a meteor solved from multi-station timing has no tolerance for that. Zone
+ * ids start with a letter and are spelled from `[A-Za-z0-9_+/-]`, which keeps
+ * `Etc/GMT+8`, `W-SU` and `America/Argentina/Buenos_Aires` while rejecting
+ * anything beginning with a sign. 64 is the server column width
+ * (`MsCloudStationSaveReqVO.timezone`).
+ */
+const TIMEZONE_RE = /^[A-Za-z][A-Za-z0-9_+/-]{0,63}$/;
+
+/**
+ * C0 plus DEL. Names are stored and later rendered in the web console, and a
+ * stray CR or NUL in a display name is a log-forging and rendering hazard that
+ * costs nothing to refuse here. Written as a scan rather than a regex literal
+ * so the control points stay legible as code points instead of escapes.
+ */
+function hasControlChar(value) {
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/** `displayName` on both `MsCloudStationSaveReqVO` and `MsCloudCameraSaveReqVO`. */
+const MAX_NAME_LENGTH = 128;
+
+/** Contract §7.9: "1-64 safe ASCII". Kept beside `CAMERA_KEY_RE`, which encodes it. */
+const MAX_CAMERA_KEY_LENGTH = 64;
+
+/**
+ * Mirrors the admin-side bean validation the registry reuses
+ * (`MsCloudStationSaveReqVO`): latitude `@DecimalMin/-90 @DecimalMax/90`,
+ * longitude `-180/180`, elevation `@Min/-500 @Max/10000` on an `Integer`.
+ * Duplicated locally so the caller learns the bound at the call site instead of
+ * from a round trip; the server stays the authority.
+ */
+const STATION_RANGES = Object.freeze({
+  latitude: Object.freeze([-90, 90]),
+  longitude: Object.freeze([-180, 180]),
+  elevationM: Object.freeze([-500, 10000])
+});
+
+const CAMERA_FIELDS = Object.freeze(['key', 'name', 'station']);
+const STATION_FIELDS = Object.freeze(['latitude', 'longitude', 'elevationM', 'timezone', 'name']);
+
+/**
+ * Every failure in this module is the same class of failure: the caller passed
+ * something wrong, retrying it will fail identically, and no amount of waiting
+ * helps. `kind` and `retryable` are stated rather than left to `fail`'s
+ * defaults so that a later change to those defaults cannot quietly turn a
+ * caller bug into something an upload loop retries forever.
+ *
+ * The message names the field and the rule it broke and **never the value**:
+ * contract §10.1 keeps payload detail out of anything a host routinely logs,
+ * and coordinates are the location of somebody's home.
+ */
+function invalid(message) {
+  fail(message, { kind: 'validation', retryable: false });
+}
+
+/**
+ * Unknown keys are refused so a near miss cannot pass as an omission — the
+ * motivating case is `elevation` for `elevationM`, which would otherwise be
+ * dropped on the floor and re-read as "no elevation given", failing as a
+ * *missing* required field or, worse, registering a station at the wrong
+ * altitude if the field were ever optional.
+ *
+ * The offending key names are echoed only when they look like identifiers.
+ * A key is caller-authored text, and while it is structure rather than payload,
+ * there is no reason for this module to be the one that copies an arbitrary
+ * string into an error a host will log.
+ */
+function assertKnownFields(value, allowed, path) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length === 0) return;
+  const named = unknown.map((key) => (/^[A-Za-z0-9_]{1,40}$/.test(key) ? key : '<unprintable>'));
+  invalid(`${path} has unknown field(s): ${named.join(', ')}; allowed: ${allowed.join(', ')}`);
+}
+
+/**
+ * `undefined` means absent, `null` does not.
+ *
+ * `{ name: undefined }` is how JavaScript spells "I have no value for this",
+ * and the existing wire code already treats it that way (`_authorizePrepared`
+ * omits `cameraUid` on `!== undefined`). `null` is a decision, it survives
+ * `JSON.stringify`, and the server's `@NotBlank` would answer it with an opaque
+ * 400 — so it is caught here with a message that says which field.
+ */
+function isAbsent(value) {
+  return value === undefined;
+}
+
+function normalizeName(value, path) {
+  if (isAbsent(value)) return undefined;
+  if (typeof value !== 'string') invalid(`${path} must be a string when present`);
+  // Blank is refused rather than treated as absent: silently rewriting a
+  // caller's value is the behaviour this module exists to avoid, and the
+  // server's @NotBlank would reject it anyway once it reached the wire.
+  if (value.trim() === '') invalid(`${path} must not be blank; omit it instead`);
+  if (value.length > MAX_NAME_LENGTH) invalid(`${path} must be at most ${MAX_NAME_LENGTH} characters`);
+  if (hasControlChar(value)) invalid(`${path} must not contain control characters`);
+  return value;
+}
+
+/**
+ * Coordinates are read as numbers only. A numeric *string* is refused rather
+ * than coerced because `'36.07'` and `'36,07'` are both strings and only one of
+ * them is a latitude — `Number()` turns the other into `NaN` and, before the
+ * finiteness check, into a station somewhere undefined. Making the caller hand
+ * over a number puts that parse in their code, where the locale is known.
+ */
+function normalizeNumber(value, path, [min, max], { integer = false } = {}) {
+  if (isAbsent(value)) invalid(`${path} is required`);
+  if (typeof value !== 'number') {
+    invalid(`${path} must be a number; a numeric string or null is not accepted`);
+  }
+  if (!Number.isFinite(value)) invalid(`${path} must be a finite number; NaN and Infinity are not positions`);
+  if (integer && !Number.isInteger(value)) invalid(`${path} must be a whole number of metres`);
+  if (value < min || value > max) invalid(`${path} must be within [${min}, ${max}]`);
+  return value;
+}
+
+/**
+ * The zone is validated for real, not merely shape-checked: `Intl` carries the
+ * ICU zone database this runtime already ships, so a retired or misspelled id
+ * ("Asia/Peking", "Mars/Olympus") throws a `RangeError` here instead of being
+ * stored and only noticed when a solved trajectory's local time makes no sense.
+ * Zero cost, zero dependencies, and it is the same database the pipeline will
+ * later use to interpret the station's timestamps.
+ *
+ * The accepted string is passed through byte-for-byte, not canonicalised. Zone
+ * identity belongs to the server (station identity is by coordinates anyway,
+ * contract §7.9), and rewriting a caller's value would be the silent
+ * normalisation this module refuses everywhere else.
+ */
+function normalizeTimezone(value, path) {
+  if (isAbsent(value)) invalid(`${path} is required`);
+  if (typeof value !== 'string') invalid(`${path} must be a string`);
+  if (!TIMEZONE_RE.test(value)) {
+    invalid(`${path} must be an IANA zone id such as Asia/Shanghai; a UTC offset is not accepted`);
+  }
+  try {
+    new Intl.DateTimeFormat(undefined, { timeZone: value });
+  } catch {
+    invalid(`${path} is not a zone this runtime's IANA database knows`);
+  }
+  return value;
+}
+
+function normalizeStation(input, path) {
+  if (isAbsent(input)) invalid(`${path} is required: a camera declares the position it observes from`);
+  if (!isObject(input)) invalid(`${path} must be an object`);
+  assertKnownFields(input, STATION_FIELDS, path);
+
+  // Built field by field rather than by spreading the caller's object, so the
+  // wire body can only ever contain what was validated above.
+  const station = {
+    latitude: normalizeNumber(input.latitude, `${path}.latitude`, STATION_RANGES.latitude),
+    longitude: normalizeNumber(input.longitude, `${path}.longitude`, STATION_RANGES.longitude),
+    elevationM: normalizeNumber(input.elevationM, `${path}.elevationM`, STATION_RANGES.elevationM, {
+      integer: true
+    }),
+    ...(input.timezone == null || input.timezone === '' ? {} : { timezone: normalizeTimezone(input.timezone, `${path}.timezone`) })
+  };
+  // Adopted only when the station is first created (contract §7.9), so it is
+  // omitted rather than sent empty: an absent name and a blank one must not
+  // look alike to a server that will fall back to a coordinate summary.
+  const name = normalizeName(input.name, `${path}.name`);
+  if (name !== undefined) station.name = name;
+  return station;
+}
+
+/**
+ * Validates one `camera` block and returns the exact object to put on the wire.
+ *
+ * Exported on its own because `ensureCamera()` — the optional pre-registration
+ * endpoint — takes the identical block and performs the identical upsert
+ * (contract §7.9), and the two must not drift into two dialects of the same
+ * declaration.
+ */
+function normalizeCameraBlock(input, path = 'camera') {
+  if (!isObject(input)) invalid(`${path} must be an object`);
+  assertKnownFields(input, CAMERA_FIELDS, path);
+
+  if (isAbsent(input.key)) invalid(`${path}.key is required: the host's own stable key for this channel`);
+  if (typeof input.key !== 'string') invalid(`${path}.key must be a string`);
+  if (!CAMERA_KEY_RE.test(input.key)) {
+    invalid(
+      `${path}.key must be 1-${MAX_CAMERA_KEY_LENGTH} characters of A-Z a-z 0-9 . _ : - ` +
+        'starting with a letter or digit; use newCameraKey() for a generated one'
+    );
+  }
+
+  const camera = { key: input.key, station: normalizeStation(input.station, `${path}.station`) };
+  const name = normalizeName(input.name, `${path}.name`);
+  if (name !== undefined) camera.name = name;
+  return camera;
+}
+
+/**
+ * Turns whatever machine position an upload request declared into the fragment
+ * to merge into the `upload-sessions/authorize` body.
+ *
+ * Accepts the whole request object and reads only `camera` and `cameraUid`:
+ * every other key (`clientRequestKey`, `manifestJson`, `artifacts`,
+ * `journalPath`, `onProgress`, …) belongs to the caller of `uploadEvent` and is
+ * none of this function's business. Unknown-field strictness applies *inside*
+ * the declaration, where a typo is silent, not at the top level, where it is
+ * not.
+ *
+ * Exactly one of the two is required; giving both is legal and both are passed
+ * through. The server resolves the pair — `cameraUid` is authoritative and it
+ * checks the registered `client_key` against `camera.key`, answering 400 on a
+ * mismatch (contract §7.9). Cross-checking them here is impossible without the
+ * camera list the SDK deliberately does not hold, and guessing would be worse
+ * than asking.
+ *
+ * @param {object} request an upload request, or any object carrying the two fields
+ * @returns {{cameraUid?: string, camera?: object}} a fresh object, safe to
+ *   `Object.assign` into the authorize payload
+ * @throws {MeteorCloudError} kind `validation`, never retryable
+ */
+function normalizeCameraSelector(request = {}) {
+  if (!isObject(request)) invalid('upload request must be an object');
+
+  const hasUid = !isAbsent(request.cameraUid);
+  const hasBlock = !isAbsent(request.camera);
+  if (!hasUid && !hasBlock) {
+    // The local twin of the server's 400 CAMERA_REQUIRED (1030003035). Phrased
+    // as the fix rather than the symptom, because "camera is required" tells a
+    // host application nothing about where the value is supposed to come from,
+    // and there is no console page to copy it from any more.
+    invalid(
+      'an upload must declare where it came from: pass camera ' +
+        '{ key, station: { latitude, longitude, elevationM, timezone } }, ' +
+        'or a cameraUid you already know'
+    );
+  }
+
+  const payload = {};
+  if (hasUid) {
+    if (typeof request.cameraUid !== 'string' || !CAMERA_RE.test(request.cameraUid)) {
+      invalid('cameraUid is not canonical: expected cam_ followed by 32 lowercase hex characters');
+    }
+    payload.cameraUid = request.cameraUid;
+  }
+  if (hasBlock) payload.camera = normalizeCameraBlock(request.camera);
+  return payload;
+}
+
+module.exports = {
+  normalizeCameraSelector,
+  normalizeCameraBlock,
+  CAMERA_RE,
+  CAMERA_KEY_RE,
+  TIMEZONE_RE,
+  STATION_RANGES,
+  MAX_NAME_LENGTH,
+  MAX_CAMERA_KEY_LENGTH
+};