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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassly/cloud-client",
-  "version": "0.1.0-dev.0",
+  "version": "0.1.0-dev.22",
   "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.22",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {

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 those is how a flaky
+   * cold start (the first launch after an app update, typically) used to log
+   * users out of a perfectly healthy session.
    */
   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;