@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/index.js

@@ -0,0 +1,945 @@
+'use strict';
+
+const { jobCapability, parseJob, jobErrorAction } = require('./lib/jobs');
+const fs = require('node:fs');
+
+const { MeteorCloudError, fail, isObject } = require('./lib/errors');
+const {
+  CONFIG_SCHEMA,
+  loadInstallationConfig,
+  saveInstallationConfig,
+  normalizeApiBase,
+  normalizeIssuer,
+  validateInstallationConfig
+} = require('./lib/config');
+const {
+  KeyStore,
+  FileKeyStore,
+  DpapiKeyStore,
+  CngKeyStore,
+  createKeyStore,
+  parseKeyReference,
+  defaultKeyStoreScheme,
+  DPAPI_MODULE,
+  CNG_MODULE
+} = require('./lib/keystore');
+const { InstallationTokenSource, CLIENT_ASSERTION_TYPE, DEVICE_SCOPES } = require('./lib/tokens');
+const {
+  connect: bindThroughBrowser,
+  beginConnect: beginBindThroughBrowser,
+  BIND_SCOPE
+} = require('./lib/connect');
+const { createResources, newCameraKey } = require('./lib/resources');
+const { normalizeCameraSelector, normalizeCameraBlock } = require('./lib/camera');
+const { defaultTransport, decodeEnvelope, headerValue, backoffSeconds, RETRYABLE_HTTP } = require('./lib/http');
+const { UploadJournal, JOURNAL_VERSION } = require('./lib/journal');
+const {
+  ROLES,
+  ROLE_SET,
+  describeArtifacts,
+  validateManifest,
+  validateManifestDigests,
+  sha256Path,
+  normalizeContentType
+} = require('./lib/artifacts');
+const {
+  DEFAULT_CHUNK_SIZE,
+  MAX_CHUNK_SIZE,
+  API_CODE,
+  normalizeChunkSize,
+  uploadArtifactChunks
+} = require('./lib/upload');
+const jose = require('./lib/jose');
+
+/** Version matches package.json and index.d.ts. */
+const SDK_VERSION = '0.5.1';
+/** Data-plane contract advertised by the server as `capabilities.directPut.contractVersion`. */
+const DIRECT_PUT_CONTRACT = 'mlc.device-direct-put/1';
+const DEVICE_ROOT = '/cloud/device-api/mscloud';
+const CONTROL_ROOT = `${DEVICE_ROOT}/upload-sessions`;
+const SESSION_RE = /^us_[0-9a-f]{32}$/;
+const FILE_ID_RE = /^uf_[0-9a-f]{32}$/;
+const JOB_RE = /^job_[0-9a-f]{32}$/;
+const EVENT_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+// The scope group an installation client asks for (contract §7.1 plus plan §0.5)
+// is defined once in `lib/tokens.js` and re-exported here. Keeping a second copy
+// in this file would let the public constant drift away from the list actually
+// put on the wire by the token source — which is the bug this consolidation
+// removes, since `InstallationTokenSource` is itself part of the public surface
+// and a caller may construct it directly.
+
+/**
+ * What a server must have deployed for the account-level methods to exist.
+ *
+ * The server half is written and on `main` (commit f079ef19): account, station
+ * and camera endpoints, passive machine registration, the owner-chain
+ * authorizer, the eight scopes and the browser login handoff. What is missing
+ * is a deployment carrying it. Naming the commit rather than a release version
+ * is deliberate — there is no released build to name, and the commit is what an
+ * operator can actually go and check a deployment against.
+ */
+const ACCOUNT_API_REQUIREMENT =
+  'a MeteorCloud deployment carrying the account-level Device API ' +
+  '(contract §7.2 GET /account; implemented on main in f079ef19, not yet deployed)';
+
+/**
+ * MeteorCloud device client, token stack.
+ *
+ * Everything it can do is gated by a 10 minute opaque token minted on demand
+ * from the local P-256 key. There is no long-lived credential on disk, no COS
+ * SDK, and no runtime dependency: `require('@thuzjq/meteorcloud-device-sdk-node')` pulls
+ * in nothing but `node:` builtins.
+ */
+class MeteorCloudClient {
+  constructor(input = {}) {
+    if (!isObject(input)) fail('client config must be an object');
+    const installation = validateInstallationConfig({
+      schema: input.schema ?? CONFIG_SCHEMA,
+      issuer: input.issuer,
+      client_id: input.clientId ?? input.client_id,
+      installation_uid: input.installationUid ?? input.installation_uid,
+      key_reference: input.keyReference ?? input.key_reference
+    });
+
+    this.issuer = installation.issuer;
+    this.clientId = installation.clientId;
+    this.installationUid = installation.installationUid;
+    this.keyReference = installation.keyReference;
+    // The Device API and the authorization server share an origin in every
+    // supported topology; `apiBase` exists so a split deployment stays possible
+    // without reintroducing a second persisted field.
+    this.apiBase = normalizeApiBase(input.apiBase || normalizeIssuer(installation.issuer));
+
+    this._jobQuery = Object.freeze({ observed: false, supported: false, compatible: false, minimumPollSeconds: 10 });
+    this.httpTimeoutMs = input.httpTimeoutMs ?? 30000;
+    this.chunkTimeoutMs = input.chunkTimeoutMs ?? 600000;
+    this.controlAttempts = input.controlAttempts ?? 3;
+    this.chunkAttempts = input.chunkAttempts ?? 5;
+    this.chunkSize = normalizeChunkSize(input.chunkSize ?? DEFAULT_CHUNK_SIZE, undefined);
+    this.transport = input.transport || defaultTransport;
+    this.now = input.now || (() => Math.floor(Date.now() / 1000));
+    this.random = input.random || Math.random;
+    this.sleep = input.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+
+    // Both tier options travel, not just `dpapi`: a `cng://` reference resolves
+    // to a CngKeyStore that needs its backend, and `fromConfig()` is the route
+    // where nobody else can supply one.
+    this.keyStore =
+      input.keyStore || createKeyStore(this.keyReference, { dpapi: input.dpapi, cng: input.cng });
+    this.tokens =
+      input.tokenSource ||
+      new InstallationTokenSource({
+        issuer: this.issuer,
+        installationUid: this.installationUid,
+        keyStore: this.keyStore,
+        keyReference: this.keyReference,
+        scopes: input.scopes || DEVICE_SCOPES,
+        dpop: input.dpop !== false,
+        authScheme: input.authScheme,
+        transport: this.transport,
+        timeoutMs: this.httpTimeoutMs,
+        attempts: this.controlAttempts,
+        marginSeconds: input.tokenMarginSeconds,
+        now: this.now,
+        random: this.random,
+        sleep: this.sleep,
+        jti: input.jti
+      });
+
+    /**
+     * The account-scoped reads and the optional pre-registration write, bound to
+     * this client's authenticated `_request`.
+     *
+     * `validateCamera` is injected rather than left to `lib/resources.js`'s own
+     * copy so that `ensureCamera()` and `uploadEvent()` validate a `camera`
+     * block through the *same* function. Contract §7.9 requires the
+     * pre-registration path to behave identically to the upsert an upload
+     * performs, and two validators drift the moment one of them learns a rule
+     * the other does not.
+     */
+    this._resources = createResources({
+      request: (method, requestPath, payload, expected) =>
+        this._request(method, requestPath, payload, expected),
+      validateCamera: normalizeCameraBlock
+    });
+  }
+
+  /** Builds a client from the zero-secret config written by {@link connect}. */
+  static async fromConfig(configPath, options = {}) {
+    const config = await loadInstallationConfig(configPath);
+    return new MeteorCloudClient({ ...options, ...config });
+  }
+
+  // There is deliberately no `static connect()`. Plan §0.9 froze the public
+  // entry points at `MeteorCloud.connect()` and `MeteorCloud.beginConnect()`
+  // (with the top-level named exports being the same function objects, not a
+  // compatibility layer). A second spelling on the class was a 0.4.x carry-over
+  // with no users to carry — 0.4.x was never published — and every extra name
+  // for one entry point is a name the docs, the types and the C++ SDK have to
+  // keep agreeing about.
+
+  async _emit(callback, progress) {
+    if (!callback) return;
+    if ((await callback(progress)) === false) {
+      throw new MeteorCloudError('upload cancelled', { kind: 'cancelled' });
+    }
+  }
+
+  _url(requestPath) {
+    return `${this.apiBase}${requestPath}`;
+  }
+
+  /**
+   * One authenticated control-plane call, with retries.
+   *
+   * A 401 is treated as "the token died" exactly **once per request** (contract
+   * §12.1): the cached token is dropped and the next attempt re-asserts, and a
+   * second 401 is raised rather than re-asserted again. The distinction matters
+   * because the two 401s have different causes. The first is ordinary — a token
+   * that expired inside its margin, or a revocation. A *second* one, against a
+   * token minted seconds earlier, is a configuration disagreement the client
+   * cannot fix by trying harder: a DPoP `htu` computed from the wrong base, an
+   * `ath` the resource server does not expect, a clock outside the assertion
+   * window. Retrying that burns one signed assertion and one `jti` budget entry
+   * per attempt, on every request, for as long as the drift lasts.
+   */
+  async _request(method, requestPath, payload, expectedStatuses, attempts = this.controlAttempts) {
+    const url = this._url(requestPath);
+    const body = payload === undefined ? undefined : Buffer.from(JSON.stringify(payload), 'utf8');
+    let lastError;
+    let reauthenticated = false;
+
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      const headers = {
+        Accept: 'application/json',
+        ...(await this.tokens.authorizationHeaders(method, url))
+      };
+      if (body !== undefined) headers['Content-Type'] = 'application/json; charset=utf-8';
+
+      let response;
+      try {
+        response = await this.transport({
+          method,
+          url,
+          headers,
+          body,
+          timeoutMs: this.httpTimeoutMs
+        });
+      } catch (error) {
+        lastError = error instanceof MeteorCloudError
+          ? error
+          : new MeteorCloudError('Device API transport failed', {
+            kind: 'transport',
+            retryable: true,
+            cause: error
+          });
+        if (!lastError.retryable || attempt === attempts) throw lastError;
+        await this.sleep(backoffSeconds(attempt, lastError.retryAfterSeconds, this.random) * 1000);
+        continue;
+      }
+
+      this.tokens.noteResourceNonce(headerValue(response.headers, 'dpop-nonce'));
+
+      try {
+        const data = decodeEnvelope(response, expectedStatuses);
+        if (requestPath.startsWith(CONTROL_ROOT) && isObject(data)) this._jobQuery = jobCapability(data);
+        return data;
+      } catch (error) {
+        if (this._shouldReauthenticate(error) && !reauthenticated && attempt < attempts) {
+          reauthenticated = true;
+          this.tokens.invalidate();
+          lastError = error;
+          continue;
+        }
+        if (!error.retryable || attempt === attempts) throw error;
+        lastError = error;
+        await this.sleep(backoffSeconds(attempt, error.retryAfterSeconds, this.random) * 1000);
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * 401 means re-assert — except when it carries the digest-mismatch code, which
+   * the server also answers with 401 and which no new token can fix.
+   */
+  _shouldReauthenticate(error) {
+    return error.httpStatus === 401 && error.apiCode !== API_CODE.DIGEST_MISMATCH;
+  }
+
+  _sessionPath(sessionUid, operation) {
+    if (!SESSION_RE.test(sessionUid || '')) fail('sessionUid is not canonical');
+    return `${CONTROL_ROOT}/${sessionUid}/${operation}`;
+  }
+
+  /**
+   * The short-lived operational token, minted on demand and renewed inside its
+   * margin (contract §2.2).
+   *
+   * Returned for interoperability — a host that has to sign its own request
+   * against another MeteorCloud endpoint should not have to re-implement the
+   * assertion — and not as an invitation to manage renewal by hand: call it
+   * again and it hands back a live one.
+   *
+   * A copy, so a caller cannot reach into the token source's cache and change
+   * the expiry the renewal decision is made from. `accessToken` is a secret:
+   * §2.2 keeps it in memory only, and `fingerprint` exists for the log line.
+   *
+   * @returns {Promise<{accessToken: string, tokenType: string, scope: string,
+   *                    expiresAt: number, fingerprint: string}>}
+   */
+  async getAccessToken() {
+    return { ...(await this.tokens.getToken()) };
+  }
+
+  /**
+   * The authorized account, contract §7.2.
+   *
+   * Also the SDK's capability probe (§11.2, plan §0.6): it is the first
+   * account-level call `connect()` makes, and on a server that predates the
+   * account API it is a 404 for a *route*, not for a resource. §9.4 has the
+   * server answer 404 for "no such resource, or not yours", so letting that
+   * through unchanged would tell an integrator their account does not exist —
+   * the one reading that is certainly wrong, since the token was just minted
+   * from a key the same server registered.
+   */
+  async getAccount() {
+    try {
+      return await this._resources.getAccount();
+    } catch (error) {
+      if (error instanceof MeteorCloudError && error.httpStatus === 404) {
+        throw new MeteorCloudError(
+          'this MeteorCloud server does not support the account-level SDK: ' +
+            `GET ${DEVICE_ROOT}/account is not routed. It requires ${ACCOUNT_API_REQUIREMENT}. ` +
+            'There is no earlier SDK to fall back to: 0.4.x had no users, was never ' +
+            'published, and the account model replaced it outright. Wait for the deployment.',
+          { kind: 'device_api', httpStatus: 404, action: 'account_api_unsupported', cause: error }
+        );
+      }
+      throw error;
+    }
+  }
+
+  /** Stations already registered under this account (§7.3). A query, never a cache. */
+  listStations(query) {
+    return this._resources.listStations(query);
+  }
+
+  /** Cameras already registered under this account (§7.4). A query, never a cache. */
+  listCameras(query) {
+    return this._resources.listCameras(query);
+  }
+
+  /** One registered camera by uid (§7.4). */
+  getCamera(cameraUid) {
+    return this._resources.getCamera(cameraUid);
+  }
+
+  /**
+   * Optional pre-registration (§7.9): the same upsert an upload performs, run
+   * early. The argument is the `camera` block itself, flat.
+   *
+   * Nothing has to be done with the uid it returns. The block identifies the
+   * camera on every later upload, which is why the SDK stores none of this.
+   */
+  ensureCamera(input) {
+    return this._resources.ensureCamera(input);
+  }
+
+  // There is deliberately no profileStatus(), and no deviceContext() either.
+  //
+  // `/profile/status` and `/profile/latest` are defined over a single camera
+  // and a credential row; an installation token is scoped to an account and has
+  // neither shape, so the server answers 409 to both. `/device-context` was the
+  // token-stack answer to that, but it reported the installation's bound camera
+  // set — a concept 0.5.0 deleted outright (plan §0.9), and the route is gone
+  // from the server with it. What replaces it is not one document but four
+  // deliberate questions: getAccount(), listStations(), listCameras() and
+  // getInstallationContext()'s eventual successor. Shipping any of the three
+  // removed methods would ship a call that cannot succeed.
+
+  /**
+   * Whether this client has a complete identity AND a private key it can
+   * actually sign with.
+   *
+   * `fromConfig()` deliberately does not touch the key — it only parses the
+   * reference — so a config that outlived its key (profile wipe, restored
+   * backup, a different Windows user) loads perfectly and then fails at the
+   * first token mint. Without this, the earliest an integrator learns that is
+   * *after* `uploadEvent()` has hashed every artifact: a full pass over the
+   * media plus up to 2 GiB of ecsv, thrown away.
+   *
+   * This signs a fixed probe rather than calling `keyStore.exists()`, because
+   * `exists()` only lstats. On Windows the common failure is a DPAPI blob that
+   * is present but cannot be unprotected by the current user — `exists()` says
+   * true, `sign()` is what tells the truth. Mirrors `is_bound()` in the C++ SDK.
+   *
+   * @returns {Promise<boolean>} false means "re-run the bind flow"
+   */
+  async isBound() {
+    try {
+      await this.keyStore.sign(this.keyReference, Buffer.from('mlc.is-bound-probe', 'utf8'));
+      return true;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  jobQueryCapability() {
+    return { ...this._jobQuery };
+  }
+
+  async jobStatus(jobUid) {
+    if (!JOB_RE.test(jobUid || '')) fail('jobUid is not canonical', { action: 'job_request_invalid' });
+    if (this._jobQuery.observed && !this._jobQuery.compatible) {
+      fail('job query is not enabled or compatible; retain the jobUid and stop polling', {
+        kind: 'device_api', action: 'job_query_not_enabled'
+      });
+    }
+    // One resource request: the host owns the per-job poll budget and schedule.
+    try {
+      const data = await this._request('GET', `${DEVICE_ROOT}/jobs/${jobUid}`, undefined, new Set([200]), 1);
+      return parseJob(data, jobUid, this._jobQuery.minimumPollSeconds);
+    } catch (error) {
+      if (this._shouldReauthenticate(error)) this.tokens.invalidate();
+      error.action = error.action || jobErrorAction(error);
+      if (['job_query_not_enabled', 'job_unavailable', 'job_expired', 'job_request_invalid', 'contract_invalid'].includes(error.action)) {
+        error.retryable = false;
+      }
+      if (error.action === 'job_query_not_enabled') {
+        this._jobQuery = jobCapability({});
+      }
+      throw error;
+    }
+  }
+
+  uploadSessionStatus(sessionUid) {
+    return this._request('GET', this._sessionPath(sessionUid, 'status'), undefined, new Set([200]));
+  }
+
+  refresh(sessionUid) {
+    return this._request('POST', this._sessionPath(sessionUid, 'refresh'), {}, new Set([200]));
+  }
+
+  /**
+   * `{files: []}` is the local plane's finalize. The server already holds the
+   * bytes and re-digests them itself, so there are no receipts to present — but
+   * the member must be present and empty: an absent `files` is rejected as a
+   * malformed COS-plane finalize.
+   */
+  finalize(sessionUid) {
+    return this._request('POST', this._sessionPath(sessionUid, 'finalize'), { files: [] }, new Set([200, 201]));
+  }
+
+  abort(sessionUid, reason = '') {
+    if (typeof reason !== 'string' || reason.length > 128 || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$|^$/.test(reason)) {
+      fail('abort reason is invalid');
+    }
+    return this._request('POST', this._sessionPath(sessionUid, 'abort'), reason ? { reason } : {}, new Set([200]));
+  }
+
+  /**
+   * Opens an upload session.
+   *
+   * Every upload declares where it came from (§7.6, §7.9): either a `camera`
+   * block — the host's own stable key plus the station coordinates — or a
+   * `cameraUid` it already holds. The declaration is validated *first*, for the
+   * same reason it is in `uploadEvent`: a caller that split authorize and upload
+   * must not learn about a missing coordinate after the hashing pass either.
+   */
+  async authorize(request) {
+    const selector = normalizeCameraSelector(request);
+    return this._authorizePrepared(request, await this._prepareFiles(request), selector);
+  }
+
+  /**
+   * Local validation and the one full-file hashing pass, split out so
+   * `uploadEvent` can hand the resulting digests to `uploadAuthorized` instead
+   * of computing them a second time.
+   *
+   * The machine declaration is *not* checked here: it is checked by
+   * `normalizeCameraSelector` before this method is entered at all, so a typo in
+   * a coordinate cannot cost a full pass over a 40 GiB capture (§7.6).
+   */
+  async _prepareFiles(request) {
+    if (!isObject(request) || !EVENT_RE.test(request.clientRequestKey || '')) {
+      fail('clientRequestKey is not canonical');
+    }
+    await this._emit(request.onProgress, { stage: 'hashing' });
+    const files = await describeArtifacts(request.artifacts);
+    const manifest = await validateManifest(request);
+    // Locally, because the server answers a digest mismatch with 401 — which
+    // reads as "your credentials are wrong" for a manifest content error.
+    validateManifestDigests(manifest, files);
+    return files;
+  }
+
+  /**
+   * @param {object} request the caller's upload request
+   * @param {Array<object>} files the digests from {@link _prepareFiles}
+   * @param {{camera?: object, cameraUid?: string}} selector the validated machine
+   *   declaration. Required, and produced by the caller rather than here: it has
+   *   to be computed before hashing, and passing it down is what proves it was.
+   */
+  async _authorizePrepared(request, files, selector) {
+    await this._emit(request.onProgress, { stage: 'authorizing' });
+    const payload = { clientRequestKey: request.clientRequestKey, manifestJson: request.manifestJson, files };
+    // Whichever of `camera` / `cameraUid` the caller declared, already validated
+    // and rebuilt field by field. Absent keys stay absent rather than being sent
+    // null: the server's @Pattern rejects a present blank.
+    Object.assign(payload, selector);
+    try {
+      return await this._request('POST', `${CONTROL_ROOT}/authorize`, payload, new Set([200, 201]));
+    } catch (error) {
+      if (error.apiCode === API_CODE.CAMERA_REQUIRED) {
+        // The SDK has already refused an upload that declares nothing, so
+        // reaching this means the server did not accept what *was* declared —
+        // in practice a server that predates the §7.9 `camera` block and knows
+        // only `cameraUid`. The server's own text describes a multi-binding
+        // installation, which stopped being the cause.
+        error.message =
+          'the server rejected this upload for naming no camera it recognises. ' +
+          (selector && selector.camera && !selector.cameraUid
+            ? `A camera block was sent, which needs ${ACCOUNT_API_REQUIREMENT}; ` +
+              'against an older server, pass a cameraUid you already hold instead.'
+            : 'Pass a camera block ({ key, station: { latitude, longitude, elevationM, timezone } }) ' +
+              'or a cameraUid that belongs to this account.');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Turns an authorize/status response into the per-role upload plan, refusing
+   * anything that is not a local-direct session.
+   *
+   * The PUT URL is derived from `sessionUid` and `role` here and merely
+   * *cross-checked* against the server's `path`. A server-supplied path is data,
+   * not a routing instruction: accepting it verbatim would let a compromised or
+   * confused control plane redirect file bytes anywhere the client can reach.
+   */
+  _uploadTargets(session) {
+    if (!isObject(session) || !SESSION_RE.test(session.sessionUid || '')) fail('sessionUid is invalid');
+    this._assertDirectPutContract(session);
+    if (session.credentials) {
+      fail('server returned COS credentials for a local session', { kind: 'device_api' });
+    }
+    if (!Array.isArray(session.uploadTargets) || session.uploadTargets.length === 0) {
+      fail(
+        'server returned a COS session; this SDK speaks the local direct-PUT plane only ' +
+          '(enable mscloud.direct-put.enabled)',
+        { kind: 'device_api' }
+      );
+    }
+    const targets = new Map();
+    for (const target of session.uploadTargets) {
+      if (!isObject(target) || !ROLE_SET.has(target.role)) fail('upload target role is invalid');
+      if (targets.has(target.role)) fail(`duplicate upload target role: ${target.role}`);
+      const expectedPath = `upload-sessions/${session.sessionUid}/artifacts/${target.role}`;
+      if (String(target.path).replace(/^\//, '') !== expectedPath) {
+        fail(`upload target path is not canonical: ${target.role}`, { kind: 'device_api' });
+      }
+      const receivedBytes = Number(target.receivedBytes ?? 0);
+      const sizeBytes = Number(target.sizeBytes);
+      if (!Number.isSafeInteger(receivedBytes) || receivedBytes < 0) fail('receivedBytes is invalid');
+      if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 1) fail('upload target sizeBytes is invalid');
+      targets.set(target.role, {
+        role: target.role,
+        targetPath: expectedPath,
+        requestPath: `${CONTROL_ROOT}/${session.sessionUid}/artifacts/${target.role}`,
+        receivedBytes,
+        sizeBytes
+      });
+    }
+    return targets;
+  }
+
+  /**
+   * Fails closed when the server advertises a direct-PUT contract whose major
+   * version this SDK does not implement.
+   *
+   * A major bump means the chunk framing itself changed — `Content-Range`
+   * semantics, the digest header, or the offset rule — so continuing would put
+   * bytes on the wire under a contract neither side agrees on, and the failure
+   * would surface much later as a digest mismatch at finalize. An absent
+   * `contractVersion` is accepted: the server omits the whole block when the
+   * plane is unsupported, and that case is already caught by `uploadTargets`.
+   */
+  _assertDirectPutContract(session) {
+    const advertised = isObject(session.capabilities) && isObject(session.capabilities.directPut)
+      ? session.capabilities.directPut.contractVersion
+      : undefined;
+    if (typeof advertised !== 'string' || advertised === '') return;
+    const major = (value) => String(value).split('/')[1] ?? '';
+    if (major(advertised) !== major(DIRECT_PUT_CONTRACT)) {
+      fail(
+        `server speaks direct-PUT contract ${advertised}; this SDK implements ${DIRECT_PUT_CONTRACT}`,
+        { kind: 'device_api' }
+      );
+    }
+  }
+
+  /** Chunk size, clamped to whatever this server says it will accept. */
+  _chunkSizeFor(session) {
+    const advertised = isObject(session.capabilities) && isObject(session.capabilities.directPut)
+      ? Number(session.capabilities.directPut.maxChunkBytes)
+      : undefined;
+    return normalizeChunkSize(this.chunkSize, advertised);
+  }
+
+  /**
+   * One chunk PUT. `Content-Length` is set explicitly and the body is a fresh
+   * stream per attempt: the server refuses chunked transfer-encoding outright
+   * (it cannot enforce the size ceiling on a length it does not know yet).
+   */
+  async _putChunk(chunk) {
+    const url = this._url(chunk.requestPath);
+    const headers = {
+      Accept: 'application/json',
+      'Content-Type': 'application/octet-stream',
+      'Content-Length': String(chunk.length),
+      'Content-Range': `bytes ${chunk.start}-${chunk.endInclusive}/${chunk.total}`,
+      'X-Content-SHA256': chunk.sha256,
+      ...(await this.tokens.authorizationHeaders('PUT', url))
+    };
+    const response = await this.transport({
+      method: 'PUT',
+      url,
+      headers,
+      bodyStream: () => fs.createReadStream(chunk.filePath, { start: chunk.start, end: chunk.endInclusive }),
+      timeoutMs: this.chunkTimeoutMs
+    });
+    this.tokens.noteResourceNonce(headerValue(response.headers, 'dpop-nonce'));
+    try {
+      return decodeEnvelope(response, new Set([200]));
+    } catch (error) {
+      if (this._shouldReauthenticate(error)) this.tokens.invalidate();
+      // Unknown/complete offsets are reconciled through status by the upload loop.
+      throw error;
+    }
+  }
+
+  async _readReceivedBytes(sessionUid, role) {
+    const status = await this.uploadSessionStatus(sessionUid);
+    const targets = this._uploadTargets(status);
+    const target = targets.get(role);
+    if (!target) fail(`status response omitted the ${role} upload target`, { kind: 'device_api' });
+    return target.receivedBytes;
+  }
+
+  /**
+   * Streams every artifact of an authorized session, resuming from the server's
+   * own byte counts. Safe to call repeatedly: an artifact the server already
+   * holds in full costs one status read and no bytes.
+   */
+  async uploadAuthorized(session, artifacts, journalPath, onProgress, precomputed) {
+    if (typeof journalPath !== 'string' || !journalPath) fail('journalPath is required');
+    const targets = this._uploadTargets(session);
+    // After `_uploadTargets`, which is where `sessionUid` is actually validated.
+    const sessionUid = session.sessionUid;
+    const journal = await new UploadJournal(journalPath, sessionUid).load();
+    const chunkSize = this._chunkSizeFor(session);
+
+    const local = new Map(artifacts.map((item) => [item.role, item]));
+    const plans = Array.isArray(session.files) ? session.files : [];
+    if (plans.length !== targets.size) fail('session file plan and upload targets disagree');
+    // Before streaming, not after: called directly with four local artifacts
+    // against a three-target session, the old check ran past the upload loop and
+    // only complained once every byte was already on the wire. The guard below
+    // compares two server-supplied numbers and so can never catch this.
+    if (local.size !== targets.size || [...local.keys()].some((role) => !targets.has(role))) {
+      fail('local and authorized role sets differ');
+    }
+    // Digests `uploadEvent` already computed for exactly these files, moments
+    // ago. Re-reading a 40 GiB media file to reach the same answer costs ~7
+    // minutes of disk on a machine that is simultaneously capturing video, and
+    // it is the third full pass in one call. Skipping it does not weaken the
+    // contract: every chunk is digested from the live file as it is sent, and
+    // finalize re-digests the whole thing server-side against the size and
+    // sha256 declared at authorize.
+    //
+    // Reused only when `precomputed` describes *this* artifacts array by
+    // identity. A public caller reaching uploadAuthorized() directly, after a
+    // restart, gets the full re-hash — there the local digest is the only
+    // check that the file on disk is still the one that was authorized.
+    const reusable = isObject(precomputed) && precomputed.artifacts === artifacts;
+    const known = new Map(reusable ? precomputed.files.map((file) => [file.role, file]) : []);
+
+    const emit = (progress) => this._emit(onProgress, progress);
+
+    for (const plan of plans) {
+      if (!isObject(plan) || !FILE_ID_RE.test(plan.clientFileId || '')) fail('authorized file plan is invalid');
+      const target = targets.get(plan.role);
+      if (!target) fail(`session plan has no upload target: ${plan.role}`);
+      const artifact = local.get(plan.role);
+      if (!artifact) fail(`local artifact is missing: ${plan.role}`);
+
+      const cached = known.get(plan.role);
+      const digest = cached ? cached.sha256 : await sha256Path(artifact.path);
+      const planSize = Number(plan.sizeBytes);
+      // The server lowercases and trims contentType before it stores it, and
+      // echoes the stored form back. Comparing raw strings made `Video/MP4`
+      // authorize successfully and then fail locally with an error blaming the
+      // caller's files, leaving an orphan session holding quota until expiry.
+      if (
+        planSize !== target.sizeBytes ||
+        String(plan.sha256 || '').toLowerCase() !== digest ||
+        normalizeContentType(plan.contentType) !== normalizeContentType(artifact.contentType)
+      ) {
+        fail(`local artifact does not match the authorized plan: ${plan.role}`);
+      }
+
+      await uploadArtifactChunks(
+        {
+          chunkSize,
+          attempts: this.chunkAttempts,
+          sleep: this.sleep,
+          random: this.random,
+          putChunk: (chunk) => this._putChunk({ ...chunk, requestPath: target.requestPath }),
+          readReceivedBytes: (role) => this._readReceivedBytes(sessionUid, role)
+        },
+        {
+          role: plan.role,
+          filePath: artifact.path,
+          sizeBytes: planSize,
+          targetPath: target.targetPath,
+          sha256: digest,
+          receivedBytes: target.receivedBytes
+        },
+        journal,
+        emit
+      );
+    }
+
+    if (local.size !== targets.size || [...local.keys()].some((role) => !targets.has(role))) {
+      fail('local and authorized role sets differ');
+    }
+    return journal.state;
+  }
+
+  /** authorize → chunked PUT → finalize, resumable at every step. */
+  async uploadEvent(request) {
+    // The very first statement, ahead of every file read. Contract §7.6: a
+    // missing or malformed machine declaration is a caller argument error, and
+    // it must be caught before multi-gigabyte artifacts are hashed — otherwise
+    // an unattended station spends minutes of disk to earn a 400.
+    const selector = normalizeCameraSelector(request);
+    const files = await this._prepareFiles(request);
+    const session = await this._authorizePrepared(request, files, selector);
+    if (session.status === 'completed') {
+      await this._emit(request.onProgress, { stage: 'completed' });
+      return session;
+    }
+    await this.uploadAuthorized(session, request.artifacts, request.journalPath, request.onProgress, {
+      files,
+      artifacts: request.artifacts
+    });
+    await this._emit(request.onProgress, { stage: 'finalizing' });
+    const result = await this.finalize(session.sessionUid);
+    if (!isObject(result) || result.status !== 'completed') {
+      fail('finalize did not return completed', { kind: 'device_api' });
+    }
+    await this._emit(request.onProgress, { stage: 'completed' });
+    return result;
+  }
+}
+
+/**
+ * Turns the raw bind outcome from `lib/connect.js` into the contract §6.1
+ * `ConnectResult`.
+ *
+ * Two round trips happen here and both are required by §2.1. The token the
+ * browser flow produced carries `mscloud.bind` and nothing else — it cannot
+ * upload, cannot read the account, and must never be handed to a caller as if
+ * it could — so the operational token is minted separately, from the local
+ * private key via `private_key_jwt`. Reading the account then proves the whole
+ * chain works before `connect()` resolves: key on disk, assertion accepted,
+ * scope group granted, server new enough to answer `/account`.
+ */
+async function finishConnect(outcome, options) {
+  const clientOptions = { ...(options.clientOptions || {}) };
+  // A caller who handed connect() a DPAPI/CNG store or a tighter timeout meant
+  // it for the installation, not just for the bind: the client that comes back
+  // has to be able to sign with the key that was just created.
+  if (options.keyStore !== undefined && clientOptions.keyStore === undefined) {
+    clientOptions.keyStore = options.keyStore;
+  }
+  // Same reasoning one level down, and this one is not optional. A caller who
+  // asked for `keyStoreScheme: 'dpapi'` never constructs a KeyStore at all —
+  // `resolveKeyStore()` builds it from these two blocks — so dropping them here
+  // leaves the client to build a store of its own with no backend and no
+  // entropy. The key on disk is then unreadable by the very client that just
+  // created it, and because the installation is already registered by then the
+  // caller sees `bind_registered_load_config` on a bind that succeeded.
+  if (options.dpapi !== undefined && clientOptions.dpapi === undefined) {
+    clientOptions.dpapi = options.dpapi;
+  }
+  if (options.cng !== undefined && clientOptions.cng === undefined) {
+    clientOptions.cng = options.cng;
+  }
+  if (options.httpTimeoutMs !== undefined && clientOptions.httpTimeoutMs === undefined) {
+    clientOptions.httpTimeoutMs = options.httpTimeoutMs;
+  }
+  // `transport` travels for the same reason, and it is the one that bites in
+  // tests and in hosts that tunnel through their own agent: `lib/connect.js`
+  // really does use it for the code exchange (it is a declared ConnectOptions
+  // member), so a caller who injected one saw the bind go through their
+  // transport and the very first call on the returned client silently go out
+  // through the default one.
+  if (options.transport !== undefined && clientOptions.transport === undefined) {
+    clientOptions.transport = options.transport;
+  }
+
+  // Everything from here on happens AFTER the server registered the
+  // installation and after `installation.json` reached the disk. A transient
+  // 5xx or a deployment whose grant does not cover `account:read` must not be
+  // reported as "the bind failed", because it did not: the caller would retry
+  // `connect()`, mint a second key, register a second installation, and strand
+  // the first one — which can then only be revoked by hand in the console.
+  // Contract §10.3 legislates the same asymmetry for the key itself.
+  //
+  // So the bind is preserved and the error says so: `action` marks it, and the
+  // message names the one correct recovery, which is to load the config that is
+  // already on disk rather than to authorize again.
+  //
+  // The construction itself is inside the try for the same reason. It is not a
+  // formality: the constructor validates `apiBase`, resolves a key store from
+  // `key_reference` and can reject a keyStoreScheme option — all of it *after*
+  // the installation exists on the server. Left outside, any of those threw a
+  // bare `kind: 'validation'` / `kind: 'keystore'` error carrying neither
+  // `action` nor `configPath`, which reads as "your arguments were wrong" and
+  // invites precisely the connect() retry this block exists to forbid.
+  let client;
+  let token;
+  let account;
+  try {
+    client = new MeteorCloudClient({ ...clientOptions, ...outcome.config });
+    token = await client.getAccessToken();
+    account = await client.getAccount();
+  } catch (cause) {
+    // One failure here already explains itself and already tells the caller not
+    // to bind again: `account_api_unsupported`, raised by getAccount() when the
+    // server routes no account API. Wrapping it would bury the one sentence
+    // that names the actual fix (upgrade the server) under a generic one.
+    if (cause instanceof MeteorCloudError && cause.action === 'account_api_unsupported') {
+      throw cause;
+    }
+    throw new MeteorCloudError(
+      'the installation was registered and its config was written, but reading '
+      + 'the first token or the account failed. Do NOT call connect() again — '
+      + 'that would mint a second key, register a second installation and strand '
+      + 'this one. Load the existing config with MeteorCloudClient.fromConfig() '
+      + '(the path is on this error as `configPath`) and retry the failing call.',
+      {
+        kind: cause instanceof MeteorCloudError ? cause.kind : 'transport',
+        httpStatus: cause instanceof MeteorCloudError ? cause.httpStatus : undefined,
+        apiCode: cause instanceof MeteorCloudError ? cause.apiCode : undefined,
+        retryable: false,
+        // Same identifier as the C++ SDK's ErrorAction. The action string is the
+        // cross-language stable discriminator, so the two must not drift.
+        action: 'bind_registered_load_config',
+        configPath: outcome.configPath,
+        cause
+      }
+    );
+  }
+
+  return {
+    client,
+    token,
+    account,
+    installation: {
+      installationUid: outcome.installationUid,
+      productClientId: outcome.config.clientId,
+      // The server registered it moments ago in this very flow. Any other state
+      // would have failed the code exchange.
+      status: 'active'
+    },
+    config: outcome.config,
+    configPath: outcome.configPath
+  };
+}
+
+/**
+ * First bind, one call (contract §6.1): browser authorization, local key,
+ * installation registration, first operational token and the account summary.
+ *
+ * @param {object} options see contract §6.1 `ConnectOptions`
+ * @returns {Promise<{client: MeteorCloudClient, token: object, account: object,
+ *   installation: {installationUid: string, productClientId: string, status: 'active'},
+ *   config: object, configPath: string}>}
+ */
+async function connect(options = {}) {
+  return finishConnect(await bindThroughBrowser(options), options);
+}
+
+/**
+ * Two-phase bind (contract §6.2), for software that opens the URL itself.
+ *
+ * The listener is already up when this returns, so the URL is safe to hand to
+ * an Electron shell, a controlled browser or another machine.
+ *
+ * `wait()` is memoized: it resolves the same `ConnectResult` however often it is
+ * called, rather than minting a second token and re-reading the account.
+ */
+async function beginConnect(options = {}) {
+  const pending = await beginBindThroughBrowser(options);
+  let result;
+  return {
+    authorizationUrl: pending.authorizationUrl,
+    wait() {
+      if (!result) {
+        result = pending.wait().then((outcome) => finishConnect(outcome, options));
+        // cancel() rejects this without anybody necessarily awaiting it yet.
+        result.catch(() => {});
+      }
+      return result;
+    },
+    cancel: () => pending.cancel()
+  };
+}
+
+/**
+ * The namespace contract §1.1 opens with: `const { MeteorCloud } = require(...)`.
+ *
+ * Three entries because those are the three things a host application calls
+ * before it holds a client — authorize, authorize in two phases, and mint the
+ * stable key it will store in its own configuration. Everything else hangs off
+ * the client the first two return.
+ */
+const MeteorCloud = Object.freeze({ connect, beginConnect, newCameraKey });
+
+module.exports = {
+  MeteorCloud,
+  MeteorCloudClient,
+  MeteorCloudError,
+  connect,
+  beginConnect,
+  newCameraKey,
+  loadInstallationConfig,
+  saveInstallationConfig,
+  KeyStore,
+  FileKeyStore,
+  DpapiKeyStore,
+  CngKeyStore,
+  createKeyStore,
+  parseKeyReference,
+  defaultKeyStoreScheme,
+  InstallationTokenSource,
+  UploadJournal,
+  jose,
+  SDK_VERSION,
+  CONFIG_SCHEMA,
+  DIRECT_PUT_CONTRACT,
+  JOURNAL_VERSION,
+  DEVICE_SCOPES,
+  BIND_SCOPE,
+  CLIENT_ASSERTION_TYPE,
+  DPAPI_MODULE,
+  CNG_MODULE,
+  ROLES,
+  DEFAULT_CHUNK_SIZE,
+  MAX_CHUNK_SIZE,
+  API_CODE
+};