@every-app/sdk 0.1.10 → 0.1.12

package/src/core/sessionManager.ts

@@ -1,3 +1,11 @@
+import {
+  BYPASS_GATEWAY_LOCAL_ONLY_EMAIL,
+  BYPASS_GATEWAY_LOCAL_ONLY_TOKEN,
+  BYPASS_GATEWAY_LOCAL_ONLY_USER_ID,
+  isBypassGatewayLocalOnlyClient,
+} from "../shared/bypassGatewayLocalOnly.js";
+import { parseMessagePayload } from "../shared/parseMessagePayload.js";
+
 interface SessionToken {
   token: string;
   expiresAt: number;
@@ -9,6 +17,52 @@ interface TokenResponse {
   error?: string;
 }
 
+interface TokenUpdateMessage {
+  type: "SESSION_TOKEN_UPDATE";
+  token?: string;
+  expiresAt?: string;
+  appId?: string;
+}
+
+function isTokenUpdateMessage(data: unknown): data is TokenUpdateMessage {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return false;
+  }
+
+  return (data as { type?: unknown }).type === "SESSION_TOKEN_UPDATE";
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    return JSON.parse(atob(padded)) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function tokenAudienceMatchesApp(
+  payload: Record<string, unknown>,
+  appId: string,
+): boolean {
+  const aud = payload.aud;
+  if (typeof aud === "string") {
+    return aud === appId;
+  }
+
+  if (Array.isArray(aud)) {
+    return aud.some((value) => value === appId);
+  }
+
+  return false;
+}
+
 export interface SessionManagerConfig {
   appId: string;
 }
@@ -16,12 +70,25 @@ export interface SessionManagerConfig {
 const MESSAGE_TIMEOUT_MS = 5000;
 const TOKEN_EXPIRY_BUFFER_MS = 10000;
 const DEFAULT_TOKEN_LIFETIME_MS = 60000;
+const REACT_NATIVE_TOKEN_WAIT_TIMEOUT_MS = 10000;
+
+/**
+ * Environment detection types
+ */
+export type EmbeddedEnvironment =
+  | "iframe"
+  | "react-native-webview"
+  | "standalone";
 
 /**
  * Detects whether the current window is running inside an iframe.
  * Returns true if in an iframe, false if running as top-level window.
  */
 export function isRunningInIframe(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+
   try {
     return window.self !== window.top;
   } catch {
@@ -31,33 +98,131 @@ export function isRunningInIframe(): boolean {
   }
 }
 
+/**
+ * Detects whether the current window is running inside a React Native WebView.
+ * Returns true if window.ReactNativeWebView is available.
+ */
+export function isRunningInReactNativeWebView(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+
+  return (
+    typeof (window as any).ReactNativeWebView?.postMessage === "function" ||
+    (window as any).isReactNativeWebView === true
+  );
+}
+
+/**
+ * Detects the current embedded environment.
+ * Priority: React Native WebView > iframe > standalone
+ */
+export function detectEnvironment(): EmbeddedEnvironment {
+  const isRNWebView = isRunningInReactNativeWebView();
+  const isIframe = isRunningInIframe();
+
+  if (isRNWebView) {
+    return "react-native-webview";
+  }
+  if (isIframe) {
+    return "iframe";
+  }
+  return "standalone";
+}
+
 export class SessionManager {
   readonly parentOrigin: string;
   readonly appId: string;
   readonly isInIframe: boolean;
+  readonly environment: EmbeddedEnvironment;
+  readonly isBypassGatewayLocalOnly: boolean;
 
   private token: SessionToken | null = null;
   private refreshPromise: Promise<string> | null = null;
+  private tokenWaiters: Array<{
+    resolve: (token: string) => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+  }> = [];
 
   constructor(config: SessionManagerConfig) {
     if (!config.appId) {
       throw new Error("[SessionManager] appId is required.");
     }
 
+    this.isBypassGatewayLocalOnly = isBypassGatewayLocalOnlyClient();
+
     const gatewayUrl = import.meta.env.VITE_GATEWAY_URL;
-    if (!gatewayUrl) {
-      throw new Error("[SessionManager] VITE_GATEWAY_URL env var is required.");
-    }
+    if (!this.isBypassGatewayLocalOnly) {
+      if (!gatewayUrl) {
+        throw new Error(
+          "[SessionManager] VITE_GATEWAY_URL env var is required.",
+        );
+      }
 
-    try {
-      new URL(gatewayUrl);
-    } catch {
-      throw new Error(`[SessionManager] Invalid gateway URL: ${gatewayUrl}`);
+      try {
+        new URL(gatewayUrl);
+      } catch {
+        throw new Error(`[SessionManager] Invalid gateway URL: ${gatewayUrl}`);
+      }
     }
 
     this.appId = config.appId;
-    this.parentOrigin = gatewayUrl;
+    this.parentOrigin = this.isBypassGatewayLocalOnly
+      ? window.location.origin
+      : gatewayUrl;
+    this.environment = detectEnvironment();
     this.isInIframe = isRunningInIframe();
+
+    if (this.environment === "react-native-webview") {
+      this.setupReactNativeTokenListener();
+    }
+
+    if (this.isBypassGatewayLocalOnly) {
+      this.token = {
+        token: BYPASS_GATEWAY_LOCAL_ONLY_TOKEN,
+        expiresAt: Date.now() + DEFAULT_TOKEN_LIFETIME_MS,
+      };
+    }
+  }
+
+  /**
+   * Check if running in an embedded environment (iframe or React Native WebView)
+   */
+  isEmbedded(): boolean {
+    return this.environment !== "standalone";
+  }
+
+  isTrustedHostMessage(event: MessageEvent): boolean {
+    if (this.environment === "react-native-webview") {
+      const origin = (event as MessageEvent & { origin?: string | null })
+        .origin;
+      return (
+        origin === "react-native" ||
+        origin === "null" ||
+        origin === "" ||
+        origin == null
+      );
+    }
+
+    return event.origin === this.parentOrigin;
+  }
+
+  postToHost(message: object): void {
+    if (this.environment === "react-native-webview") {
+      const postMessage = (window as any).ReactNativeWebView?.postMessage;
+      if (typeof postMessage !== "function") {
+        throw new Error("React Native WebView bridge is unavailable");
+      }
+
+      postMessage.call(
+        (window as any).ReactNativeWebView,
+        JSON.stringify(message),
+      );
+      return;
+    }
+
+    window.parent.postMessage(message, this.parentOrigin);
   }
 
   private isTokenExpiringSoon(
@@ -79,19 +244,17 @@ export class SessionManager {
       };
 
       const handler = (event: MessageEvent) => {
-        // Security: reject messages from wrong origin (including null from sandboxed iframes)
-        if (event.origin !== this.parentOrigin) return;
-        // Safety: ignore malformed messages that could crash the handler
-        if (!event.data || typeof event.data !== "object") return;
-        if (
-          event.data.type === responseType &&
-          event.data.requestId === requestId
-        ) {
+        // Security: validate message origin based on environment
+        if (!this.isTrustedHostMessage(event)) return;
+        const data = parseMessagePayload(event.data);
+        if (!data) return;
+
+        if (data.type === responseType && data.requestId === requestId) {
           cleanup();
-          if (event.data.error) {
-            reject(new Error(event.data.error));
+          if (typeof data.error === "string" && data.error) {
+            reject(new Error(data.error));
           } else {
-            resolve(event.data as T);
+            resolve(data as T);
           }
         }
       };
@@ -102,15 +265,126 @@ export class SessionManager {
       }, MESSAGE_TIMEOUT_MS);
 
       window.addEventListener("message", handler);
-      window.parent.postMessage(request, this.parentOrigin);
+
+      try {
+        this.postToHost(request);
+      } catch (error) {
+        cleanup();
+        reject(
+          error instanceof Error
+            ? error
+            : new Error("Failed to post message to host"),
+        );
+      }
+    });
+  }
+
+  private setupReactNativeTokenListener(): void {
+    window.addEventListener("message", (event: MessageEvent) => {
+      if (!this.isTrustedHostMessage(event)) {
+        return;
+      }
+
+      const data = parseMessagePayload(event.data);
+      if (!data) {
+        return;
+      }
+
+      if (!isTokenUpdateMessage(data)) {
+        return;
+      }
+
+      const message = data;
+
+      if (!message.token || typeof message.token !== "string") {
+        return;
+      }
+
+      if (typeof message.appId !== "string" || message.appId !== this.appId) {
+        return;
+      }
+
+      if (
+        message.expiresAt !== undefined &&
+        typeof message.expiresAt !== "string"
+      ) {
+        return;
+      }
+
+      const payload = decodeJwtPayload(message.token);
+      if (!payload || !tokenAudienceMatchesApp(payload, this.appId)) {
+        return;
+      }
+
+      // Native controls token minting and pushes updates into the embedded app.
+      // We only consume pushed tokens in React Native WebView mode.
+      let expiresAt = Date.now() + DEFAULT_TOKEN_LIFETIME_MS;
+      if (message.expiresAt) {
+        const parsed = new Date(message.expiresAt).getTime();
+        if (!Number.isNaN(parsed)) {
+          expiresAt = parsed;
+        }
+      }
+
+      this.token = {
+        token: message.token,
+        expiresAt,
+      };
+
+      if (this.tokenWaiters.length > 0) {
+        const waiters = this.tokenWaiters;
+        this.tokenWaiters = [];
+
+        for (const waiter of waiters) {
+          clearTimeout(waiter.timeout);
+          waiter.resolve(message.token);
+        }
+      }
+    });
+  }
+
+  private waitForReactNativeTokenPush(): Promise<string> {
+    if (this.token && !this.isTokenExpiringSoon()) {
+      return Promise.resolve(this.token.token);
+    }
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.tokenWaiters = this.tokenWaiters.filter(
+          (w) => w.timeout !== timeout,
+        );
+        reject(
+          new Error("Timed out waiting for token from React Native bridge"),
+        );
+      }, REACT_NATIVE_TOKEN_WAIT_TIMEOUT_MS);
+
+      this.tokenWaiters.push({ resolve, reject, timeout });
     });
   }
 
   async requestNewToken(): Promise<string> {
+    if (this.isBypassGatewayLocalOnly) {
+      this.token = {
+        token: BYPASS_GATEWAY_LOCAL_ONLY_TOKEN,
+        expiresAt: Date.now() + DEFAULT_TOKEN_LIFETIME_MS,
+      };
+      return this.token.token;
+    }
+
     if (this.refreshPromise) {
       return this.refreshPromise;
     }
 
+    if (this.environment === "react-native-webview") {
+      this.refreshPromise = this.waitForReactNativeTokenPush();
+
+      try {
+        return await this.refreshPromise;
+      } finally {
+        this.refreshPromise = null;
+      }
+    }
+
     this.refreshPromise = (async () => {
       const requestId = crypto.randomUUID();
 
@@ -153,6 +427,13 @@ export class SessionManager {
   }
 
   async getToken(): Promise<string> {
+    if (this.isBypassGatewayLocalOnly) {
+      if (!this.token || this.isTokenExpiringSoon()) {
+        return this.requestNewToken();
+      }
+      return this.token.token;
+    }
+
     if (this.isTokenExpiringSoon()) {
       return this.requestNewToken();
     }
@@ -183,27 +464,29 @@ export class SessionManager {
    * Returns null if no valid token is available.
    */
   getUser(): { userId: string; email: string } | null {
+    if (this.isBypassGatewayLocalOnly) {
+      return {
+        userId: BYPASS_GATEWAY_LOCAL_ONLY_USER_ID,
+        email: BYPASS_GATEWAY_LOCAL_ONLY_EMAIL,
+      };
+    }
+
     if (!this.token) {
       return null;
     }
 
-    try {
-      const parts = this.token.token.split(".");
-      if (parts.length !== 3) {
-        return null;
-      }
-
-      const payload = JSON.parse(atob(parts[1]));
-      if (!payload.sub) {
-        return null;
-      }
+    const payload = decodeJwtPayload(this.token.token);
+    if (!payload) {
+      return null;
+    }
 
-      return {
-        userId: payload.sub,
-        email: payload.email ?? "",
-      };
-    } catch {
+    if (typeof payload.sub !== "string") {
       return null;
     }
+
+    return {
+      userId: payload.sub,
+      email: typeof payload.email === "string" ? payload.email : "",
+    };
   }
 }

package/src/shared/bypassGatewayLocalOnly.ts

@@ -0,0 +1,55 @@
+export const BYPASS_GATEWAY_LOCAL_ONLY_TOKEN = "BYPASS_GATEWAY_LOCAL_ONLY";
+export const BYPASS_GATEWAY_LOCAL_ONLY_USER_ID = "demo-local-user";
+export const BYPASS_GATEWAY_LOCAL_ONLY_EMAIL = "demo-local-user@local";
+
+export function isBypassGatewayLocalOnlyClient(): boolean {
+  if (import.meta.env.PROD) {
+    return false;
+  }
+
+  const metaEnv = (import.meta as { env?: Record<string, string | undefined> })
+    .env;
+
+  return (
+    metaEnv?.VITE_BYPASS_GATEWAY_LOCAL_ONLY === "true" ||
+    metaEnv?.BYPASS_GATEWAY_LOCAL_ONLY === "true"
+  );
+}
+
+export function isBypassGatewayLocalOnlyServer(): boolean {
+  if (import.meta.env.PROD) {
+    return false;
+  }
+
+  const metaEnv = (import.meta as { env?: Record<string, string | undefined> })
+    .env;
+  const metaValue =
+    metaEnv?.BYPASS_GATEWAY_LOCAL_ONLY ??
+    metaEnv?.VITE_BYPASS_GATEWAY_LOCAL_ONLY;
+  if (metaValue === "true") {
+    return true;
+  }
+
+  if (
+    typeof process !== "undefined" &&
+    process.env?.BYPASS_GATEWAY_LOCAL_ONLY === "true"
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+export function createBypassGatewayLocalOnlySessionPayload(audience: string) {
+  const issuedAt = Math.floor(Date.now() / 1000);
+  const expiresAt = issuedAt + 60 * 60;
+
+  return {
+    sub: BYPASS_GATEWAY_LOCAL_ONLY_USER_ID,
+    email: BYPASS_GATEWAY_LOCAL_ONLY_EMAIL,
+    iss: "local",
+    aud: audience,
+    iat: issuedAt,
+    exp: expiresAt,
+  };
+}

package/src/shared/parseMessagePayload.ts

@@ -0,0 +1,22 @@
+export type MessagePayload = Record<string, unknown>;
+
+export function parseMessagePayload(data: unknown): MessagePayload | null {
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    return data as MessagePayload;
+  }
+
+  if (typeof data !== "string") {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as MessagePayload;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}

package/src/tanstack/EmbeddedAppProvider.tsx

@@ -30,8 +30,11 @@ export function EmbeddedAppProvider({
 
   if (!sessionManager) return null;
 
-  // Check if the app is running outside of the Gateway iframe
-  if (!sessionManager.isInIframe) {
+  // Check if the app is running outside of the Gateway (iframe or React Native WebView)
+  if (
+    !sessionManager.isEmbedded() &&
+    !sessionManager.isBypassGatewayLocalOnly
+  ) {
     return (
       <GatewayRequiredError
         gatewayOrigin={sessionManager.parentOrigin}

package/src/tanstack/_internal/useEveryAppSession.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { shouldBootstrapSession } from "./useEveryAppSession";
+
+describe("shouldBootstrapSession", () => {
+  it("returns false for standalone apps without bypass", () => {
+    expect(
+      shouldBootstrapSession({
+        isEmbedded: () => false,
+        isBypassGatewayLocalOnly: false,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns true for embedded apps", () => {
+    expect(
+      shouldBootstrapSession({
+        isEmbedded: () => true,
+        isBypassGatewayLocalOnly: false,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns true for local bypass mode", () => {
+    expect(
+      shouldBootstrapSession({
+        isEmbedded: () => false,
+        isBypassGatewayLocalOnly: true,
+      }),
+    ).toBe(true);
+  });
+
+  it("does not depend on iframe detection for RN webviews", () => {
+    expect(
+      shouldBootstrapSession({
+        isEmbedded: () => true,
+        isBypassGatewayLocalOnly: false,
+      }),
+    ).toBe(true);
+  });
+});

package/src/tanstack/_internal/useEveryAppSession.tsx

@@ -9,6 +9,20 @@ interface UseEveryAppSessionParams {
   sessionManagerConfig: SessionManagerConfig;
 }
 
+type SessionBootstrapGate = Pick<
+  SessionManager,
+  "isEmbedded" | "isBypassGatewayLocalOnly"
+>;
+
+export function shouldBootstrapSession(
+  sessionManager: SessionBootstrapGate,
+): boolean {
+  // Bootstrapping should happen whenever the app is hosted by a trusted container.
+  // This intentionally keys off embedded environment semantics (iframe OR RN WebView),
+  // not iframe-only detection, so RN can initialize auth from pushed tokens.
+  return sessionManager.isEmbedded() || sessionManager.isBypassGatewayLocalOnly;
+}
+
 export function useEveryAppSession({
   sessionManagerConfig,
 }: UseEveryAppSessionParams) {
@@ -28,8 +42,8 @@ export function useEveryAppSession({
 
   useEffect(() => {
     if (!sessionManager) return;
-    // Skip token requests when not in iframe - the app will show GatewayRequiredError instead
-    if (!sessionManager.isInIframe) return;
+    // Skip token bootstrap when not embedded (unless in demo mode) - the app will show GatewayRequiredError instead
+    if (!shouldBootstrapSession(sessionManager)) return;
 
     const interval = setInterval(() => {
       setSessionTokenState(sessionManager.getTokenState());

package/src/tanstack/server/authConfig.ts

@@ -1,9 +1,19 @@
 import type { AuthConfig } from "./types.js";
 import { env } from "cloudflare:workers";
+import { isBypassGatewayLocalOnlyServer } from "../../shared/bypassGatewayLocalOnly.js";
 
 export function getAuthConfig(): AuthConfig {
+  const bypassGatewayLocalOnlyEnv = (
+    env as { BYPASS_GATEWAY_LOCAL_ONLY?: string }
+  ).BYPASS_GATEWAY_LOCAL_ONLY;
+  const isBypassGatewayLocalOnly =
+    import.meta.env.PROD !== true &&
+    (bypassGatewayLocalOnlyEnv === "true" ||
+      isBypassGatewayLocalOnlyServer() === true);
+  const issuer = env.GATEWAY_URL || (isBypassGatewayLocalOnly ? "local" : "");
+
   return {
-    issuer: env.GATEWAY_URL,
+    issuer,
     audience: import.meta.env.VITE_APP_ID,
   };
 }

package/src/tanstack/server/authenticateRequest.test.ts

@@ -16,6 +16,7 @@ vi.mock("@tanstack/react-start/server", () => ({
 
 import { authenticateRequest } from "./authenticateRequest";
 import type { AuthConfig } from "./types";
+import { env } from "cloudflare:workers";
 
 describe("authenticateRequest", () => {
   let keyPair: Awaited<ReturnType<typeof generateKeyPair>>;
@@ -25,6 +26,9 @@ describe("authenticateRequest", () => {
     issuer: "https://gateway.example.com",
     audience: "test-app",
   };
+  const workersEnv = env as unknown as {
+    BYPASS_GATEWAY_LOCAL_ONLY?: string;
+  };
 
   beforeEach(async () => {
     // Generate a fresh key pair for each test
@@ -56,6 +60,7 @@ describe("authenticateRequest", () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
+    delete workersEnv.BYPASS_GATEWAY_LOCAL_ONLY;
   });
 
   async function createValidToken(overrides: Record<string, unknown> = {}) {
@@ -117,6 +122,33 @@ describe("authenticateRequest", () => {
     });
   });
 
+  describe("BYPASS_GATEWAY_LOCAL_ONLY mode", () => {
+    it("accepts the local bypass token when BYPASS_GATEWAY_LOCAL_ONLY is true", async () => {
+      workersEnv.BYPASS_GATEWAY_LOCAL_ONLY = "true";
+      const request = createRequest("Bearer BYPASS_GATEWAY_LOCAL_ONLY");
+
+      const result = await authenticateRequest(authConfig, request);
+
+      expect(result).toMatchObject({
+        sub: "demo-local-user",
+        email: "demo-local-user@local",
+        iss: "local",
+        aud: authConfig.audience,
+      });
+      expect(global.fetch).not.toHaveBeenCalled();
+    });
+
+    it("rejects non-bypass tokens when BYPASS_GATEWAY_LOCAL_ONLY is true", async () => {
+      workersEnv.BYPASS_GATEWAY_LOCAL_ONLY = "true";
+      const request = createRequest("Bearer regular-token");
+
+      const result = await authenticateRequest(authConfig, request);
+
+      expect(result).toBeNull();
+      expect(global.fetch).not.toHaveBeenCalled();
+    });
+  });
+
   describe("valid token verification", () => {
     it("returns payload for valid token with correct issuer and audience", async () => {
       const token = await createValidToken();