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

package/src/react/useMentraLiveOta.ts

@@ -34,6 +34,7 @@ export type MentraLiveOtaScreen =
   | "wifi_required"
   | "up_to_date"
   | "dev_build"
+  | "unofficial_client"
   | "check_failed"
   | "update_info_unavailable"
   | "starting"
@@ -103,6 +104,8 @@ export type MentraLiveOtaState = {
   releaseTransition: MentraLiveOtaReleaseTransition | null
   /** Release notes crossed by this update, newest first. Populated on completion. */
   changelogs: ReleaseChangelog[]
+  /** Sideloaded glasses client package, set only on the `unofficial_client` screen. */
+  glassesPackageName: string | null
 }
 
 export type UseMentraLiveOtaOptions = {
@@ -129,7 +132,7 @@ export type MentraLiveOtaController = {
   openWifiSetup: () => void
 }
 
-type CheckState = "checking" | "update_available" | "no_update" | "dev_build" | "error"
+type CheckState = "checking" | "update_available" | "no_update" | "dev_build" | "unofficial_client" | "error"
 
 const AUTO_CHAIN_NETWORK_RETRY_DELAY_MS = 5000
 const AUTO_CHAIN_COMPLETE_DELAY_MS = 750
@@ -216,6 +219,7 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
   const [isUpdateRequired, setIsUpdateRequired] = useState(true)
   const [isVersionChange, setIsVersionChange] = useState(false)
   const [errorKind, setErrorKind] = useState<"network" | "pin_unavailable">("network")
+  const [unofficialClientPackage, setUnofficialClientPackage] = useState<string | null>(null)
   const [updateFingerprint, setUpdateFingerprint] = useState<string | null>(null)
   const [offeredReleaseTransition, setOfferedReleaseTransition] = useState<MentraLiveOtaReleaseTransition | null>(null)
   const [completedReleaseTransition, setCompletedReleaseTransition] = useState<MentraLiveOtaReleaseTransition | null>(
@@ -379,6 +383,14 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
           setCheckState("dev_build")
           return
         }
+        if (result.skippedReason === "unofficial_client") {
+          stopOtaAutoChain()
+          checkCompletedRef.current = true
+          ota.clearUpdateAvailable()
+          setUnofficialClientPackage(result.packageName ?? null)
+          setCheckState("unofficial_client")
+          return
+        }
         if (!result.hasCheckCompleted) {
           stopOtaAutoChain()
           checkCompletedRef.current = true
@@ -642,6 +654,7 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
         completedUpdate: false,
         releaseTransition: null,
         changelogs: [],
+        glassesPackageName: null,
       }
     }
 
@@ -653,6 +666,7 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
         screen = wifiRequired ? "wifi_required" : batteryBlocked ? "battery_required" : "update_available"
       } else if (checkState === "no_update") screen = "up_to_date"
       else if (checkState === "dev_build") screen = "dev_build"
+      else if (checkState === "unofficial_client") screen = "unofficial_client"
       else screen = errorKind === "pin_unavailable" ? "update_info_unavailable" : "check_failed"
 
       let error: MentraLiveOtaError | null = null
@@ -688,7 +702,11 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
         error,
         canInstall: screen === "update_available" && canInstall,
         canRetry: screen === "check_failed",
-        canFinish: screen === "up_to_date" || screen === "dev_build" || screen === "update_info_unavailable",
+        canFinish:
+          screen === "up_to_date" ||
+          screen === "dev_build" ||
+          screen === "unofficial_client" ||
+          screen === "update_info_unavailable",
         canDismiss:
           (screen === "update_available" || screen === "wifi_required" || screen === "battery_required") &&
           !isUpdateRequired &&
@@ -706,6 +724,7 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
               ? completedReleaseTransition
               : null,
         changelogs: screen === "up_to_date" ? completedChangelogs : [],
+        glassesPackageName: screen === "unofficial_client" ? unofficialClientPackage : null,
       }
     }
 
@@ -768,8 +787,10 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
       completedUpdate: false,
       releaseTransition: releaseTransitionFromRange(otaAutoChainReleaseRange()),
       changelogs,
+      glassesPackageName: null,
     }
   }, [
+    unofficialClientPackage,
     checkState,
     batteryBlocked,
     completedChangelogs,

package/src/runtime/bootstrap.ts

@@ -10,7 +10,11 @@ export type SubjectTokenType = "supabase" | "authing" | (string & {})
 
 export interface IslandAuth {
   /** Returns the host's current (auto-refreshed) subject token for the backend. */
-  getSubjectToken: () => Promise<{token: string; type: SubjectTokenType}>
+  getSubjectToken?: () => Promise<{token: string; type: SubjectTokenType}>
+  /** Supplies a token issued directly for Runtime in a Core-free deployment. */
+  getRuntimeToken?: (opts?: {forceRefresh?: boolean}) => Promise<string>
+  /** Stable, deployment-scoped local identity for bundled miniapp storage. */
+  getUserId?: () => Promise<string> | string
   /**
    * Optional auth-session listener. Hosts that can emit auth changes should
    * wire this so engine can reconnect backend sessions after restored login
@@ -21,9 +25,23 @@ export interface IslandAuth {
 
 export interface IslandConfigValues {
   /** cloud-v2 core service base URL (defaults resolved by the cloud client). */
-  coreUrl?: string
+  coreUrl?: string | null
   /** cloud-v2 runtime service base URL. */
-  runtimeUrl?: string
+  runtimeUrl?: string | null
+  /** Open Runtime's live WebSocket/audio session. Defaults to true. */
+  runtimeRealtimeSession?: boolean
+  /** Complete allowlist for bundled/local miniapps; null or omitted allows all. */
+  localMiniappAllowlist?: readonly string[] | null
+  /** Provenance-aware policy for workspace SYSTEM and managed miniapps. */
+  localMiniappPolicy?: LocalMiniappPolicy
+  /** Optional per-package configuration supplied by the host deployment. */
+  miniappConfiguration?: Readonly<Record<string, Readonly<Record<string, string>>>>
+  /** Deployment-scoped key for the persisted Core refresh token. */
+  cloudAuthStorageKey?: string
+  /** Deployment-pinned Mentra Live OTA manifest; explicit null disables remote OTA. */
+  otaManifestUrl?: string | null
+  /** Deployment capability policy. Omitted entries preserve consumer behavior. */
+  features?: Partial<Record<IslandFeatureName, boolean>>
   /** OEM identifier (Mentra is OEM #0); reserved for OEM auth/telemetry. */
   oemId?: string
   /**
@@ -38,6 +56,21 @@ export interface IslandConfigValues {
   devServerHost?: () => string | undefined
 }
 
+export interface ManagedMiniappPolicyEntry {
+  packageName: string
+  version: string
+  sha256: string
+  deploymentId: string
+  deploymentOrigin: string
+}
+
+export interface LocalMiniappPolicy {
+  systemPackageNames: readonly string[] | null
+  managed: readonly ManagedMiniappPolicyEntry[]
+}
+
+export type IslandFeatureName = "managedStreams" | "nativeMeetings" | "cloudSpeech" | "onDeviceSpeech" | "navigation"
+
 export type IslandAnalytics = (event: string, props?: Record<string, unknown>) => void
 
 /**
@@ -74,6 +107,62 @@ export interface IslandConfigureOptions {
   ui?: IslandUiSeams
 }
 
+export function isLocalMiniappPackageAllowed(packageName: string): boolean {
+  const policy = options?.config?.localMiniappPolicy
+  if (policy) {
+    return (
+      policy.systemPackageNames === null ||
+      policy.systemPackageNames.includes(packageName) ||
+      policy.managed.some((entry) => entry.packageName === packageName)
+    )
+  }
+  const allowlist = options?.config?.localMiniappAllowlist
+  return allowlist == null || allowlist.includes(packageName)
+}
+
+export function isOfflineSystemMiniappAllowed(packageName: string): boolean {
+  const policy = options?.config?.localMiniappPolicy
+  if (!policy) return isLocalMiniappPackageAllowed(packageName)
+  return policy.systemPackageNames === null || policy.systemPackageNames.includes(packageName)
+}
+
+export function isInstalledMiniappAllowed(
+  packageName: string,
+  version: string | undefined,
+  releaseIdentity: {
+    source: string
+    bundleSha256?: string
+    deploymentId?: string
+    deploymentOrigin?: string
+  } | null,
+): boolean {
+  const policy = options?.config?.localMiniappPolicy
+  if (!policy) return isLocalMiniappPackageAllowed(packageName)
+
+  const systemApproved = policy.systemPackageNames === null || policy.systemPackageNames.includes(packageName)
+  if (systemApproved && releaseIdentity?.source === "bundled_asset") return true
+  if (!version || releaseIdentity?.source !== "deployment_manifest") return false
+
+  return policy.managed.some(
+    (entry) =>
+      entry.packageName === packageName &&
+      entry.version === version &&
+      entry.sha256 === releaseIdentity.bundleSha256?.toLowerCase() &&
+      entry.deploymentId === releaseIdentity.deploymentId &&
+      entry.deploymentOrigin === releaseIdentity.deploymentOrigin,
+  )
+}
+
+/** Read a defensive package-scoped configuration snapshot. */
+export function getMiniappConfiguration(packageName: string): Record<string, string> {
+  const configuration = options?.config?.miniappConfiguration?.[packageName]
+  return configuration ? {...configuration} : {}
+}
+
+export function isFeatureEnabled(feature: IslandFeatureName): boolean {
+  return options?.config?.features?.[feature] !== false
+}
+
 let options: IslandConfigureOptions | null = null
 let started = false
 
@@ -91,7 +180,31 @@ export function configure(opts: IslandConfigureOptions): void {
     console.warn("engine.configure() called after engine.start(); ignored — stop() the runtime before reconfiguring")
     return
   }
-  options = opts
+  const localMiniappAllowlist = opts.config?.localMiniappAllowlist
+  const localMiniappPolicy = opts.config?.localMiniappPolicy
+  options = {
+    ...opts,
+    config: opts.config
+      ? {
+          ...opts.config,
+          localMiniappAllowlist: Array.isArray(localMiniappAllowlist)
+            ? Object.freeze([...localMiniappAllowlist])
+            : localMiniappAllowlist,
+          localMiniappPolicy: localMiniappPolicy
+            ? Object.freeze({
+                systemPackageNames: Array.isArray(localMiniappPolicy.systemPackageNames)
+                  ? Object.freeze([...localMiniappPolicy.systemPackageNames])
+                  : null,
+                managed: Object.freeze(
+                  localMiniappPolicy.managed.map((entry) =>
+                    Object.freeze({...entry, sha256: entry.sha256.toLowerCase()}),
+                  ),
+                ),
+              })
+            : undefined,
+        }
+      : undefined,
+  }
 }
 
 /**

package/src/runtime/config.ts

@@ -101,6 +101,10 @@ export interface StreamVideoConfig {
   width?: number
   height?: number
   bitrate?: number
+  /** WHIP minimum target in bps; omitted leaves it unset. Clamped to the maximum. */
+  minBitrateBps?: number
+  /** WHIP startup bitrate in bps, clamped to the requested bounds. */
+  initialBitrateBps?: number
   fps?: number
 }
 

package/src/runtime/streamConfig.ts

@@ -12,11 +12,15 @@ export const normalizeStreamVideoConfig = (value: unknown): StreamVideoConfig |
   const width = finiteNumber(value.width)
   const height = finiteNumber(value.height)
   const bitrate = finiteNumber(value.bitrate)
+  const minBitrateBps = finiteNumber(value.minBitrateBps)
+  const initialBitrateBps = finiteNumber(value.initialBitrateBps)
   const frameRate = finiteNumber(value.frameRate)
   const fps = frameRate ?? finiteNumber(value.fps)
   if (width !== undefined) config.width = width
   if (height !== undefined) config.height = height
   if (bitrate !== undefined) config.bitrate = bitrate
+  if (minBitrateBps !== undefined) config.minBitrateBps = Math.max(0, Math.trunc(minBitrateBps))
+  if (initialBitrateBps !== undefined) config.initialBitrateBps = Math.max(0, Math.trunc(initialBitrateBps))
   if (fps !== undefined) config.fps = fps
   return Object.keys(config).length > 0 ? config : undefined
 }

package/src/services/AppRegistry.ts

@@ -28,12 +28,25 @@ import {HardwareRequirement, HardwareRequirementLevel, HardwareType} from "../ty
 import {configuredDevHost} from "../utils/configuredDevHost"
 import {storage} from "../utils/storage/storage"
 import {printDirectory} from "../utils/storage/zip"
+import {isInstalledMiniappAllowed, isOfflineSystemMiniappAllowed} from "../runtime/bootstrap"
 import {checkManifestVersions} from "./manifestVersionGate"
 import {normalizeManifestActions} from "./manifestActions"
+import {miniappInstallIdentityError, type MiniappInstallExpectations} from "./miniappInstallIdentity"
 import {miniappRunningRegistry} from "./MiniappRunningRegistry"
 
 export {normalizeManifestActions} from "./manifestActions"
 
+let installQueue: Promise<void> = Promise.resolve()
+
+function serializeInstall<T>(operation: () => Promise<T>): Promise<T> {
+  const result = installQueue.then(operation, operation)
+  installQueue = result.then(
+    () => undefined,
+    () => undefined,
+  )
+  return result
+}
+
 const ALLOWED_PERMISSION_TYPES: ReadonlySet<AppPermissionType> = new Set<AppPermissionType>([
   "MICROPHONE",
   "CAMERA",
@@ -141,10 +154,12 @@ interface InstalledLma {
 }
 
 export interface MiniappReleaseIdentity {
-  source: "direct_download" | "bundled_asset" | "preinstalled_registry" | "dev_snapshot"
+  source: "direct_download" | "bundled_asset" | "preinstalled_registry" | "deployment_manifest" | "dev_snapshot"
   releaseId?: string
   bundleSha256?: string
   channel?: string
+  deploymentId?: string
+  deploymentOrigin?: string
 }
 
 function releaseIdentityKey(packageName: string, version: string): string {
@@ -209,6 +224,7 @@ async function downloadMiniAppZip(url: string): Promise<string> {
 async function unpackMiniApp(
   zipPath: string,
   versionOverride?: string,
+  expected?: MiniappInstallExpectations,
 ): Promise<{packageName: string; version: string}> {
   const unzipDir = new Directory(Paths.cache, "lma_unzip")
   try {
@@ -246,6 +262,8 @@ async function unpackMiniApp(
     throw "READ_MANIFEST_FAILED"
   }
   const version = versionOverride ?? manifestVersion
+  const identityError = miniappInstallIdentityError({packageName, version: manifestVersion}, expected)
+  if (identityError) throw new Error(identityError)
   console.log(`ZIP: installing ${packageName} as version ${version}`)
 
   const basePackageDir = new Directory(Paths.document, "lmas", packageName)
@@ -260,6 +278,9 @@ async function unpackMiniApp(
 
   const versionDir = new Directory(basePackageDir, version)
   try {
+    if (expected?.rejectExistingVersion && versionDir.exists) {
+      throw new Error(`Miniapp ${packageName}@${version} is already installed`)
+    }
     if (!versionDir.exists) {
       versionDir.create()
     } else {
@@ -299,10 +320,11 @@ async function unpackMiniApp(
 async function downloadAndInstallMiniApp(
   url: string,
   versionOverride?: string,
+  expected?: MiniappInstallExpectations,
 ): Promise<{packageName: string; version: string}> {
   const downloadedZipPath = await downloadMiniAppZip(url)
   console.log("ZIP: done downloading, starting unzip")
-  return unpackMiniApp(downloadedZipPath, versionOverride)
+  return unpackMiniApp(downloadedZipPath, versionOverride, expected)
 }
 
 type Listener = () => void
@@ -445,17 +467,29 @@ class AppRegistry {
    */
   public installFromUrl(
     url: string,
-    opts?: {versionOverride?: string; releaseIdentity?: MiniappReleaseIdentity},
+    opts?: {
+      versionOverride?: string
+      releaseIdentity?: MiniappReleaseIdentity
+      expectedPackageName?: string
+      expectedVersion?: string
+      rejectExistingVersion?: boolean
+    },
   ): AsyncResult<void, Error> {
-    return Res.try_async(async () => {
-      const {packageName, version} = await downloadAndInstallMiniApp(url, opts?.versionOverride)
-      console.log("APP_REGISTRY: Downloaded and installed mini app")
-      this.finalizeInstall(
-        packageName,
-        version,
-        opts?.releaseIdentity ?? {source: version.startsWith("dev-") ? "dev_snapshot" : "direct_download"},
-      )
-    })
+    return Res.try_async(() =>
+      serializeInstall(async () => {
+        const {packageName, version} = await downloadAndInstallMiniApp(url, opts?.versionOverride, {
+          packageName: opts?.expectedPackageName,
+          version: opts?.expectedVersion,
+          rejectExistingVersion: opts?.rejectExistingVersion,
+        })
+        console.log("APP_REGISTRY: Downloaded and installed mini app")
+        this.finalizeInstall(
+          packageName,
+          version,
+          opts?.releaseIdentity ?? {source: version.startsWith("dev-") ? "dev_snapshot" : "direct_download"},
+        )
+      }),
+    )
   }
 
   /**
@@ -467,14 +501,26 @@ class AppRegistry {
    */
   public installFromLocalZip(
     zipPath: string,
-    opts?: {versionOverride?: string; releaseIdentity?: MiniappReleaseIdentity},
+    opts?: {
+      versionOverride?: string
+      releaseIdentity?: MiniappReleaseIdentity
+      expectedPackageName?: string
+      expectedVersion?: string
+      rejectExistingVersion?: boolean
+    },
   ): AsyncResult<{packageName: string; version: string}, Error> {
-    return Res.try_async(async () => {
-      const {packageName, version} = await unpackMiniApp(zipPath, opts?.versionOverride)
-      console.log("APP_REGISTRY: Installed mini app from local zip")
-      this.finalizeInstall(packageName, version, opts?.releaseIdentity ?? {source: "bundled_asset"})
-      return {packageName, version}
-    })
+    return Res.try_async(() =>
+      serializeInstall(async () => {
+        const {packageName, version} = await unpackMiniApp(zipPath, opts?.versionOverride, {
+          packageName: opts?.expectedPackageName,
+          version: opts?.expectedVersion,
+          rejectExistingVersion: opts?.rejectExistingVersion,
+        })
+        console.log("APP_REGISTRY: Installed mini app from local zip")
+        this.finalizeInstall(packageName, version, opts?.releaseIdentity ?? {source: "bundled_asset"})
+        return {packageName, version}
+      }),
+    )
   }
 
   /**
@@ -504,6 +550,22 @@ class AppRegistry {
     return result.is_ok() ? result.value : null
   }
 
+  /** Enumerate installed releases carrying deployment ownership metadata. */
+  public getDeploymentOwnedReleases(): Array<{
+    packageName: string
+    version: string
+    identity: MiniappReleaseIdentity
+  }> {
+    const releases: Array<{packageName: string; version: string; identity: MiniappReleaseIdentity}> = []
+    for (const packageName of this.getPackageNames()) {
+      for (const version of this.getInstalledVersions(packageName)) {
+        const identity = this.getReleaseIdentity(packageName, version)
+        if (identity?.source === "deployment_manifest") releases.push({packageName, version, identity})
+      }
+    }
+    return releases
+  }
+
   public installFromJsonUrl(baseUrl: string): AsyncResult<{packageName: string; version: string; name: string}, Error> {
     return Res.try_async(async () => {
       const trimmed = baseUrl.replace(/\/$/, "")
@@ -732,12 +794,21 @@ class AppRegistry {
    * registration in finalizeInstall. Native offline apps keep top priority.
    */
   private mergeProjectedApps(diskApps: ClientApp[]): ClientApp[] {
-    const offline = this.projectOfflineApps()
+    const offline = this.projectOfflineApps().filter((app) => isOfflineSystemMiniappAllowed(app.packageName))
     const offlinePackages = new Set(offline.map((app) => app.packageName))
-    const dev = this.projectDevApps().filter((app) => !offlinePackages.has(app.packageName))
+    const dev = this.projectDevApps().filter(
+      (app) => isInstalledMiniappAllowed(app.packageName, undefined, null) && !offlinePackages.has(app.packageName),
+    )
     const devPackages = new Set(dev.map((app) => app.packageName))
     const installed = diskApps.filter(
-      (app) => !offlinePackages.has(app.packageName) && !devPackages.has(app.packageName),
+      (app) =>
+        isInstalledMiniappAllowed(
+          app.packageName,
+          app.version,
+          app.version ? this.getReleaseIdentity(app.packageName, app.version) : null,
+        ) &&
+        !offlinePackages.has(app.packageName) &&
+        !devPackages.has(app.packageName),
     )
     return [...installed, ...dev, ...offline]
   }
@@ -1003,7 +1074,6 @@ export interface DevAppRecord {
 const DEV_APPS_INDEX_KEY = "dev_apps_index"
 const DEV_APP_ICONS_DIR = "dev-miniapp-icons"
 
-
 function isPrivateLanHost(hostname: string): boolean {
   return (
     hostname === "localhost" ||
@@ -1167,8 +1237,7 @@ export async function registerDevApp(record: DevAppRecord): Promise<void> {
   // Relaunch paths (developer-URL screen, loadDevMiniapp) omit mdnsHost, so an
   // omitted field keeps whatever the QR scan stored instead of wiping the
   // `.local` failover host.
-  const mdnsHost =
-    record.mdnsHost !== undefined ? record.mdnsHost.trim() || undefined : readStoredMdnsHost(packageName)
+  const mdnsHost = record.mdnsHost !== undefined ? record.mdnsHost.trim() || undefined : readStoredMdnsHost(packageName)
   const devRecord: DevAppRecord = {
     ...record,
     packageName,