@mentra/cloud-client 0.1.0-beta.0

package/src/modules/auth/jwt.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Read the claims out of a JWT without verifying its signature.
+ *
+ * The client is not a security boundary for its own token: the cloud verifies
+ * the signature on every call. So here we only need to read claims the client
+ * already trusts (its own `mentraUserId`, `tenant_id`, and `exp` for the refresh
+ * timing), and we deliberately skip signature checks. Doing a real verification
+ * would mean shipping the cloud's public keys to the device, which buys nothing.
+ *
+ * See docs/issues/004-cloud-client/design.md ("cloud.auth", identity) and
+ * docs/issues/001-cloud-core/auth/spec.md (access-token claims).
+ */
+
+/**
+ * The claims this client reads off an access token.
+ *
+ * `sub` is the `mentraUserId`, `tenant_id` is the issuing OEM, and `exp` is the
+ * Unix-seconds expiry used to decide when to refresh. The index signature keeps
+ * the rest of the claims (`sessionId`, `jti`, `aud`, `iss`) accessible without
+ * naming each one, since the client only acts on these three.
+ */
+export interface JwtClaims {
+  sub: string;
+  tenant_id: string;
+  exp: number;
+  [k: string]: unknown;
+}
+
+/**
+ * Decode one base64url segment to a UTF-8 string.
+ *
+ * JWT segments are base64url (with `-`/`_` and no padding), which `atob` does
+ * not accept directly, so we translate to standard base64 and re-pad first. We
+ * avoid Node's `Buffer` on purpose: this code also runs on the phone (React
+ * Native / Hermes), where `Buffer` is not guaranteed but `atob` is. We then
+ * rebuild the UTF-8 bytes by hand because `atob` yields a binary (latin1)
+ * string, so a multi-byte claim value (a non-ASCII display name, say) would be
+ * mangled if read directly.
+ */
+function decodeBase64UrlToUtf8(segment: string): string {
+  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  // Re-pad to a multiple of 4 so `atob` accepts the input.
+  const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  // TextDecoder exists on both a modern phone and a modern server, and turns the
+  // raw bytes back into a proper UTF-8 string.
+  return new TextDecoder().decode(bytes);
+}
+
+/**
+ * Pull the claims out of a JWT's payload segment.
+ *
+ * A JWT is three dot-separated base64url segments (`header.payload.signature`);
+ * the claims live in the middle one. We throw a plain `Error` on a malformed
+ * token rather than returning a partial object, so a caller never acts on
+ * half-decoded identity.
+ */
+export function decodeClaims(jwt: string): JwtClaims {
+  const segments = jwt.split(".");
+  if (segments.length < 2) {
+    throw new Error("decodeClaims: not a JWT (expected at least two segments)");
+  }
+
+  let claims: unknown;
+  try {
+    claims = JSON.parse(decodeBase64UrlToUtf8(segments[1]!));
+  } catch {
+    // Either the segment is not valid base64url or the payload is not JSON.
+    throw new Error("decodeClaims: JWT payload is not valid base64url JSON");
+  }
+
+  if (typeof claims !== "object" || claims === null) {
+    throw new Error("decodeClaims: JWT payload is not an object");
+  }
+
+  return claims as JwtClaims;
+}

package/src/modules/auth/token-store.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Token state for `cloud.auth`: the in-memory access token, the
+ * persisted refresh token, and a single-flight lock.
+ *
+ * Split out from `auth.ts` so the storage details and the de-duplication lock
+ * live in one place. Two facts drive the design:
+ *
+ *  - Only the refresh token is persisted (through the injected `KeyValueStore`),
+ *    so a relaunch can re-mint an access token without a fresh login. The access
+ *    token stays in memory: it is short-lived (~1h) and re-derivable.
+ *  - Refreshes and miniapp-token mints must be de-duplicated. A reconnect storm
+ *    can ask for a token from many callers at once; without the lock, each would
+ *    fire its own `/refresh` and the rotation would invalidate the others'.
+ *
+ * Security: the access token is never written to storage and neither token is
+ * ever logged.
+ *
+ * See docs/issues/004-cloud-client/design.md ("cloud.auth").
+ */
+import type { KeyValueStore } from "../../transports";
+import { decodeClaims } from "./jwt";
+
+/**
+ * Storage key for the persisted refresh token.
+ *
+ * Namespaced so it cannot collide with anything else a host keeps in the same
+ * secure store.
+ */
+const REFRESH_TOKEN_KEY = "mentra.cloud-client.refreshToken";
+
+/** The access token plus its Unix-seconds expiry, held in memory only. */
+interface AccessTokenState {
+  accessToken: string;
+  exp: number;
+}
+
+export class TokenStore {
+  private readonly storage: KeyValueStore;
+
+  /** The current access token, or null before the first exchange/refresh. */
+  private access: AccessTokenState | null = null;
+
+  /**
+   * In-flight operations keyed by a caller-chosen string.
+   *
+   * Holding the promise (not just a boolean) lets every concurrent caller await
+   * the same result, which is the whole point of single-flight here.
+   */
+  private readonly inFlight = new Map<string, Promise<unknown>>();
+
+  constructor(deps: { storage: KeyValueStore }) {
+    this.storage = deps.storage;
+  }
+
+  /**
+   * The current in-memory access token and its expiry, or null if none.
+   *
+   * Synchronous because the access token never round-trips through storage; the
+   * caller (auth) decides whether it is still fresh using `exp`.
+   */
+  current(): AccessTokenState | null {
+    return this.access;
+  }
+
+  /**
+   * Record a freshly exchanged or refreshed token pair.
+   *
+   * The access token is decoded for its `exp` so callers can check freshness
+   * without re-parsing; the refresh token is persisted so it survives a
+   * relaunch. We read `exp` here (rather than in the caller) to keep all the
+   * token-state bookkeeping in one place.
+   */
+  async save(tokens: { accessToken: string; refreshToken: string }): Promise<void> {
+    this.access = {
+      accessToken: tokens.accessToken,
+      exp: decodeClaims(tokens.accessToken).exp,
+    };
+    await this.storage.set(REFRESH_TOKEN_KEY, tokens.refreshToken);
+  }
+
+  /**
+   * The persisted refresh token, or null if none has ever been saved.
+   *
+   * Read from storage every time (not cached) so a token rotated by another
+   * process or restored out of band is always the one used.
+   */
+  refreshToken(): Promise<string | null> {
+    return this.storage.get(REFRESH_TOKEN_KEY);
+  }
+
+  /**
+   * Drop only the in-memory access token, keeping the persisted refresh token.
+   *
+   * Called when the cloud rejects an access token the store still believes is
+   * fresh (clock skew, or a mid-session revoke surfaced as AUTH_EXPIRED): the
+   * next `current()` returns null so the caller refreshes against the still-good
+   * refresh token, rather than handing back the rejected token again.
+   */
+  invalidateAccess(): void {
+    this.access = null;
+  }
+
+  /**
+   * Clear all token state, in memory and in storage.
+   *
+   * Called when the refresh token is dead, so a later attempt does not keep
+   * presenting a known-bad token to the cloud.
+   */
+  async clear(): Promise<void> {
+    this.access = null;
+    await this.storage.delete(REFRESH_TOKEN_KEY);
+  }
+
+  /**
+   * Run `fn` once even if several callers ask for the same `key` at the same
+   * time, handing all of them the single result.
+   *
+   * The entry is removed once the work settles (whether it resolves or rejects)
+   * so the next call after completion starts fresh rather than replaying a stale
+   * promise. A rejection propagates to every waiter, which is correct: if a
+   * refresh failed, all callers waiting on it should see that failure.
+   */
+  singleFlight<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const existing = this.inFlight.get(key);
+    if (existing) return existing as Promise<T>;
+
+    const promise = (async () => {
+      try {
+        return await fn();
+      } finally {
+        this.inFlight.delete(key);
+      }
+    })();
+
+    this.inFlight.set(key, promise);
+    return promise;
+  }
+}

package/src/modules/core/core.ts

@@ -0,0 +1,202 @@
+/**
+ * @fileoverview `cloud.core`: the device's stateless v2 REST calls.
+ *
+ * This is the simplest module: no live connection and no session state, so any
+ * cloud pod can serve any call here. Each request goes through the shared HTTP
+ * helper, which attaches the access token from `cloud.auth` as the Bearer, so
+ * core never touches credentials itself.
+ *
+ * Today it exposes the miniapp lookups the device needs at launch plus the
+ * unified report submission surface. It is meant to grow as miniapp-service and
+ * other core resources are specced.
+ *
+ * Guardrail: this is device-facing only. It deliberately carries none of the
+ * Dev Console / OEM Portal / store web UI surface; those are separate clients.
+ *
+ * See docs/issues/004-cloud-client/spec.md ("cloud.core") and design.md
+ * ("src/modules/core/core.ts").
+ */
+import type { HttpClient } from "../../http";
+import {
+  Reports,
+  type AddReportArtifactsResult,
+  type ReportAttachmentInput,
+  type ReportLogEntry,
+  type ReportStatus,
+  type SubmitReportInput,
+  type SubmitReportResult,
+} from "./reports";
+
+export type {
+  AddReportArtifactsResult,
+  ReportAttachmentInput,
+  ReportContext,
+  ReportDetails,
+  ReportKind,
+  ReportLogEntry,
+  ReportStatus,
+  ReportSystemPriority,
+  ReportTrigger,
+  SubmitReportInput,
+  SubmitReportResult,
+} from "./reports";
+
+/**
+ * A single miniapp entry as returned by the listing.
+ *
+ * These shapes are owned by miniapp-service, which is not finalized yet, so they
+ * are defined here against the spec rather than imported. They are intentionally
+ * NOT taken from `@mentra/cloud-protocol`: that package is the live
+ * session wire contract (subscriptions, transcripts, the message unions), while
+ * a miniapp listing is a core REST resource with no place on the runtime wire.
+ * When miniapp-service locks its schema, move these to the shared package and
+ * import them here instead.
+ */
+export interface MiniappListing {
+  /** The reverse-DNS identifier, for example "com.example.notes". */
+  packageName: string;
+  /** Human-readable name shown to the user. */
+  name: string;
+  /** The version offered to this user (the latest the user is entitled to). */
+  version: string;
+  /** Optional one-line summary for a launcher list. */
+  description?: string;
+  /** Optional icon URL for a launcher list. */
+  iconUrl?: string;
+}
+
+/**
+ * The manifest that ships inside a miniapp bundle.
+ *
+ * Same ownership note as `MiniappListing`: this is a miniapp-service shape,
+ * defined here against the spec until that schema is locked. The fields below
+ * are the minimum the device needs to identify and describe a fetched bundle;
+ * miniapp-service is expected to add permission and capability declarations.
+ */
+export interface MiniappManifest {
+  packageName: string;
+  name: string;
+  version: string;
+  /** Optional permissions the miniapp declares it needs. */
+  permissions?: string[];
+}
+
+/** What `getBundle` resolves to: where to download the bundle, plus its manifest. */
+export interface MiniappBundle {
+  /** A (typically signed, short-lived) URL the device downloads the bundle from. */
+  downloadUrl: string;
+  /** The concrete version resolved, important when the caller omitted `version`. */
+  version: string;
+  manifest: MiniappManifest;
+}
+
+export type PreinstalledInstallPolicy =
+  | "install_once"
+  | "keep_updated"
+  | "mandatory";
+
+export interface PreinstalledMiniappRegistryEntry {
+  packageName: string;
+  version: string;
+  bundleUrl: string;
+  bundleSha256: string;
+  required: boolean;
+  installPolicy: PreinstalledInstallPolicy;
+  channel: string;
+  minMobileVersion?: string;
+  maxMobileVersion?: string;
+  tenantId?: string;
+}
+
+export interface PreinstalledMiniappRegistry {
+  generatedAt: string;
+  entries: PreinstalledMiniappRegistryEntry[];
+}
+
+/** The dependencies `cloud.core` is wired with. */
+export interface CoreDeps {
+  http: HttpClient;
+}
+
+/**
+ * `cloud.core`. Stateless REST grouped by resource (only `miniapps` so far).
+ *
+ * The grouping is exposed as a plain object so callers write
+ * `cloud.core.miniapps.list()`, matching the public `CoreModule` contract in the
+ * spec. Methods are bound in the constructor so destructuring `miniapps` keeps
+ * working.
+ */
+export class Core {
+  readonly miniapps: {
+    list(): Promise<MiniappListing[]>;
+    getBundle(packageName: string, version?: string): Promise<MiniappBundle>;
+    getRegistry(opts?: { environment?: string }): Promise<PreinstalledMiniappRegistry>;
+  };
+  readonly reports: {
+    submit(input: SubmitReportInput): Promise<SubmitReportResult>;
+    addLogs(
+      reportId: string,
+      source: string,
+      entries: ReportLogEntry[],
+    ): Promise<AddReportArtifactsResult>;
+    addScreenshots(
+      reportId: string,
+      images: ReportAttachmentInput[],
+    ): Promise<AddReportArtifactsResult>;
+    complete(reportId: string): Promise<{ status: ReportStatus }>;
+  };
+
+  constructor(deps: CoreDeps) {
+    const { http } = deps;
+    const reports = new Reports({ http });
+
+    this.miniapps = {
+      /**
+       * List the miniapps available to the authenticated user.
+       *
+       * A GET so it is naturally safe to retry on a transient network error,
+       * which the shared HTTP helper does for us.
+       */
+      list(): Promise<MiniappListing[]> {
+        return http.get<MiniappListing[]>("/api/client/miniapps");
+      },
+
+      /**
+       * Fetch the downloadable bundle for one miniapp.
+       *
+       * When `version` is omitted the cloud resolves the version the user is
+       * entitled to (usually the latest); the resolved value comes back in the
+       * response so the caller can record exactly what it got. The version is
+       * passed as a query parameter and URL-encoded so an unusual version string
+       * cannot break the path.
+       */
+      getBundle(packageName: string, version?: string): Promise<MiniappBundle> {
+        const base = `/api/client/miniapps/${encodeURIComponent(packageName)}/bundle`;
+        const path =
+          version === undefined
+            ? base
+            : `${base}?version=${encodeURIComponent(version)}`;
+        return http.get<MiniappBundle>(path);
+      },
+
+      /**
+       * Fetch the admin-managed preinstalled miniapp registry for this device.
+       *
+       * The mobile client owns reconciliation: Core only returns the desired
+       * bundle versions and install policy for the current user/OEM/channel.
+       */
+      getRegistry(opts?: { environment?: string }): Promise<PreinstalledMiniappRegistry> {
+        const query = opts?.environment
+          ? `?environment=${encodeURIComponent(opts.environment)}`
+          : "";
+        return http.get<PreinstalledMiniappRegistry>(`/api/client/miniapps/registry${query}`);
+      },
+    };
+    this.reports = {
+      submit: reports.submit.bind(reports),
+      addLogs: reports.addLogs.bind(reports),
+      addScreenshots: reports.addScreenshots.bind(reports),
+      complete: reports.complete.bind(reports),
+    };
+  }
+}

package/src/modules/core/reports.ts

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Cloud V2 user/system reporting API.
+ *
+ * A report is the single device-facing primitive for manual bug reports,
+ * feature/general feedback, and automatic runtime reports. The engine supplies
+ * diagnostic context and artifacts; host UI supplies only user-visible content.
+ */
+
+import type { HttpClient } from "../../http";
+
+const REPORTS_PATH = "/api/client/reports";
+
+export type ReportKind = "bug" | "feedback" | "automatic";
+export type ReportStatus = "collecting" | "ready" | "closed";
+export type ReportSystemPriority = "low" | "medium" | "high" | "critical";
+
+interface BaseReportTrigger {
+  source: string;
+  reason: string;
+  sourceAppletPackageName?: string;
+  sourceAppletName?: string;
+}
+
+export type ReportTrigger =
+  | (BaseReportTrigger & { type: "manual" })
+  | (BaseReportTrigger & { type: "automatic" });
+
+export interface ReportDetails {
+  actualBehavior: string;
+  expectedBehavior?: string;
+  userSeverity?: 1 | 2 | 3 | 4 | 5;
+  systemPriority?: ReportSystemPriority;
+  contactEmail?: string;
+}
+
+export interface ReportContext extends Record<string, unknown> {
+  app?: Record<string, unknown>;
+  phone?: Record<string, unknown>;
+  glasses?: Record<string, unknown>;
+  runtime?: Record<string, unknown>;
+  apps?: Record<string, unknown>;
+  settings?: Record<string, unknown>;
+}
+
+export type SubmitReportInput =
+  | {
+      kind: "bug";
+      trigger: ReportTrigger;
+      report: ReportDetails;
+      context: ReportContext;
+    }
+  | {
+      kind: "automatic";
+      trigger: Extract<ReportTrigger, { type: "automatic" }>;
+      report: ReportDetails;
+      context: ReportContext;
+    }
+  | {
+      kind: "feedback";
+      feedback: string | Record<string, unknown>;
+      context: ReportContext;
+    };
+
+export interface SubmitReportResult {
+  reportId: string;
+  status: ReportStatus;
+}
+
+export interface ReportLogEntry {
+  timestamp: number;
+  level: string;
+  message: string;
+  source?: string;
+}
+
+export interface ReportAttachmentInput {
+  uri?: string;
+  fileName?: string | null;
+  mimeType?: string | null;
+  blob?: Blob;
+}
+
+export interface AddReportArtifactsResult {
+  stored: number;
+}
+
+export interface ReportsDeps {
+  http: HttpClient;
+}
+
+export class Reports {
+  private readonly http: HttpClient;
+
+  constructor(deps: ReportsDeps) {
+    this.http = deps.http;
+  }
+
+  submit(input: SubmitReportInput): Promise<SubmitReportResult> {
+    return this.http.post<SubmitReportResult>(REPORTS_PATH, input);
+  }
+
+  async addLogs(
+    reportId: string,
+    source: string,
+    entries: ReportLogEntry[],
+  ): Promise<AddReportArtifactsResult> {
+    return await this.http.post<AddReportArtifactsResult>(
+      `${REPORTS_PATH}/${encodeURIComponent(reportId)}/artifacts`,
+      {
+        type: "logs",
+        source,
+        entries,
+      },
+    );
+  }
+
+  addScreenshots(
+    reportId: string,
+    images: ReportAttachmentInput[],
+  ): Promise<AddReportArtifactsResult> {
+    const form = new FormData();
+    form.append("type", "screenshot");
+    form.append("source", "phone");
+    for (const image of images) {
+      const filename = image.fileName || `screenshot-${Date.now()}.jpg`;
+      const mimeType = image.mimeType || "image/jpeg";
+      if (image.blob) {
+        form.append("files", image.blob, filename);
+        continue;
+      }
+      if (!image.uri) {
+        throw new Error("report screenshot requires either blob or uri");
+      }
+      form.append("files", {
+        uri: image.uri,
+        name: filename,
+        type: mimeType,
+      } as unknown as Blob);
+    }
+
+    return this.http.postForm<AddReportArtifactsResult>(
+      `${REPORTS_PATH}/${encodeURIComponent(reportId)}/artifacts`,
+      form,
+    );
+  }
+
+  complete(reportId: string): Promise<{ status: ReportStatus }> {
+    return this.http.post<{ status: ReportStatus }>(
+      `${REPORTS_PATH}/${encodeURIComponent(reportId)}/complete`,
+      {},
+    );
+  }
+}