npm - @thuzjq/meteorcloud-device-sdk-node - Versions diffs - 0.5.1 - Mend

@thuzjq/meteorcloud-device-sdk-node 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md +45 -0
package/docs/NODE_INTEGRATION_GUIDE.zh-CN.md +414 -0
package/index.d.ts +930 -0
package/index.js +945 -0
package/lib/artifacts.js +279 -0
package/lib/camera.js +316 -0
package/lib/config.js +257 -0
package/lib/connect.js +718 -0
package/lib/durable.js +85 -0
package/lib/errors.js +70 -0
package/lib/http.js +188 -0
package/lib/jobs.js +54 -0
package/lib/jose.js +146 -0
package/lib/journal.js +116 -0
package/lib/keystore.js +585 -0
package/lib/resources.js +408 -0
package/lib/tokens.js +311 -0
package/lib/upload.js +188 -0
package/package.json +44 -0
package/tools/migrate-key-to-dpapi.js +386 -0

package/lib/connect.js ADDED Viewed

@@ -0,0 +1,718 @@
+'use strict';
+const crypto = require('node:crypto');
+const http = require('node:http');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { MeteorCloudError, fail, isObject } = require('./errors');
+const { defaultTransport, headerValue } = require('./http');
+const { base64UrlEncodeJson, createPkcePair } = require('./jose');
+const {
+  PRODUCT_CLIENT_IDS,
+  INSTALLATION_UID_RE,
+  authorizeEndpoint,
+  normalizeApiBase,
+  normalizeIssuer,
+  tokenEndpoint,
+  saveInstallationConfig
+} = require('./config');
+const { defaultKeyStoreScheme, FileKeyStore, DpapiKeyStore, CngKeyStore } = require('./keystore');
+const BIND_SCOPE = 'mscloud.bind';
+const CALLBACK_PATH = '/callback';
+const DEFAULT_TIMEOUT_MS = 300000;
+const BROWSER_MODES = Object.freeze(['system', 'manual']);
+/**
+ * The complete public authorize surface (contract §5.3), in the published
+ * order. It is asserted against the built URL rather than merely documented:
+ * every parameter this list does not name was deleted for a reason — `bridge`
+ * was a session credential in a process argv, `proposal` / `channels` /
+ * `devices` were a device inventory the consent page no longer shows, and
+ * `cameraUid` / `stationUid` pinned an account-wide grant to one resource. A
+ * future edit that re-adds any of them fails here instead of on a server that
+ * would quietly accept it.
+ */
+const AUTHORIZE_PARAMS = Object.freeze([
+  'response_type',
+  'client_id',
+  'redirect_uri',
+  'scope',
+  'code_challenge',
+  'code_challenge_method',
+  'state',
+  'installation_jwk'
+]);
+/**
+ * Options the 0.4.x surface accepted and 0.5.0 must not. They are *rejected*,
+ * not ignored: a caller that keeps passing `bridgeGrant` after upgrading would
+ * otherwise get a silently different URL, and the only symptom would be the
+ * server's `401 账号未登录` with nothing pointing at the removed parameter.
+ * Each value says what replaced it, because "unknown option" is not a migration
+ * note.
+ */
+const REMOVED_CONNECT_OPTIONS = Object.freeze({
+  bridgeGrant:
+    'the browser signs in on its own and the SDK never relays a session grant',
+  proposal:
+    'the consent page shows no cameras; declare the camera on each upload instead',
+  installationDecisions: 'the consent page submits no per-camera decisions',
+  channels: 'the SDK neither reads nor forwards host capture channels',
+  devices: 'the SDK neither reads nor forwards host devices',
+  cameras: 'the SDK holds no camera inventory',
+  cameraUid: 'the grant is account-wide; name the camera on each upload instead',
+  stationUid: 'the grant is account-wide; the station follows from the upload'
+});
+const CALLBACK_HTML_OK =
+  '<!doctype html><meta charset="utf-8"><title>MeteorCloud</title>' +
+  '<body style="font:16px system-ui;margin:4rem auto;max-width:30rem;text-align:center">' +
+  '<h1>Binding complete</h1><p>You can close this tab and return to the application.</p>';
+const CALLBACK_HTML_FAIL =
+  '<!doctype html><meta charset="utf-8"><title>MeteorCloud</title>' +
+  '<body style="font:16px system-ui;margin:4rem auto;max-width:30rem;text-align:center">' +
+  '<h1>Binding failed</h1><p>Return to the application for details.</p>';
+function cancelled(message, action) {
+  return new MeteorCloudError(message, { kind: 'cancelled', action });
+}
+/**
+ * Hands the authorization URL to the desktop's default browser.
+ *
+ * SECURITY, and the balance here changed in 0.5.0: the URL no longer carries a
+ * credential. A child process's argv is world-readable in the process table on
+ * macOS and on default-configured Linux (`hidepid=0`), and until 0.4.x this
+ * spawn published the one-time bridge grant there — a value that, presented to
+ * `/oauth2/authorize`, *created an authenticated session as the user*. That
+ * parameter is gone (contract §5.3), so what crosses the process boundary now
+ * is the PKCE *challenge* (a hash), the installation's public JWK, the loopback
+ * port and `state`.
+ *
+ * That is not nothing. A local process that reads `state` and the port can beat
+ * the browser to the loopback listener and burn the single accepted callback —
+ * a denial of service on this bind, and with a fabricated `code` it wastes one
+ * exchange that PKCE then fails. It cannot complete the bind: it holds no
+ * authorization code the server will honour, and the code it cannot forge is
+ * what the exchange is checked against. The standard fix for the residue is to
+ * stop putting authorization parameters in the URL at all — push them once over
+ * TLS (RFC 9126 PAR) and hand the browser `client_id` + `request_uri`. That is
+ * a server change and is tracked separately.
+ *
+ * `internals` is a test seam (platform, env, spawnImpl); production callers pass
+ * nothing.
+ */
+function openSystemBrowser(url, internals = {}) {
+  const platform = internals.platform || process.platform;
+  const spawnImpl = internals.spawnImpl || spawn;
+  let command;
+  const args = [];
+  if (platform === 'win32') {
+    // Never put an OAuth URL through cmd.exe. `cmd /c start ...` parses `&` as
+    // a command separator and expands `%NAME%`, so the server receives only the
+    // first query parameter (and reports the request as unauthenticated). Using
+    // FileProtocolHandler gives CreateProcess one opaque URL argv element and
+    // asks Windows to dispatch it through the registered default handler.
+    const windowsRoot = (internals.env || process.env).SystemRoot;
+    if (!windowsRoot) {
+      return Promise.reject(
+        new MeteorCloudError('cannot open the authorization URL: SystemRoot is unavailable', {
+          kind: 'io',
+          action: 'open_browser'
+        })
+      );
+    }
+    const system32 = path.win32.join(windowsRoot, 'System32');
+    command = path.win32.join(system32, 'rundll32.exe');
+    args.push(`${path.win32.join(system32, 'url.dll')},FileProtocolHandler`);
+  } else {
+    command = platform === 'darwin' ? 'open' : 'xdg-open';
+  }
+  args.push(url);
+  const spawnOptions = {
+    detached: true,
+    stdio: 'ignore',
+    // The same rule as the Windows branch, for the same reason: with `shell`
+    // set, `&` in the query would split the command on every platform.
+    shell: false,
+    ...(platform === 'win32' ? { windowsHide: true } : {})
+  };
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawnImpl(command, args, spawnOptions);
+    } catch (cause) {
+      reject(
+        new MeteorCloudError('failed to open the authorization URL in the system browser', {
+          kind: 'io',
+          action: 'open_browser',
+          cause
+        })
+      );
+      return;
+    }
+    let settled = false;
+    child.once('error', (cause) => {
+      if (settled) return;
+      settled = true;
+      reject(
+        new MeteorCloudError('failed to open the authorization URL in the system browser', {
+          kind: 'io',
+          action: 'open_browser',
+          cause
+        })
+      );
+    });
+    child.once('spawn', () => {
+      if (settled) return;
+      settled = true;
+      child.unref();
+      resolve();
+    });
+  });
+}
+/**
+ * A single-shot loopback listener on 127.0.0.1 with an OS-assigned port
+ * (RFC 8252 §7.3, contract §10.2). Bound to the literal loopback address, never
+ * 0.0.0.0 and never the name `localhost`, and it answers exactly one path —
+ * anything else gets a 404 without touching state.
+ *
+ * "Single-shot" is enforced, not assumed: the first request that reaches
+ * `/callback` settles the outcome and every later one is refused. Without that
+ * guard a second callback — a page reload, or a local process replaying the
+ * URL — would run the state comparison again against a listener that has
+ * already handed its code to the exchange.
+ */
+function startLoopbackListener({ timeoutMs, expectedState, signal }) {
+  let settle;
+  const received = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  // The callback can arrive (or the timer can fire) before the caller reaches
+  // `await received`, which would surface a correct rejection as an
+  // unhandledRejection. Attaching an inert handler now marks it handled without
+  // consuming it — the awaiter still sees the real error.
+  received.catch(() => {});
+  let done = false;
+  const resolveOnce = (code) => {
+    if (done) return;
+    done = true;
+    settle.resolve(code);
+  };
+  const rejectOnce = (error) => {
+    if (done) return;
+    done = true;
+    settle.reject(error);
+  };
+  const server = http.createServer((request, response) => {
+    let url;
+    try {
+      url = new URL(request.url, 'http://127.0.0.1');
+    } catch (_) {
+      response.writeHead(400).end();
+      return;
+    }
+    if (request.method !== 'GET' || url.pathname !== CALLBACK_PATH) {
+      response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }).end('not found');
+      return;
+    }
+    if (done) {
+      // The outcome is already decided; a second callback must not be able to
+      // reopen it, and answering 400 keeps the response shape uniform.
+      response.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' }).end(CALLBACK_HTML_FAIL);
+      return;
+    }
+    const error = url.searchParams.get('error');
+    const code = url.searchParams.get('code');
+    const state = url.searchParams.get('state') || '';
+    const expected = Buffer.from(expectedState, 'utf8');
+    const actual = Buffer.from(state, 'utf8');
+    const stateOk = expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
+    const ok = stateOk && !error && Boolean(code);
+    response
+      .writeHead(ok ? 200 : 400, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+        // The page is inert, but it is served on localhost where any other local
+        // page could try to frame or script it.
+        'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'",
+        'Referrer-Policy': 'no-referrer'
+      })
+      .end(ok ? CALLBACK_HTML_OK : CALLBACK_HTML_FAIL);
+    if (!stateOk) {
+      rejectOnce(new MeteorCloudError('authorization callback state did not match', { kind: 'auth' }));
+      return;
+    }
+    if (error) {
+      rejectOnce(
+        new MeteorCloudError(`authorization was refused: ${error}`, { kind: 'auth', oauthError: error })
+      );
+      return;
+    }
+    if (!code) {
+      rejectOnce(new MeteorCloudError('authorization callback carried no code', { kind: 'auth' }));
+      return;
+    }
+    resolveOnce(code);
+  });
+  // A user who closed the tab and a caller who called cancel() reach the same
+  // place — nothing will ever arrive — so both are `cancelled`. `action` is what
+  // tells them apart, because a timeout is a thing to retry and a cancel is not.
+  const timer = setTimeout(() => {
+    rejectOnce(cancelled('timed out waiting for the authorization callback', 'authorize_timeout'));
+  }, timeoutMs);
+  timer.unref();
+  const onAbort = () => {
+    rejectOnce(cancelled('the authorization flow was aborted', 'authorize_aborted'));
+  };
+  if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  const listening = new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve(server.address().port));
+  });
+  return {
+    listening,
+    received,
+    /** Settle the wait from outside — cancel(), or a caller-side failure. */
+    abort(error) {
+      rejectOnce(error);
+    },
+    async close() {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      // A browser (or a probe) that kept the connection alive would otherwise
+      // hold `close()` open until its idle timeout: `close()` stops new
+      // connections but waits for established ones.
+      if (typeof server.closeIdleConnections === 'function') server.closeIdleConnections();
+      await new Promise((resolve) => server.close(resolve));
+    }
+  };
+}
+function resolveKeyStore(options) {
+  if (options.keyStore) return options.keyStore;
+  const scheme = options.keyStoreScheme || defaultKeyStoreScheme();
+  if (scheme === 'file') return new FileKeyStore();
+  if (scheme === 'dpapi') return new DpapiKeyStore(options.dpapi || {});
+  if (scheme === 'cng') return new CngKeyStore(options.cng || {});
+  return fail(`unsupported keyStoreScheme: ${scheme}`, { kind: 'keystore' });
+}
+/**
+ * Runs the client's own `apiBase` rule ahead of time, so a URL the
+ * `MeteorCloudClient` constructor will refuse cannot reach the constructor
+ * after a bind has already succeeded.
+ *
+ * The offending path is named, never the whole URL: an issuer can carry a
+ * deployment-specific host and this message is the string callers log most
+ * reliably.
+ */
+function assertUsableAsApiBase(value, label) {
+  try {
+    normalizeApiBase(value);
+  } catch (cause) {
+    let where = '';
+    try {
+      where = ` (path '${new URL(value).pathname}')`;
+    } catch (_) {
+      /* not even a URL: the cause already says so */
+    }
+    throw new MeteorCloudError(
+      `${label} cannot be used as the Device API base${where}: it must be an origin, `
+      + 'optionally ending in /cloud. The client built by connect() derives its Device '
+      + 'API base from the issuer, so this is checked before any key is generated.',
+      { kind: 'validation', cause }
+    );
+  }
+}
+/**
+ * Everything that can be decided without touching the keystore, the network or
+ * a port, decided first. The ordering is a requirement, not a style choice: a
+ * rejected option must not leave a generated private key behind, and the key
+ * store's `wx` guard would then make the next attempt fail on a file the caller
+ * never asked for.
+ */
+function validateConnectOptions(options, entry) {
+  if (!isObject(options)) fail('connect options must be an object');
+  // First, before anything else can produce a more confusing complaint: a
+  // caller still on the 0.4.x shape needs to be told which parameter died.
+  for (const [name, replacement] of Object.entries(REMOVED_CONNECT_OPTIONS)) {
+    if (options[name] !== undefined) {
+      fail(`${name} was removed in 0.5.0: ${replacement}`);
+    }
+  }
+  const issuer = normalizeIssuer(options.issuer);
+  // `normalizeIssuer` keeps any path prefix; `normalizeApiBase` accepts only
+  // '', '/', '/cloud' or '/cloud/'. The client built from a completed bind
+  // derives its Device API base from the issuer, so an issuer path outside that
+  // set is fatal — and used to be fatal in the *worst* possible place: after the
+  // browser consent, after the server registered the installation, after the
+  // key and installation.json reached the disk. The caller saw a bare
+  // `kind: 'validation'` error with no `action` and no `configPath`, read it as
+  // "my arguments were wrong", and called connect() again — minting a second key
+  // and stranding a registered installation that then needs a human in the
+  // console to revoke. That is exactly the retry finishConnect()'s
+  // `bind_registered_load_config` comment exists to prevent. Here it costs a
+  // string parse and happens before a single byte of key material exists.
+  assertUsableAsApiBase(issuer, 'issuer');
+  const clientApiBase = isObject(options.clientOptions) ? options.clientOptions.apiBase : undefined;
+  if (clientApiBase !== undefined) assertUsableAsApiBase(clientApiBase, 'clientOptions.apiBase');
+  const clientId = options.clientId;
+  if (!PRODUCT_CLIENT_IDS.has(clientId)) fail('clientId is not an approved product client');
+  if (typeof options.configPath !== 'string' || !options.configPath) fail('configPath is required');
+  const browserMode = options.browserMode ?? 'system';
+  if (!BROWSER_MODES.includes(browserMode)) {
+    fail(`browserMode must be one of ${BROWSER_MODES.join(', ')}`);
+  }
+  if (browserMode === 'manual' && options.openBrowser) {
+    // Contradictory instructions, and the ambiguity is the dangerous part: one
+    // reading opens a browser the caller asked not to open, the other silently
+    // drops the caller's opener and the flow hangs until the timeout.
+    fail("browserMode 'manual' cannot be combined with openBrowser; the caller opens the URL itself");
+  }
+  if (entry === 'connect' && browserMode === 'manual' && !options.onAuthorizeUrl) {
+    // Nothing in `connect()` opens the URL in manual mode, so without
+    // `onAuthorizeUrl` the caller never receives it and the flow sits until the
+    // timeout with no diagnosis. `beginConnect()` is the API for that shape:
+    // there the URL comes back as a return value.
+    fail("browserMode 'manual' requires onAuthorizeUrl, or use beginConnect() and read authorizationUrl");
+  }
+  if (!options.keyReference && (typeof options.keyPath !== 'string' || !options.keyPath)) {
+    fail('either keyReference (existing key) or keyPath (new key) is required');
+  }
+  const signal = options.signal;
+  if (signal !== undefined && (!isObject(signal) || typeof signal.addEventListener !== 'function')) {
+    fail('signal must be an AbortSignal');
+  }
+  if (signal && signal.aborted) {
+    throw cancelled('the connect flow was aborted before it started', 'authorize_aborted');
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) fail('timeoutMs must be a positive number');
+  return {
+    issuer,
+    clientId,
+    browserMode,
+    signal,
+    timeoutMs,
+    httpTimeoutMs: options.httpTimeoutMs ?? 30000,
+    transport: options.transport || defaultTransport,
+    randomBytes: options.randomBytes || crypto.randomBytes
+  };
+}
+/** Contract §5.3, asserted rather than trusted. See {@link AUTHORIZE_PARAMS}. */
+function buildAuthorizeUrl({ issuer, clientId, redirectUri, pkce, state, publicJwk }) {
+  const url = new URL(authorizeEndpoint(issuer));
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('scope', BIND_SCOPE);
+  url.searchParams.set('code_challenge', pkce.challenge);
+  url.searchParams.set('code_challenge_method', pkce.method);
+  url.searchParams.set('state', state);
+  url.searchParams.set('installation_jwk', base64UrlEncodeJson(publicJwk));
+  const emitted = [...url.searchParams.keys()];
+  if (emitted.length !== AUTHORIZE_PARAMS.length || emitted.some((key, i) => key !== AUTHORIZE_PARAMS[i])) {
+    // Deliberately does not name the offending parameter or echo the URL:
+    // contract §10.1 forbids logging the authorize URL, and an error message is
+    // the most reliably logged string in the SDK.
+    fail('the authorize URL carries parameters outside the published contract');
+  }
+  return url.toString();
+}
+/**
+ * Phase one of the browser bind (contract §6.2): generate the local key, bind
+ * the loopback listener, and hand back a URL that is *already answerable*.
+ *
+ * The ordering is the whole point of the two-phase API. A caller that opens the
+ * URL itself — Electron `openExternal`, a controlled browser, a QR code on
+ * another machine — has no way to know when the SDK's port came up, and a
+ * consent redirect that lands on a closed port is unrecoverable: the code is
+ * spent and the user sees a browser error. So `beginConnect()` does not return
+ * until `listen()` has succeeded.
+ *
+ * The flow then runs on its own from here, not from `wait()`. The callback
+ * arrives whether or not anybody is awaiting, and so do the timeout and the
+ * abort — driving them from `wait()` would mean a caller who cancels without
+ * ever awaiting leaks a bound port and an orphan key.
+ *
+ * @returns {Promise<{authorizationUrl: string, wait: () => Promise<object>,
+ *                    cancel: () => Promise<void>}>}
+ */
+async function beginConnect(options = {}) {
+  const plan = validateConnectOptions(options, 'beginConnect');
+  const keyStore = resolveKeyStore(options);
+  let keyReference = options.keyReference;
+  // Only a key *this run* generated may ever be destroyed. A caller-supplied
+  // `keyReference` names a key with a history — possibly a registered
+  // installation — and cleaning up after a failed bind must not touch it.
+  let orphanKeyReference = null;
+  if (!keyReference) {
+    // `keyPath` is a filesystem path for the file-backed tiers and a container
+    // leaf for cng://, which has no files at all — CngKeyStore takes the
+    // basename either way, so a caller that hands over a path still gets a
+    // sensible container rather than a rejection.
+    keyReference = await keyStore.create(options.keyPath);
+    orphanKeyReference = keyReference;
+  }
+  const destroyOrphanKey = async () => {
+    // A key generated for a bind that never completed is dead weight the user
+    // cannot see; leaving it behind would also make the next attempt fail on the
+    // 'wx' guard in the key store.
+    if (!orphanKeyReference) return;
+    const doomed = orphanKeyReference;
+    orphanKeyReference = null;
+    try {
+      await keyStore.destroy(doomed);
+    } catch (_) {
+      /* best effort: the bind already failed, and this is tidying */
+    }
+  };
+  let listener = null;
+  try {
+    const publicJwk = await keyStore.publicJwk(keyReference);
+    const pkce = createPkcePair(plan.randomBytes);
+    const state = Buffer.from(plan.randomBytes(32)).toString('base64url');
+    listener = startLoopbackListener({
+      timeoutMs: plan.timeoutMs,
+      expectedState: state,
+      signal: plan.signal
+    });
+    let port;
+    try {
+      port = await listener.listening;
+    } catch (cause) {
+      throw new MeteorCloudError('cannot bind the loopback callback listener on 127.0.0.1', {
+        kind: 'io',
+        action: 'loopback_listen',
+        cause
+      });
+    }
+    const redirectUri = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+    const authorizationUrl = buildAuthorizeUrl({
+      issuer: plan.issuer,
+      clientId: plan.clientId,
+      redirectUri,
+      pkce,
+      state,
+      publicJwk
+    });
+    const bound = listener;
+    const outcome = (async () => {
+      try {
+        const code = await bound.received;
+        // An abort that lands between the callback and the exchange still wins:
+        // nothing is registered yet, so stopping here is clean, whereas an
+        // abort *during* the exchange could leave a registered installation
+        // whose key we then destroy.
+        if (plan.signal && plan.signal.aborted) {
+          throw cancelled('the authorization flow was aborted', 'authorize_aborted');
+        }
+        const exchanged = await exchangeAuthorizationCode({
+          transport: plan.transport,
+          tokenEndpoint: tokenEndpoint(plan.issuer),
+          code,
+          redirectUri,
+          clientId: plan.clientId,
+          codeVerifier: pkce.verifier,
+          timeoutMs: plan.httpTimeoutMs
+        });
+        // The server now holds this public key and has minted an
+        // installation_uid (contract §10.3). Destroying the private key past
+        // this point would strand a registered installation that can never
+        // authenticate again and has to be revoked by hand in the web console —
+        // and the caller would see only the filesystem error that triggered it.
+        // From here the key is worth more than the tidiness of not leaving one
+        // behind, so the orphan is disowned *before* the config write.
+        orphanKeyReference = null;
+        const config = await saveInstallationConfig(options.configPath, {
+          issuer: plan.issuer,
+          client_id: plan.clientId,
+          installation_uid: exchanged.installationUid,
+          key_reference: keyReference
+        });
+        return {
+          config,
+          configPath: options.configPath,
+          keyReference,
+          installationUid: exchanged.installationUid,
+          publicJwk
+        };
+      } catch (error) {
+        await destroyOrphanKey();
+        throw error;
+      } finally {
+        await bound.close();
+      }
+    })();
+    // cancel() without a preceding wait() is a legitimate sequence, and the
+    // rejection it produces belongs to whoever calls wait() — if nobody does,
+    // it must not reach the process as an unhandledRejection.
+    outcome.catch(() => {});
+    return {
+      authorizationUrl,
+      wait: () => outcome,
+      async cancel() {
+        bound.abort(cancelled('the authorization flow was cancelled', 'authorize_cancelled'));
+        try {
+          await outcome;
+        } catch (_) {
+          /* cancel() reports nothing; wait() is where the error surfaces */
+        }
+      }
+    };
+  } catch (error) {
+    if (listener) await listener.close();
+    await destroyOrphanKey();
+    throw error;
+  }
+}
+/**
+ * First bind, one call: generate a local key, drive the browser through
+ * authorization code + PKCE, exchange the code, and persist a config file that
+ * contains nothing an attacker could use.
+ *
+ * A thin wrapper over {@link beginConnect} on purpose — the listener is up
+ * before the browser is opened, which is the only ordering in which the consent
+ * redirect cannot race the port.
+ *
+ * The returned object is the raw bind outcome. Minting an operational token and
+ * reading the account (contract §6.1's `{client, token, account, installation}`)
+ * happen a layer up, in index.js, which is where the client type lives.
+ *
+ * @returns {Promise<{config: object, configPath: string, keyReference: string,
+ *                    installationUid: string, publicJwk: object}>}
+ */
+async function connect(options = {}) {
+  // Validated twice, on purpose: this pass is the only one that knows the call
+  // came through `connect()`, and it has to run *before* `beginConnect()`
+  // generates a key that a rejected option would orphan. The pass itself has no
+  // side effects, so repeating it inside `beginConnect()` costs nothing.
+  validateConnectOptions(options, 'connect');
+  const pending = await beginConnect(options);
+  try {
+    if (options.onAuthorizeUrl) await options.onAuthorizeUrl(pending.authorizationUrl);
+    if ((options.browserMode ?? 'system') === 'system') {
+      const openBrowser = options.openBrowser || openSystemBrowser;
+      await openBrowser(pending.authorizationUrl, options.browserInternals);
+    }
+  } catch (error) {
+    // Nothing will arrive on a listener whose URL never reached a browser.
+    // Cancelling releases the port and cleans up the key this run created,
+    // before the caller sees why the browser could not be opened.
+    await pending.cancel();
+    throw error;
+  }
+  return pending.wait();
+}
+async function exchangeAuthorizationCode(options) {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: options.code,
+    redirect_uri: options.redirectUri,
+    client_id: options.clientId,
+    code_verifier: options.codeVerifier
+  }).toString();
+  const response = await options.transport({
+    method: 'POST',
+    url: options.tokenEndpoint,
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
+    },
+    body: Buffer.from(body, 'utf8'),
+    timeoutMs: options.timeoutMs,
+    maxResponseBytes: 64 * 1024
+  });
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(response.body || '').toString('utf8'));
+  } catch (cause) {
+    throw new MeteorCloudError('token endpoint returned invalid JSON', {
+      kind: 'auth',
+      httpStatus: response.status,
+      cause
+    });
+  }
+  if (response.status !== 200) {
+    const oauthError = isObject(decoded) && typeof decoded.error === 'string' ? decoded.error : undefined;
+    throw new MeteorCloudError(
+      oauthError ? `code exchange failed: ${oauthError}` : 'code exchange failed',
+      { kind: 'auth', httpStatus: response.status, oauthError }
+    );
+  }
+  if (!isObject(decoded)) fail('code exchange response is not an object', { kind: 'auth' });
+  // Contract assertion, not paranoia: this stack issues no refresh tokens at any
+  // layer. One appearing means the server was reconfigured in a way that
+  // reintroduces a long-lived bearer credential on disk.
+  if (decoded.refresh_token !== undefined) {
+    fail('code exchange returned a refresh_token, which this stack must never issue', { kind: 'auth' });
+  }
+  const installationUid = decoded.installation_uid;
+  if (!INSTALLATION_UID_RE.test(installationUid || '')) {
+    fail('code exchange response omitted a canonical installation_uid', { kind: 'auth' });
+  }
+  return {
+    installationUid,
+    // Deliberately not returned to the caller: the bind access token carries
+    // only `mscloud.bind` and is useless for uploads.
+    tokenType: typeof decoded.token_type === 'string' ? decoded.token_type : 'Bearer',
+    dpopNonce: headerValue(response.headers, 'dpop-nonce')
+  };
+}
+module.exports = {
+  connect,
+  beginConnect,
+  exchangeAuthorizationCode,
+  startLoopbackListener,
+  openSystemBrowser,
+  BIND_SCOPE,
+  CALLBACK_PATH,
+  AUTHORIZE_PARAMS,
+  BROWSER_MODES,
+  REMOVED_CONNECT_OPTIONS,
+  DEFAULT_TIMEOUT_MS
+};