@mentra/cloud-protocol 3.4.0-dev.999 → 3.5.0-dev.1238

package/README.md

@@ -1,9 +1,10 @@
 # @mentra/cloud-protocol
 
 The MentraOS phone ↔ cloud wire protocol: message schemas, envelopes, and
-error types shared by everything that speaks to the MentraOS cloud. Pure
-TypeScript + [zod](https://github.com/colinhacks/zod) — no server or native
-dependencies.
+error types shared by everything that speaks to the MentraOS cloud, and the
+miniapp URL rules Core and the engine both apply. Pure TypeScript +
+[zod](https://github.com/colinhacks/zod), and [tldts](https://github.com/remusao/tldts)
+for the Public Suffix List — no server or native dependencies.
 
 This is a **leaf package**: [`@mentra/cloud-client`](https://www.npmjs.com/package/@mentra/cloud-client)
 and [`@mentra/engine`](https://www.npmjs.com/package/@mentra/engine) depend on
@@ -33,7 +34,8 @@ import {normalizePhotoSizeTier} from "@mentra/cloud-protocol/camera";
 ```
 
 Modules: `envelope`, `messages`, `handshake`, `control`, `camera`, `audio`,
-`maps`, `errors` — each importable as `@mentra/cloud-protocol/<module>`.
+`maps`, `errors`, `miniapp-url` — each importable as
+`@mentra/cloud-protocol/<module>`.
 
 The package ships TypeScript source (`main: ./src/index.ts`) and targets
 consumers that compile TS themselves (Metro / bundlers / tsc); it is not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/cloud-protocol",
-  "version": "3.4.0-dev.999",
+  "version": "3.5.0-dev.1238",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -15,6 +15,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "tldts": "7.4.19",
     "zod": "^3.24.1"
   },
   "publishConfig": {

package/src/__fixtures__/miniapp-url-vectors.json

@@ -0,0 +1,194 @@
+{
+  "$comment": "Shared by the protocol tests (miniapp-url.test.ts) and the engine tests, so Core and the Mentra App answer every case the same way. `null` means refused.",
+  "normalize": [
+    {"input": "https://notes.example.com", "expected": {"url": "https://notes.example.com/", "host": "notes.example.com", "kind": "public"}},
+    {"input": "https://notes.example.com/app", "expected": {"url": "https://notes.example.com/app/", "host": "notes.example.com", "kind": "public"}},
+    {"input": "https://notes.example.com/app/", "expected": {"url": "https://notes.example.com/app/", "host": "notes.example.com", "kind": "public"}},
+    {"input": "HTTPS://Notes.Example.COM/App", "expected": {"url": "https://notes.example.com/App/", "host": "notes.example.com", "kind": "public"}, "why": "the scheme and host are lowercased; the path keeps its case"},
+    {"input": "https://notes.example.com:443/app", "expected": {"url": "https://notes.example.com/app/", "host": "notes.example.com", "kind": "public"}, "why": "the default port is dropped"},
+    {"input": "https://notes.example.com:8443/app", "expected": {"url": "https://notes.example.com:8443/app/", "host": "notes.example.com", "kind": "public"}},
+    {"input": "https://notes.example.com./app", "expected": {"url": "https://notes.example.com/app/", "host": "notes.example.com", "kind": "public"}, "why": "a trailing dot names the same host"},
+    {"input": "  https://notes.example.com/app  ", "expected": {"url": "https://notes.example.com/app/", "host": "notes.example.com", "kind": "public"}},
+    {"input": "https://notes.example.com/a/./b/../c", "expected": {"url": "https://notes.example.com/a/c/", "host": "notes.example.com", "kind": "public"}},
+    {"input": "https://alice.github.io/notes", "expected": {"url": "https://alice.github.io/notes/", "host": "alice.github.io", "kind": "public"}},
+    {"input": "https://tools.acme.co.uk", "expected": {"url": "https://tools.acme.co.uk/", "host": "tools.acme.co.uk", "kind": "public"}},
+    {"input": "https://miniapps.mentraglass.com/com.mentra.notes", "expected": {"url": "https://miniapps.mentraglass.com/com.mentra.notes/", "host": "miniapps.mentraglass.com", "kind": "public"}},
+    {"input": "https://notes.my-site.com", "expected": {"url": "https://notes.my-site.com/", "host": "notes.my-site.com", "kind": "public"}},
+    {"input": "https://xn--mnchen-3ya.de/notes", "expected": {"url": "https://xn--mnchen-3ya.de/notes/", "host": "xn--mnchen-3ya.de", "kind": "public"}},
+    {"input": "https://93.184.215.14/notes", "expected": {"url": "https://93.184.215.14/notes/", "host": "93.184.215.14", "kind": "public"}, "why": "a public IP address is a valid URL, but no package name passes the domain rule on it"},
+    {"input": "http://localhost:8080", "expected": {"url": "http://localhost:8080/", "host": "localhost", "kind": "local"}},
+    {"input": "http://LOCALHOST:8080/app", "expected": {"url": "http://localhost:8080/app/", "host": "localhost", "kind": "local"}},
+    {"input": "http://localhost:80/", "expected": {"url": "http://localhost/", "host": "localhost", "kind": "local"}},
+    {"input": "http://10.0.0.5:3000/app", "expected": {"url": "http://10.0.0.5:3000/app/", "host": "10.0.0.5", "kind": "local"}},
+    {"input": "https://10.0.0.5/app", "expected": {"url": "https://10.0.0.5/app/", "host": "10.0.0.5", "kind": "local"}},
+    {"input": "http://127.1:8080", "expected": {"url": "http://127.0.0.1:8080/", "host": "127.0.0.1", "kind": "local"}, "why": "IPv4 shorthand is written out"},
+    {"input": "http://[fd00::1]:8080", "expected": {"url": "http://[fd00::1]:8080/", "host": "[fd00::1]", "kind": "local"}},
+    {"input": "http://[FD00:0:0:0:0:0:0:1]/", "expected": {"url": "http://[fd00::1]/", "host": "[fd00::1]", "kind": "local"}},
+    {"input": "http://[::ffff:10.0.0.5]/", "expected": {"url": "http://[::ffff:a00:5]/", "host": "[::ffff:a00:5]", "kind": "local"}},
+    {"input": "http://printer.local:8080/", "expected": {"url": "http://printer.local:8080/", "host": "printer.local", "kind": "local"}},
+    {"input": "http://dev.localhost:5173", "expected": {"url": "http://dev.localhost:5173/", "host": "dev.localhost", "kind": "local"}},
+    {"input": "http://notes.example.com/", "expected": null, "why": "HTTP is for local-network addresses only"},
+    {"input": "http://93.184.215.14/", "expected": null},
+    {"input": "https://user:secret@notes.example.com/", "expected": null, "why": "credentials"},
+    {"input": "https://user@notes.example.com/", "expected": null},
+    {"input": "https://@notes.example.com/", "expected": null},
+    {"input": "https://notes.example.com/app?v=2", "expected": null, "why": "a query"},
+    {"input": "https://notes.example.com/app?", "expected": null},
+    {"input": "https://notes.example.com/app#top", "expected": null, "why": "a fragment"},
+    {"input": "https://notes.example.com/app#", "expected": null},
+    {"input": "https://münchen.de/", "expected": null, "why": "a host in Unicode; IDN hosts are written in their xn-- form"},
+    {"input": "https://notes.example.com/ä/", "expected": null, "why": "non-ASCII; paths are percent-encoded"},
+    {"input": "https://notes.example.com/a b/", "expected": null},
+    {"input": "https://notes.example.com\\app", "expected": null},
+    {"input": "https://notes..example.com/", "expected": null},
+    {"input": "https://notes_app.example.com/", "expected": {"url": "https://notes_app.example.com/", "host": "notes_app.example.com", "kind": "public"}},
+    {"input": "https://-notes.example.com/", "expected": null},
+    {"input": "https://notes.example.com:99999/", "expected": null},
+    {"input": "https:notes.example.com", "expected": null},
+    {"input": "//notes.example.com/", "expected": null},
+    {"input": "notes.example.com", "expected": null},
+    {"input": "ftp://notes.example.com/", "expected": null},
+    {"input": "javascript:alert(1)", "expected": null},
+    {"input": "https://", "expected": null},
+    {"input": "", "expected": null}
+  ],
+  "registrableDomain": [
+    {"host": "notes.example.com", "expected": "example.com"},
+    {"host": "example.com", "expected": "example.com"},
+    {"host": "alice.github.io", "expected": "alice.github.io"},
+    {"host": "notes.alice.github.io", "expected": "alice.github.io"},
+    {"host": "tools.acme.co.uk", "expected": "acme.co.uk"},
+    {"host": "miniapps.mentraglass.com", "expected": "mentraglass.com"},
+    {"host": "miniapps.dev.mentraglass.com", "expected": "mentraglass.com"},
+    {"host": "Notes.Example.COM", "expected": "example.com"},
+    {"host": "notes.example.com.", "expected": "example.com"},
+    {"host": "notes.my-site.com", "expected": "my-site.com"},
+    {"host": "xn--mnchen-3ya.de", "expected": "xn--mnchen-3ya.de"},
+    {"host": "shop.example.xn--p1ai", "expected": "example.xn--p1ai"},
+    {"host": "com", "expected": null, "why": "a public suffix is nobody's domain"},
+    {"host": "co.uk", "expected": null},
+    {"host": "github.io", "expected": null},
+    {"host": "93.184.215.14", "expected": null},
+    {"host": "[2001:db8::1]", "expected": null},
+    {"host": "localhost", "expected": null},
+    {"host": "dev.localhost", "expected": null},
+    {"host": "printer.local", "expected": null},
+    {"host": "10.0.0.5", "expected": null},
+    {"host": "fd00::1", "expected": null},
+    {"host": "notes.corp.internal", "expected": null, "why": "a suffix the Public Suffix List doesn't know is owned by nobody"},
+    {"host": "notes.acme.example", "expected": null},
+    {"host": "printer.home.arpa", "expected": null},
+    {"host": "notes..example.com", "expected": null},
+    {"host": "notes.example.com:443", "expected": null, "why": "a host, not a URL or host and port"},
+    {"host": "https://notes.example.com/", "expected": null},
+    {"host": "user@notes.example.com", "expected": null},
+    {"host": "", "expected": null}
+  ],
+  "packagePrefix": [
+    {"host": "notes.example.com", "expected": "com.example"},
+    {"host": "alice.github.io", "expected": "io.github.alice"},
+    {"host": "tools.acme.co.uk", "expected": "uk.co.acme"},
+    {"host": "miniapps.mentraglass.com", "expected": "com.mentraglass"},
+    {"host": "NOTES.Example.COM.", "expected": "com.example"},
+    {"host": "notes.my-site.com", "expected": "com.my_site"},
+    {"host": "a--b.com", "expected": "com.a__b"},
+    {"host": "xn--mnchen-3ya.de", "expected": "de.xn__mnchen_3ya"},
+    {"host": "shop.example.xn--p1ai", "expected": "xn__p1ai.example"},
+    {"host": "app.1password.com", "expected": null, "why": "a label that starts with a digit can't start a package part"},
+    {"host": "my_site.com", "expected": null, "why": "only a hyphen becomes an underscore, so an underscore in the domain could collide with it"},
+    {"host": "93.184.215.14", "expected": null},
+    {"host": "localhost", "expected": null},
+    {"host": "github.io", "expected": null}
+  ],
+  "localNetwork": [
+    {"host": "localhost", "expected": true},
+    {"host": "LOCALHOST", "expected": true},
+    {"host": "localhost.", "expected": true},
+    {"host": "dev.localhost", "expected": true},
+    {"host": "printer.local", "expected": true},
+    {"host": "alexs-macbook.local", "expected": true},
+    {"host": "10.0.0.5", "expected": true},
+    {"host": "10.255.255.255", "expected": true},
+    {"host": "127.0.0.1", "expected": true},
+    {"host": "127.1", "expected": true},
+    {"host": "172.16.0.1", "expected": true},
+    {"host": "172.31.255.255", "expected": true},
+    {"host": "192.168.1.20", "expected": true},
+    {"host": "169.254.10.1", "expected": true},
+    {"host": "100.64.0.1", "expected": true, "why": "shared address space, used by overlay networks"},
+    {"host": "100.127.255.255", "expected": true},
+    {"host": "fd00::1", "expected": true},
+    {"host": "[fd00::1]", "expected": true},
+    {"host": "fc00::1", "expected": true},
+    {"host": "fe80::1", "expected": true},
+    {"host": "::1", "expected": true},
+    {"host": "[::1]", "expected": true},
+    {"host": "::ffff:10.0.0.5", "expected": true},
+    {"host": "[::ffff:a00:5]", "expected": true},
+    {"host": "local", "expected": false},
+    {"host": "notes.example.com", "expected": false},
+    {"host": "printer.local.example.com", "expected": false},
+    {"host": "localhost.example.com", "expected": false},
+    {"host": "172.15.255.255", "expected": false},
+    {"host": "172.32.0.1", "expected": false},
+    {"host": "192.169.0.1", "expected": false},
+    {"host": "100.63.255.255", "expected": false},
+    {"host": "100.128.0.1", "expected": false},
+    {"host": "11.0.0.1", "expected": false},
+    {"host": "8.8.8.8", "expected": false},
+    {"host": "::ffff:8.8.8.8", "expected": false},
+    {"host": "2001:db8::1", "expected": false},
+    {"host": "::", "expected": false},
+    {"host": "10.0.0.5:8080", "expected": false},
+    {"host": "http://10.0.0.5/", "expected": false},
+    {"host": "", "expected": false}
+  ],
+  "domainRule": [
+    {"packageName": "com.example.notes", "url": "https://notes.example.com/", "allowed": true},
+    {"packageName": "com.example.notes.pro", "url": "https://notes.example.com/app/", "allowed": true},
+    {"packageName": "com.example.notes", "url": "https://example.com/", "allowed": true},
+    {"packageName": "com.example", "url": "https://notes.example.com/", "allowed": false, "why": "the reversed domain needs at least one more part"},
+    {"packageName": "com.other.notes", "url": "https://notes.example.com/", "allowed": false},
+    {"packageName": "com.exampl.notes", "url": "https://notes.example.com/", "allowed": false},
+    {"packageName": "com.example.notes", "url": "https://notes.example.com.evil.net/", "allowed": false},
+    {"packageName": "com.example.notes", "url": "https://notes.examplex.com/", "allowed": false},
+    {"packageName": "io.github.alice.notes", "url": "https://alice.github.io/notes/", "allowed": true},
+    {"packageName": "io.github.bob.notes", "url": "https://alice.github.io/notes/", "allowed": false, "why": "each GitHub Pages user has their own namespace"},
+    {"packageName": "io.github.notes", "url": "https://alice.github.io/", "allowed": false},
+    {"packageName": "uk.co.acme.tools", "url": "https://tools.acme.co.uk/", "allowed": true},
+    {"packageName": "uk.co.tools", "url": "https://tools.acme.co.uk/", "allowed": false},
+    {"packageName": "com.mentra.notes", "url": "https://miniapps.mentraglass.com/com.mentra.notes/", "allowed": true, "why": "com.mentra.* belongs to mentraglass.com"},
+    {"packageName": "com.mentra.notes", "url": "https://miniapps.dev.mentraglass.com/com.mentra.notes/", "allowed": true},
+    {"packageName": "com.mentraglass.tools", "url": "https://mentraglass.com/tools/", "allowed": true},
+    {"packageName": "com.mentra.notes", "url": "https://notes.example.com/", "allowed": false},
+    {"packageName": "com.mentra.notes", "url": "https://mentra.com/notes/", "allowed": false, "why": "Mentra owns mentraglass.com, not mentra.com"},
+    {"packageName": "com.mentra.notes", "url": "https://mentraglass.com.evil.example/", "allowed": false},
+    {"packageName": "com.mentra.notes", "url": "https://notmentraglass.com/", "allowed": false},
+    {"packageName": "com.mentra.notes", "url": "http://miniapps.mentraglass.com/com.mentra.notes/", "allowed": false},
+    {"packageName": "com.mentra", "url": "https://mentraglass.com/", "allowed": false},
+    {"packageName": "com.mentrax.notes", "url": "https://notes.mentrax.com/", "allowed": true},
+    {"packageName": "com.my_site.notes", "url": "https://notes.my-site.com/", "allowed": true, "why": "a hyphen in a domain label is an underscore in the package name"},
+    {"packageName": "com.my-site.notes", "url": "https://notes.my-site.com/", "allowed": false, "why": "package names have no hyphens"},
+    {"packageName": "com.mysite.notes", "url": "https://notes.my-site.com/", "allowed": false},
+    {"packageName": "de.xn__mnchen_3ya.notes", "url": "https://xn--mnchen-3ya.de/notes/", "allowed": true},
+    {"packageName": "de.xn__mnchen_3ya.notes", "url": "https://münchen.de/notes/", "allowed": false},
+    {"packageName": "com.example.notes", "url": "https://NOTES.Example.COM./app/", "allowed": true},
+    {"packageName": "com.Example.notes", "url": "https://notes.example.com/", "allowed": false, "why": "package names are lowercase"},
+    {"packageName": "com.example.Notes", "url": "https://notes.example.com/", "allowed": false},
+    {"packageName": "com.example.1notes", "url": "https://notes.example.com/", "allowed": false},
+    {"packageName": "com.example.", "url": "https://notes.example.com/", "allowed": false},
+    {"packageName": "com.1password.notes", "url": "https://app.1password.com/", "allowed": false},
+    {"packageName": "com.example.notes", "url": "https://93.184.215.14/", "allowed": false, "why": "an IP address has no registrable domain"},
+    {"packageName": "com.example.notes", "url": "http://localhost:8080/", "allowed": false, "why": "a local-network address has no domain to own the name"},
+    {"packageName": "com.example.notes", "url": "https://10.0.0.5/", "allowed": false},
+    {"packageName": "com.example.notes", "url": "https://[fd00::1]/", "allowed": false},
+    {"packageName": "local.printer.notes", "url": "https://printer.local/", "allowed": false},
+    {"packageName": "internal.corp.notes", "url": "https://notes.corp.internal/", "allowed": false},
+    {"packageName": "arpa.home.notes", "url": "https://notes.home.arpa/", "allowed": false},
+    {"packageName": "com.example.notes", "url": "https://user:secret@notes.example.com/", "allowed": false},
+    {"packageName": "com.example.notes", "url": "https://notes.example.com/miniapp.json", "allowed": true, "why": "only the host decides; the path doesn't"},
+    {"packageName": "com.example.notes", "url": "https://cdn.example.com/notes/miniapp.json?sig=abc", "allowed": true, "why": "a query on a redirect target doesn't change its host"},
+    {"packageName": "com.example.notes", "url": "notes.example.com", "allowed": false},
+    {"packageName": "com.example.notes", "url": "", "allowed": false}
+  ]
+}

package/src/declared-age.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview A person's declared age, kept on their Core account: `/api/account/declared-age`.
+ *
+ * A miniapp that declares an `ageRating` above the host app's own App Store rating installs or opens only for a person
+ * whose declared age is old enough (App Store Review Guideline 4.7.5). The first time that comes up, the app asks the
+ * person's age once, and Core keeps it on their account with the date they gave it. Their age now is the declared age
+ * plus the whole years since that date ({@link currentDeclaredAge}). Core never puts it in a token or sends it to a
+ * miniapp.
+ *
+ *   GET /api/account/declared-age           {declaredAge, declaredAgeAt}, both null until the person answers
+ *   PUT /api/account/declared-age   {age}   {declaredAge, declaredAgeAt}
+ *
+ * `GET /api/account/me` carries the same two fields.
+ */
+import {z} from "zod"
+
+/** The ages a person may give: a whole number of years. */
+export const DECLARED_AGE_MIN = 1
+export const DECLARED_AGE_MAX = 120
+
+export const DeclaredAgeRequestSchema = z.object({
+  age: z.number().int().min(DECLARED_AGE_MIN).max(DECLARED_AGE_MAX),
+})
+export type DeclaredAgeRequest = z.infer<typeof DeclaredAgeRequestSchema>
+
+/** What Core keeps. Both fields are null until the person answers, and set together after. */
+export interface DeclaredAge {
+  /** The age the person gave. */
+  declaredAge: number | null
+  /** When they gave it, ISO 8601. */
+  declaredAgeAt: string | null
+}
+
+export const DeclaredAgeSchema: z.ZodType<DeclaredAge> = z.union([
+  z.object({
+    declaredAge: z.number().int().min(DECLARED_AGE_MIN).max(DECLARED_AGE_MAX),
+    declaredAgeAt: z.string().datetime({offset: true}),
+  }),
+  z.object({declaredAge: z.null(), declaredAgeAt: z.null()}),
+])
+
+/**
+ * The person's age at `now`: the age they gave plus the whole years since they gave it, counted by calendar date in
+ * UTC. Never less than the age they gave, even when `now` is earlier.
+ */
+export function currentDeclaredAge(declaredAge: number, declaredAgeAt: string | Date, now: Date): number {
+  const at = new Date(declaredAgeAt)
+  if (Number.isNaN(at.getTime()) || Number.isNaN(now.getTime())) return declaredAge
+  let years = now.getUTCFullYear() - at.getUTCFullYear()
+  const beforeAnniversary =
+    now.getUTCMonth() < at.getUTCMonth() ||
+    (now.getUTCMonth() === at.getUTCMonth() && now.getUTCDate() < at.getUTCDate())
+  if (beforeAnniversary) years -= 1
+  return declaredAge + Math.max(0, years)
+}

package/src/fleet.ts

@@ -17,12 +17,32 @@ export const FLEET_LIMITS = {
   maxBatchBytes: 1_048_576,
   maxSessionsPerCheckpoint: 32,
   maxSessionElapsedMs: 7 * 24 * 60 * 60 * 1000,
+  maxInventoryMiniapps: 500,
+  maxAssignmentEntries: 500,
   phoneQueueMaxRecords: 10_000,
   phoneQueueMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
   replayWindowMs: 14 * 24 * 60 * 60 * 1000,
   maxFutureSkewMs: 5 * 60 * 1000,
+  maxTelemetryLossPackages: 500,
+  maxCrashesInWindow: 1_000,
+  maxReconnectMs: 7 * 24 * 60 * 60 * 1000,
 } as const
 
+/**
+ * Phase 12: a miniapp's own events. The Mentra App applies these before it queues an event (dropping the event, a
+ * property, or cutting a string) and MFM checks them again, rejecting a record that still breaks one.
+ */
+export const FLEET_TELEMETRY_LIMITS = {
+  maxProperties: 25,
+  maxStringValueLength: 64,
+  eventsPerMinute: 60,
+  eventsPerDay: 2_000,
+  /** Places of the phone's queue telemetry may hold; when full, the oldest telemetry record gives way. */
+  queueShare: 2_000,
+} as const
+/** An event or property name: 1-64 lowercase letters, digits and underscores, starting with a letter. */
+export const FLEET_TELEMETRY_NAME = /^[a-z][a-z0-9_]{0,63}$/
+
 const FleetId = z
   .string()
   .min(1)
@@ -60,6 +80,11 @@ export const FLEET_CAPABILITIES = [
   "app_foreground",
   "engine_active",
   "photo_operations",
+  "phone_battery",
+  // Phase 12. A record kind the phone can produce is declared, so a view tells a measured 0 from an unknown.
+  "miniapp_failures",
+  "glasses_connectivity",
+  "miniapp_telemetry",
 ] as const
 
 const Battery = z.discriminatedUnion("state", [
@@ -86,6 +111,8 @@ export const FleetSnapshotPayloadSchema = z
         appBuild: FleetText,
         engineVersion: FleetText.optional(),
         sdkVersion: FleetText.optional(),
+        /** The phone's own battery; absent from an app that does not report one. */
+        battery: Battery.optional(),
       })
       .strict(),
     glasses: z
@@ -110,6 +137,18 @@ export const FleetSnapshotPayloadSchema = z
   })
   .strict()
 
+/** Phase 12: why a launch failed. Codes only, never error text. */
+export const FLEET_LAUNCH_FAILURE_REASONS = [
+  "bundle_missing",
+  "incompatible_host",
+  "policy_blocked",
+  "spawn_failed",
+  "connect_timeout",
+  "permission_denied",
+  "unknown",
+] as const
+export type FleetLaunchFailureReason = (typeof FLEET_LAUNCH_FAILURE_REASONS)[number]
+
 export const FleetLaunchPayloadSchema = z
   .object({
     packageName: FleetText,
@@ -117,8 +156,14 @@ export const FleetLaunchPayloadSchema = z
     versionName: FleetText.optional(),
     start: z.enum(["user", "automatic"]),
     outcome: z.enum(["started", "failed"]),
+    /** Phase 12. Only a failed launch carries it; a Mentra App from before Phase 12 sends none. */
+    failureReason: z.enum(FLEET_LAUNCH_FAILURE_REASONS).optional(),
   })
   .strict()
+  .refine((v) => v.failureReason === undefined || v.outcome === "failed", {
+    path: ["failureReason"],
+    message: "only a failed launch carries a failureReason",
+  })
 
 export const FLEET_ACTIVITIES = ["glasses_connection", "miniapp_execution", "app_foreground", "engine_active"] as const
 export const FleetActivityCheckpointSchema = z
@@ -154,6 +199,96 @@ export const FleetPhotoPayloadSchema = z
   .strict()
   .refine((v) => (v.stage === "failed") === (v.failedStage !== undefined), "failedStage goes with stage failed")
 
+/** The provisioning spec's installation reasons. Management reasons are kept apart from the artifact's provenance. */
+export const FLEET_INSTALL_REASONS = ["bundled", "explicit", "manifest", "assignment"] as const
+export type FleetInstallReason = (typeof FLEET_INSTALL_REASONS)[number]
+
+/** Phase 11: the phone's installed miniapps. Sent when the collector starts and whenever the inventory changes. */
+export const FleetMiniappInventoryPayloadSchema = z
+  .object({
+    miniapps: z
+      .array(
+        z
+          .object({
+            packageName: FleetText,
+            versionName: FleetText,
+            digest: FleetText,
+            reasons: z.array(z.enum(FLEET_INSTALL_REASONS)).min(1).max(FLEET_INSTALL_REASONS.length),
+          })
+          .strict(),
+      )
+      .max(FLEET_LIMITS.maxInventoryMiniapps),
+  })
+  .strict()
+
+/** The provisioning spec's outcome states for one assignment on one phone. */
+export const FLEET_ASSIGNMENT_STATES = [
+  "pending",
+  "deferred_running",
+  "downloading",
+  "installing",
+  "installed",
+  "blocked",
+  "retrying",
+  "withdrawn",
+] as const
+export type FleetAssignmentState = (typeof FLEET_ASSIGNMENT_STATES)[number]
+
+/** Stable reasons for a blocked or retrying assignment. Never error text. */
+export const FLEET_ASSIGNMENT_REASONS = [
+  "archived",
+  "access_denied",
+  "not_a_miniapp",
+  "download_failed",
+  "signature_invalid",
+  "incompatible_host",
+  "newer_version_installed",
+  "manifest_conflict",
+  "storage_full",
+] as const
+export type FleetAssignmentReason = (typeof FLEET_ASSIGNMENT_REASONS)[number]
+
+/** A miniapp's address: https, bounded, and with no credentials in it. */
+export const FleetMiniappUrl = z
+  .string()
+  .min(1)
+  .max(2048)
+  .refine((value) => {
+    try {
+      const url = new URL(value)
+      return url.protocol === "https:" && url.username === "" && url.password === ""
+    } catch {
+      return false
+    }
+  }, "a miniapp URL is an https address without credentials")
+
+const FleetRevision = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER)
+
+/** Phase 11: one assignment's state on this phone. */
+export const FleetAssignmentOutcomePayloadSchema = z
+  .object({
+    assignmentId: FleetId,
+    /** The assignment's own revision. */
+    assignmentRevision: FleetRevision,
+    /** The account's desired-state revision the phone acted on. */
+    desiredRevision: FleetRevision,
+    packageName: FleetText,
+    state: z.enum(FLEET_ASSIGNMENT_STATES),
+    reason: z.enum(FLEET_ASSIGNMENT_REASONS).optional(),
+    selectedVersion: FleetText.optional(),
+    installedVersion: FleetText.optional(),
+    attempts: z.number().int().min(0).max(1_000_000),
+    attemptedAt: FleetUtcTime,
+    lastSuccessAt: FleetUtcTime.optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.state === "blocked" && value.reason === undefined)
+      ctx.addIssue({code: "custom", path: ["reason"], message: "a blocked assignment carries its reason"})
+    if (value.state !== "blocked" && value.state !== "retrying" && value.reason !== undefined)
+      ctx.addIssue({code: "custom", path: ["reason"], message: "only a blocked or retrying assignment carries a reason"})
+  })
+
 export const FleetCoverageGapPayloadSchema = z
   .object({
     reason: z.enum(["queue_dropped", "queue_expired", "clock_untrusted", "reporter_stopped", "record_rejected"]),
@@ -163,6 +298,146 @@ export const FleetCoverageGapPayloadSchema = z
   })
   .strict()
 
+const TelemetryName = z.string().regex(FLEET_TELEMETRY_NAME)
+const TelemetryValue = z.union([
+  z.string().max(FLEET_TELEMETRY_LIMITS.maxStringValueLength),
+  z.number().finite(),
+  z.boolean(),
+])
+
+/** Phase 12: one event a miniapp captured, attributed by the Mentra App to the miniapp whose bridge sent it. */
+export const FleetTelemetryEventPayloadSchema = z
+  .object({
+    packageName: FleetText,
+    versionName: FleetText.optional(),
+    /** The miniapp's execution session at capture (its `miniapp_execution` activitySessionId), when one was open. */
+    executionSessionId: FleetId.optional(),
+    event: TelemetryName,
+    properties: z
+      .record(TelemetryName, TelemetryValue)
+      .refine((p) => Object.keys(p).length <= FLEET_TELEMETRY_LIMITS.maxProperties, "too many properties"),
+    /** Properties the Mentra App dropped from this event (bad name or value, or past the 25th). */
+    droppedProperties: z.number().int().min(0).max(1_000_000),
+    /** String values the Mentra App cut to 64 characters. */
+    cutValues: z.number().int().min(0).max(FLEET_TELEMETRY_LIMITS.maxProperties),
+  })
+  .strict()
+
+/** What the Mentra App lost of one miniapp's telemetry. */
+export const FleetTelemetryLossSchema = z
+  .object({
+    packageName: FleetText,
+    /** Over the name, rate or daily limit. */
+    overLimit: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    /** Given way in the queue to newer telemetry. */
+    evicted: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    /** Too old in the queue to send. */
+    expired: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    /** Sent, and rejected by MFM. */
+    rejected: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  })
+  .strict()
+  .refine((v) => v.overLimit + v.evicted + v.expired + v.rejected > 0, "a loss counts something")
+
+/** Phase 12: telemetry the Mentra App lost over a period, per miniapp. Never a coverage gap. */
+export const FleetTelemetryLossPayloadSchema = z
+  .object({
+    from: FleetUtcTime,
+    to: FleetUtcTime,
+    losses: z.array(FleetTelemetryLossSchema).min(1).max(FLEET_LIMITS.maxTelemetryLossPackages),
+  })
+  .strict()
+  .refine((v) => Date.parse(v.from) <= Date.parse(v.to), {path: ["to"], message: "to is not before from"})
+
+export const FLEET_CRASH_SURFACES = ["context", "webview"] as const
+export const FLEET_CRASH_CATEGORIES = [
+  "uncaught_exception",
+  "bridge_error",
+  "unresponsive",
+  "watchdog_kill",
+  "content_process_terminated",
+  "unknown",
+] as const
+export type FleetCrashCategory = (typeof FLEET_CRASH_CATEGORIES)[number]
+/**
+ * What followed a crash: the engine restarts the miniapp, or stops restarting it after repeated crashes, or (a screen
+ * whose content process died) the screen closes and nothing restarts it until the person opens it again.
+ */
+export const FLEET_CRASH_OUTCOMES = ["respawn_scheduled", "crash_loop_stopped", "closed"] as const
+
+/** Phase 12: one miniapp crash. The engine maps its reason to a category; the reason text never leaves the phone. */
+export const FleetMiniappCrashPayloadSchema = z
+  .object({
+    packageName: FleetText,
+    versionName: FleetText.optional(),
+    executionSessionId: FleetId.optional(),
+    surface: z.enum(FLEET_CRASH_SURFACES),
+    category: z.enum(FLEET_CRASH_CATEGORIES),
+    outcome: z.enum(FLEET_CRASH_OUTCOMES),
+    /** Crashes of this miniapp in the crash window, this one included. */
+    crashesInWindow: z.number().int().min(1).max(FLEET_LIMITS.maxCrashesInWindow),
+  })
+  .strict()
+
+export const FLEET_INSTALL_OPERATIONS = ["install", "update", "remove"] as const
+/** What started an install: `url` covers a link, the QR scanner, the paste box, the system list and the update check. */
+export const FLEET_INSTALL_SOURCES = ["bundled", "url", "manifest", "local", "assignment"] as const
+export const FLEET_INSTALL_OUTCOMES = ["succeeded", "failed", "deferred"] as const
+/** `assignment_outcome`'s reasons where they apply, and three of its own. */
+export const FLEET_INSTALL_FAILURE_REASONS = [...FLEET_ASSIGNMENT_REASONS, "network", "user_cancelled", "unknown"] as const
+export type FleetInstallFailureReason = (typeof FLEET_INSTALL_FAILURE_REASONS)[number]
+
+/** Phase 12: one install, update or removal attempt, managed or not. */
+export const FleetMiniappInstallPayloadSchema = z
+  .object({
+    packageName: FleetText,
+    operation: z.enum(FLEET_INSTALL_OPERATIONS),
+    source: z.enum(FLEET_INSTALL_SOURCES),
+    fromVersion: FleetText.optional(),
+    toVersion: FleetText.optional(),
+    outcome: z.enum(FLEET_INSTALL_OUTCOMES),
+    reason: z.enum(FLEET_INSTALL_FAILURE_REASONS).optional(),
+  })
+  .strict()
+  .refine((v) => (v.outcome === "succeeded") === (v.reason === undefined), {
+    path: ["reason"],
+    message: "a failed or deferred attempt carries its reason, and only it",
+  })
+
+export const FLEET_CONNECTION_EVENTS = ["pair_failed", "connect_failed", "disconnected", "reconnected"] as const
+export type FleetConnectionEventKind = (typeof FLEET_CONNECTION_EVENTS)[number]
+export const FLEET_CONNECTION_CATEGORIES = [
+  "bluetooth_off",
+  "permission_denied",
+  "bond_failed",
+  "not_found",
+  "timeout",
+  "firmware_incompatible",
+  "link_lost",
+  "user_action",
+  "unknown",
+] as const
+export type FleetConnectionCategory = (typeof FLEET_CONNECTION_CATEGORIES)[number]
+
+/**
+ * Phase 12: a pairing or connection change. A disconnect the person asked for is `user_action`, and is not shown as a
+ * problem. The glasses are the record's `deviceBinding` when the phone knows them.
+ */
+export const FleetConnectionEventPayloadSchema = z
+  .object({
+    event: z.enum(FLEET_CONNECTION_EVENTS),
+    category: z.enum(FLEET_CONNECTION_CATEGORIES),
+    glassesModel: FleetText.optional(),
+    appVersion: FleetText,
+    /** How long the reconnect took, for `reconnected` only. */
+    reconnectMs: z.number().int().min(0).max(FLEET_LIMITS.maxReconnectMs).optional(),
+  })
+  .strict()
+  .refine((v) => (v.event === "reconnected") === (v.reconnectMs !== undefined), {
+    path: ["reconnectMs"],
+    message: "a reconnect carries the time it took, and only it",
+  })
+
 const base = {
   schemaVersion: z.literal(FLEET_SCHEMA_VERSION),
   recordId: FleetId,
@@ -170,10 +445,6 @@ const base = {
   collectorSessionId: FleetId,
   sequence: z.number().int().min(0),
   observedAt: FleetUtcTime,
-  management: z
-    .object({associationId: FleetId, generation: z.number().int().min(0)})
-    .strict()
-    .optional(),
   capabilities: z.array(z.enum(FLEET_CAPABILITIES)).max(FLEET_CAPABILITIES.length),
 }
 export const FleetRecordSchema = z.discriminatedUnion("kind", [
@@ -197,6 +468,20 @@ export const FleetRecordSchema = z.discriminatedUnion("kind", [
     })
     .strict(),
   z.object({...base, kind: z.literal("coverage_gap"), payload: FleetCoverageGapPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("miniapp_inventory"), payload: FleetMiniappInventoryPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("assignment_outcome"), payload: FleetAssignmentOutcomePayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("telemetry_event"), payload: FleetTelemetryEventPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("telemetry_loss"), payload: FleetTelemetryLossPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("miniapp_crash"), payload: FleetMiniappCrashPayloadSchema}).strict(),
+  z.object({...base, kind: z.literal("miniapp_install"), payload: FleetMiniappInstallPayloadSchema}).strict(),
+  z
+    .object({
+      ...base,
+      kind: z.literal("connection_event"),
+      deviceBinding: FleetDeviceBindingSchema.optional(),
+      payload: FleetConnectionEventPayloadSchema,
+    })
+    .strict(),
 ]).superRefine((value, ctx) => {
   // A snapshot's glasses belong to the pair its binding names, so the two come together.
   if (value.kind === "snapshot" && (value.payload.glasses !== undefined) !== (value.deviceBinding !== undefined))
@@ -243,11 +528,63 @@ export const FleetReportAckSchema = z
   .object({
     schemaVersion: z.literal(FLEET_SCHEMA_VERSION),
     results: z.array(FleetRecordResultSchema),
+    /**
+     * The account's current desired-state revision (Phase 11). A phone holding an older one fetches desired state at
+     * once; there is no push channel. Optional so an acknowledgment from an older MFM still parses.
+     */
+    revision: FleetRevision.optional(),
   })
   .strict()
 export type FleetRecordResult = z.infer<typeof FleetRecordResultSchema>
 export type FleetReportAck = z.infer<typeof FleetReportAckSchema>
 
+/**
+ * Desired state, as MFM answers a phone through Core (`GET /api/client/fleet/desired-state`). Every answer carries one
+ * monotonic per-account `revision` and its generation time.
+ *
+ * - `managed`: the account's workspace and the assignment entries, which may be empty. A member of a workspace with
+ *   nothing assigned is still managed.
+ * - `unmanaged`: the account belongs to no workspace. Authoritative: the phone clears its assignment reasons.
+ *
+ * An error, timeout, partial response or missing MFM is never an empty set: MFM answers {@link FLEET_UNAVAILABLE}
+ * (503) and the phone keeps its last complete snapshot. `paused` (Phase 15) is not part of this schema, so a phone
+ * that receives an unknown status keeps its last snapshot.
+ */
+export const FleetDesiredStateEntrySchema = z
+  .object({
+    assignmentId: FleetId,
+    revision: FleetRevision,
+    /** The miniapp's own URL (Mentra-Specs #140). The phone installs it with `installMiniapp(url)` and takes the version it serves. */
+    url: FleetMiniappUrl,
+    /** The package the URL's manifest named when it was assigned. Display and matching only; the URL decides what installs. */
+    packageName: FleetText,
+    selection: z.literal("latest"),
+  })
+  .strict()
+
+export const FleetDesiredStateSchema = z.discriminatedUnion("status", [
+  z
+    .object({
+      status: z.literal("managed"),
+      revision: FleetRevision,
+      generatedAt: FleetUtcTime,
+      workspace: z.object({workspaceId: FleetId, name: z.string().min(1).max(200)}).strict(),
+      entries: z.array(FleetDesiredStateEntrySchema).max(FLEET_LIMITS.maxAssignmentEntries),
+    })
+    .strict(),
+  z.object({status: z.literal("unmanaged"), revision: FleetRevision, generatedAt: FleetUtcTime}).strict(),
+])
+export type FleetDesiredStateEntry = z.infer<typeof FleetDesiredStateEntrySchema>
+export type FleetDesiredState = z.infer<typeof FleetDesiredStateSchema>
+export type FleetMiniappInventoryPayload = z.infer<typeof FleetMiniappInventoryPayloadSchema>
+export type FleetAssignmentOutcomePayload = z.infer<typeof FleetAssignmentOutcomePayloadSchema>
+export type FleetLaunchPayload = z.infer<typeof FleetLaunchPayloadSchema>
+export type FleetTelemetryEventPayload = z.infer<typeof FleetTelemetryEventPayloadSchema>
+export type FleetTelemetryLossPayload = z.infer<typeof FleetTelemetryLossPayloadSchema>
+export type FleetMiniappCrashPayload = z.infer<typeof FleetMiniappCrashPayloadSchema>
+export type FleetMiniappInstallPayload = z.infer<typeof FleetMiniappInstallPayloadSchema>
+export type FleetConnectionEventPayload = z.infer<typeof FleetConnectionEventPayloadSchema>
+
 /** Whole-response error codes Core and MFM answer with. */
 export const FLEET_NOT_INSTALLED = "fleet_not_installed"
 export const FLEET_UNAVAILABLE = "fleet_unavailable"

package/src/index.ts

@@ -18,3 +18,6 @@ export * from "./camera";
 export * from "./maps";
 export * from "./report-automation";
 export * from "./fleet";
+export * from "./miniapp-url";
+export * from "./miniapp-registry";
+export * from "./declared-age";

package/src/miniapp-registry.ts

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview The Mentra App's registry calls to Core: `/api/client/registry/register` and `/status`.
+ *
+ * Every install of a miniapp URL registers it. Core verifies the URL itself, with its own fetcher, and answers:
+ * - `accepted`, with the `miniapp.json` Core read;
+ * - `accepted_unverified`, when Core could not read it: the URL is reachable only from the phone, or its server asks
+ *   for sign-in and refused the person's token. The phone's own request decides whether it installs;
+ * - `not_a_miniapp`, which stops the install;
+ * - `archived`, which stops it too.
+ *
+ * The updater sends one status batch for every installed URL and keeps the answer for `validForSeconds`. An archived
+ * URL is never updated; installed copies keep running.
+ *
+ * Core validates requests with these schemas, and the Cloud Client validates Core's answers with them. Objects keep
+ * only the fields they name, so a later Core can add fields without breaking an older phone.
+ */
+import {z} from "zod"
+import {
+  MINIAPP_AGE_RATINGS,
+  MINIAPP_PACKAGE_NAME_PATTERN,
+  MINIAPP_VERSION_PATTERN,
+  ServedMiniappManifestSchema,
+  type MiniappAgeRating,
+  type ServedMiniappManifest,
+} from "./miniapp-url"
+
+/** The most URLs one status call may name. */
+export const MINIAPP_REGISTRY_STATUS_MAX_ENTRIES = 500
+/** How long the phone keeps a status answer when Core doesn't say: 6 hours. */
+export const MINIAPP_REGISTRY_STATUS_DEFAULT_TTL_SECONDS = 21_600
+
+const MAX_URL_LENGTH = 2048
+const MAX_NAME_LENGTH = 500
+const MAX_VERSION_LENGTH = 256
+
+/** `verified`: Core read the URL's `miniapp.json` itself. `phone_reported`: Core could not, so it holds the phone's report. */
+export type MiniappRegistryVerification = "verified" | "phone_reported"
+/** An entry's own status. An archive rule can also cover an `active` entry; the status call answers for both. */
+export type MiniappRegistryEntryStatus = "active" | "archived"
+
+/** One registry entry, as Core shows it to a caller. */
+export interface RegistryEntryView {
+  /** The normalized miniapp URL: the entry's key. */
+  url: string
+  packageName: string
+  registrableDomain: string
+  /**
+   * Null when Core knows only the package name: a private miniapp whose server refused Core's token, or a private
+   * entry whose server hasn't admitted this caller.
+   */
+  name: string | null
+  version: string | null
+  ageRating: MiniappAgeRating | null
+  iconUrl: string | null
+  verification: MiniappRegistryVerification
+  /** Its server asks for sign-in. */
+  private: boolean
+  status: MiniappRegistryEntryStatus
+  /** ISO 8601. */
+  firstRegisteredAt: string
+  /** ISO 8601, or null when Core has never read it. */
+  lastVerifiedAt: string | null
+}
+
+/** Why a URL isn't a miniapp. */
+export const MINIAPP_REGISTRY_NOT_A_MINIAPP_REASONS = [
+  "invalid_manifest",
+  "domain_mismatch",
+  "not_https",
+  "local_network_url",
+] as const
+export type MiniappRegistryNotAMiniappReason = (typeof MINIAPP_REGISTRY_NOT_A_MINIAPP_REASONS)[number]
+
+/** What the phone read from the URL, sent with every registration. Core keeps it only when it can't read the URL. */
+export const RegistryReportedManifestSchema = z.object({
+  packageName: z.string().regex(MINIAPP_PACKAGE_NAME_PATTERN),
+  name: z
+    .string()
+    .max(MAX_NAME_LENGTH)
+    .refine((name) => name.trim().length > 0, "must not be blank"),
+  version: z.string().max(MAX_VERSION_LENGTH).regex(MINIAPP_VERSION_PATTERN),
+  /** Absent (or null) when the miniapp declares none. */
+  ageRating: z.enum(MINIAPP_AGE_RATINGS).nullish(),
+})
+export type RegistryReportedManifest = z.infer<typeof RegistryReportedManifestSchema>
+
+export const RegistryRegisterRequestSchema = z.object({
+  url: z.string().min(1).max(MAX_URL_LENGTH),
+  reported: RegistryReportedManifestSchema.optional(),
+})
+export type RegistryRegisterRequest = z.infer<typeof RegistryRegisterRequestSchema>
+
+const IsoTime = z.string().min(1)
+
+export const RegistryEntryViewSchema: z.ZodType<RegistryEntryView> = z.object({
+  url: z.string().min(1),
+  packageName: z.string().min(1),
+  registrableDomain: z.string().min(1),
+  name: z.string().nullable(),
+  version: z.string().nullable(),
+  ageRating: z.enum(MINIAPP_AGE_RATINGS).nullable(),
+  iconUrl: z.string().nullable(),
+  verification: z.enum(["verified", "phone_reported"]),
+  private: z.boolean(),
+  status: z.enum(["active", "archived"]),
+  firstRegisteredAt: IsoTime,
+  lastVerifiedAt: IsoTime.nullable(),
+})
+
+export type RegistryRegisterResponse =
+  | {result: "accepted"; entry: RegistryEntryView; manifest: ServedMiniappManifest}
+  | {result: "accepted_unverified"; entry: RegistryEntryView}
+  | {result: "not_a_miniapp"; reason: MiniappRegistryNotAMiniappReason}
+  | {result: "archived"}
+
+export const RegistryRegisterResponseSchema: z.ZodType<RegistryRegisterResponse> = z.discriminatedUnion("result", [
+  z.object({result: z.literal("accepted"), entry: RegistryEntryViewSchema, manifest: ServedMiniappManifestSchema}),
+  z.object({result: z.literal("accepted_unverified"), entry: RegistryEntryViewSchema}),
+  z.object({result: z.literal("not_a_miniapp"), reason: z.enum(MINIAPP_REGISTRY_NOT_A_MINIAPP_REASONS)}),
+  z.object({result: z.literal("archived")}),
+])
+
+export const RegistryStatusRequestSchema = z.object({
+  entries: z
+    .array(
+      z.object({
+        url: z.string().min(1).max(MAX_URL_LENGTH),
+        /** The installed version. */
+        version: z.string().min(1).max(MAX_VERSION_LENGTH),
+      }),
+    )
+    .max(MINIAPP_REGISTRY_STATUS_MAX_ENTRIES),
+})
+export type RegistryStatusRequest = z.infer<typeof RegistryStatusRequestSchema>
+
+/** `unknown`: the URL isn't in the registry, or isn't a miniapp URL. */
+export type MiniappRegistryUrlStatus = "active" | "archived" | "unknown"
+
+export interface RegistryStatusResponse {
+  /** One per requested entry, in order, with the URL as the phone sent it. */
+  statuses: Array<{url: string; status: MiniappRegistryUrlStatus}>
+  /** How long the answer stays valid, in seconds. */
+  validForSeconds: number
+}
+
+export const RegistryStatusResponseSchema: z.ZodType<RegistryStatusResponse> = z.object({
+  statuses: z.array(z.object({url: z.string(), status: z.enum(["active", "archived", "unknown"])})),
+  validForSeconds: z.number().int().positive(),
+})

package/src/miniapp-url.ts

@@ -0,0 +1,311 @@
+/**
+ * @fileoverview Miniapp URLs, and the package names each may serve.
+ *
+ * A miniapp URL is a base URL that serves `miniapp.json` and the files it names. A miniapp's package name is its
+ * identity, so a name may only be served from a domain that owns it: the URL's reversed registrable domain, plus at
+ * least one more part (`notes.example.com` may serve `com.example.*`). Core checks this when it verifies a
+ * registration and the engine checks it on every install and update, both from this one implementation.
+ *
+ * Registrable domains come from the Public Suffix List (tldts), private section included, as browsers use it to scope
+ * cookies, so each GitHub Pages user has their own namespace. Nobody owns names under an IP address, a local-network
+ * name, a suffix the list doesn't know (`.internal`, `.test`) or `.arpa`, so those have no registrable domain.
+ *
+ * Every input is parsed the same way on Bun and on Hermes, whose URL implementation has no IDN support: anything
+ * outside printable ASCII is refused, and IDN hosts are written in their `xn--` form.
+ */
+import {parse as parseDomain} from "tldts"
+import {z} from "zod"
+
+/** A public miniapp URL is HTTPS; a local-network one, on the developer's own network, may be HTTP. */
+export type MiniappHostKind = "public" | "local"
+
+export interface NormalizedMiniappUrl {
+  /** The canonical URL: lowercase scheme and host, no default port, a path that ends in `/`. */
+  url: string
+  /** The URL's hostname: lowercase, without a port or a trailing dot; an IPv6 address keeps its brackets. */
+  host: string
+  kind: MiniappHostKind
+}
+
+/** Package names: lowercase dot-separated parts that start with a letter, with no hyphens. */
+export const MINIAPP_PACKAGE_NAME_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/
+
+/** Apple's age categories, which `ageRating` in `miniapp.json` takes. */
+export const MINIAPP_AGE_RATINGS = ["4+", "9+", "13+", "16+", "18+"] as const
+export type MiniappAgeRating = (typeof MINIAPP_AGE_RATINGS)[number]
+
+/** `com.mentra.*` belongs to mentraglass.com, which Mentra owns; mentra.com is not Mentra's. */
+const MENTRA_PACKAGE_PREFIX = "com.mentra."
+const MENTRA_DOMAIN_PREFIX = "com.mentraglass"
+
+const MAX_URL_LENGTH = 2048
+const MAX_HOST_LENGTH = 253
+const PRINTABLE_ASCII = /^[\x21-\x7e]+$/
+const SCHEME_AND_AUTHORITY = /^https?:\/\/([^/?#]*)/i
+const HOST_CHARACTERS = /^[a-z0-9._:[\]-]+$/i
+const HOST_LABEL = /^[a-z0-9_-]{1,63}$/
+const PACKAGE_PART = /^[a-z][a-z0-9_]*$/
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/
+const IPV6_GROUP = /^[0-9a-f]{1,4}$/
+
+/**
+ * Normalize a miniapp URL, or answer null when it isn't one: lowercase the scheme and host, drop the default port and
+ * a trailing dot, and end the path in `/`. Credentials, a query and a fragment are refused. A public URL must be
+ * HTTPS; a local-network URL ({@link isLocalNetworkHost}) may be HTTP or HTTPS.
+ */
+export function normalizeMiniappUrl(input: string): NormalizedMiniappUrl | null {
+  const parsed = parseHttpUrl(input)
+  if (!parsed) return null
+  // Any `?` or `#` starts a query or a fragment, even an empty one.
+  if (/[?#]/.test(input)) return null
+  const kind: MiniappHostKind = isLocalCanonicalHost(parsed.host) ? "local" : "public"
+  if (kind === "public" && parsed.url.protocol !== "https:") return null
+  const port = parsed.url.port ? `:${parsed.url.port}` : ""
+  const path = parsed.url.pathname.endsWith("/") ? parsed.url.pathname : `${parsed.url.pathname}/`
+  return {url: `${parsed.url.protocol}//${parsed.host}${port}${path}`, host: parsed.host, kind}
+}
+
+/**
+ * The registrable domain of a host, from the Public Suffix List: `notes.example.com` is `example.com`, and
+ * `alice.github.io` is itself. Null for a public suffix, an IP address, a local-network name, a suffix the list
+ * doesn't know, `.arpa`, or anything that isn't a hostname.
+ */
+export function registrableDomain(host: string): string | null {
+  const canonical = canonicalHost(host)
+  return canonical ? registrableDomainOf(canonical) : null
+}
+
+/**
+ * The package-name prefix a host's domain owns: its reversed registrable domain, with each hyphen as an underscore
+ * (`notes.my-site.com` is `com.my_site`). Null when the host has no registrable domain, or when the domain can't map
+ * to package-name parts: a label that starts with a digit, or one with an underscore, which could collide with a
+ * mapped hyphen.
+ */
+export function packagePrefixForHost(host: string): string | null {
+  const canonical = canonicalHost(host)
+  return canonical ? packagePrefixOf(canonical) : null
+}
+
+/**
+ * The domain rule: whether a miniapp URL may serve this package name. The name must start with the prefix its host's
+ * domain owns ({@link packagePrefixForHost}) plus at least one more part, and `com.mentra.*` is served only from
+ * mentraglass.com. Only the host decides, so this also checks where a redirect ended, query and all. A URL that isn't
+ * public HTTPS serves no name: a local-network address has no domain to own one.
+ */
+export function isPackageNameAllowedForUrl(packageName: string, url: string): boolean {
+  if (typeof packageName !== "string" || !MINIAPP_PACKAGE_NAME_PATTERN.test(packageName)) return false
+  const parsed = parseHttpUrl(url)
+  if (!parsed || parsed.url.protocol !== "https:" || isLocalCanonicalHost(parsed.host)) return false
+  const prefix = packagePrefixOf(parsed.host)
+  if (!prefix) return false
+  if (packageName.startsWith(MENTRA_PACKAGE_PREFIX)) return prefix === MENTRA_DOMAIN_PREFIX
+  return packageName.startsWith(`${prefix}.`)
+}
+
+/**
+ * Whether a host is on the local network: `localhost` and `*.localhost`, `*.local` names, and loopback, private,
+ * link-local and shared (100.64.0.0/10) IPv4 addresses, and loopback, unique local and link-local IPv6 addresses,
+ * including IPv4 addresses mapped into IPv6. Takes a hostname, with or without IPv6 brackets.
+ */
+export function isLocalNetworkHost(host: string): boolean {
+  const canonical = canonicalHost(host)
+  return canonical !== null && isLocalCanonicalHost(canonical)
+}
+
+/** Parse an absolute HTTP or HTTPS URL without credentials, the same way on every runtime. */
+function parseHttpUrl(input: string): {url: URL; host: string} | null {
+  if (typeof input !== "string") return null
+  const value = input.trim()
+  if (value.length === 0 || value.length > MAX_URL_LENGTH) return null
+  // URL parsers differ on non-ASCII and on backslashes, so neither is accepted.
+  if (!PRINTABLE_ASCII.test(value) || value.includes("\\")) return null
+  const authority = SCHEME_AND_AUTHORITY.exec(value)
+  if (!authority || authority[1]!.includes("@")) return null
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return null
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null
+  if (url.username || url.password) return null
+  const host = canonicalHostname(url.hostname)
+  return host ? {url, host} : null
+}
+
+/** A hostname given on its own, canonicalized as a URL's would be: `127.1` is `127.0.0.1`. */
+function canonicalHost(host: string): string | null {
+  if (typeof host !== "string" || !HOST_CHARACTERS.test(host)) return null
+  const candidate = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host
+  let url: URL
+  try {
+    url = new URL(`http://${candidate}/`)
+  } catch {
+    return null
+  }
+  // A port, or anything else that isn't part of the hostname.
+  if (url.host !== url.hostname) return null
+  return canonicalHostname(url.hostname)
+}
+
+/** A URL's hostname, lowercase, without a trailing dot, and with each label checked. */
+function canonicalHostname(hostname: string): string | null {
+  let host = hostname.toLowerCase()
+  if (host.startsWith("[")) return host.endsWith("]") && parseIpv6(host.slice(1, -1)) ? host : null
+  if (host.endsWith(".")) host = host.slice(0, -1)
+  if (host.length === 0 || host.length > MAX_HOST_LENGTH) return null
+  if (IPV4.test(host)) return parseIpv4(host) ? host : null
+  const valid = host
+    .split(".")
+    .every((label) => HOST_LABEL.test(label) && !label.startsWith("-") && !label.endsWith("-"))
+  return valid ? host : null
+}
+
+function isLocalCanonicalHost(host: string): boolean {
+  if (host.startsWith("[")) {
+    const words = parseIpv6(host.slice(1, -1))
+    return words !== null && isLocalIpv6(words)
+  }
+  const ipv4 = parseIpv4(host)
+  if (ipv4) return isLocalIpv4(ipv4)
+  return host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")
+}
+
+function registrableDomainOf(host: string): string | null {
+  if (host.startsWith("[") || parseIpv4(host) || isLocalCanonicalHost(host)) return null
+  const parsed = parseDomain(host, {allowPrivateDomains: true})
+  if (parsed.hostname !== host || !parsed.domain || !parsed.publicSuffix) return null
+  // A suffix the list doesn't know matches only its implicit `*` rule; nobody owns names under it.
+  if (!parsed.isIcann && !parsed.isPrivate) return null
+  if (parsed.publicSuffix === "arpa" || parsed.publicSuffix.endsWith(".arpa")) return null
+  return parsed.domain
+}
+
+function packagePrefixOf(host: string): string | null {
+  const domain = registrableDomainOf(host)
+  if (!domain) return null
+  const parts: string[] = []
+  for (const label of domain.split(".").reverse()) {
+    if (label.includes("_")) return null
+    const part = label.replace(/-/g, "_")
+    if (!PACKAGE_PART.test(part)) return null
+    parts.push(part)
+  }
+  return parts.join(".")
+}
+
+function parseIpv4(text: string): number[] | null {
+  const match = IPV4.exec(text)
+  if (!match) return null
+  const octets = match.slice(1).map((octet) => (/^(0|[1-9]\d*)$/.test(octet!) ? Number(octet) : 256))
+  return octets.every((octet) => octet <= 255) ? octets : null
+}
+
+function isLocalIpv4([a, b]: number[]): boolean {
+  return (
+    a === 10 ||
+    a === 127 ||
+    (a === 172 && b! >= 16 && b! <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 169 && b === 254) ||
+    (a === 100 && b! >= 64 && b! <= 127)
+  )
+}
+
+/** Eight 16-bit words, from an IPv6 address without brackets. */
+function parseIpv6(text: string): number[] | null {
+  const halves = text.toLowerCase().split("::")
+  if (halves.length > 2) return null
+  const compressed = halves.length === 2
+  const head = parseIpv6Groups(halves[0]!, !compressed)
+  const tail = compressed ? parseIpv6Groups(halves[1]!, true) : []
+  if (!head || !tail) return null
+  if (!compressed) return head.length === 8 ? head : null
+  const missing = 8 - head.length - tail.length
+  return missing >= 1 ? [...head, ...new Array<number>(missing).fill(0), ...tail] : null
+}
+
+/** IPv6 groups; the last group of the address may be a dotted IPv4 address. */
+function parseIpv6Groups(part: string, endsAddress: boolean): number[] | null {
+  if (part === "") return []
+  const groups = part.split(":")
+  const words: number[] = []
+  for (let index = 0; index < groups.length; index += 1) {
+    const group = groups[index]!
+    if (endsAddress && index === groups.length - 1 && group.includes(".")) {
+      const ipv4 = parseIpv4(group)
+      if (!ipv4) return null
+      words.push((ipv4[0]! << 8) | ipv4[1]!, (ipv4[2]! << 8) | ipv4[3]!)
+    } else if (IPV6_GROUP.test(group)) {
+      words.push(parseInt(group, 16))
+    } else {
+      return null
+    }
+  }
+  return words
+}
+
+function isLocalIpv6(words: number[]): boolean {
+  const first = words[0]!
+  const isLoopback = words.slice(0, 7).every((word) => word === 0) && words[7] === 1
+  const isUniqueLocal = (first & 0xfe00) === 0xfc00
+  const isLinkLocal = (first & 0xffc0) === 0xfe80
+  const isMappedIpv4 = words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff
+  if (isMappedIpv4) return isLocalIpv4([words[6]! >> 8, words[6]! & 0xff, words[7]! >> 8, words[7]! & 0xff])
+  return isLoopback || isUniqueLocal || isLinkLocal
+}
+
+/** SemVer 2.0.0 (semver.org): `1.4.2`, `1.4.2-beta.1`; not `v1.4.2` or `1.4`. The `version` of a served `miniapp.json`. */
+export const MINIAPP_VERSION_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+
+/** What a miniapp URL serves at `<url>/miniapp.json`: the manifest inside its current ZIP, plus `bundle`. */
+export interface ServedMiniappManifest {
+  packageName: string
+  version: string
+  name: string
+  description?: string
+  /** Relative to the miniapp URL, or an absolute URL. */
+  icon?: string
+  /** Absent: the Mentra App's own rating, so the miniapp is never age-gated. */
+  ageRating?: MiniappAgeRating
+  sdkVersion?: string
+  minHostVersion?: string
+  hardwareRequirements?: Array<{type: string; level: string; description?: string}>
+  /** The directory's listing; the phone ignores it, so it isn't checked here. */
+  listing?: unknown
+  /** The ZIP: its URL, relative to the miniapp URL or absolute, and its SHA-256, in lowercase hex. */
+  bundle: {url: string; sha256: string}
+}
+
+const NonBlankString = z.string().refine((value) => value.trim().length > 0, "must not be blank")
+
+/**
+ * The served `miniapp.json`. Fields this schema doesn't name, such as `entry` and `permissions`, are kept as served;
+ * the engine checks them in the ZIP's own copy when it installs.
+ */
+export const ServedMiniappManifestSchema: z.ZodType<ServedMiniappManifest> = z
+  .object({
+    packageName: z.string().regex(MINIAPP_PACKAGE_NAME_PATTERN),
+    version: z.string().regex(MINIAPP_VERSION_PATTERN),
+    name: NonBlankString,
+    description: z.string().optional(),
+    icon: NonBlankString.optional(),
+    ageRating: z.enum(MINIAPP_AGE_RATINGS).optional(),
+    sdkVersion: NonBlankString.optional(),
+    minHostVersion: NonBlankString.optional(),
+    hardwareRequirements: z
+      .array(z.object({type: z.string(), level: z.string(), description: z.string().optional()}).passthrough())
+      .optional(),
+    listing: z.unknown(),
+    bundle: z
+      .object({
+        url: NonBlankString,
+        sha256: z
+          .string()
+          .regex(/^[0-9a-fA-F]{64}$/)
+          .transform((sha256) => sha256.toLowerCase()),
+      })
+      .passthrough(),
+  })
+  .passthrough()