@mentra/engine 3.2.0-dev.137 → 3.2.0-dev.154

package/src/services/CloudClientService.ts

@@ -14,6 +14,7 @@
  * this service.
  */
 import {CloudClient, setNativeHttp, setNativeUdp, setSecureStorage} from "@mentra/cloud-client/react-native"
+import {DEFAULT_REFRESH_TOKEN_KEY} from "@mentra/cloud-client"
 import type {PreinstalledMiniappRegistry, RuntimeSnapshot} from "@mentra/cloud-client/react-native"
 import type {SubjectTokenType} from "@mentra/cloud-client"
 import {Platform} from "react-native"
@@ -21,7 +22,7 @@ import type {AudioSubscription, TranscriptionData, TranslationData} from "@mentr
 
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 import CrustModule from "@mentra/crust"
-import {getAuth, getConfigValues} from "../runtime/bootstrap"
+import {getAuth, getConfigValues, isFeatureEnabled} from "../runtime/bootstrap"
 import {useSettingsStore, SETTINGS} from "../stores/settings"
 import {type CloudClientStatusSnapshot, type MiniappAuthToken} from "../runtime/config"
 import {createCloudUdpSocket} from "../utils/cloudClient/RnUdpAdapter"
@@ -69,7 +70,7 @@ let persistentFailureNotified = false
 let audioSubscriptions: AudioSubscription[] = []
 let transportsReady = false
 /** Endpoints to build with — seeded from config, overridable via reconnect(). */
-let endpointsOverride: {core: string; runtime: string} | null = null
+let endpointsOverride: {core?: string; runtime: string} | null = null
 let runtimeStatusUnsubscribe: (() => void) | null = null
 let transcriptUnsubscribe: (() => void) | null = null
 let translationUnsubscribe: (() => void) | null = null
@@ -98,12 +99,15 @@ const translationListeners = new Set<(d: TranslationData) => void>()
 const statusListeners = new Set<(snapshot: CloudClientStatusSnapshot) => void>()
 const connectionListeners = new Set<(connected: boolean) => void>()
 
-function resolveEndpoints(): {core: string; runtime: string} {
+function resolveEndpoints(): {core?: string; runtime: string} {
   if (endpointsOverride) return endpointsOverride
   const cfg = getConfigValues()
+  const runtime = cfg.runtimeUrl === null ? "" : cfg.runtimeUrl?.trim() || FALLBACK_RUNTIME_URL
+  if (!runtime) throw new Error("cloudClient: Runtime endpoint is not configured")
+  const core = cfg.coreUrl === null ? undefined : cfg.coreUrl?.trim() || FALLBACK_CORE_URL
   return {
-    core: cfg.coreUrl?.trim() || FALLBACK_CORE_URL,
-    runtime: cfg.runtimeUrl?.trim() || FALLBACK_RUNTIME_URL,
+    ...(core ? {core} : {}),
+    runtime,
   }
 }
 
@@ -159,7 +163,7 @@ function frameSizeBytes(): Lc3FrameSizeBytes {
 
 async function getSubjectToken(): Promise<{token: string; type: SubjectTokenType}> {
   const a = getAuth()
-  if (!a) throw new Error("cloudClient: engine.configure({auth}) not called")
+  if (!a?.getSubjectToken) throw new Error("cloudClient: Core subject-token auth is not configured")
   const r = await a.getSubjectToken()
   // IslandAuth's SubjectTokenType is intentionally open (`string & {}`) so OEMs
   // can use other token kinds; cloud-client's is a closed union. The host's
@@ -408,13 +412,23 @@ function construct(): void {
   const endpoints = resolveEndpoints()
   console.log(`${LOG_TAG}: endpoints ${JSON.stringify(endpoints)}`)
 
-  const coreAuth = {getSubjectToken}
-  const auth = shouldUseLocalDevRuntimeToken(endpoints)
+  const configuredAuth = getAuth()
+  if (!configuredAuth) throw new Error("cloudClient: engine.configure({auth}) not called")
+  const coreAuth = configuredAuth.getSubjectToken ? {getSubjectToken} : undefined
+  const auth = configuredAuth.getRuntimeToken
     ? {
-        core: coreAuth,
-        runtime: {getToken: (opts?: {forceRefresh?: boolean}) => getLocalDevRuntimeToken(endpoints.runtime, opts)},
+        ...(coreAuth && endpoints.core ? {core: coreAuth} : {}),
+        runtime: {getToken: configuredAuth.getRuntimeToken},
       }
-    : {core: coreAuth, runtime: {source: "core" as const}}
+    : shouldUseLocalDevRuntimeToken(endpoints)
+      ? {
+          ...(coreAuth ? {core: coreAuth} : {}),
+          runtime: {getToken: (opts?: {forceRefresh?: boolean}) => getLocalDevRuntimeToken(endpoints.runtime, opts)},
+        }
+      : coreAuth && endpoints.core
+        ? {core: coreAuth, runtime: {source: "core" as const}}
+        : null
+  if (!auth) throw new Error("cloudClient: no Runtime authentication mode is configured")
 
   client = new CloudClient({
     endpoints,
@@ -422,6 +436,7 @@ function construct(): void {
     // LC3 at 16 kHz with the frame size the encoder emits.
     audio: {codec: "lc3", sampleRate: 16000, frameSizeBytes: frameSizeBytes()},
     auth,
+    authStorageKey: getConfigValues().cloudAuthStorageKey,
     timers: {
       setTimeout: (callback, delayMs) => BgTimer.setTimeout(callback, delayMs),
       clearTimeout: (handle) => BgTimer.clearTimeout(handle as number),
@@ -470,7 +485,9 @@ function construct(): void {
     connected = false
     console.log(`${LOG_TAG}: runtime disconnected (${info.reason})`)
     console.log(
-      `${LOG_TAG}: debug: ws-session-debug disconnected reason=${info.reason} willStayDown=${/superseded by newer session/i.test(info.reason)}`,
+      `${LOG_TAG}: debug: ws-session-debug disconnected reason=${
+        info.reason
+      } willStayDown=${/superseded by newer session/i.test(info.reason)}`,
     )
     // Arm the persistent-failure alarm once; if we're still down when it fires, raise
     // the notification. A reconnect within the window cancels it (onConnected above).
@@ -493,17 +510,22 @@ function construct(): void {
     console.warn(`${LOG_TAG}: runtime error: ${err.code}`)
   })
 
-  // Best-effort connect. Do not crash the app if the dev cloud is unreachable.
-  c.runtime
-    .connect()
-    .then(() => console.log(`${LOG_TAG}: connect() resolved`))
-    .catch((err) => console.warn(`${LOG_TAG}: connect() failed: ${err?.message ?? err}`))
-
-  syncCoreAccessTokenToBluetooth().catch((err) =>
-    console.warn(`${LOG_TAG}: initial Bluetooth core_token sync failed: ${(err as Error)?.message ?? err}`),
-  )
+  if (getConfigValues().runtimeRealtimeSession !== false) {
+    // Best-effort connect. Do not crash the app if the dev cloud is unreachable.
+    c.runtime
+      .connect()
+      .then(() => console.log(`${LOG_TAG}: connect() resolved`))
+      .catch((err) => console.warn(`${LOG_TAG}: connect() failed: ${err?.message ?? err}`))
+    startLc3FrameSizeWatcher()
+  } else {
+    console.log(`${LOG_TAG}: Runtime live session disabled; REST capabilities remain available`)
+  }
 
-  startLc3FrameSizeWatcher()
+  if (c.core) {
+    syncCoreAccessTokenToBluetooth().catch((err) =>
+      console.warn(`${LOG_TAG}: initial Bluetooth core_token sync failed: ${(err as Error)?.message ?? err}`),
+    )
+  }
 }
 
 /**
@@ -511,6 +533,14 @@ function construct(): void {
  * and the runtime-hook wiring.
  */
 export const cloudClientService = {
+  async clearAuthSession(): Promise<void> {
+    if (client) {
+      await client.auth.clearSession()
+      return
+    }
+    await cloudSecureStore.delete(getConfigValues().cloudAuthStorageKey ?? DEFAULT_REFRESH_TOKEN_KEY)
+  },
+
   /**
    * Construct (once) + connect the client. Idempotent. Best-effort connect — a
    * failure is logged and the app keeps running. Requires
@@ -527,7 +557,7 @@ export const cloudClientService = {
    * a prior override and fall back to the boot config (so cleared/default cloud
    * URLs don't keep reconnecting to a stale override); omit to keep the current.
    */
-  reconnect(endpoints?: {core: string; runtime: string} | null): void {
+  reconnect(endpoints?: {core?: string; runtime: string} | null): void {
     if (endpoints !== undefined) endpointsOverride = endpoints
     try {
       client?.runtime.close()
@@ -565,6 +595,8 @@ export const cloudClientService = {
    */
   async resolveMentraUserId(): Promise<string> {
     return localMiniappUserIdentity.resolve(async () => {
+      const hostIdentity = getAuth()?.getUserId
+      if (hostIdentity) return await hostIdentity()
       if (!client) this.init()
       const c = client
       if (!c) throw new Error("cloud client not initialized")
@@ -636,14 +668,17 @@ export const cloudClientService = {
 
   /** Managed stream (cloud-v2): provision ingest+playback on the runtime. */
   startManagedStream(opts: Record<string, unknown> = {}) {
+    if (!isFeatureEnabled("managedStreams")) throw new Error("managed streams are disabled by this deployment")
     if (!client) throw new Error("cloud client not connected")
     return client.runtime.startManagedStream(opts)
   },
   getManagedStreamStatus(streamId: string) {
+    if (!isFeatureEnabled("managedStreams")) throw new Error("managed streams are disabled by this deployment")
     if (!client) throw new Error("cloud client not connected")
     return client.runtime.getManagedStreamStatus(streamId)
   },
   stopManagedStream(streamId: string) {
+    if (!isFeatureEnabled("managedStreams")) throw new Error("managed streams are disabled by this deployment")
     if (!client) throw new Error("cloud client not connected")
     return client.runtime.stopManagedStream(streamId)
   },
@@ -695,7 +730,13 @@ export const cloudClientService = {
   },
 
   getCoreUrl(): string {
-    return resolveEndpoints().core
+    const core = resolveEndpoints().core
+    if (!core) throw new Error("cloud client core is unavailable")
+    return core
+  },
+
+  hasCore(): boolean {
+    return Boolean(client?.core)
   },
 
   syncCoreTokenToBluetooth(): Promise<string> {
@@ -711,6 +752,7 @@ export const cloudClientService = {
 
   tts: {
     speak(text: string, options?: Parameters<CloudClient["runtime"]["tts"]["speak"]>[1]) {
+      if (!isFeatureEnabled("cloudSpeech")) throw new Error("cloud speech is disabled by this deployment")
       if (!client) throw new Error("cloud client not connected")
       return client.runtime.tts.speak(text, options)
     },
@@ -718,18 +760,22 @@ export const cloudClientService = {
 
   maps: {
     directions(req: Parameters<CloudClient["runtime"]["maps"]["directions"]>[0]) {
+      if (!isFeatureEnabled("navigation")) throw new Error("navigation is disabled by this deployment")
       if (!client) throw new Error("cloud client not connected")
       return client.runtime.maps.directions(req)
     },
     reverseGeocode(coord: Parameters<CloudClient["runtime"]["maps"]["reverseGeocode"]>[0]) {
+      if (!isFeatureEnabled("navigation")) throw new Error("navigation is disabled by this deployment")
       if (!client) throw new Error("cloud client not connected")
       return client.runtime.maps.reverseGeocode(coord)
     },
     placeAutocomplete(req: Parameters<CloudClient["runtime"]["maps"]["placeAutocomplete"]>[0]) {
+      if (!isFeatureEnabled("navigation")) throw new Error("navigation is disabled by this deployment")
       if (!client) throw new Error("cloud client not connected")
       return client.runtime.maps.placeAutocomplete(req)
     },
     placeDetails(req: Parameters<CloudClient["runtime"]["maps"]["placeDetails"]>[0]) {
+      if (!isFeatureEnabled("navigation")) throw new Error("navigation is disabled by this deployment")
       if (!client) throw new Error("cloud client not connected")
       return client.runtime.maps.placeDetails(req)
     },

package/src/services/LocalMiniappRuntime.ts

@@ -66,7 +66,7 @@ import {
   type MiniappAuthToken,
   type TtsSynthesisResult,
 } from "../runtime/config"
-import {getAnalytics, getUiSeams} from "../runtime/bootstrap"
+import {getAnalytics, getMiniappConfiguration, getUiSeams, isFeatureEnabled} from "../runtime/bootstrap"
 import {invokeScanQrSeam} from "../runtime/scanQrSeam"
 import {normalizeStreamAudioConfig, normalizeStreamVideoConfig, resolveCaptureAudio} from "../runtime/streamConfig"
 import {toLanguageHint} from "@mentra/cloud-protocol/languages"
@@ -76,7 +76,7 @@ import ttsModelManager from "./TTSModelManager"
 import {NavigationHandlers} from "./NavigationHandlers"
 import type {ClientApp} from "../types/applet"
 import {useAppStatusStore} from "../stores/apps"
-import {getDevAppAttestation, getDevAppSourcePackage} from "./AppRegistry"
+import appRegistry, {getDevAppAttestation, getDevAppSourcePackage} from "./AppRegistry"
 import {resolveForegroundLocationPermission} from "./ForegroundLocationPermission"
 import {advanceMiniappPingLiveness} from "./MiniappLiveness"
 import {listPhoneCalendarEvents, PhoneCalendarError} from "./PhoneCalendarService"
@@ -189,14 +189,7 @@ const LOG_TAG = "LOCAL_MINIAPP"
 const DIAGNOSTIC_MAX_LIST_ITEMS = 100
 const DIAGNOSTIC_MAX_STRING_LENGTH = 512
 
-function diagnosticStringList(values: Iterable<string>): string[] {
-  return [...values]
-    .map((value) => value.slice(0, DIAGNOSTIC_MAX_STRING_LENGTH))
-    .sort()
-    .slice(0, DIAGNOSTIC_MAX_LIST_ITEMS)
-}
-
-const SYSTEM_MINIAPP_PACKAGES = new Set([
+const SYSTEM_MINIAPP_PACKAGE_SET = new Set([
   "com.mentra.camera",
   "com.mentra.gallery",
   "com.mentra.settings",
@@ -207,6 +200,14 @@ const SYSTEM_MINIAPP_PACKAGES = new Set([
   "com.mentra.feedback",
   "com.mentra.miniappdev",
 ])
+
+function diagnosticStringList(values: Iterable<string>): string[] {
+  return [...values]
+    .map((value) => value.slice(0, DIAGNOSTIC_MAX_STRING_LENGTH))
+    .sort()
+    .slice(0, DIAGNOSTIC_MAX_LIST_ITEMS)
+}
+
 const PING_INTERVAL_MS = 5_000
 const MINIAPP_AUTH_REFRESH_HEADROOM_MS = 5 * 60 * 1000
 const MINIAPP_AUTH_REFRESH_MIN_DELAY_MS = 5_000
@@ -1445,6 +1446,7 @@ class LocalMiniappRuntime {
         packageName,
         capabilities,
         permissions: declaredPermissions,
+        configuration: getMiniappConfiguration(packageName),
         hostFeatures: {captureAudio: true},
         ...(initialAuth ? {auth: initialAuth} : {}),
       },
@@ -1468,6 +1470,9 @@ class LocalMiniappRuntime {
   }
 
   private async requestMiniappAuth(packageName: string, opts?: {minTtlMs?: number}): Promise<MiniappAuthToken | null> {
+    // Core owns miniapp-backend token minting. A Runtime-only deployment has
+    // no such capability, so fail once instead of entering the retry loop.
+    if (!cloudClientService.hasCore()) return null
     const authPackageName = getDevAppSourcePackage(packageName) ?? packageName
     const devAttestation = getDevAppAttestation(packageName) ?? undefined
     return cloudClientService.getMiniappAuthToken(authPackageName, {
@@ -1705,6 +1710,34 @@ class LocalMiniappRuntime {
       return
     }
 
+    for (const subscription of rawStreams ?? []) {
+      const stream = typeof subscription === "string" ? subscription : subscription.stream
+      if (stream.startsWith("translation:") && !isFeatureEnabled("cloudSpeech")) {
+        this.sendResult(packageName, requestId, false, undefined, {
+          code: MiniappErrorCode.NOT_IMPLEMENTED,
+          message: "Cloud speech is disabled by this deployment",
+        })
+        return
+      }
+      if (!stream.startsWith("transcription:")) continue
+      const forceLocal = typeof subscription === "object" && subscription.forceLocal === true
+      const includeCloud = typeof subscription === "object" && subscription.includeCloud === true
+      if (forceLocal && !isFeatureEnabled("onDeviceSpeech")) {
+        this.sendResult(packageName, requestId, false, undefined, {
+          code: MiniappErrorCode.NOT_IMPLEMENTED,
+          message: "On-device speech is disabled by this deployment",
+        })
+        return
+      }
+      if ((!forceLocal || includeCloud) && !isFeatureEnabled("cloudSpeech")) {
+        this.sendResult(packageName, requestId, false, undefined, {
+          code: MiniappErrorCode.NOT_IMPLEMENTED,
+          message: "Cloud speech is disabled by this deployment",
+        })
+        return
+      }
+    }
+
     console.log(`${LOG_TAG}: SUBSCRIBE from ${packageName}: [${streams.join(", ")}]`)
 
     // Gate each stream on the permission type its data requires. The manifest
@@ -2244,11 +2277,11 @@ class LocalMiniappRuntime {
       typeof rawText === "string"
         ? [rawText.trim()].filter(Boolean)
         : Array.isArray(rawText)
-          ? rawText
-              .filter((sentence): sentence is string => typeof sentence === "string")
-              .map((sentence) => sentence.trim())
-              .filter(Boolean)
-          : []
+        ? rawText
+            .filter((sentence): sentence is string => typeof sentence === "string")
+            .map((sentence) => sentence.trim())
+            .filter(Boolean)
+        : []
     const enableSanitization = payload.enableSanitization !== false
     const sentences = prepareTtsSentences(rawSentences, enableSanitization)
     if (sentences.length === 0) {
@@ -2333,6 +2366,7 @@ class LocalMiniappRuntime {
 
       const playOfflineTts = async (reason?: string): Promise<boolean> => {
         if (run.cancelled) return true
+        if (!isFeatureEnabled("onDeviceSpeech")) return false
         if (!offlineSupportsVoice || !(await ttsModelManager.isModelAvailable())) {
           return false
         }
@@ -2577,7 +2611,9 @@ class LocalMiniappRuntime {
       const permission = await resolveForegroundLocationPermission(Location, () => AppState.currentState)
       const {status} = permission
       console.log(
-        `${LOG_TAG}: location poll permission status=${status} appState=${AppState.currentState} elapsed=${Date.now() - permissionStartedAt}ms`,
+        `${LOG_TAG}: location poll permission status=${status} appState=${AppState.currentState} elapsed=${
+          Date.now() - permissionStartedAt
+        }ms`,
       )
       if (status !== "granted") {
         this.sendResult(packageName, requestId, false, undefined, {
@@ -3138,11 +3174,7 @@ class LocalMiniappRuntime {
    * session.system.scanQr — host camera overlay. Must not clear miniapp
    * foreground; the host seam is responsible for presenting a Modal on top.
    */
-  private async handleScanQr(
-    packageName: string,
-    payload: Record<string, unknown>,
-    requestId?: string,
-  ): Promise<void> {
+  private async handleScanQr(packageName: string, payload: Record<string, unknown>, requestId?: string): Promise<void> {
     try {
       const result = await invokeScanQrSeam(getUiSeams().scanQr, payload)
       this.sendResult(packageName, requestId, true, result)
@@ -3465,7 +3497,15 @@ class LocalMiniappRuntime {
       return
     }
     // A stream is the glasses camera (and mic) leaving the device; gate it like a photo.
-    if (!this.requireManifestPermission(packageName, requestId, "CAMERA", "to stream the camera", MiniappRequestType.STREAM_START)) {
+    if (
+      !this.requireManifestPermission(
+        packageName,
+        requestId,
+        "CAMERA",
+        "to stream the camera",
+        MiniappRequestType.STREAM_START,
+      )
+    ) {
       return
     }
     try {
@@ -3582,8 +3622,20 @@ class LocalMiniappRuntime {
     // A meeting puts the glasses camera and mic in front of remote strangers; it
     // needs both declared, same as photo/stream and mic capture do individually.
     if (
-      !this.requireManifestPermission(packageName, requestId, "CAMERA", "to join a meeting", MiniappRequestType.MEETING_JOIN) ||
-      !this.requireManifestPermission(packageName, requestId, "MICROPHONE", "to join a meeting", MiniappRequestType.MEETING_JOIN)
+      !this.requireManifestPermission(
+        packageName,
+        requestId,
+        "CAMERA",
+        "to join a meeting",
+        MiniappRequestType.MEETING_JOIN,
+      ) ||
+      !this.requireManifestPermission(
+        packageName,
+        requestId,
+        "MICROPHONE",
+        "to join a meeting",
+        MiniappRequestType.MEETING_JOIN,
+      )
     ) {
       return
     }
@@ -4333,8 +4385,15 @@ class LocalMiniappRuntime {
   }
 
   private isSystemPackage(packageName: string): boolean {
-    if (SYSTEM_MINIAPP_PACKAGES.has(packageName)) return true
-    return this.interopApps().find((app) => app.packageName === packageName)?.isMiniappDev === true
+    const app = this.interopApps().find((candidate) => candidate.packageName === packageName)
+    if (SYSTEM_MINIAPP_PACKAGE_SET.has(packageName)) {
+      if (app?.offline) return true
+      if (app?.local && app.version) {
+        return appRegistry.getReleaseIdentity(packageName, app.version)?.source === "bundled_asset"
+      }
+      return false
+    }
+    return app?.isMiniappDev === true
   }
 
   private async startInteropApp(packageName: string): Promise<boolean> {

package/src/services/MiniappLauncher.ts

@@ -25,6 +25,7 @@
 
 import {File} from "expo-file-system"
 
+import {isInstalledMiniappAllowed, isLocalMiniappPackageAllowed} from "../runtime/bootstrap"
 import {resolveDevBundleSource} from "../utils/devMiniappSnapshot"
 import {storage} from "../utils/storage/storage"
 import appRegistry, {getLocalAppRunningState, saveLocalAppRunningState} from "./AppRegistry"
@@ -134,7 +135,7 @@ class MiniappLauncher {
     if (!entry?.background) return null
 
     // Use the host that actually answered — may differ from the stored IP
-    // after a laptop Wi-Fi change (mDNS / Metro failover inside decideDevLaunchRoute).
+    // after a laptop Wi-Fi change (mDNS / Metro failover inside resolveDevBundleSource).
     const base = resolvedUrl.replace(/\/$/, "")
     // entry.* are bundle-root paths (dist/ stripped); the dev server serves
     // files relative to cwd, so prepend dist/.
@@ -243,6 +244,9 @@ class MiniappLauncher {
    * {@link LocalMiniappRuntime.waitForConnect}.
    */
   async ensureRunning(packageName: string, hints?: LaunchHints): Promise<LaunchResult> {
+    if (!isLocalMiniappPackageAllowed(packageName)) {
+      throw new Error(`MiniappLauncher: ${packageName} is disabled by deployment policy`)
+    }
     const router = this.requireRouter()
 
     // Already spawned: best-effort resolve for the UI entry, never throw —
@@ -273,6 +277,16 @@ class MiniappLauncher {
     if (!resolved) {
       throw new Error(`MiniappLauncher: cannot resolve bundle for ${packageName}`)
     }
+    const version = resolved.installedManifest?.version
+    if (
+      !isInstalledMiniappAllowed(
+        packageName,
+        version,
+        version ? appRegistry.getReleaseIdentity(packageName, version) : null,
+      )
+    ) {
+      throw new Error(`MiniappLauncher: ${packageName} bundle is not authorized by deployment policy`)
+    }
 
     // Re-check after the async resolve: a different path may have spawned it
     // while we were fetching/reading the bundle.

package/src/services/NavigationHandlers.ts

@@ -26,6 +26,7 @@ import {type NavLocation, type NavRoute, type NavUpdate} from "../runtime/config
 import {cloudClientService} from "./CloudClientService"
 import navigationService from "./NavigationService"
 import {MiniappErrorCode, MiniappResponseType, MiniappStreamType} from "@mentra/miniapp"
+import {isFeatureEnabled} from "../runtime/bootstrap"
 
 const LOG_TAG = "LocalMiniappRuntime"
 
@@ -81,6 +82,13 @@ export class NavigationHandlers {
   }
 
   async handleStart(packageName: string, payload: Record<string, unknown>, requestId?: string): Promise<void> {
+    if (!isFeatureEnabled("navigation")) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.NOT_IMPLEMENTED,
+        message: "Navigation is disabled by this deployment",
+      })
+      return
+    }
     console.log(`${LOG_TAG}: handleNavigationStart from ${packageName}`, JSON.stringify(payload))
 
     // v2 wire shape sends `stops`; v1 shape sends bare lat/lng. Accept both.

package/src/services/OtaUpdateCheckService.ts

@@ -78,7 +78,15 @@ export interface OtaCheckResult {
   checkFailureReason?: "network" | "pin_unavailable"
 }
 
-export type OtaCheckSkippedReason = "disconnected" | "missing_build" | "dev_build"
+/**
+ * Package the stock glasses client installs as, and the key every apps-shaped manifest pins the
+ * ASG APK under. Android forces a distinct package (`.thirdparty` suffix) on any build not signed
+ * with Mentra's release key, so a client reporting anything else is a sideloaded build that
+ * coexists with the stock system app.
+ */
+export const STOCK_ASG_PACKAGE = "com.mentra.asg_client"
+
+export type OtaCheckSkippedReason = "disconnected" | "missing_build" | "dev_build" | "unofficial_client"
 
 export interface OtaCheckCurrentGlassesResult extends OtaCheckResult {
   updateInfo: OtaUpdateInfo | null
@@ -86,6 +94,8 @@ export interface OtaCheckCurrentGlassesResult extends OtaCheckResult {
   skippedReason?: OtaCheckSkippedReason
   manifestUrl?: string
   buildNumber?: string
+  /** Glasses client package, when it reported one. Set on an `unofficial_client` skip. */
+  packageName?: string
   mtkFirmwareVersion?: string
   besFirmwareVersion?: string
 }
@@ -100,7 +110,10 @@ export interface OtaCheckCurrentGlassesOptions {
   floorVersionCode?: number
 }
 
-function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurrentGlassesResult {
+function emptyCheckResult(
+  skippedReason?: OtaCheckSkippedReason,
+  extra?: Partial<OtaCheckCurrentGlassesResult>,
+): OtaCheckCurrentGlassesResult {
   return {
     hasCheckCompleted: false,
     updateAvailable: false,
@@ -114,6 +127,7 @@ function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurren
     updateInfo: null,
     isRequired: true,
     skippedReason,
+    ...extra,
   }
 }
 
@@ -183,7 +197,7 @@ export function getApkUpdateDirection(
   let serverVersion: number | undefined
   let exactPin = false
 
-  const appEntry = versionJson.apps?.["com.mentra.asg_client"]
+  const appEntry = versionJson.apps?.[STOCK_ASG_PACKAGE]
   if (appEntry) {
     serverVersion = appEntry.versionCode
     exactPin = true
@@ -212,8 +226,8 @@ export function getLatestVersionInfo(versionJson: VersionJson | null): VersionIn
     return null
   }
 
-  if (versionJson.apps?.["com.mentra.asg_client"]) {
-    return versionJson.apps["com.mentra.asg_client"]
+  if (versionJson.apps?.[STOCK_ASG_PACKAGE]) {
+    return versionJson.apps[STOCK_ASG_PACKAGE]
   }
 
   if (versionJson.versionCode) {
@@ -315,7 +329,7 @@ export async function checkForOtaUpdate(
     // than silently completing as "up to date" — an unverifiable state must never
     // present as a verified one.
     const currentVersionNumber = parseInt(currentBuildNumber, 10)
-    const pinnedEntry = versionJson?.apps?.["com.mentra.asg_client"]
+    const pinnedEntry = versionJson?.apps?.[STOCK_ASG_PACKAGE]
     const pinnedVersion = pinnedEntry?.versionCode ?? versionJson?.versionCode
     if (
       versionJson &&
@@ -442,6 +456,18 @@ export async function checkCurrentGlassesForUpdate(
     return emptyCheckResult("missing_build")
   }
 
+  // A sideloaded ASG client installs under its own package (Android forces the `.thirdparty`
+  // suffix on any build not signed with Mentra's release key) and coexists with the stock system
+  // app. Its build number is therefore not comparable to the manifest's pin, and installing the
+  // manifest APK would replace the stock package while the sideloaded client keeps holding the
+  // link and reporting its own unchanged version — an update prompt that can never be satisfied.
+  // Absent means the glasses predate the field: assume stock, preserving existing behavior.
+  const packageName = useGlassesStore.getState().packageName
+  if (packageName && packageName !== STOCK_ASG_PACKAGE) {
+    console.log(`OTA: check skipped - glasses run an unofficial client (${packageName})`)
+    return emptyCheckResult("unofficial_client", {buildNumber, packageName})
+  }
+
   if (!glassesConnectedNow()) {
     return emptyCheckResult("disconnected")
   }

package/src/services/miniappInstallIdentity.ts

@@ -0,0 +1,18 @@
+export interface MiniappInstallExpectations {
+  packageName?: string
+  version?: string
+  rejectExistingVersion?: boolean
+}
+
+export function miniappInstallIdentityError(
+  manifest: {packageName: string; version: string},
+  expected?: MiniappInstallExpectations,
+): string | null {
+  if (expected?.packageName && manifest.packageName !== expected.packageName) {
+    return `Bundle package mismatch: expected ${expected.packageName}, got ${manifest.packageName}`
+  }
+  if (expected?.version && manifest.version !== expected.version) {
+    return `Bundle version mismatch: expected ${expected.version}, got ${manifest.version}`
+  }
+  return null
+}

package/src/services/otaManifestPolicy.ts

@@ -40,3 +40,14 @@ export function resolveOtaManifestPolicy({
   }
   return selectModernOtaManifestPin({developerOverride, hostReleasePin, engineReleasePin})
 }
+
+export function resolveDeploymentAwareOtaManifestPolicy({
+  hostPolicyConfigured,
+  ...policy
+}: Parameters<typeof resolveOtaManifestPolicy>[0] & {hostPolicyConfigured: boolean}): string | null {
+  // A selected deployment is authoritative for every glasses generation. An
+  // explicit null is a deliberate OTA-off policy, not permission to inherit a
+  // device-reported URL or Mentra's legacy public default.
+  if (hostPolicyConfigured) return trimmed(policy.hostReleasePin)
+  return resolveOtaManifestPolicy(policy)
+}

package/src/services/otaManifestUrl.ts

@@ -1,6 +1,7 @@
 import {ENGINE_RELEASE_METADATA} from "../generated/releaseMetadata"
 import {SETTINGS, useSettingsStore} from "../stores/settings"
-import {resolveOtaManifestPolicy, selectModernOtaManifestPin} from "./otaManifestPolicy"
+import {resolveDeploymentAwareOtaManifestPolicy, selectModernOtaManifestPin} from "./otaManifestPolicy"
+import {getConfigValues} from "../runtime/bootstrap"
 
 function getOtaVersionUrlDevOverride(): string | null {
   // Super mode only: a wrong OTA manifest can brick glasses, so a saved
@@ -14,10 +15,16 @@ function getOtaVersionUrlDevOverride(): string | null {
 }
 
 function getHostReleasePin(): string | null {
+  const configured = getConfigValues().otaManifestUrl
+  if (configured !== undefined) return configured?.trim() || null
   const value = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()
   return value || null
 }
 
+function hasDeploymentOtaPolicy(): boolean {
+  return getConfigValues().otaManifestUrl !== undefined
+}
+
 function getEmbeddedEngineReleasePin(): string | null {
   const value = ENGINE_RELEASE_METADATA.otaManifestUrl?.trim()
   return value || null
@@ -34,7 +41,8 @@ export function hasConfiguredModernOtaManifestPin(): boolean {
 }
 
 export function resolveOtaManifestUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string | null {
-  return resolveOtaManifestPolicy({
+  return resolveDeploymentAwareOtaManifestPolicy({
+    hostPolicyConfigured: hasDeploymentOtaPolicy(),
     glassesUrl,
     glassesBuildNumber,
     developerOverride: getOtaVersionUrlDevOverride(),