@mentra/cloud-client 3.2.0-dev.136 → 3.2.0-dev.153

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/cloud-client",
-  "version": "3.2.0-dev.136",
+  "version": "3.2.0-dev.153",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -12,7 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "3.2.0-dev.136",
+    "@mentra/cloud-protocol": "3.2.0-dev.153",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {

package/src/client.ts

@@ -14,28 +14,28 @@
  *
  * See docs/issues/004-cloud-client/design.md ("The top-level CloudClient").
  */
-import { noopLogger } from "./logger";
-import type { Logger } from "./logger";
-import type { CloudClientConfig } from "./config";
-import { createHttpClient } from "./http";
-import { CloudClientError } from "./errors";
-import type { ConnectionInit } from "@mentra/cloud-protocol";
-import { systemTimers } from "./timers";
+import {noopLogger} from "./logger"
+import type {Logger} from "./logger"
+import type {CloudClientConfig} from "./config"
+import {createHttpClient} from "./http"
+import {CloudClientError} from "./errors"
+import type {ConnectionInit} from "@mentra/cloud-protocol"
+import {systemTimers} from "./timers"
 
 // The module implementations. Each is owned by another agent under ./modules/**;
 // this file only constructs them, matching the constructor signatures fixed in
 // design.md exactly.
-import { Auth } from "./modules/auth/auth";
-import { TokenStore } from "./modules/auth/token-store";
-import { Runtime } from "./modules/runtime/runtime";
-import { Connection } from "./modules/runtime/connection";
-import { RuntimeEmitter } from "./modules/runtime/emitter";
-import { Subscriptions } from "./modules/runtime/subscriptions";
-import { Camera } from "./modules/runtime/camera";
-import { Maps } from "./modules/runtime/maps";
-import { Tts } from "./modules/runtime/tts";
-import { UdpAudio } from "./modules/runtime/audio-udp";
-import { Core } from "./modules/core/core";
+import {Auth} from "./modules/auth/auth"
+import {TokenStore} from "./modules/auth/token-store"
+import {Runtime} from "./modules/runtime/runtime"
+import {Connection} from "./modules/runtime/connection"
+import {RuntimeEmitter} from "./modules/runtime/emitter"
+import {Subscriptions} from "./modules/runtime/subscriptions"
+import {Camera} from "./modules/runtime/camera"
+import {Maps} from "./modules/runtime/maps"
+import {Tts} from "./modules/runtime/tts"
+import {UdpAudio} from "./modules/runtime/audio-udp"
+import {Core} from "./modules/core/core"
 
 /**
  * Default reconnect/backoff for the live socket when a host supplies none.
@@ -47,7 +47,7 @@ import { Core } from "./modules/core/core";
  * lockstep after a shared blip. A host can override any of these through
  * `config.reconnect`.
  */
-const DEFAULT_RECONNECT = { baseMs: 500, maxMs: 5_000, jitter: true };
+const DEFAULT_RECONNECT = {baseMs: 500, maxMs: 5_000, jitter: true}
 
 /**
  * The default audio codec the client announces in the handshake.
@@ -57,8 +57,8 @@ const DEFAULT_RECONNECT = { baseMs: 500, maxMs: 5_000, jitter: true };
  * now the handshake announces the device default so audio that starts immediately
  * after connect is decoded correctly.
  */
-const DEFAULT_AUDIO_CODEC = "pcm" as const;
-const DEFAULT_AUDIO_SAMPLE_RATE = 16_000;
+const DEFAULT_AUDIO_CODEC = "pcm" as const
+const DEFAULT_AUDIO_SAMPLE_RATE = 16_000
 
 /**
  * The protocol semver this client build speaks, announced in `connection.init`.
@@ -66,7 +66,7 @@ const DEFAULT_AUDIO_SAMPLE_RATE = 16_000;
  * Hardcoded to the 2.x line this package targets; bumped here when the client
  * starts speaking a newer protocol build, so there is one place to change it.
  */
-const PROTOCOL_VERSION = "2.0.0";
+const PROTOCOL_VERSION = "2.0.0"
 
 /**
  * Rewrite a base URL to route through a proxy host while preserving its path.
@@ -77,12 +77,12 @@ const PROTOCOL_VERSION = "2.0.0";
  * core/runtime address that carries a path prefix is not lost when proxied.
  */
 function rewriteThroughProxy(target: string, proxy: string): string {
-  const proxyUrl = new URL(proxy);
-  const targetUrl = new URL(target);
+  const proxyUrl = new URL(proxy)
+  const targetUrl = new URL(target)
   // Keep the target's path/query, take the proxy's origin.
-  targetUrl.protocol = proxyUrl.protocol;
-  targetUrl.host = proxyUrl.host;
-  return targetUrl.toString();
+  targetUrl.protocol = proxyUrl.protocol
+  targetUrl.host = proxyUrl.host
+  return targetUrl.toString()
 }
 
 /**
@@ -95,10 +95,10 @@ function rewriteThroughProxy(target: string, proxy: string): string {
  * place that knows the runtime's HTTP shape also derives its socket URL.
  */
 function toRuntimeWsUrl(httpBase: string): string {
-  const u = new URL(httpBase);
-  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
-  u.pathname = `${u.pathname.replace(/\/$/, "")}/ws/session`;
-  return u.toString();
+  const u = new URL(httpBase)
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:"
+  u.pathname = `${u.pathname.replace(/\/$/, "")}/ws/session`
+  return u.toString()
 }
 
 export class CloudClient {
@@ -107,27 +107,27 @@ export class CloudClient {
   // of its public contract (per design.md), so a host gets the full, typed
   // surface (`cloud.auth.getRuntimeToken()`, etc.) straight off these fields with
   // no parallel interface to keep in sync.
-  readonly auth: Auth;
-  readonly runtime: Runtime;
-  readonly core?: Core;
+  readonly auth: Auth
+  readonly runtime: Runtime
+  readonly core?: Core
 
   constructor(config: CloudClientConfig) {
     // One logger for the whole client, so a host routes every module's logs in
     // one place. Default to the silent no-op so we never print uninvited.
-    const logger: Logger = config.logger ?? noopLogger;
+    const logger: Logger = config.logger ?? noopLogger
 
     // Reconnect/backoff lives here so the socket's timing is tuned in one spot.
-    const reconnect = config.reconnect ?? DEFAULT_RECONNECT;
-    const timers = config.timers ?? systemTimers;
+    const reconnect = config.reconnect ?? DEFAULT_RECONNECT
+    const timers = config.timers ?? systemTimers
 
     // Resolve the two base addresses. With a proxy set, both route through it;
     // without one, each module talks to its own service directly.
-    const { core: coreBase, runtime: runtimeBase, proxy } = config.endpoints;
-    const coreUrl = coreBase ? (proxy ? rewriteThroughProxy(coreBase, proxy) : coreBase) : undefined;
-    const runtimeUrl = proxy ? rewriteThroughProxy(runtimeBase, proxy) : runtimeBase;
+    const {core: coreBase, runtime: runtimeBase, proxy} = config.endpoints
+    const coreUrl = coreBase ? (proxy ? rewriteThroughProxy(coreBase, proxy) : coreBase) : undefined
+    const runtimeUrl = proxy ? rewriteThroughProxy(runtimeBase, proxy) : runtimeBase
 
     if (config.auth.core && !coreUrl) {
-      throw new CloudClientError("auth.core requires endpoints.core");
+      throw new CloudClientError("auth.core requires endpoints.core")
     }
 
     // Runtime auth is the mandatory half (Core is optional). Guard it before the
@@ -135,12 +135,12 @@ export class CloudClient {
     // (`{ subjectToken, subjectTokenType }`, no `runtime`) gets a clear
     // configuration error instead of an opaque `TypeError` from `"source" in undefined`.
     if (!config.auth.runtime) {
-      throw new CloudClientError("auth.runtime is required (got a pre-split/flat auth config?)");
+      throw new CloudClientError("auth.runtime is required (got a pre-split/flat auth config?)")
     }
 
-    const runtimeUsesCore = "source" in config.auth.runtime && config.auth.runtime.source === "core";
+    const runtimeUsesCore = "source" in config.auth.runtime && config.auth.runtime.source === "core"
     if (runtimeUsesCore && (!coreUrl || !config.auth.core)) {
-      throw new CloudClientError("auth.runtime.source='core' requires endpoints.core and auth.core");
+      throw new CloudClientError("auth.runtime.source='core' requires endpoints.core and auth.core")
     }
 
     // Build auth FIRST: runtime and core both source their Bearer from it, so it
@@ -151,9 +151,12 @@ export class CloudClient {
     // before any access token exists. It is deliberately Core-only: runtime-only
     // clients never get a fallback that points Core/Auth calls at Runtime.
     const authHttp = coreUrl
-      ? createHttpClient({ baseUrl: coreUrl, logger, fetch: config.transports.http, timers })
-      : undefined;
-    const store = new TokenStore({ storage: config.transports.storage });
+      ? createHttpClient({baseUrl: coreUrl, logger, fetch: config.transports.http, timers})
+      : undefined
+    const store = new TokenStore({
+      storage: config.transports.storage,
+      storageKey: config.authStorageKey,
+    })
     const auth = new Auth({
       http: authHttp,
       store,
@@ -163,10 +166,11 @@ export class CloudClient {
       // requests, but still use the host's injected HTTP transport.
       baseUrl: coreUrl,
       fetch: config.transports.http,
-    });
+      timers,
+    })
 
-    const getRuntimeToken = (): Promise<string> => auth.getRuntimeToken();
-    const getCoreToken = (): Promise<string> => auth.getCoreToken();
+    const getRuntimeToken = (): Promise<string> => auth.getRuntimeToken()
+    const getCoreToken = (): Promise<string> => auth.getCoreToken()
 
     const coreHttp =
       coreUrl && config.auth.core
@@ -177,17 +181,17 @@ export class CloudClient {
             fetch: config.transports.http,
             timers,
           })
-        : null;
+        : null
     const runtimeHttp = createHttpClient({
       baseUrl: runtimeUrl,
       getToken: getRuntimeToken,
       logger,
       fetch: config.transports.http,
       timers,
-    });
+    })
 
-    const emitter = new RuntimeEmitter();
-    const subscriptions = new Subscriptions({ http: runtimeHttp, timers });
+    const emitter = new RuntimeEmitter()
+    const subscriptions = new Subscriptions({http: runtimeHttp, timers})
 
     // The handshake payload the connection sends on every (re)open. It is a
     // factory (not a fixed value) so each reconnect re-reads the current defaults
@@ -213,10 +217,10 @@ export class CloudClient {
         sampleRate: config.audio?.sampleRate ?? DEFAULT_AUDIO_SAMPLE_RATE,
         // Only LC3 carries a frame size; the config type forces LC3 hosts to
         // state theirs explicitly (decoder is sized from this — no safe guess).
-        ...(config.audio?.codec === "lc3" ? { frameSizeBytes: config.audio.frameSizeBytes } : {}),
+        ...(config.audio?.codec === "lc3" ? {frameSizeBytes: config.audio.frameSizeBytes} : {}),
         initialSubscriptions: subscriptions.currentSet(),
       },
-    });
+    })
 
     // Build the remaining runtime pieces, then the runtime that orchestrates them.
     const connection = new Connection({
@@ -227,14 +231,14 @@ export class CloudClient {
       reconnect,
       timers,
       onAuthRejected: async () => {
-        await auth.getRuntimeToken({ forceRefresh: true });
+        await auth.getRuntimeToken({forceRefresh: true})
       },
       logger,
-    });
-    const camera = new Camera({ http: runtimeHttp, timers });
-    const tts = new Tts({ http: runtimeHttp });
-    const maps = new Maps({ http: runtimeHttp });
-    const audio = new UdpAudio({ udp: config.transports.udp });
+    })
+    const camera = new Camera({http: runtimeHttp, timers})
+    const tts = new Tts({http: runtimeHttp})
+    const maps = new Maps({http: runtimeHttp})
+    const audio = new UdpAudio({udp: config.transports.udp})
 
     const runtime = new Runtime({
       connection,
@@ -249,14 +253,14 @@ export class CloudClient {
       // On a fatal AUTH_EXPIRED at handshake, runtime forces auth to drop its
       // cached access token and refresh; the connection then re-reads the fresh
       // token via getRuntimeToken on the reopen.
-      forceRefreshToken: () => auth.getRuntimeToken({ forceRefresh: true }),
-    });
+      forceRefreshToken: () => auth.getRuntimeToken({forceRefresh: true}),
+    })
 
     // Core is last: stateless REST on the core service, Bearer from auth.
-    const core = coreHttp ? new Core({ http: coreHttp }) : undefined;
+    const core = coreHttp ? new Core({http: coreHttp}) : undefined
 
-    this.auth = auth;
-    this.runtime = runtime;
-    this.core = core;
+    this.auth = auth
+    this.runtime = runtime
+    this.core = core
   }
 }

package/src/config.ts

@@ -7,9 +7,9 @@
  *
  * See docs/issues/004-cloud-client/spec.md ("Construction") and design.md.
  */
-import type { Logger } from "./logger";
-import type { CloudClientTransports } from "./transports";
-import type { CloudClientTimers } from "./timers";
+import type {Logger} from "./logger"
+import type {CloudClientTransports} from "./transports"
+import type {CloudClientTimers} from "./timers"
 
 /**
  * The full shape passed to the root `CloudClient`.
@@ -23,28 +23,28 @@ export interface CloudClientConfig {
   // `core` is optional only for runtime-only deployments. If `auth.core` is set,
   // or if `auth.runtime.source` is `"core"`, this must be present; Core/Auth
   // calls are never routed to Runtime.
-  endpoints: { core?: string; runtime: string; proxy?: string };
-  auth: AuthConfig;
-  transports: CloudClientTransports;
+  endpoints: {core?: string; runtime: string; proxy?: string}
+  auth: AuthConfig
+  transports: CloudClientTransports
   /**
    * Scheduler for all delayed client work, including connection/audio
    * liveness, retries, and request timeouts. React Native hosts must provide
    * native background timers because ordinary JS timers pause when Android
    * backgrounds the app.
    */
-  timers?: CloudClientTimers;
-  logger?: Logger;
+  timers?: CloudClientTimers
+  logger?: Logger
+  /** Override the persisted refresh-token key to isolate deployment sessions. */
+  authStorageKey?: string
   // backoff tuning for the live socket; one place so a host can match its fleet
-  reconnect?: { baseMs: number; maxMs: number; jitter: boolean };
+  reconnect?: {baseMs: number; maxMs: number; jitter: boolean}
   /**
    * Audio format announced in `connection.init`. Defaults to PCM at 16 kHz when
    * omitted. An LC3 host MUST pass the frame size its encoder emits — the
    * runtime sizes its decoder from this field, and phone builds legitimately
    * differ (20/40/60); there is no safe default, so the type requires it.
    */
-  audio?:
-    | { codec: "pcm"; sampleRate?: number }
-    | { codec: "lc3"; sampleRate?: number; frameSizeBytes: 20 | 40 | 60 };
+  audio?: {codec: "pcm"; sampleRate?: number} | {codec: "lc3"; sampleRate?: number; frameSizeBytes: 20 | 40 | 60}
 }
 
 /**
@@ -53,7 +53,7 @@ export interface CloudClientConfig {
  * The cloud's `/exchange` endpoint needs to know how to verify the incoming
  * token, so the type travels alongside the token itself.
  */
-export type SubjectTokenType = "oem-jwt" | "mentra-core" | "supabase";
+export type SubjectTokenType = "oidc" | "oem-jwt" | "mentra-core" | "supabase"
 
 /**
  * The three ways a host can give the client its credentials.
@@ -65,11 +65,11 @@ export type SubjectTokenType = "oem-jwt" | "mentra-core" | "supabase";
  */
 export type CoreAuthConfig =
   // exchanged once on first use
-  | { subjectToken: string; subjectTokenType: SubjectTokenType }
+  | {subjectToken: string; subjectTokenType: SubjectTokenType}
   // fetched on demand, for subject tokens that expire before exchange
-  | { getSubjectToken: () => Promise<{ token: string; type: SubjectTokenType }> }
+  | {getSubjectToken: () => Promise<{token: string; type: SubjectTokenType}>}
   // already exchanged, skip straight to refresh
-  | { accessToken: string; refreshToken: string };
+  | {accessToken: string; refreshToken: string}
 
 export type RuntimeAuthConfig =
   | {
@@ -77,16 +77,16 @@ export type RuntimeAuthConfig =
        * Ask Cloud Core/Auth to mint a short-lived `cloud-runtime` token. This is
        * explicit hosted-Core mode, not an implicit Core-token fallback.
        */
-      source: "core";
+      source: "core"
     }
   | {
       /** Host/OEM/local-dev supplied runtime-token provider. */
-      getToken(opts?: { forceRefresh?: boolean }): Promise<string>;
-    };
+      getToken(opts?: {forceRefresh?: boolean}): Promise<string>
+    }
 
 export interface AuthConfig {
   // Core-backed auth owns identity, Core token exchange/refresh, miniapp token
   // minting, and miniapp auto-auth. Omit only for true runtime-only deployments.
-  core?: CoreAuthConfig;
-  runtime: RuntimeAuthConfig;
+  core?: CoreAuthConfig
+  runtime: RuntimeAuthConfig
 }

package/src/errors.ts

@@ -40,6 +40,24 @@ export class HttpError extends CloudClientError {
   }
 }
 
+/**
+ * Thrown by `cloud.auth.clearSession()` when local credentials were cleared but
+ * Core did not confirm revocation of the session (revoke failed after bounded
+ * retries, or the token needed to authorize it could not be refreshed). The
+ * client is logged out locally; the host must not treat the server-side session
+ * as dead and should surface or defer the failure. `cause` is the underlying error.
+ */
+export class SessionRevocationError extends CloudClientError {
+  readonly cause: unknown;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = "SessionRevocationError";
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
 /**
  * Thrown when a token refresh fails and the host must send the user back through
  * login. Separate from `HttpError` so a host can catch the "credentials are

package/src/index.ts

@@ -17,6 +17,7 @@
 // The top-level object. Implemented in ./client by the client agent; re-exported
 // here so the public import is `@mentra/cloud-client`, not a deep path.
 export { CloudClient } from "./client";
+export { DEFAULT_REFRESH_TOKEN_KEY } from "./modules/auth/token-store";
 
 // Construction contract.
 export type {
@@ -35,7 +36,12 @@ export type {
 export type { CloudClientTimers } from "./timers";
 
 // Local error types a host can branch on with `instanceof`.
-export { CloudClientError, HttpError, AuthExpiredError } from "./errors";
+export {
+  CloudClientError,
+  HttpError,
+  AuthExpiredError,
+  SessionRevocationError,
+} from "./errors";
 
 // The logging hook a host can implement to route library logs.
 export { noopLogger } from "./logger";