chatablex-web-sdk 1.0.3 → 1.0.31

package/README.md

@@ -1,5 +1,11 @@
 # ChatableX Web SDK
 
+[![license](https://img.shields.io/npm/l/chatablex-web-sdk.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/blob/main/package.json)
+[![npm version](https://img.shields.io/npm/v/chatablex-web-sdk.svg?style=flat-square)](https://www.npmjs.com/package/chatablex-web-sdk)
+[![CI](https://img.shields.io/github/actions/workflow/status/chatablex/chatablex-web-sdk/ci.yml?branch=main&label=Build%20%26%20Test&logo=github)](https://github.com/chatablex/chatablex-web-sdk/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/pulls)
+
 English | [**简体中文**](README.zh-CN.md)
 
 **Runtime SDK for building ChatableX AI App WebUI extensions.**
@@ -27,6 +33,7 @@ Your WebUI runs inside a WebView. Many capabilities — native dialogs, file pic
   - [sdk.storage](#sdkstorage)
   - [sdk.tools](#sdktools)
   - [sdk.platform](#sdkplatform)
+  - [sdk.auth](#sdkauth)
 - [Events Reference](#events-reference)
 - [Permissions](#permissions)
 - [Host Capability Matrix](#host-capability-matrix)
@@ -533,6 +540,52 @@ Throws if `targetUrl` is empty or whitespace-only.
 
 ---
 
+### `sdk.auth`
+
+Unified authentication for **every** WebUI app. In a hosted (Flutter WebView)
+environment it transparently reuses the desktop login session — your app writes
+**zero** login/token code. Just call `getAuthHeaders()` and attach it to your
+`fetch`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getToken` | `() => Promise<AuthTokenData \| null>` | Get a valid token (cached, refreshed on demand). `null` when not authenticated. |
+| `getAuthHeaders` | `() => Promise<Record<string,string>>` | `{ Authorization: "Bearer <token>" }`, or `{}` when not authenticated. |
+| `getUserId` | `() => string \| null` | Authenticated user id (sync, cache only). |
+| `isAuthenticated` | `() => boolean` | Whether a valid token is cached (sync). |
+| `refresh` | `() => Promise<boolean>` | Force a refresh via the host. Concurrent calls are merged (single-flight). |
+
+```ts
+// Attach the host login session to any authenticated request — no login code.
+const res = await fetch('https://api.example.com/scenes', {
+  headers: {
+    'Content-Type': 'application/json',
+    ...(await sdk.auth.getAuthHeaders()),
+  },
+});
+
+if (!sdk.auth.isAuthenticated()) {
+  // not logged in / not hosted — disable features that need auth
+}
+
+// On a 401 from your backend, force a refresh and retry once:
+if (res.status === 401 && (await sdk.auth.refresh())) {
+  // retry with await sdk.auth.getAuthHeaders()
+}
+```
+
+**Behavior & guarantees**
+
+- **Token is in-memory only.** The `refresh_token` never crosses the bridge.
+- **Pre-emptive refresh.** The host refreshes the `access_token` before sending
+  when it is expired or near expiry, so you normally never see an expired token.
+- **Safe degradation.** Outside a WebView, or when the host is logged out,
+  `getAuthHeaders()` resolves to `{}` and never throws.
+- **Pluggable provider.** Today only `HostAuthProvider` (WebView) is wired up; a
+  future browser/unified-login provider will slot in without changing your code.
+
+---
+
 ## Events Reference
 
 | Event | Payload | When fired |
@@ -576,6 +629,7 @@ SDK methods are thin RPC wrappers. Some host handlers are fully implemented; oth
 | `sdk.ui.pickFile` | **Production** | Requires `file_access` |
 | `sdk.ui.updateState` | **Production** | Delegates to host |
 | `sdk.platform.openInBrowser` | **Production** | Auth handoff |
+| `sdk.auth.*` | **Production** | Hosted: reuses desktop login via `host.getAuthToken` (pre-refresh) |
 | `sdk.ai.chat` | **Production** | Requires `ai_chat` + delegate |
 | `sdk.ai.getContext` | **Partial** | Returns minimal context |
 | `sdk.ai.chatStream` | **Partial** | Returns `{ streaming: true }`; tokens via events |

package/README.zh-CN.md

@@ -1,5 +1,11 @@
 # ChatableX Web SDK
 
+[![license](https://img.shields.io/npm/l/chatablex-web-sdk.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/blob/main/package.json)
+[![npm version](https://img.shields.io/npm/v/chatablex-web-sdk.svg?style=flat-square)](https://www.npmjs.com/package/chatablex-web-sdk)
+[![CI](https://img.shields.io/github/actions/workflow/status/chatablex/chatablex-web-sdk/ci.yml?branch=main&label=Build%20%26%20Test&logo=github)](https://github.com/chatablex/chatablex-web-sdk/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/chatablex/chatablex-web-sdk/pulls)
+
 **[English](README.md)** | 简体中文
 
 **用于构建 ChatableX AI App WebUI 扩展的官方运行时 SDK。**
@@ -27,6 +33,7 @@
   - [sdk.storage](#sdkstorage)
   - [sdk.tools](#sdktools)
   - [sdk.platform](#sdkplatform)
+  - [sdk.auth](#sdkauth)
 - [事件参考](#事件参考)
 - [权限声明](#权限声明)
 - [宿主能力矩阵](#宿主能力矩阵)
@@ -533,6 +540,51 @@ await sdk.platform.openInBrowser('https://docs.example.com/guide');
 
 ---
 
+### `sdk.auth`
+
+面向**所有** WebUI 应用的统一鉴权入口。在宿主（Flutter WebView）环境下，它会
+透明复用桌面端的登录态——你的应用**无需编写任何登录/Token 代码**，只需调用
+`getAuthHeaders()` 并附加到 `fetch` 即可。
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `getToken` | `() => Promise<AuthTokenData \| null>` | 取有效 Token（内存缓存，按需刷新）；未登录返回 `null`。 |
+| `getAuthHeaders` | `() => Promise<Record<string,string>>` | 返回 `{ Authorization: "Bearer <token>" }`，未登录则返回 `{}`。 |
+| `getUserId` | `() => string \| null` | 当前登录用户 id（同步，仅读缓存）。 |
+| `isAuthenticated` | `() => boolean` | 是否已缓存有效 Token（同步）。 |
+| `refresh` | `() => Promise<boolean>` | 强制经宿主刷新；并发调用合并为一次（single-flight）。 |
+
+```ts
+// 给任意需要鉴权的请求附加宿主登录态——无需任何登录代码。
+const res = await fetch('https://api.example.com/scenes', {
+  headers: {
+    'Content-Type': 'application/json',
+    ...(await sdk.auth.getAuthHeaders()),
+  },
+});
+
+if (!sdk.auth.isAuthenticated()) {
+  // 未登录 / 非 WebView——禁用需要鉴权的功能
+}
+
+// 后端返回 401 时，强制刷新并重试一次：
+if (res.status === 401 && (await sdk.auth.refresh())) {
+  // 用 await sdk.auth.getAuthHeaders() 重试
+}
+```
+
+**行为与保证**
+
+- **Token 仅存内存。** `refresh_token` 永不经过 bridge。
+- **下发前刷新。** 宿主在 Token 过期或临近过期时会先刷新再下发，正常情况下你
+  不会拿到过期 Token。
+- **安全降级。** 在非 WebView 或宿主未登录时，`getAuthHeaders()` 返回 `{}` 且
+  不抛异常。
+- **Provider 可插拔。** 目前仅接入 `HostAuthProvider`（WebView）；未来的浏览器/
+  统一登录 provider 可无缝替换，消费方代码无需改动。
+
+---
+
 ## 事件参考
 
 | 事件 | 载荷 | 触发时机 |
@@ -576,6 +628,7 @@ SDK 方法是薄 RPC 封装。部分宿主处理器已完整实现，部分返
 | `sdk.ui.pickFile` | **生产可用** | 需要 `file_access` |
 | `sdk.ui.updateState` | **生产可用** | 委托给宿主 |
 | `sdk.platform.openInBrowser` | **生产可用** | 鉴权传递 |
+| `sdk.auth.*` | **生产可用** | 宿主态：经 `host.getAuthToken` 复用桌面登录（下发前刷新） |
 | `sdk.ai.chat` | **生产可用** | 需要 `ai_chat` + delegate |
 | `sdk.ai.getContext` | **部分实现** | 返回最小上下文 |
 | `sdk.ai.chatStream` | **部分实现** | 返回 `{ streaming: true }`；token 走事件 |

package/dist/index.d.mts

@@ -156,6 +156,41 @@ interface ChatableXPlatform {
     /** Open URL in system browser with auth handoff (WebView only; implemented by Flutter host). */
     openInBrowser(targetUrl: string): Promise<void>;
 }
+/** Token payload returned by the host (never includes the refresh_token). */
+interface AuthTokenData {
+    /** Bearer access token to put in the Authorization header. */
+    access_token: string;
+    /** Access token expiry, epoch milliseconds. */
+    expires_at: number;
+    /** Authenticated user id. */
+    user_id: string;
+}
+/**
+ * Unified auth entry point for all WebUI apps.
+ *
+ * In a hosted (Flutter WebView) environment this reuses the desktop login
+ * session via the `host.getAuthToken` bridge call — apps never implement
+ * login or token handling themselves.
+ */
+interface ChatableXAuth {
+    /**
+     * Get a valid access token. Returns the in-memory cached token when still
+     * valid, otherwise fetches a fresh one from the host. Returns `null` when
+     * not authenticated / not hosted.
+     */
+    getToken(): Promise<AuthTokenData | null>;
+    /**
+     * Build auth headers ready to spread into a `fetch`. Returns
+     * `{ Authorization: "Bearer <token>" }` when authenticated, otherwise `{}`.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** Currently authenticated user id, or `null`. Synchronous (cache only). */
+    getUserId(): string | null;
+    /** Whether a valid token is currently cached. Synchronous (cache only). */
+    isAuthenticated(): boolean;
+    /** Force a token refresh via the host. Resolves `true` on success. */
+    refresh(): Promise<boolean>;
+}
 interface ChatableXSDK {
     ai: ChatableXAI;
     tools: ChatableXTools;
@@ -164,6 +199,7 @@ interface ChatableXSDK {
     storage: ChatableXStorage;
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
+    auth: ChatableXAuth;
 }
 declare global {
     interface Window {
@@ -252,4 +288,4 @@ declare const ChatableX: {
     version: string;
 };
 
-export { type AiResponseEventData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };
+export { type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAuth, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };

package/dist/index.d.ts

@@ -156,6 +156,41 @@ interface ChatableXPlatform {
     /** Open URL in system browser with auth handoff (WebView only; implemented by Flutter host). */
     openInBrowser(targetUrl: string): Promise<void>;
 }
+/** Token payload returned by the host (never includes the refresh_token). */
+interface AuthTokenData {
+    /** Bearer access token to put in the Authorization header. */
+    access_token: string;
+    /** Access token expiry, epoch milliseconds. */
+    expires_at: number;
+    /** Authenticated user id. */
+    user_id: string;
+}
+/**
+ * Unified auth entry point for all WebUI apps.
+ *
+ * In a hosted (Flutter WebView) environment this reuses the desktop login
+ * session via the `host.getAuthToken` bridge call — apps never implement
+ * login or token handling themselves.
+ */
+interface ChatableXAuth {
+    /**
+     * Get a valid access token. Returns the in-memory cached token when still
+     * valid, otherwise fetches a fresh one from the host. Returns `null` when
+     * not authenticated / not hosted.
+     */
+    getToken(): Promise<AuthTokenData | null>;
+    /**
+     * Build auth headers ready to spread into a `fetch`. Returns
+     * `{ Authorization: "Bearer <token>" }` when authenticated, otherwise `{}`.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** Currently authenticated user id, or `null`. Synchronous (cache only). */
+    getUserId(): string | null;
+    /** Whether a valid token is currently cached. Synchronous (cache only). */
+    isAuthenticated(): boolean;
+    /** Force a token refresh via the host. Resolves `true` on success. */
+    refresh(): Promise<boolean>;
+}
 interface ChatableXSDK {
     ai: ChatableXAI;
     tools: ChatableXTools;
@@ -164,6 +199,7 @@ interface ChatableXSDK {
     storage: ChatableXStorage;
     tool: ChatableXToolModule;
     platform: ChatableXPlatform;
+    auth: ChatableXAuth;
 }
 declare global {
     interface Window {
@@ -252,4 +288,4 @@ declare const ChatableX: {
     version: string;
 };
 
-export { type AiResponseEventData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };
+export { type AiResponseEventData, type AuthTokenData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXAuth, type ChatableXEvents, type ChatableXInitConfig, type ChatableXPlatform, type ChatableXSDK, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };

package/dist/index.js

@@ -299,10 +299,68 @@ function createPlatformModule(bridge) {
   };
 }
 
+// src/modules/auth.ts
+var EXPIRY_SKEW_MS = 5e3;
+function isValid(token, now) {
+  return !!token && typeof token.access_token === "string" && token.access_token.length > 0 && token.expires_at - EXPIRY_SKEW_MS > now;
+}
+var HostAuthProvider = class {
+  constructor(bridge) {
+    this._token = null;
+    /** In-flight refresh, so concurrent callers share one host round-trip. */
+    this._refreshing = null;
+    this._bridge = bridge;
+  }
+  async getToken() {
+    if (isValid(this._token, Date.now())) return this._token;
+    const ok = await this.refresh();
+    return ok ? this._token : null;
+  }
+  async getAuthHeaders() {
+    const token = await this.getToken();
+    if (!token) return {};
+    return { Authorization: `Bearer ${token.access_token}` };
+  }
+  getUserId() {
+    return this._token?.user_id ?? null;
+  }
+  isAuthenticated() {
+    return isValid(this._token, Date.now());
+  }
+  refresh() {
+    if (this._refreshing) return this._refreshing;
+    this._refreshing = this._doRefresh().finally(() => {
+      this._refreshing = null;
+    });
+    return this._refreshing;
+  }
+  async _doRefresh() {
+    try {
+      const raw = await this._bridge.sendMessage("host.getAuthToken");
+      if (raw && typeof raw === "object" && typeof raw.access_token === "string" && raw.access_token.length > 0) {
+        this._token = {
+          access_token: raw.access_token,
+          expires_at: Number(raw.expires_at) || 0,
+          user_id: String(raw.user_id ?? "")
+        };
+        return true;
+      }
+      this._token = null;
+      return false;
+    } catch {
+      this._token = null;
+      return false;
+    }
+  }
+};
+function createAuthModule(bridge) {
+  return new HostAuthProvider(bridge);
+}
+
 // package.json
 var package_default = {
   name: "chatablex-web-sdk",
-  version: "1.0.3",
+  version: "1.0.31",
   description: "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -401,7 +459,8 @@ var ChatableX = {
       events: createEventsModule(bridge),
       storage: createStorageModule(bridge),
       tool: toolModule,
-      platform: createPlatformModule(bridge)
+      platform: createPlatformModule(bridge),
+      auth: createAuthModule(bridge)
     };
     window.ChatableX = sdk;
     _instance = sdk;

package/dist/index.mjs

@@ -271,10 +271,68 @@ function createPlatformModule(bridge) {
   };
 }
 
+// src/modules/auth.ts
+var EXPIRY_SKEW_MS = 5e3;
+function isValid(token, now) {
+  return !!token && typeof token.access_token === "string" && token.access_token.length > 0 && token.expires_at - EXPIRY_SKEW_MS > now;
+}
+var HostAuthProvider = class {
+  constructor(bridge) {
+    this._token = null;
+    /** In-flight refresh, so concurrent callers share one host round-trip. */
+    this._refreshing = null;
+    this._bridge = bridge;
+  }
+  async getToken() {
+    if (isValid(this._token, Date.now())) return this._token;
+    const ok = await this.refresh();
+    return ok ? this._token : null;
+  }
+  async getAuthHeaders() {
+    const token = await this.getToken();
+    if (!token) return {};
+    return { Authorization: `Bearer ${token.access_token}` };
+  }
+  getUserId() {
+    return this._token?.user_id ?? null;
+  }
+  isAuthenticated() {
+    return isValid(this._token, Date.now());
+  }
+  refresh() {
+    if (this._refreshing) return this._refreshing;
+    this._refreshing = this._doRefresh().finally(() => {
+      this._refreshing = null;
+    });
+    return this._refreshing;
+  }
+  async _doRefresh() {
+    try {
+      const raw = await this._bridge.sendMessage("host.getAuthToken");
+      if (raw && typeof raw === "object" && typeof raw.access_token === "string" && raw.access_token.length > 0) {
+        this._token = {
+          access_token: raw.access_token,
+          expires_at: Number(raw.expires_at) || 0,
+          user_id: String(raw.user_id ?? "")
+        };
+        return true;
+      }
+      this._token = null;
+      return false;
+    } catch {
+      this._token = null;
+      return false;
+    }
+  }
+};
+function createAuthModule(bridge) {
+  return new HostAuthProvider(bridge);
+}
+
 // package.json
 var package_default = {
   name: "chatablex-web-sdk",
-  version: "1.0.3",
+  version: "1.0.31",
   description: "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -373,7 +431,8 @@ var ChatableX = {
       events: createEventsModule(bridge),
       storage: createStorageModule(bridge),
       tool: toolModule,
-      platform: createPlatformModule(bridge)
+      platform: createPlatformModule(bridge),
+      auth: createAuthModule(bridge)
     };
     window.ChatableX = sdk;
     _instance = sdk;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatablex-web-sdk",
-  "version": "1.0.3",
+  "version": "1.0.31",
   "description": "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -26,6 +26,7 @@ import { createUIModule } from './modules/ui';
 import { createStorageModule } from './modules/storage';
 import { createToolsModule } from './modules/tools';
 import { createPlatformModule } from './modules/platform';
+import { createAuthModule } from './modules/auth';
 import type { ChatableXSDK, ChatableXInitConfig, ToolInfo } from './types';
 import pkg from '../package.json';
 
@@ -86,6 +87,7 @@ export const ChatableX = {
       storage: createStorageModule(bridge),
       tool: toolModule,
       platform: createPlatformModule(bridge),
+      auth: createAuthModule(bridge),
     };
 
     // Expose on window for debugging / Flutter interop

package/src/modules/auth.ts

@@ -0,0 +1,102 @@
+import type { Bridge } from '../bridge';
+import type { AuthTokenData, ChatableXAuth } from '../types';
+
+/**
+ * Strategy interface behind `sdk.auth`. Lets us swap how a token is obtained
+ * (hosted WebView today, browser/unified-login later) without touching any
+ * consumer code or the public `ChatableXAuth` surface.
+ */
+export interface AuthProvider extends ChatableXAuth {}
+
+/** Treat a token as expired this many ms before its real `expires_at`. */
+const EXPIRY_SKEW_MS = 5_000;
+
+/** Shape of the host reply to `host.getAuthToken`. */
+type HostAuthResponse =
+  | { access_token: string; expires_at: number; user_id: string; error?: undefined }
+  | { error: string; access_token?: undefined };
+
+function isValid(token: AuthTokenData | null, now: number): token is AuthTokenData {
+  return !!token && typeof token.access_token === 'string' && token.access_token.length > 0
+    && token.expires_at - EXPIRY_SKEW_MS > now;
+}
+
+/**
+ * Auth provider that reuses the desktop host's login session over the bridge.
+ * Token lives in memory only; the refresh_token never crosses the bridge —
+ * the host refreshes before sending (see FR-05).
+ */
+export class HostAuthProvider implements AuthProvider {
+  private _bridge: Bridge;
+  private _token: AuthTokenData | null = null;
+  /** In-flight refresh, so concurrent callers share one host round-trip. */
+  private _refreshing: Promise<boolean> | null = null;
+
+  constructor(bridge: Bridge) {
+    this._bridge = bridge;
+  }
+
+  async getToken(): Promise<AuthTokenData | null> {
+    if (isValid(this._token, Date.now())) return this._token;
+    const ok = await this.refresh();
+    return ok ? this._token : null;
+  }
+
+  async getAuthHeaders(): Promise<Record<string, string>> {
+    const token = await this.getToken();
+    if (!token) return {};
+    return { Authorization: `Bearer ${token.access_token}` };
+  }
+
+  getUserId(): string | null {
+    return this._token?.user_id ?? null;
+  }
+
+  isAuthenticated(): boolean {
+    return isValid(this._token, Date.now());
+  }
+
+  refresh(): Promise<boolean> {
+    // single-flight: merge concurrent refreshes into one host round-trip
+    if (this._refreshing) return this._refreshing;
+    this._refreshing = this._doRefresh().finally(() => {
+      this._refreshing = null;
+    });
+    return this._refreshing;
+  }
+
+  private async _doRefresh(): Promise<boolean> {
+    try {
+      const raw = (await this._bridge.sendMessage('host.getAuthToken')) as HostAuthResponse | null;
+      if (
+        raw &&
+        typeof raw === 'object' &&
+        typeof raw.access_token === 'string' &&
+        raw.access_token.length > 0
+      ) {
+        this._token = {
+          access_token: raw.access_token,
+          expires_at: Number(raw.expires_at) || 0,
+          user_id: String(raw.user_id ?? ''),
+        };
+        return true;
+      }
+      // not authenticated / not hosted / host returned { error }
+      this._token = null;
+      return false;
+    } catch {
+      // bridge unavailable (non-WebView) or host error — degrade safely
+      this._token = null;
+      return false;
+    }
+  }
+}
+
+/**
+ * Build the `auth` module. Selects the provider for the current environment;
+ * today there is only `HostAuthProvider`. A future `WebAuthProvider`
+ * (browser / unified login) can be slotted in here without changing callers.
+ */
+export function createAuthModule(bridge: Bridge): ChatableXAuth {
+  return new HostAuthProvider(bridge);
+}

package/src/types.ts

@@ -210,6 +210,47 @@ export interface ChatableXPlatform {
   openInBrowser(targetUrl: string): Promise<void>;
 }
 
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+/** Token payload returned by the host (never includes the refresh_token). */
+export interface AuthTokenData {
+  /** Bearer access token to put in the Authorization header. */
+  access_token: string;
+  /** Access token expiry, epoch milliseconds. */
+  expires_at: number;
+  /** Authenticated user id. */
+  user_id: string;
+}
+
+/**
+ * Unified auth entry point for all WebUI apps.
+ *
+ * In a hosted (Flutter WebView) environment this reuses the desktop login
+ * session via the `host.getAuthToken` bridge call — apps never implement
+ * login or token handling themselves.
+ */
+export interface ChatableXAuth {
+  /**
+   * Get a valid access token. Returns the in-memory cached token when still
+   * valid, otherwise fetches a fresh one from the host. Returns `null` when
+   * not authenticated / not hosted.
+   */
+  getToken(): Promise<AuthTokenData | null>;
+  /**
+   * Build auth headers ready to spread into a `fetch`. Returns
+   * `{ Authorization: "Bearer <token>" }` when authenticated, otherwise `{}`.
+   */
+  getAuthHeaders(): Promise<Record<string, string>>;
+  /** Currently authenticated user id, or `null`. Synchronous (cache only). */
+  getUserId(): string | null;
+  /** Whether a valid token is currently cached. Synchronous (cache only). */
+  isAuthenticated(): boolean;
+  /** Force a token refresh via the host. Resolves `true` on success. */
+  refresh(): Promise<boolean>;
+}
+
 export interface ChatableXSDK {
   ai: ChatableXAI;
   tools: ChatableXTools;
@@ -218,6 +259,7 @@ export interface ChatableXSDK {
   storage: ChatableXStorage;
   tool: ChatableXToolModule;
   platform: ChatableXPlatform;
+  auth: ChatableXAuth;
 }
 
 // ---------------------------------------------------------------------------