@glassly/cloud-client 0.1.0-dev.0 → 0.1.0-dev.100

package/package.json

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

package/src/client.ts

@@ -22,9 +22,8 @@ import { CloudClientError } from "./errors";
 import type { ConnectionInit } from "@glassly/cloud-protocol";
 import { systemTimers } from "./timers";
 
-// The module implementations. Each is owned by another agent under ./modules/**;
-// this file only constructs them, matching the constructor signatures fixed in
-// design.md exactly.
+// The module implementations, under ./modules/**. This file only constructs
+// them, matching the constructor signatures fixed in design.md exactly.
 import { Auth } from "./modules/auth/auth";
 import { TokenStore } from "./modules/auth/token-store";
 import { Runtime } from "./modules/runtime/runtime";
@@ -51,12 +50,12 @@ import { Core } from "./modules/core/core";
 const DEFAULT_RECONNECT = { baseMs: 500, maxMs: 5_000, jitter: true };
 
 /**
- * The default audio codec the client announces in the handshake.
+ * The default audio codec the client announces in the handshake when a host
+ * does not set `config.audio.codec`.
  *
- * LC3 at 16 kHz matches the glasses' on-device codec, so the cloud transcribes
- * the same bytes the device captures. A future config knob can override this; for
- * now the handshake announces the device default so audio that starts immediately
- * after connect is decoded correctly.
+ * PCM at 16 kHz needs no frame-size negotiation, so it is the safe default; a
+ * host whose device captures LC3 sets `config.audio.codec = "lc3"` (and the
+ * required `frameSizeBytes`) explicitly.
  */
 const DEFAULT_AUDIO_CODEC = "pcm" as const;
 const DEFAULT_AUDIO_SAMPLE_RATE = 16_000;

package/src/errors.ts

@@ -52,3 +52,20 @@ export class AuthExpiredError extends CloudClientError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
+
+/**
+ * A token endpoint DEFINITIVELY rejected the presented credential — the RFC
+ * `invalid_grant` shape or an authorization-level 401. Only this proves a
+ * stored token is dead. Network failures, 5xx, 429, and other 400 shapes are
+ * transient: throwing anything else must never cost the stored session
+ * (clearing tokens on a flaky cold boot is how users get logged out by an
+ * app update). Subclasses `AuthExpiredError` so hosts catching the broad
+ * "re-auth required" case keep working.
+ */
+export class AuthRejectedError extends AuthExpiredError {
+  constructor(message = "Credential rejected by the token endpoint; re-auth required") {
+    super(message);
+    this.name = "AuthRejectedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/index.ts

@@ -35,7 +35,7 @@ export type {
 export type { CloudClientTimers } from "./timers";
 
 // Local error types a host can branch on with `instanceof`.
-export { CloudClientError, HttpError, AuthExpiredError } from "./errors";
+export { CloudClientError, HttpError, AuthExpiredError, AuthRejectedError } from "./errors";
 
 // The logging hook a host can implement to route library logs.
 export { noopLogger } from "./logger";

package/src/modules/auth/auth.ts

@@ -14,10 +14,14 @@
  *  - Exchange, refresh, and each per-miniapp mint are single-flighted, so a
  *    reconnect storm cannot fire a burst of competing requests (and a rotated
  *    refresh token cannot be invalidated out from under a concurrent caller).
- *  - If a refresh fails and the host can fetch a fresh subject token on demand,
- *    we clear the dead refresh token and exchange once. If no fresh subject is
- *    available (or exchange also fails), `onExpired` fires once and the host
+ *  - If a refresh is DEFINITIVELY rejected (`invalid_grant` / 401) and the
+ *    host can fetch a fresh subject token on demand, we clear the dead
+ *    refresh token and exchange once. If no fresh subject is available (or
+ *    the exchange is itself rejected), `onExpired` fires once and the host
  *    re-authenticates. We do not retry forever against a dead refresh token.
+ *    Transient failures — network errors, 5xx, 429 — never clear stored
+ *    tokens and never fire `onExpired`: a flaky cold boot (first launch
+ *    after an app update) must not cost a healthy session.
  *
  * Security: the access token is never written to storage, never given to a
  * miniapp, and no token is ever logged.
@@ -34,7 +38,7 @@ import type {
 import type { HttpClient } from "../../http";
 import type { Logger } from "../../logger";
 import type { HttpTransport } from "../../transports";
-import { AuthExpiredError } from "../../errors";
+import { AuthExpiredError, AuthRejectedError, HttpError } from "../../errors";
 import { decodeClaims } from "./jwt";
 import { TokenStore } from "./token-store";
 
@@ -329,12 +333,23 @@ export class Auth implements AuthModule {
       try {
         return await this.refresh(refreshToken, { deferExpired: this.canExchangeFreshSubject() });
       } catch (err) {
-        if (this.canExchangeFreshSubject()) {
-          this.logger.info("refresh failed; exchanging fresh subject token");
+        // Only a DEFINITIVE rejection warrants burning the session and
+        // minting a new one through the subject-token fallback. A transient
+        // failure (network down at cold boot, core mid-deploy) keeps the
+        // stored refresh token; the caller's next attempt retries with it.
+        if (err instanceof AuthExpiredError && this.canExchangeFreshSubject()) {
+          this.logger.info("refresh rejected; exchanging fresh subject token");
           try {
             return await this.exchange();
-          } catch {
-            this.fireExpired();
+          } catch (exchangeErr) {
+            // The exchange itself was rejected → credentials are truly dead.
+            // A transient exchange failure (getSubjectToken offline, POST
+            // failed) must NOT declare the session expired — the refresh
+            // token was already cleared, but the host's account session is
+            // intact and the next attempt re-exchanges.
+            if (exchangeErr instanceof AuthRejectedError) {
+              this.fireExpired();
+            }
           }
         }
         throw err;
@@ -389,11 +404,16 @@ export class Auth implements AuthModule {
    * Refresh near expiry: trade the stored refresh token for a new access token
    * and a rotated refresh token, saving both.
    *
-   * On failure (the refresh token is dead or revoked) we clear stored state.
-   * The caller either falls back to one fresh subject-token exchange (for
-   * on-demand subject-token configs) or fires `onExpired` once and surfaces an
-   * `AuthExpiredError`. We do not retry refresh forever: a dead refresh token
-   * will not heal on its own, and retrying would loop.
+   * Only a DEFINITIVE rejection (`invalid_grant` / 401) clears stored state:
+   * the caller then either falls back to one fresh subject-token exchange
+   * (for on-demand subject-token configs) or fires `onExpired` once and
+   * surfaces an `AuthExpiredError`. We do not retry a rejected refresh: a
+   * dead refresh token will not heal on its own, and retrying would loop.
+   *
+   * A transient failure — network error, 5xx during a deploy, 429 — keeps
+   * the stored token and propagates as-is: clearing on a transient failure
+   * would log out a perfectly healthy session on a flaky cold start (e.g.
+   * first launch after an app update).
    */
   private async refresh(refreshToken: string, opts?: { deferExpired?: boolean }): Promise<string> {
     const body = new URLSearchParams({
@@ -404,14 +424,17 @@ export class Auth implements AuthModule {
     let tokens: TokenResponse;
     try {
       tokens = await this.postForm(REFRESH_PATH, body, "refresh");
-    } catch {
-      // The refresh token is unusable: drop it so we do not keep presenting a
-      // known-bad token.
+    } catch (err) {
+      if (!(err instanceof AuthRejectedError)) {
+        throw err; // transient: the stored token may well still be good
+      }
+      // The refresh token is definitively unusable: drop it so we do not keep
+      // presenting a known-bad token.
       await this.store.clear();
       if (!opts?.deferExpired) {
         this.fireExpired();
       }
-      throw new AuthExpiredError("token refresh failed; re-auth required");
+      throw new AuthExpiredError("token refresh rejected; re-auth required");
     }
 
     await this.store.save({
@@ -504,11 +527,23 @@ export class Auth implements AuthModule {
     });
 
     if (!res.ok) {
-      // The body may carry an RFC `{ error, error_description }`, but we keep the
-      // thrown detail to the status + label so no token field can leak into a
-      // message a host might surface. The caller maps this to re-auth.
-      this.logger.warn("auth token request failed", { label, status: res.status });
-      throw new AuthExpiredError(`${label} request failed with status ${res.status}`);
+      // The body may carry an RFC `{ error, error_description }`; read only the
+      // machine code so no token field can leak into a message a host might
+      // surface. Only `invalid_grant` (or an authorization-level 401) proves
+      // the presented credential is dead — anything else (5xx during a deploy,
+      // 429, a malformed-request 400) is transient and must not cost the
+      // stored session.
+      let code: string | undefined;
+      try {
+        code = ((await res.json()) as { error?: string })?.error;
+      } catch {
+        // Non-JSON body (proxy error page); status alone decides.
+      }
+      this.logger.warn("auth token request failed", { label, status: res.status, code });
+      if (res.status === 401 || (res.status === 400 && code === "invalid_grant")) {
+        throw new AuthRejectedError(`${label} rejected with status ${res.status}`);
+      }
+      throw new HttpError(`${label} request failed with status ${res.status}`, res.status, code);
     }
 
     return (await res.json()) as TokenResponse;

package/src/modules/runtime/connection.ts

@@ -12,30 +12,14 @@
  * It never imports a real socket: the platform supplies a `WebSocketLike`
  * factory, so the same code runs on the phone and in a Node/Bun test harness.
  *
- * Reconnect robustness (why the loop is self-sustaining + watchdogged):
- * The reconnect loop used to be driven ONLY by the socket's `onClose` event
- * (`handleClose` -> `scheduleReconnect`), and a scheduled attempt's
- * `connectOnce().catch()` just swallowed the rejection, trusting that a close
- * event would always fire and schedule the next try. That assumption is the
- * bug: a connect attempt can fail WITHOUT ever firing a clean `onClose` -- a
- * transient network/DNS blip mid-handshake, or a `WebSocketLike` transport that
- * emits only `onError` and no `onClose`. When that happens the chain breaks:
- * nothing schedules the next retry, so the client sits SILENTLY disconnected
- * forever until a full app relaunch. We hit this in dev (ADB/Metro flapping
- * wedged the v2 socket; only a cold relaunch recovered it).
- *
- * Three changes close that gap, belt-and-suspenders:
- *   0. A failed initial `open()` now also enters the reconnect loop. Before
- *      this, reconnect was robust only AFTER the first successful session had
- *      dropped; if the app booted while cloud was down, `open()` rejected and no
- *      retry was queued.
- *   1. The scheduled attempt's `.catch()` now reschedules itself, so a failure
- *      that did NOT fire `onClose` still queues the next try. `scheduleReconnect`
- *      is idempotent (guarded by `reconnectTimer`), so the double call from
- *      `onClose` + this catch never stacks two timers.
- *   2. A lightweight watchdog interval revives the loop if some unforeseen path
- *      ever leaves us `closed`, not host-closed, with no reconnect pending. Even
- *      if reasoning (1) misses a case, the watchdog guarantees we never sit dead.
+ * Reconnect must not depend on `onClose`: a connect attempt can fail without
+ * ever firing a clean close (network/DNS blip mid-handshake, or a
+ * `WebSocketLike` transport that emits only `onError`), which would otherwise
+ * leave the client silently disconnected until relaunch. So the loop is driven
+ * from three places: a failed initial `open()`, the scheduled attempt's own
+ * `.catch()`, and a watchdog interval that revives it if we are ever `closed`,
+ * not host-closed, with no reconnect pending. `scheduleReconnect` is idempotent
+ * (guarded by `reconnectTimer`) so the overlapping callers never stack timers.
  *
  * See docs/issues/004-cloud-client/design.md ("src/modules/runtime/connection.ts")
  * and docs/issues/002-cloud-runtime/protocol.md (envelope, handshake, control).