@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/index.d.ts

@@ -0,0 +1,930 @@
+// Type definitions for @thuzjq/meteorcloud-device-sdk-node 0.5.1
+// MeteorCloud device SDK: account authorization + chunked direct-PUT uploads.
+//
+// 0.5.0 changes the authorization model, not the upload wire contract. The
+// browser bind no longer relays a management-page grant and the consent page no
+// longer picks cameras; instead every upload carries its own machine
+// declaration (a `camera` block) and the server registers on first sight. The
+// SDK holds no camera list, no station list and no key-to-uid map.
+//
+// Contract: docs/architecture/account-client-sdk-contract.zh-CN.md §1.2, §5.3,
+// §6.1-§6.6, §7.6, §7.9; decisions in docs/ACCOUNT_CLIENT_SDK_PLAN.md §0.
+//
+// ⚠ ALPHA. The server endpoints these types describe (`/account`, `/stations`,
+// `/cameras`, `/cameras/ensure`, the owner-chain authorizer, zero-binding
+// registration, the browser login handoff) are NOT built. See
+// docs/NODE_INTEGRATION_GUIDE.zh-CN.md §0.
+
+export type ArtifactRole = 'manifest' | 'ecsv' | 'media' | 'preview';
+
+export type ProductClientId = 'meteormasterai' | 'meteorstudio' | 'ufocapture-adapter';
+
+export type UploadStage = 'hashing' | 'authorizing' | 'uploading' | 'finalizing' | 'completed';
+
+export type ErrorKind =
+  | 'validation'
+  | 'io'
+  | 'transport'
+  | 'device_api'
+  | 'auth'
+  | 'keystore'
+  | 'cancelled';
+
+/**
+ * `key_reference` URI schemes, weakest to strongest.
+ *
+ * Spelled the same as in the C++ SDK: the installation config is a cross-SDK
+ * wire contract, so a config written by one has to be readable by the other.
+ * (`windows-cng` appeared in 0.3-era docs as a reserved name and was never
+ * implemented under that spelling; it is rejected with a pointer to `cng`.)
+ */
+export type KeyReferenceScheme = 'file' | 'dpapi' | 'cng';
+
+export interface Artifact {
+  role: ArtifactRole;
+  path: string;
+  contentType: string;
+}
+
+export interface Progress {
+  stage: UploadStage;
+  role?: ArtifactRole;
+  transferredBytes?: number;
+  totalBytes?: number;
+}
+
+/** Returning `false` cancels the upload with a `cancelled` error. */
+export type ProgressCallback = (progress: Progress) => boolean | void | Promise<boolean | void>;
+
+export interface SafeError {
+  name: string;
+  kind: ErrorKind;
+  httpStatus?: number;
+  apiCode?: number;
+  oauthError?: string;
+  retryable: boolean;
+  retryAfterSeconds?: number;
+  action?: string;
+  message: string;
+}
+
+export declare class MeteorCloudError extends Error {
+  readonly kind: ErrorKind;
+  readonly httpStatus?: number;
+  /** Device API stable business code (the `code` member of the response envelope). */
+  readonly apiCode?: number;
+  /** RFC 6749 `error` value when the failure came from the token endpoint. */
+  readonly oauthError?: string;
+  readonly retryable: boolean;
+  readonly retryAfterSeconds?: number;
+  /**
+   * Which step failed, when the step is worth branching on. The bind flow
+   * emits `authorize_timeout` (nobody came back — retryable by asking the user
+   * again), `authorize_cancelled` and `authorize_aborted` (a deliberate stop —
+   * not retryable on its own), `open_browser` and `loopback_listen`.
+   *
+   * Two are worth special-casing, and both mean the bind SUCCEEDED:
+   *
+   * - `account_api_unsupported` — the server does not route the account-level
+   *   Device API at all. Upgrade the server; never bind again.
+   * - `bind_registered_load_config` — the installation is registered and the
+   *   config is written, but the first token or the account read failed. Load
+   *   the config named by {@link MeteorCloudError.configPath} instead of
+   *   calling `connect()` again, which would mint a second key, register a
+   *   second installation and strand this one. The C++ SDK raises the same
+   *   identifier for the same window; the string is the cross-language
+   *   contract.
+   */
+  readonly action?: string;
+  /**
+   * Where a completed-but-unenriched bind left its config, set only with
+   * `action: 'bind_registered_load_config'`.
+   *
+   * Absent from `message` and from {@link MeteorCloudError.toSafeObject} on
+   * purpose: an absolute path carries the local account name, and both of those
+   * are written to logs and evidence files. Read it off the error.
+   */
+  readonly configPath?: string;
+  /** A log-safe projection: no `cause`, no local paths, no credential material. */
+  toSafeObject(): SafeError;
+}
+
+// --- key storage -----------------------------------------------------------
+
+/**
+ * The private key never leaves the store: `sign` takes bytes and returns a
+ * signature. A future non-exportable CNG backend satisfies this interface
+ * unchanged.
+ */
+export declare abstract class KeyStore {
+  readonly scheme: string;
+  /** Creates a new P-256 key. Must refuse to overwrite an existing one. */
+  create(name: string): Promise<string>;
+  publicJwk(keyReference: string): Promise<JsonWebKey>;
+  /** @returns the 64-byte IEEE P1363 (JOSE) ECDSA signature over `data`. */
+  sign(keyReference: string, data: Buffer): Promise<Buffer>;
+  exists(keyReference: string): Promise<boolean>;
+  destroy(keyReference: string): Promise<void>;
+}
+
+/** Tier 2 — PKCS#8 PEM at `file:///<abs path>`, mode 0600. Dev / non-Windows. */
+export declare class FileKeyStore extends KeyStore {
+  readonly scheme: 'file';
+}
+
+/**
+ * The optional native binding `DpapiKeyStore` requires. Ship it as
+ * `@meteorlive/dpapi`; it must be a thin CryptProtectData / CryptUnprotectData
+ * wrapper scoped to `CurrentUser`.
+ */
+export interface DpapiBackend {
+  protectData(plaintext: Buffer, entropy?: Buffer): Buffer;
+  unprotectData(ciphertext: Buffer, entropy?: Buffer): Buffer;
+}
+
+/** Tier 1 (Windows) — DPAPI-wrapped PKCS#8 DER at `dpapi:///<abs path>`. */
+export declare class DpapiKeyStore extends KeyStore {
+  constructor(options?: { backend?: DpapiBackend; entropy?: Buffer });
+  readonly scheme: 'dpapi';
+}
+
+/**
+ * What `CngKeyStore` needs from `@meteorlive/cng`. Note what is absent: there
+ * is no way to obtain the private key, because there is no such API — the key
+ * is created non-exportable inside the KSP and signing happens there.
+ */
+export interface CngBackend {
+  /** Creates a non-exportable P-256 key. Throws rather than overwrite. */
+  createKey(container: string): void;
+  /** BCRYPT_ECCKEY_BLOB: magic, cbKey, X, Y. */
+  publicKeyBlob(container: string): Buffer;
+  /** @returns fixed-width r||s — already JOSE P1363, no DER to convert. */
+  signDigest(container: string, digest: Buffer): Buffer;
+  keyExists(container: string): boolean;
+  deleteKey(container: string): boolean;
+}
+
+/**
+ * Tier 0 (Windows, strongest) — a non-exportable CNG key at
+ * `cng://meteorlive/<id>`.
+ *
+ * Unlike every other tier the private key is never in this process: DPAPI stops
+ * it being readable on disk but hands the bytes back to sign, while here it is
+ * generated inside the key storage provider with the export policy cleared
+ * before finalize and never leaves. An attacker who owns the process can still
+ * ask the provider to sign while they hold the user's token; they cannot take
+ * the key and sign later, elsewhere, forever.
+ */
+export declare class CngKeyStore extends KeyStore {
+  constructor(options?: { backend?: CngBackend });
+  readonly scheme: 'cng';
+}
+
+export declare function createKeyStore(
+  keyReference: string,
+  options?: { dpapi?: { backend?: DpapiBackend; entropy?: Buffer }; cng?: { backend?: CngBackend } }
+): KeyStore;
+
+/**
+ * `path` for the file-backed tiers; `container` for `cng://`, which never
+ * touches the filesystem. Exactly one is present.
+ */
+export declare function parseKeyReference(keyReference: string): {
+  scheme: KeyReferenceScheme;
+  path?: string;
+  container?: string;
+};
+
+/** `'dpapi'` on win32, `'file'` elsewhere. Pass `keyStoreScheme` to override. */
+export declare function defaultKeyStoreScheme(): 'file' | 'dpapi';
+
+// --- installation config ---------------------------------------------------
+
+/**
+ * The complete on-disk config. Every member is non-secret by construction, and
+ * the list is closed: there is no camera, no station, no coordinate and no
+ * key-to-uid map here, because the SDK holds no inventory (contract §1.2).
+ */
+export interface InstallationConfig {
+  schema: 'mlc.installation/1';
+  issuer: string;
+  clientId: ProductClientId;
+  installationUid: string;
+  keyReference: string;
+}
+
+export declare function loadInstallationConfig(configPath: string): Promise<InstallationConfig>;
+
+export declare function saveInstallationConfig(
+  configPath: string,
+  config: {
+    issuer: string;
+    client_id?: ProductClientId;
+    clientId?: ProductClientId;
+    installation_uid?: string;
+    installationUid?: string;
+    key_reference?: string;
+    keyReference?: string;
+  }
+): Promise<InstallationConfig>;
+
+// --- account, stations, cameras --------------------------------------------
+
+/**
+ * The authorized account, minimum fields only (contract §7.2, §10.4): no phone
+ * number, no department, no role list.
+ */
+export interface AccountSummary {
+  accountId: string;
+  nickname: string;
+  tenantId?: string;
+}
+
+/**
+ * One station registered under this account (contract §6.5).
+ *
+ * A station is a *position*, not a device: two cameras that declare the same
+ * coordinates land on the same station, and a camera that moves is re-hung on
+ * another one while the old station stays (§7.9). The client never edits a
+ * station.
+ */
+export interface StationSummary {
+  stationUid: string;
+  stationCode: string;
+  displayName: string;
+  /**
+   * Every station a client creates is `temporary`. `permanent` is set by a
+   * person on the web console, and nothing about the upload path changes when
+   * they do (plan §0.4).
+   */
+  kind: 'permanent' | 'temporary';
+  /** Reserved. Undefined until the science-quality track (S9-S12) ships. */
+  positionSigmaHorizontalM?: number;
+  /** Reserved. Undefined until the science-quality track (S9-S12) ships. */
+  positionSigmaVerticalM?: number;
+  /** Reserved. Undefined until the science-quality track (S9-S12) ships. */
+  validFromUtc?: string;
+  /** Reserved. Undefined until the science-quality track (S9-S12) ships. */
+  validToUtc?: string;
+  countryCode?: string;
+  provinceCode?: string;
+  cityName?: string;
+  districtName?: string;
+  /** Resolved IANA zone; absent/null means pending. */
+  timezone?: string | null;
+  /**
+   * `active`, `revoked` (set from the console — `MsCloudStationSaveReqVO`
+   * accepts `active|revoked`) or `archived` for a retired temporary station
+   * (`MsCloudStationKinds.STATUS_ARCHIVED`). `disabled` was never a server
+   * value. The union keeps `string` on purpose: the vocabulary is the server's
+   * to grow, and a closed union would turn every future state into a type
+   * error in host code that only wanted to display it.
+   */
+  status: 'active' | 'revoked' | 'archived' | string;
+  /**
+   * When an idle temporary station was retired, ISO-8601 UTC. Sent only for an
+   * archived station, so its presence is the signal.
+   *
+   * It is the only way to tell "my position stopped matching" apart from "my
+   * position was never registered": an archived station keeps its row but stops
+   * matching by position, so the next upload from the same coordinates quietly
+   * gets a fresh station (contract §7.9).
+   *
+   * No server writes it yet — nothing sets a station to `archived`, so in
+   * practice this is always undefined today.
+   */
+  archivedAt?: string;
+  [key: string]: unknown;
+}
+
+/** One camera registered under this account (contract §6.5). */
+export interface CameraSummary {
+  cameraUid: string;
+  cameraCode: string;
+  /** The host application's own stable key. Present only on cameras a `camera` block registered. */
+  cameraKey?: string;
+  displayName: string;
+  stationUid: string;
+  stationCode: string;
+  /**
+   * `active` or `revoked` — the two values `MsCloudCameraSaveReqVO`'s
+   * `@Pattern` accepts. There is no `disabled` on the camera axis either, and a
+   * camera is never `archived`: only stations are. `string` is kept for the
+   * same reason as on {@link StationSummary.status}.
+   */
+  status: 'active' | 'revoked' | string;
+  configVersion?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * The station half of a machine declaration (contract §7.9).
+ *
+ * The coordinates and elevation come from the host application's own site configuration —
+ * a meteor detector already knows them, because astrometry needs them. They are
+ * what identifies the station: same rounded coordinates under one account means
+ * the same station.
+ */
+export interface StationBlock {
+  /** WGS84 degrees, -90 to 90. */
+  latitude: number;
+  /** WGS84 degrees, -180 to 180. */
+  longitude: number;
+  /** Whole metres, -500 to 10000. */
+  elevationM: number;
+  /** Optional IANA override; omitted means server coordinate lookup. UTC offsets are refused. */
+  timezone?: string;
+  /** Adopted when the station is first created; ignored afterwards. */
+  name?: string;
+}
+
+/**
+ * A machine declaration: which channel this is, and where it observes from.
+ *
+ * Carried on every upload. The server registers on first sight and answers with
+ * the uids purely as information — the host application does not have to store
+ * them, and the SDK stores nothing.
+ */
+export interface CameraBlock {
+  /**
+   * The host application's own stable key for this channel: 1-64 characters of
+   * `A-Za-z0-9._:-` starting with a letter or digit, carrying no PII.
+   * Generate it once with {@link newCameraKey} and persist it in your own
+   * configuration. Changing it means a different camera.
+   */
+  key: string;
+  /** Display name. Adopted on first sight; a later change renames the camera. */
+  name?: string;
+  station: StationBlock;
+}
+
+/** What the server answers about a declaration. Informational — nothing needs storing. */
+export interface CameraRegistration {
+  cameraUid: string;
+  stationUid: string;
+  createdCamera?: boolean;
+  createdStation?: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * One page of a list endpoint. Not a snapshot and never cached: the account can
+ * gain, lose or disable a camera on the web console at any moment, and the next
+ * upload is judged on the server's live facts (contract §6.6).
+ */
+export interface Page<T> {
+  list: T[];
+  total?: number;
+  [key: string]: unknown;
+}
+
+/** Pagination and filters only. The server derives owner and tenant from the token. */
+export interface StationQuery {
+  pageNo?: number;
+  pageSize?: number;
+  status?: string;
+}
+
+/** Pagination and filters only. The server derives owner and tenant from the token. */
+export interface CameraQuery {
+  pageNo?: number;
+  pageSize?: number;
+  stationUid?: string;
+  status?: string;
+}
+
+/**
+ * A random 32-hex stable key for one host-app channel. Pure local: no network,
+ * no state, no PII. Call it once per channel and write the result into your own
+ * configuration — never on each start, and never derived from a hostname or MAC.
+ */
+export declare function newCameraKey(): string;
+
+// --- first bind ------------------------------------------------------------
+
+export interface ConnectOptions {
+  /** Must carry the `/cloud` path segment; it is the issuer identity, not a hostname. */
+  issuer: string;
+  clientId: ProductClientId;
+  /** Where the zero-secret config is written. */
+  configPath: string;
+  /** Path for a new key. Required unless `keyReference` names an existing one. */
+  keyPath?: string;
+  keyReference?: string;
+  keyStore?: KeyStore;
+  keyStoreScheme?: KeyReferenceScheme;
+  dpapi?: { backend?: DpapiBackend; entropy?: Buffer };
+  cng?: { backend?: CngBackend };
+  /**
+   * `'system'` (default) opens the desktop's default browser. `'manual'` opens
+   * nothing: take the URL from {@link PendingConnect.authorizationUrl}, or pass
+   * `onAuthorizeUrl` — `connect()` refuses manual mode without one, because
+   * otherwise the URL never reaches anybody and the call just times out.
+   */
+  browserMode?: 'system' | 'manual';
+  /** Replace how the URL reaches a browser. Cannot be combined with `browserMode: 'manual'`. */
+  openBrowser?: (url: string) => void | Promise<void>;
+  /**
+   * Receives the authorization URL before the browser is opened.
+   *
+   * The URL no longer carries a session credential — `bridge` is gone — but it
+   * still carries `state` and the loopback port, and contract §10.1 forbids
+   * logging it. Hand it to a browser; do not print it.
+   */
+  onAuthorizeUrl?: (url: string) => void | Promise<void>;
+  /** Aborting settles the flow with `kind: 'cancelled'`, `action: 'authorize_aborted'`. */
+  signal?: AbortSignal;
+  /** How long to wait for the browser callback. Default 300000. */
+  timeoutMs?: number;
+  httpTimeoutMs?: number;
+  /** Options for the {@link MeteorCloudClient} built from the result. */
+  clientOptions?: ClientOptions;
+  transport?: Transport;
+  randomBytes?: (size: number) => Buffer | Uint8Array;
+
+  /** @deprecated Removed in 0.5.0: the browser signs in on its own and the SDK never relays a session grant. */
+  bridgeGrant?: never;
+  /** @deprecated Removed in 0.5.0: the consent page shows no cameras; declare the camera on each upload instead. */
+  proposal?: never;
+  /** @deprecated Removed in 0.5.0: the consent page submits no per-camera decisions. */
+  installationDecisions?: never;
+  /** @deprecated Removed in 0.5.0: the SDK neither reads nor forwards host capture channels. */
+  channels?: never;
+  /** @deprecated Removed in 0.5.0: the SDK neither reads nor forwards host devices. */
+  devices?: never;
+  /** @deprecated Removed in 0.5.0: the SDK holds no camera inventory. */
+  cameras?: never;
+  /** @deprecated Removed in 0.5.0: the grant is account-wide; name the camera on each upload instead. */
+  cameraUid?: never;
+  /** @deprecated Removed in 0.5.0: the grant is account-wide; the station follows from the upload. */
+  stationUid?: never;
+}
+
+export interface InstallationSummary {
+  installationUid: string;
+  productClientId: ProductClientId;
+  status: 'active';
+}
+
+export interface ConnectResult {
+  /** Ready to use. Everything below is a convenience the bind already paid for. */
+  client: MeteorCloudClient;
+  /**
+   * The first operational token (contract §2.2, §6.1). Interoperability only —
+   * it is **not** a signal that you should manage renewal yourself; the client
+   * mints and renews on demand. Memory only: never write it to
+   * `installation.json`, a journal, a log or a crash report.
+   */
+  token: AccessToken;
+  account: AccountSummary;
+  installation: InstallationSummary;
+  config: InstallationConfig;
+  configPath: string;
+}
+
+/**
+ * A bind in progress. The loopback listener is already up when you receive
+ * this, so the URL is safe to open immediately — a consent redirect that lands
+ * on a port which has not been bound yet is unrecoverable.
+ */
+export interface PendingConnect {
+  authorizationUrl: string;
+  wait(): Promise<ConnectResult>;
+  /** Settles `wait()` with `kind: 'cancelled'`; reports nothing itself. */
+  cancel(): Promise<void>;
+}
+
+/**
+ * The account namespace (contract §6.1). `MeteorCloud.connect()` is the one
+ * call a first-time integration needs.
+ */
+export declare const MeteorCloud: {
+  /**
+   * First bind, one call: generate a local P-256 key, open the browser at the
+   * authorization endpoint (code + PKCE S256, loopback redirect on an
+   * OS-assigned port), wait for the callback, exchange the code, persist a
+   * zero-secret config, mint the first operational token and read the account.
+   *
+   * The user signs in with the ordinary MeteorCloud web login (including
+   * WeChat) and clicks one "allow" screen. No grant to copy, no code to paste,
+   * and no camera to pick.
+   */
+  connect(options: ConnectOptions): Promise<ConnectResult>;
+  /** Two-phase bind for callers that open the URL themselves (Electron, an embedded WebView). */
+  beginConnect(options: ConnectOptions): Promise<PendingConnect>;
+  /** A random stable key for one host-app channel. Pure local. */
+  newCameraKey(): string;
+};
+
+/** @deprecated Prefer {@link MeteorCloud.connect}. Same function, kept for the migration window. */
+export declare function connect(options: ConnectOptions): Promise<ConnectResult>;
+
+/** Two-phase bind. See {@link MeteorCloud.beginConnect}. */
+export declare function beginConnect(options: ConnectOptions): Promise<PendingConnect>;
+
+// --- transport -------------------------------------------------------------
+
+export interface TransportRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: Buffer;
+  /** A *factory* — a retried chunk needs a fresh stream over the same bytes. */
+  bodyStream?: () => NodeJS.ReadableStream;
+  timeoutMs: number;
+  maxResponseBytes?: number;
+}
+
+export interface TransportResponse {
+  status: number;
+  headers: Headers | Record<string, string>;
+  body: Buffer;
+}
+
+export type Transport = (request: TransportRequest) => Promise<TransportResponse>;
+
+// --- tokens ----------------------------------------------------------------
+
+export interface AccessToken {
+  accessToken: string;
+  tokenType: string;
+  scope: string;
+  /** Absolute epoch seconds. */
+  expiresAt: number;
+  /** Truncated SHA-256 of the token, safe to log. */
+  fingerprint: string;
+}
+
+export interface InstallationTokenSourceOptions {
+  issuer: string;
+  installationUid: string;
+  keyStore: KeyStore;
+  keyReference: string;
+  scopes?: string[];
+  /** Send a DPoP proof with every request. Default true. */
+  dpop?: boolean;
+  /** Default `'auto'`: DPoP when the token is DPoP-bound, else Bearer. */
+  authScheme?: 'auto' | 'bearer' | 'dpop';
+  transport?: Transport;
+  timeoutMs?: number;
+  attempts?: number;
+  /** Renew this many seconds before nominal expiry. Default 60. */
+  marginSeconds?: number;
+  now?: () => number;
+  random?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  jti?: () => string;
+}
+
+/** Mints short-lived opaque device tokens from the local key (RFC 7523). */
+export declare class InstallationTokenSource {
+  constructor(options: InstallationTokenSourceOptions);
+  getToken(): Promise<AccessToken>;
+  /** Drops the cached token so the next call re-asserts. */
+  invalidate(): void;
+  noteResourceNonce(nonce?: string): void;
+  publicJwk(): Promise<JsonWebKey>;
+  authorizationHeaders(method: string, url: string): Promise<Record<string, string>>;
+  /** RFC 7523 client assertion, ES256, `exp - iat = 60`. */
+  createAssertion(): Promise<string>;
+  /** RFC 9449 DPoP proof. `ath` is included only when `accessToken` is given. */
+  createProof(
+    method: string,
+    url: string,
+    options?: { accessToken?: string; nonce?: string }
+  ): Promise<string>;
+}
+
+// --- journal ---------------------------------------------------------------
+
+export interface JournalFileState {
+  /** Relative upload target path; the local plane has no COS object key. */
+  key: string;
+  size: number;
+  sha256: string;
+  /** Last offset the client believes the server holds. The server is authoritative. */
+  offset: number;
+}
+
+export interface JournalState {
+  version: 2;
+  sessionUid: string;
+  files: Record<string, JournalFileState>;
+}
+
+export declare class UploadJournal {
+  constructor(journalPath: string, sessionUid: string);
+  readonly path: string;
+  readonly sessionUid: string;
+  state: JournalState;
+  load(): Promise<this>;
+  fileState(role: ArtifactRole | string): JournalFileState;
+  reconcile(
+    role: ArtifactRole | string,
+    identity: { key: string; size: number; sha256: string }
+  ): JournalFileState;
+  save(): Promise<void>;
+  /**
+   * The last `io` failure swallowed by a best-effort journal write, or
+   * undefined. The journal is advisory — a full disk must not abort an upload
+   * that needs no local disk — so failures are recorded here instead of thrown.
+   * Read it if you want to warn about a station whose disk is failing.
+   */
+  lastSaveError?: MeteorCloudError;
+}
+
+// --- client ----------------------------------------------------------------
+
+export interface ClientOptions {
+  /** Defaults to the issuer origin. */
+  apiBase?: string;
+  httpTimeoutMs?: number;
+  /** Timeout for one chunk PUT. Default 600000. */
+  chunkTimeoutMs?: number;
+  controlAttempts?: number;
+  chunkAttempts?: number;
+  /** Default and maximum 32 MiB. Clamped to `capabilities.directPut.maxChunkBytes`. */
+  chunkSize?: number;
+  dpop?: boolean;
+  authScheme?: 'auto' | 'bearer' | 'dpop';
+  tokenMarginSeconds?: number;
+  keyStore?: KeyStore;
+  /** Only consulted when `keyStore` is absent and the reference is `dpapi://`. */
+  dpapi?: { backend?: DpapiBackend; entropy?: Buffer };
+  /** Only consulted when `keyStore` is absent and the reference is `cng://`. */
+  cng?: { backend?: CngBackend };
+  tokenSource?: InstallationTokenSource;
+  transport?: Transport;
+  now?: () => number;
+  random?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  jti?: () => string;
+}
+
+export interface ClientConfig extends ClientOptions {
+  issuer: string;
+  clientId: ProductClientId;
+  installationUid: string;
+  keyReference: string;
+}
+
+interface AuthorizeRequestBase {
+  clientRequestKey: string;
+  manifestJson: string;
+  artifacts: Artifact[];
+  onProgress?: ProgressCallback;
+}
+
+/**
+ * Where an upload came from. Exactly one of the two is required, and both are
+ * accepted together (contract §7.6, §7.9).
+ *
+ * - `camera` is the supported shape: the host application's own stable key plus
+ *   the station's coordinates, replayed on every upload. The server registers
+ *   on first sight and answers with the uids as information.
+ * - `cameraUid` names a camera you already happen to know — from a previous
+ *   `ensureCamera()`, or from `listCameras()`. It is authoritative when both
+ *   are given, and the server checks the registered key against `camera.key`.
+ *
+ * Neither one is a *grant*: the server resolves ownership from the token every
+ * time, so this selects a camera and never confers access to one.
+ */
+export type AuthorizeRequest =
+  | (AuthorizeRequestBase & { camera: CameraBlock; cameraUid?: string })
+  | (AuthorizeRequestBase & { cameraUid: string; camera?: CameraBlock });
+
+/** One event: an {@link AuthorizeRequest} plus the journal that makes it resumable. */
+export type UploadEventRequest = AuthorizeRequest & { journalPath: string };
+
+/** Per-artifact PUT target. Present only for `local_direct` sessions. */
+export interface UploadTarget {
+  role: ArtifactRole;
+  /** Relative Device API path, e.g. `upload-sessions/us_.../artifacts/ecsv`. */
+  path: string;
+  /** The server's durable count — the only legal offset for the next chunk. */
+  receivedBytes: number;
+  sizeBytes: number;
+}
+
+export interface UploadSession {
+  sessionUid: string;
+  uploadUid?: string;
+  jobUid?: string;
+  status: string;
+  duplicate?: boolean;
+  expiresAt?: string;
+  /**
+   * Where the declaration landed. Echoed on the `authorize` response only —
+   * that is the hop that registers the machine — so `uploadEvent()`, which
+   * resolves with the *finalize* response, does not carry them. Informational
+   * either way; nothing needs storing.
+   */
+  stationUid?: string;
+  cameraUid?: string;
+  createdStation?: boolean;
+  createdCamera?: boolean;
+  uploadTargets?: UploadTarget[];
+  files?: Record<string, unknown>[];
+  capabilities?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface JobQueryCapability {
+  observed: boolean;
+  supported: boolean;
+  compatible: boolean;
+  contractVersion?: string;
+  minimumPollSeconds: number;
+}
+
+export interface JobStatus {
+  contractVersion: 'mlc.device-job-status/2' | string;
+  uploadUid: string;
+  jobUid: string;
+  submissionStatus: string;
+  jobStatus: 'queued' | 'running' | 'succeeded' | 'failed' | 'dead' | string;
+  resultStatus: string;
+  resultFinal: boolean;
+  terminal: boolean;
+  nextPollAfterSeconds?: number | null;
+  reasonCode?: string | null;
+  reasonMessage?: string | null;
+  attemptCount?: number;
+  requeueCount?: number;
+  updatedAt: string;
+  result?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+
+export declare class MeteorCloudClient {
+  constructor(config: ClientConfig);
+
+  readonly issuer: string;
+  readonly apiBase: string;
+  readonly clientId: ProductClientId;
+  readonly installationUid: string;
+  readonly keyReference: string;
+  readonly keyStore: KeyStore;
+  readonly tokens: InstallationTokenSource;
+
+  static fromConfig(configPath: string, options?: ClientOptions): Promise<MeteorCloudClient>;
+
+  /**
+   * @deprecated Removed. The bind entry points are {@link MeteorCloud.connect}
+   * and {@link MeteorCloud.beginConnect} (plan §0.9), and nothing on the class
+   * duplicates them. Declared as `never` so a caller still on the 0.4.x
+   * spelling gets a compile error naming the replacement rather than a runtime
+   * "is not a function".
+   */
+  static connect?: never;
+
+  /**
+   * Whether this client has a complete identity AND a usable private key.
+   *
+   * `fromConfig()` never touches the key, so a config that outlived its key
+   * loads fine and fails at the first token mint — after `uploadEvent()` has
+   * already hashed every artifact. Check this at startup instead. Signs a probe
+   * rather than stat-ing, because a DPAPI blob can exist and still be
+   * unreadable by the current Windows user.
+   */
+  isBound(): Promise<boolean>;
+
+  /**
+   * The current operational token, minted or renewed as needed.
+   *
+   * Interoperability only. Ordinary integrations never call this: the client
+   * already attaches `Authorization` and the DPoP proof to every request, and a
+   * token you hold yourself is one you have to keep out of your own logs.
+   */
+  getAccessToken(): Promise<AccessToken>;
+
+  /** The authorized account (contract §7.2). Requires `account:read`. */
+  getAccount(): Promise<AccountSummary>;
+
+  /**
+   * The stations already registered under this account (contract §7.3).
+   *
+   * An ordinary query, not a snapshot and not cached. Call it when your UI
+   * needs the list — never on connect, renewal or upload. The server narrows
+   * to the token's owner and tenant, so the query carries pagination and
+   * filters only; an owner-shaped key is refused locally.
+   */
+  listStations(query?: StationQuery): Promise<Page<StationSummary>>;
+
+  /**
+   * The cameras already registered under this account (contract §7.4).
+   *
+   * This queries MeteorCloud; it does not scan the machine. A host application
+   * that carries a `camera` block on each upload never needs it.
+   */
+  listCameras(query?: CameraQuery): Promise<Page<CameraSummary>>;
+
+
+  /**
+   * One camera by uid. A camera that does not exist and one that belongs to
+   * somebody else are deliberately indistinguishable (both 404, contract §9.4).
+   */
+  getCamera(cameraUid: string): Promise<CameraSummary>;
+
+  /**
+   * Optional pre-registration (contract §7.9). The argument is the camera block
+   * itself — `{key, name?, station}`, not `{camera: {...}}` — and the upsert is
+   * the same one an upload performs.
+   *
+   * Optional means optional: carrying the block on each `uploadEvent()` is the
+   * supported path, and even here the returned uid does not have to be stored.
+   */
+  ensureCamera(input: CameraBlock): Promise<CameraRegistration>;
+
+  /** Snapshot from the latest session response; malformed/absent capability disables polling. */
+  jobQueryCapability(): JobQueryCapability;
+  /** One HTTP resource request; schedule retries using nextPollAfterSeconds or the error. */
+  jobStatus(jobUid: string): Promise<JobStatus>;
+
+  authorize(request: AuthorizeRequest): Promise<UploadSession>;
+  uploadSessionStatus(sessionUid: string): Promise<UploadSession>;
+  refresh(sessionUid: string): Promise<UploadSession>;
+  /** Sends `{files: []}` — the local plane carries no receipts. */
+  finalize(sessionUid: string): Promise<UploadSession>;
+  abort(sessionUid: string, reason?: string): Promise<boolean>;
+
+  uploadAuthorized(
+    session: UploadSession,
+    artifacts: Artifact[],
+    journalPath: string,
+    onProgress?: ProgressCallback
+  ): Promise<JournalState>;
+
+  /** authorize → chunked PUT → finalize, resumable at every step. */
+  uploadEvent(request: UploadEventRequest): Promise<UploadSession>;
+}
+
+// --- low-level JOSE helpers ------------------------------------------------
+
+export declare const jose: {
+  ES256: 'ES256';
+  P256_CRV: 'P-256';
+  base64UrlEncode(input: Buffer | Uint8Array | string): string;
+  base64UrlEncodeJson(value: unknown): string;
+  base64UrlDecode(value: string): Buffer;
+  randomToken(bytes?: number): string;
+  /** RFC 7636 S256. */
+  pkceChallengeS256(verifier: string): string;
+  createPkcePair(randomBytes?: (size: number) => Buffer | Uint8Array): {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+  };
+  p256PublicJwk(key: unknown): JsonWebKey;
+  /** RFC 7638 thumbprint, base64url SHA-256 — matches the server's `cnf.jkt`. */
+  jwkThumbprint(jwk: JsonWebKey): string;
+  signCompactJws(
+    header: Record<string, unknown>,
+    claims: Record<string, unknown>,
+    sign: (signingInput: Buffer) => Promise<Buffer> | Buffer
+  ): Promise<string>;
+  /** RFC 9449 `htu`: the request URI without query or fragment. */
+  dpopHtu(url: string): string;
+};
+
+export declare const SDK_VERSION: '0.5.1';
+export declare const CONFIG_SCHEMA: 'mlc.installation/1';
+export declare const DIRECT_PUT_CONTRACT: 'mlc.device-direct-put/1';
+export declare const JOURNAL_VERSION: 2;
+/**
+ * The scope group an operational token requests (contract §7.1, plan §1.2).
+ *
+ * Defined and checked per endpoint from day one; v0.5.0 still issues the whole
+ * group, so narrowing a grant later needs no second breaking change.
+ * `device-context:read` is not in the group and is not accepted as an alias:
+ * `/device-context` was deleted outright along with the bound-camera model it
+ * reported (plan §0.9), so there is nothing for the old name to stand for.
+ */
+export declare const DEVICE_SCOPES: readonly [
+  'account:read',
+  'installation:read',
+  'station:read',
+  'camera:read',
+  'camera:write',
+  'ingest:create',
+  'ingest:finalize',
+  'job:read'
+];
+export declare const BIND_SCOPE: 'mscloud.bind';
+export declare const CLIENT_ASSERTION_TYPE: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+export declare const DPAPI_MODULE: '@meteorlive/dpapi';
+export declare const CNG_MODULE: '@meteorlive/cng';
+export declare const ROLES: readonly ArtifactRole[];
+export declare const DEFAULT_CHUNK_SIZE: number;
+export declare const MAX_CHUNK_SIZE: number;
+/** Device API business codes the data plane can return. */
+export declare const API_CODE: {
+  readonly DIGEST_MISMATCH: 1030002005;
+  readonly REQUEST_TOO_LARGE: 1030003010;
+  readonly CHUNK_OUT_OF_ORDER: 1030003030;
+  readonly CHUNK_RANGE_INVALID: 1030003031;
+  readonly ARTIFACT_ALREADY_COMPLETE: 1030003032;
+  readonly DIRECT_PUT_DISABLED: 1030003034;
+  /** authorize declared no camera: neither a `camera` block nor a `cameraUid`. */
+  readonly CAMERA_REQUIRED: 1030003035;
+};