@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/lib/tokens.js

@@ -0,0 +1,311 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+const { MeteorCloudError, fail, isObject } = require('./errors');
+const { defaultTransport, headerValue, backoffSeconds, retryAfterSeconds, RETRYABLE_HTTP } = require('./http');
+const {
+  ES256,
+  randomToken,
+  signCompactJws,
+  buildAssertionClaims,
+  buildDpopClaims,
+  dpopHtu
+} = require('./jose');
+const { tokenEndpoint } = require('./config');
+
+const CLIENT_ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+
+/**
+ * Exactly the scopes an installation client is registered for. Asking for
+ * anything outside this set is refused by the authorization server, so the list
+ * is a constant rather than a parameter.
+ *
+ * 0.5.0 replaced the 0.4.x group of four with the eight independent capabilities
+ * of contract §7.1 plus `camera:write` (plan §0.5). They are still issued as one
+ * group, but the server checks them per endpoint, so narrowing a client's grant
+ * later costs no second breaking change.
+ *
+ * `device-context:read` is gone from the group and is not an alias for anything.
+ * There are no released clients to carry (plan §0.9), so `/device-context` and
+ * the bound-camera set it reported were deleted rather than deprecated; the
+ * server does not recognise the old scope name at all.
+ *
+ * This is the single source of truth: `index.js` re-exports it rather than
+ * declaring a second copy, so the wire and the public constant cannot drift.
+ */
+const DEVICE_SCOPES = Object.freeze([
+  'account:read',
+  'installation:read',
+  'station:read',
+  'camera:read',
+  'camera:write',
+  'ingest:create',
+  'ingest:finalize',
+  'job:read'
+]);
+
+/** Contract value: the server rejects an assertion whose `exp - iat` exceeds this. */
+const ASSERTION_LIFETIME_SECONDS = 60;
+const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+const ACCESS_TOKEN_RE = /^[\x21\x23-\x5B\x5D-\x7E]{16,4096}$/;
+
+/**
+ * Turns the local P-256 key into short-lived opaque device tokens.
+ *
+ * There is no refresh token anywhere in this design: every renewal is a fresh
+ * RFC 7523 assertion signed on the spot. That is why a client that has not run
+ * for a year behaves exactly like one that ran a minute ago, and why a token
+ * expiring in the middle of a 40 GiB upload costs one extra round trip rather
+ * than a restart.
+ */
+class InstallationTokenSource {
+  constructor(options = {}) {
+    if (!options.installationUid) fail('installationUid is required');
+    if (!options.keyStore) fail('keyStore is required');
+    if (!options.keyReference) fail('keyReference is required');
+
+    this.issuer = options.issuer;
+    this.tokenEndpoint = tokenEndpoint(options.issuer);
+    this.installationUid = options.installationUid;
+    this.keyStore = options.keyStore;
+    this.keyReference = options.keyReference;
+    this.scopes = options.scopes ? [...options.scopes] : [...DEVICE_SCOPES];
+    this.dpopEnabled = options.dpop !== false;
+    this.authScheme = options.authScheme || 'auto';
+    if (!['auto', 'bearer', 'dpop'].includes(this.authScheme)) fail('authScheme is invalid');
+
+    this.transport = options.transport || defaultTransport;
+    this.timeoutMs = options.timeoutMs ?? 30000;
+    this.attempts = options.attempts ?? 3;
+    /**
+     * Renew this many seconds before nominal expiry. A 600s token with a 60s
+     * margin still leaves 540s of useful life, and no request is ever issued
+     * with a token that is about to die in the server's clock frame.
+     */
+    this.marginSeconds = options.marginSeconds ?? 60;
+    this.now = options.now || (() => Math.floor(Date.now() / 1000));
+    this.random = options.random || Math.random;
+    this.jti = options.jti || (() => randomToken(16));
+    this.sleep = options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+
+    this._token = undefined;
+    this._inflight = undefined;
+    this._asNonce = undefined;
+    this._rsNonce = undefined;
+    this._publicJwk = undefined;
+  }
+
+  async publicJwk() {
+    if (!this._publicJwk) this._publicJwk = await this.keyStore.publicJwk(this.keyReference);
+    return this._publicJwk;
+  }
+
+  /** Drops the cached token. Called after a 401 so the next call re-asserts. */
+  invalidate() {
+    this._token = undefined;
+  }
+
+  noteResourceNonce(nonce) {
+    if (typeof nonce === 'string' && nonce) this._rsNonce = nonce;
+  }
+
+  _isFresh() {
+    return Boolean(this._token) && this._token.expiresAt - this.marginSeconds > this.now();
+  }
+
+  /**
+   * Returns a live token, renewing if the cached one is inside its margin.
+   * Concurrent callers share one in-flight renewal: four artifacts uploading in
+   * sequence must not burn four assertions (and four `jti` budget entries) for
+   * the same expiry.
+   */
+  async getToken() {
+    if (this._isFresh()) return this._token;
+    if (!this._inflight) {
+      this._inflight = this._requestToken().finally(() => {
+        this._inflight = undefined;
+      });
+    }
+    return this._inflight;
+  }
+
+  /**
+   * Builds the headers that authenticate one resource request. When a proof is
+   * attached the scheme becomes `DPoP` — RFC 9449 §7.1 forbids presenting a
+   * DPoP-bound token under the `Bearer` scheme, and the server accepts both.
+   */
+  async authorizationHeaders(method, url) {
+    const token = await this.getToken();
+    const scheme = this._schemeFor(token);
+    const headers = { Authorization: `${scheme} ${token.accessToken}` };
+    if (scheme === 'DPoP') {
+      headers.DPoP = await this.createProof(method, url, {
+        accessToken: token.accessToken,
+        nonce: this._rsNonce
+      });
+    }
+    return headers;
+  }
+
+  _schemeFor(token) {
+    if (this.authScheme === 'bearer') return 'Bearer';
+    if (this.authScheme === 'dpop') return 'DPoP';
+    if (!this.dpopEnabled) return 'Bearer';
+    return String(token.tokenType || '').toLowerCase() === 'dpop' ? 'DPoP' : 'Bearer';
+  }
+
+  async createProof(method, url, options = {}) {
+    const header = { alg: ES256, typ: 'dpop+jwt', jwk: await this.publicJwk() };
+    const claims = buildDpopClaims({
+      method,
+      url,
+      now: this.now(),
+      jti: this.jti(),
+      accessToken: options.accessToken
+    });
+    if (options.nonce) claims.nonce = options.nonce;
+    return signCompactJws(header, claims, (data) => this.keyStore.sign(this.keyReference, data));
+  }
+
+  /**
+   * RFC 7523 assertion. The header carries no `jwk`: the server resolves the
+   * verification key from `mscloud_installation_key` by `client_id` and compares
+   * its recomputed RFC 7638 thumbprint, so an embedded key would at best be
+   * ignored and at worst invite confusion about which key is authoritative.
+   */
+  async createAssertion() {
+    const header = { alg: ES256, typ: 'JWT' };
+    const claims = buildAssertionClaims({
+      installationUid: this.installationUid,
+      tokenEndpoint: this.tokenEndpoint,
+      now: this.now(),
+      lifetimeSeconds: ASSERTION_LIFETIME_SECONDS,
+      jti: this.jti()
+    });
+    return signCompactJws(header, claims, (data) => this.keyStore.sign(this.keyReference, data));
+  }
+
+  async _requestToken() {
+    let lastError;
+    for (let attempt = 1; attempt <= this.attempts; attempt += 1) {
+      const body = new URLSearchParams({
+        grant_type: 'client_credentials',
+        // Mandatory beyond RFC 7523: it is what selects the registered client,
+        // and therefore which public key the assertion is verified against.
+        client_id: this.installationUid,
+        client_assertion_type: CLIENT_ASSERTION_TYPE,
+        client_assertion: await this.createAssertion(),
+        scope: this.scopes.join(' ')
+      }).toString();
+
+      const headers = {
+        Accept: 'application/json',
+        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
+      };
+      if (this.dpopEnabled) {
+        headers.DPoP = await this.createProof('POST', this.tokenEndpoint, { nonce: this._asNonce });
+      }
+
+      let response;
+      try {
+        response = await this.transport({
+          method: 'POST',
+          url: this.tokenEndpoint,
+          headers,
+          body: Buffer.from(body, 'utf8'),
+          timeoutMs: this.timeoutMs,
+          maxResponseBytes: MAX_TOKEN_RESPONSE_BYTES
+        });
+      } catch (error) {
+        lastError = error instanceof MeteorCloudError
+          ? error
+          : new MeteorCloudError('token endpoint transport failed', {
+            kind: 'transport',
+            retryable: true,
+            cause: error
+          });
+        if (!lastError.retryable || attempt === this.attempts) throw lastError;
+        await this.sleep(backoffSeconds(attempt, lastError.retryAfterSeconds, this.random) * 1000);
+        continue;
+      }
+
+      const nonce = headerValue(response.headers, 'dpop-nonce');
+      if (nonce) this._asNonce = nonce;
+
+      let decoded;
+      try {
+        decoded = JSON.parse(Buffer.from(response.body || '').toString('utf8'));
+      } catch (cause) {
+        lastError = new MeteorCloudError('token endpoint returned invalid JSON', {
+          kind: 'auth',
+          httpStatus: response.status,
+          retryable: RETRYABLE_HTTP.has(response.status),
+          retryAfterSeconds: retryAfterSeconds(response.headers),
+          cause
+        });
+        if (!lastError.retryable || attempt === this.attempts) throw lastError;
+        await this.sleep(backoffSeconds(attempt, lastError.retryAfterSeconds, this.random) * 1000);
+        continue;
+      }
+
+      if (response.status !== 200) {
+        const oauthError = isObject(decoded) && typeof decoded.error === 'string' ? decoded.error : undefined;
+        // RFC 9449 §8: the AS may demand a nonce it has just supplied. Retry once
+        // with it rather than surfacing a failure the client can fix itself.
+        if (oauthError === 'use_dpop_nonce' && nonce && attempt < this.attempts) {
+          continue;
+        }
+        const retryable = RETRYABLE_HTTP.has(response.status);
+        const error = new MeteorCloudError(
+          oauthError ? `token endpoint rejected the assertion: ${oauthError}` : 'token endpoint rejected the assertion',
+          {
+            kind: 'auth',
+            httpStatus: response.status,
+            oauthError,
+            retryable,
+            retryAfterSeconds: retryAfterSeconds(response.headers)
+          }
+        );
+        if (!retryable || attempt === this.attempts) throw error;
+        lastError = error;
+        await this.sleep(backoffSeconds(attempt, error.retryAfterSeconds, this.random) * 1000);
+        continue;
+      }
+
+      this._token = parseTokenResponse(decoded, this.now());
+      return this._token;
+    }
+    throw lastError;
+  }
+}
+
+function parseTokenResponse(decoded, nowSeconds) {
+  if (!isObject(decoded)) fail('token response is not an object', { kind: 'auth' });
+  const accessToken = decoded.access_token;
+  if (typeof accessToken !== 'string' || !ACCESS_TOKEN_RE.test(accessToken)) {
+    fail('token response carries an implausible access_token', { kind: 'auth' });
+  }
+  const expiresIn = Number(decoded.expires_in);
+  if (!Number.isInteger(expiresIn) || expiresIn < 30 || expiresIn > 86400) {
+    fail('token response carries an implausible expires_in', { kind: 'auth' });
+  }
+  return {
+    accessToken,
+    tokenType: typeof decoded.token_type === 'string' ? decoded.token_type : 'Bearer',
+    scope: typeof decoded.scope === 'string' ? decoded.scope : '',
+    expiresAt: nowSeconds + expiresIn,
+    // Never the token itself: this is what progress callbacks and evidence files
+    // are allowed to see.
+    fingerprint: crypto.createHash('sha256').update(accessToken, 'utf8').digest('hex').slice(0, 16)
+  };
+}
+
+module.exports = {
+  InstallationTokenSource,
+  DEVICE_SCOPES,
+  CLIENT_ASSERTION_TYPE,
+  ASSERTION_LIFETIME_SECONDS,
+  parseTokenResponse,
+  dpopHtu
+};

package/lib/upload.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const { MeteorCloudError, fail } = require('./errors');
+const { sha256Path } = require('./artifacts');
+const { backoffSeconds } = require('./http');
+
+/** Production contract: one direct-PUT request carries at most 32 MiB. */
+const DEFAULT_CHUNK_SIZE = 32 * 1024 * 1024;
+/** Frozen server ceiling (`MsCloudProperties.DirectPut.MAX_CHUNK_BYTES_CEILING`). */
+const MAX_CHUNK_SIZE = 32 * 1024 * 1024;
+const MIN_CHUNK_SIZE = 64 * 1024;
+
+const API_CODE = Object.freeze({
+  DIGEST_MISMATCH: 1030002005,
+  REQUEST_TOO_LARGE: 1030003010,
+  CHUNK_OUT_OF_ORDER: 1030003030,
+  CHUNK_RANGE_INVALID: 1030003031,
+  ARTIFACT_ALREADY_COMPLETE: 1030003032,
+  DIRECT_PUT_DISABLED: 1030003034,
+  CAMERA_REQUIRED: 1030003035
+});
+
+function normalizeChunkSize(requested, advertisedMax) {
+  const ceiling = Number.isSafeInteger(advertisedMax) && advertisedMax >= MIN_CHUNK_SIZE
+    ? Math.min(advertisedMax, MAX_CHUNK_SIZE)
+    : MAX_CHUNK_SIZE;
+  const size = Number.isSafeInteger(requested) && requested > 0 ? requested : DEFAULT_CHUNK_SIZE;
+  if (size < MIN_CHUNK_SIZE) fail(`chunkSize must be at least ${MIN_CHUNK_SIZE} bytes`);
+  return Math.min(size, ceiling);
+}
+
+/**
+ * Streams one artifact to the local direct plane, resuming from wherever the
+ * server says it already is.
+ *
+ * The governing rule, and the reason this loop is shaped the way it is: the
+ * server accepts a chunk **only** when `Content-Range` starts at exactly its own
+ * durable `receivedBytes`. It will not fill a hole and it will not overwrite. So
+ * the client never guesses an offset — after any failure whatsoever, including a
+ * transport error where the response was simply lost, it re-reads the authority
+ * before touching the wire again. A chunk that arrived intact but whose 200 went
+ * missing is thereby detected as progress rather than retried into a 409.
+ *
+ * @param deps.putChunk         performs one PUT, resolves to {receivedBytes, sizeBytes, complete}
+ * @param deps.readReceivedBytes re-reads the server's durable offset for a role
+ * @param plan {role, filePath, sizeBytes, targetPath, sha256, receivedBytes}
+ */
+async function uploadArtifactChunks(deps, plan, journal, emit) {
+  const chunkSize = deps.chunkSize;
+  const attempts = deps.attempts ?? 5;
+  const sleep = deps.sleep;
+  const random = deps.random;
+  const total = Number(plan.sizeBytes);
+  if (!Number.isSafeInteger(total) || total < 1) fail(`authorized size is invalid: ${plan.role}`);
+
+  const state = journal.reconcile(plan.role, {
+    key: plan.targetPath,
+    size: total,
+    sha256: plan.sha256
+  });
+
+  let offset = Number(plan.receivedBytes) || 0;
+  if (offset > total) {
+    // The server holds more bytes than the artifact has. The session was
+    // authorized for different content; resuming would corrupt it.
+    fail(`server holds more bytes than the authorized size: ${plan.role}`, { kind: 'device_api' });
+  }
+  await noteProgress(journal, state, offset);
+
+  await emit({ stage: 'uploading', role: plan.role, transferredBytes: offset, totalBytes: total });
+
+  let attempt = 0;
+  while (offset < total) {
+    const length = Math.min(chunkSize, total - offset);
+    const start = offset;
+    const endInclusive = start + length - 1;
+
+    // Two passes over the slice: one to digest, one to send. Buffering a 32 MiB
+    // chunk to do it in one would trade a bounded amount of disk read for an
+    // unbounded amount of RSS on a machine that is also capturing video.
+    const digest = await sha256Path(plan.filePath, { start, end: endInclusive });
+
+    let result;
+    try {
+      result = await deps.putChunk({
+        role: plan.role,
+        targetPath: plan.targetPath,
+        filePath: plan.filePath,
+        start,
+        endInclusive,
+        total,
+        length,
+        sha256: digest
+      });
+      attempt = 0;
+    } catch (error) {
+      attempt += 1;
+      const fatal = isFatalChunkError(error);
+      if (fatal || attempt >= attempts) throw error;
+      await sleep(backoffSeconds(attempt, error.retryAfterSeconds, random) * 1000);
+      // Authority re-read: covers the lost-200 case, a competing uploader, and
+      // an out-of-order rejection caused by a stale local offset.
+      const authoritative = await deps.readReceivedBytes(plan.role);
+      if (!Number.isSafeInteger(authoritative) || authoritative < 0 || authoritative > total) {
+        fail(`server reported an implausible receivedBytes for ${plan.role}`, { kind: 'device_api' });
+      }
+      offset = authoritative;
+      await noteProgress(journal, state, offset);
+      await emit({ stage: 'uploading', role: plan.role, transferredBytes: offset, totalBytes: total });
+      continue;
+    }
+
+    const received = Number(result.receivedBytes);
+    // The server neither fills holes nor overwrites, so the only arithmetically
+    // possible answer to a chunk that was accepted is `start + length`. Merely
+    // requiring it to advance lets a confused server make the client skip bytes
+    // it never sent; finalize's full-file digest would still catch that, but
+    // only after the whole remaining file had been uploaded for nothing.
+    if (!Number.isSafeInteger(received) || received !== start + length) {
+      fail(
+        `server acknowledged ${received} bytes for ${plan.role}, expected ${start + length}`,
+        { kind: 'device_api' }
+      );
+    }
+    offset = received;
+    await noteProgress(journal, state, offset);
+    await emit({ stage: 'uploading', role: plan.role, transferredBytes: offset, totalBytes: total });
+  }
+
+  return offset;
+}
+
+/**
+ * Records the offset, best-effort.
+ *
+ * The journal is an advisory hint, not a participant in the data path: resume
+ * is driven entirely by the server's `receivedBytes`, which is re-read on every
+ * failure. So a journal that cannot be written must not be able to stop an
+ * upload that needs no local disk at all — and a full disk is precisely the
+ * situation in which an operator is anxiously watching one. Before this, an
+ * `ENOSPC` here aborted the transfer before a single byte moved, with
+ * `cannot save upload journal`, on every retry forever.
+ *
+ * The failure is not swallowed silently: the last one is left on
+ * `journal.lastSaveError` for a caller that wants to warn about a station whose
+ * disk is failing. It just no longer decides whether the upload proceeds. Only
+ * `io` is absorbed — a `validation` failure from the secret scan in `save()`
+ * means the journal was about to write something it must never write, and that
+ * must still stop everything.
+ */
+async function noteProgress(journal, state, offset) {
+  state.offset = offset;
+  try {
+    await journal.save();
+  } catch (error) {
+    if (!(error instanceof MeteorCloudError) || error.kind !== 'io') throw error;
+    journal.lastSaveError = error;
+  }
+}
+
+/**
+ * Errors that no amount of retrying will fix, because the request itself is
+ * wrong rather than unlucky. Everything else earns a backoff and a re-read.
+ *
+ * `CHUNK_OUT_OF_ORDER` is deliberately absent: it is the expected answer when
+ * the local offset is stale, and the re-read on the retry path is exactly the
+ * cure for it.
+ */
+function isFatalChunkError(error) {
+  if (!(error instanceof MeteorCloudError)) return false;
+  if (['RESOURCE_DISABLED', 'RESOURCE_DELETED', 'RESOURCE_RECREATION_REQUIRED', 'UPLOAD_GENERATION_STALE'].includes(error.action)) return true;
+  if (error.kind === 'cancelled' || error.kind === 'validation' || error.kind === 'io') return true;
+  return [
+    API_CODE.CHUNK_RANGE_INVALID,
+    API_CODE.REQUEST_TOO_LARGE,
+    API_CODE.DIRECT_PUT_DISABLED
+  ].includes(error.apiCode);
+}
+
+module.exports = {
+  DEFAULT_CHUNK_SIZE,
+  MAX_CHUNK_SIZE,
+  MIN_CHUNK_SIZE,
+  API_CODE,
+  normalizeChunkSize,
+  uploadArtifactChunks,
+  isFatalChunkError
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@thuzjq/meteorcloud-device-sdk-node",
+  "version": "0.5.1",
+  "description": "MeteorCloud device SDK for Node.js: account authorization (OAuth 2 + PKCE browser bind, private_key_jwt renewal, DPoP), account-scoped queries, and chunked direct-PUT uploads that declare their own camera",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/",
+    "README.md",
+    "docs/NODE_INTEGRATION_GUIDE.zh-CN.md",
+    "tools/migrate-key-to-dpapi.js"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "test:browser:windows": "node tools/verify-windows-browser-launch.js"
+  },
+  "engines": {
+    "node": ">=20.10"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@meteorlive/dpapi": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@meteorlive/dpapi": {
+      "optional": true
+    }
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}