@intentcomputing/koko-agent-sdk 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.1.0
+
+- Add production `tokenProvider` authentication with expiry-aware caching and one forced refresh after a 401.
+- Add host-backend token exchange documentation and Node.js, Java, Go, Python, PHP and C# examples.
+- Keep static app tokens as a documented legacy development/migration path.
+
 ## 1.0.1
 
 - Clarify npm setup, host-provided entry controls, regional gateways, and privacy responsibilities in the published documentation.

package/README.md

@@ -1,6 +1,6 @@
 # Koko Agent SDK
 
-React Native SDK for an observable in-app assistant. The host supplies an app token and presents a user goal; the SDK observes the screen, asks the hosted gateway for a next step, and performs supported actions inside the app.
+React Native SDK for an observable in-app assistant. The host supplies a short-lived access token and presents a user goal; the SDK observes the screen, asks the hosted gateway for a next step, and performs supported actions inside the app.
 
 [npm package](https://www.npmjs.com/package/@intentcomputing/koko-agent-sdk) · [中文](README.zh-CN.md) · [Integration guide](docs/INTEGRATION.md) · [Privacy](docs/PRIVACY.md) · [Contributing](CONTRIBUTING.md)
 
@@ -8,7 +8,7 @@ React Native SDK for an observable in-app assistant. The host supplies an app to
 
 - React Native 0.73 or later and React 18 or later; iOS 15 or later or an Android host supporting React Native autolinking.
 - Expo development build or a native build; Expo Go cannot load this native module.
-- An Intent Computing app token bound to the host bundle ID or Android application ID. The app token is not an OpenAI or DeepSeek API key.
+- A host backend that exchanges its server-only client secret for short-lived mobile access tokens. Neither credential is an OpenAI or DeepSeek API key.
 
 ## Install
 
@@ -21,7 +21,7 @@ Rebuild and reinstall the native app after installation or a native SDK upgrade.
 
 ## Quick start
 
-Mount the provider around the host navigation tree and connect `openKokoChat()` to a host button. Replace the placeholder with the token issued for your host app and environment.
+Mount the provider around the host navigation tree and connect `openKokoChat()` to a host button. Supply short-lived credentials through `tokenProvider`.
 
 ```tsx
 import React from 'react';
@@ -29,8 +29,15 @@ import { Button, View } from 'react-native';
 import { KokoProvider, openKokoChat } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const getKokoToken = React.useCallback(async () => {
+    const response = await fetch('https://api.your-app.example/koko/access-token', {
+      headers: { Authorization: `Bearer ${await getHostSessionToken()}` },
+    });
+    if (!response.ok) throw new Error(`Koko token ${response.status}`);
+    return response.json(); // { accessToken, expiresAt } (Unix milliseconds)
+  }, []);
   return (
-    <KokoProvider config={{ gateway: { token: 'YOUR_APP_TOKEN' }, locale: 'en' }}>
+    <KokoProvider config={{ gateway: { tokenProvider: getKokoToken }, locale: 'en' }}>
       <View style={{ flex: 1 }}>
         {/* Your app and navigation go here. */}
         <Button title="Open assistant" onPress={() => openKokoChat()} />
@@ -40,7 +47,7 @@ export default function App() {
 }
 ```
 
-The default gateway is `https://sdk.intentcomputing.net` (OpenAI). For China, set `gateway.baseUrl` to `https://sdk.intentcomputing.cn` (DeepSeek). Use a token valid for the chosen environment. Provider API keys stay on the gateway and must not be bundled into the app.
+The default gateway is `https://sdk.intentcomputing.net` (OpenAI). For China, set `gateway.baseUrl` to `https://sdk.intentcomputing.cn` (DeepSeek). The SDK caches short-lived tokens, refreshes before expiry, and retries once after a 401. Long-lived client secrets and model-provider keys must never be bundled into the app. See the [backend authentication demos](docs/BACKEND_AUTH_DEMOS.md) for Node.js, Java, Go, Python, PHP and C#.
 
 Call `setKokoAppearance({ locale, theme })` when host preferences change. Configure branding through `config.branding`; custom branding is subject to the app's entitlement. See the [integration guide](docs/INTEGRATION.md) for host actions, privacy gates, and lifecycle details.
 

package/README.zh-CN.md

@@ -2,13 +2,13 @@
 
 面向 React Native 的应用内助手 SDK。用户描述任务后，SDK 观察宿主当前页面，通过网关规划下一步，并在宿主内执行支持的操作，过程对用户可见。
 
-[npm 包](https://www.npmjs.com/package/@intentcomputing/koko-agent-sdk) · [English](README.md) · [接入指南](docs/INTEGRATION.zh-CN.md) · [隐私保护](docs/PRIVACY.zh-CN.md)
+[npm 包](https://www.npmjs.com/package/@intentcomputing/koko-agent-sdk) · [English](README.md) · [接入指南](docs/INTEGRATION.zh-CN.md) · [后端鉴权 Demo](docs/BACKEND_AUTH_DEMOS.zh-CN.md) · [隐私保护](docs/PRIVACY.zh-CN.md)
 
 ## 前置条件
 
 - React Native ≥ 0.73、React ≥ 18；iOS ≥ 15，或支持原生自动链接的 Android 宿主。
 - Expo 使用开发构建或原生构建，不支持 Expo Go。
-- 使用绑定宿主 Bundle ID / Android Application ID 的应用 token；它不是模型 API 密钥。
+- 生产环境需要宿主后端：长期 `clientSecret` 只保存在后端，App 仅取得短期 access token。它们都不是模型 API 密钥。
 
 ## 安装
 
@@ -27,9 +27,16 @@ import { Button, View } from 'react-native';
 import { KokoProvider, openKokoChat } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const getKokoToken = React.useCallback(async () => {
+    const response = await fetch('https://api.your-app.example/koko/access-token', {
+      headers: { Authorization: `Bearer ${await getHostSessionToken()}` },
+    });
+    if (!response.ok) throw new Error(`Koko token ${response.status}`);
+    return response.json(); // { accessToken, expiresAt }；expiresAt 为 Unix 毫秒
+  }, []);
   return (
     <KokoProvider config={{
-      gateway: { token: 'YOUR_APP_TOKEN', baseUrl: 'https://sdk.intentcomputing.cn' },
+      gateway: { tokenProvider: getKokoToken, baseUrl: 'https://sdk.intentcomputing.cn' },
       locale: 'zh',
     }}>
       <View style={{ flex: 1 }}>
@@ -41,7 +48,7 @@ export default function App() {
 }
 ```
 
-默认网关为海外的 `https://sdk.intentcomputing.net`（OpenAI）；国内请显式选择 `https://sdk.intentcomputing.cn`（DeepSeek）。使用对应环境的应用 token，模型 API 密钥只保留在网关。语言或主题变化时调用 `setKokoAppearance({ locale, theme })`；品牌配置通过 `config.branding` 传入，并受应用权益控制。
+默认网关为海外的 `https://sdk.intentcomputing.net`（OpenAI）；国内请显式选择 `https://sdk.intentcomputing.cn`（DeepSeek）。SDK 会缓存短期 token、在过期前刷新，并在 401 后强制刷新一次。长期 `clientSecret` 和模型 API 密钥都不得进入 App。完整三端流程及 Node.js、Java、Go、Python、PHP、C# Demo 见[后端鉴权 Demo](docs/BACKEND_AUTH_DEMOS.zh-CN.md)。
 
 宿主必须在展示密码、私钥、助记词及其验证页面前设置隐私标记和用户操作门禁，由用户亲自完成敏感步骤。脱敏的页面信息和任务上下文会发送到所选网关进行规划，接入方应使用虚构数据验证隐私边界。详见[隐私说明](docs/PRIVACY.zh-CN.md)。
 

package/docs/BACKEND_AUTH_DEMOS.md

@@ -0,0 +1,38 @@
+# Host-backend authentication demos
+
+Production authentication uses three parties: the mobile app authenticates to its existing host backend; the host backend exchanges its server-only `clientId` and `clientSecret` with Koko; the app receives a 5–15 minute access token for the SDK.
+
+```text
+Host app --host session--> Host backend --client secret--> Koko /v1/sdk/token
+Host app <--short token--- Host backend <--short token---- Koko
+Host app --short token-----------------------------------> Koko /v1/agent/*
+```
+
+## Rules
+
+- Store `KOKO_CLIENT_SECRET` only in the host backend's secret manager or environment. Never return it to the app or place it in Git or logs.
+- Protect and rate-limit the host `/koko/access-token` endpoint with the host's existing authentication.
+- Derive `subject` on the server from the authenticated user. Send a stable pseudonymous value such as `HMAC-SHA256(hostUserId, separateSalt)`, never an email, phone number, wallet address or advertising ID.
+- Use `https://sdk.intentcomputing.cn` for China and `https://sdk.intentcomputing.net` globally. Credentials and access tokens are region-bound.
+- Koko returns `access_token`, `expires_in`, and `expires_at` (Unix seconds). Return `{ accessToken, expiresAt }` to the SDK, with `expiresAt` expressed in Unix milliseconds.
+- Use a short timeout. Do not log authorization headers or response tokens. Rotate long-lived client secrets.
+
+Complete, copyable examples for **Node.js/TypeScript (Express), Java (Spring Boot), Go, Python (FastAPI), PHP (Laravel), and C# (ASP.NET Core)** are maintained in the [Chinese guide](BACKEND_AUTH_DEMOS.zh-CN.md); all examples use standard HTTP Basic authentication for the server-to-server exchange and derive the subject from the host-authenticated user.
+
+## React Native
+
+```tsx
+const tokenProvider = React.useCallback(async () => {
+  const response = await hostApi.get('/koko/access-token');
+  return response.data as { accessToken: string; expiresAt: number };
+}, []);
+
+<KokoProvider config={{
+  gateway: {
+    baseUrl: 'https://sdk.intentcomputing.net',
+    tokenProvider,
+  },
+}}>{children}</KokoProvider>
+```
+
+Do not persist the access token in AsyncStorage or send it to logs/analytics. The SDK keeps it in memory, refreshes shortly before expiry, and clears it before one forced `tokenProvider` retry after a 401.

package/docs/BACKEND_AUTH_DEMOS.zh-CN.md

@@ -0,0 +1,187 @@
+# 宿主后端鉴权与多语言 Demo
+
+生产环境采用三端通信：宿主 App 通过自己的登录态请求宿主后端；宿主后端使用仅存于服务器的 `clientId` / `clientSecret` 向 Koko 换取 5～15 分钟的 access token；App 再把短期 token 交给 SDK。
+
+```text
+宿主 App ──宿主登录态──> 宿主后端 ──clientSecret──> Koko /v1/sdk/token
+宿主 App <──短期 token── 宿主后端 <──短期 token── Koko
+宿主 App ──短期 token──> Koko /v1/agent/*
+```
+
+## 安全约定
+
+- `KOKO_CLIENT_SECRET` 只能放在宿主后端的密钥系统或环境变量中，不能进入 App、Git、日志或前端响应。
+- 宿主的 `/koko/access-token` 必须验证已有登录态并限流，不能做成匿名转发接口。
+- `subject` 必须由后端根据已认证用户生成稳定的匿名值；不要发送邮箱、手机号、钱包地址或设备广告 ID。建议 `HMAC-SHA256(宿主用户ID, 独立盐)`。
+- 国内使用 `https://sdk.intentcomputing.cn`，海外使用 `https://sdk.intentcomputing.net`；凭证和 token 不跨区域使用。
+- Koko 返回字段为 `access_token`、`expires_in`、`expires_at`（Unix 秒）。宿主接口应转换为 SDK 接受的 `{ accessToken, expiresAt }`，其中 `expiresAt` 是 Unix 毫秒。
+- 请求 Koko 必须设置短超时，不记录 Authorization 头或响应 token。长期凭证应定期轮换。
+
+以下示例中的 `authenticatedUserId` 必须来自宿主已经验证的 session/JWT，不得从请求 body 或 query 直接采用。
+
+## Node.js / TypeScript（Express）
+
+```ts
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+const gateway = process.env.KOKO_REGION === 'cn'
+  ? 'https://sdk.intentcomputing.cn'
+  : 'https://sdk.intentcomputing.net';
+
+app.get('/koko/access-token', requireHostLogin, async (req, res) => {
+  const subject = crypto.createHmac('sha256', process.env.KOKO_SUBJECT_SALT!)
+    .update(req.user.id) // 只取服务端认证结果
+    .digest('hex');
+  const basic = Buffer.from(
+    `${process.env.KOKO_CLIENT_ID}:${process.env.KOKO_CLIENT_SECRET}`,
+  ).toString('base64');
+  const upstream = await fetch(`${gateway}/v1/sdk/token`, {
+    method: 'POST',
+    headers: { Authorization: `Basic ${basic}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ app_id: process.env.KOKO_APP_ID, subject }),
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!upstream.ok) return res.status(502).json({ error: 'koko_token_unavailable' });
+  const token = await upstream.json();
+  res.set('Cache-Control', 'no-store').json({
+    accessToken: token.access_token,
+    expiresAt: token.expires_at * 1000,
+  });
+});
+```
+
+## Java（Spring Boot 3）
+
+```java
+record KokoToken(String access_token, long expires_at) {}
+record AppToken(String accessToken, long expiresAt) {}
+
+AppToken exchange(String authenticatedUserId) throws Exception {
+  String subject = hmacSha256Hex(System.getenv("KOKO_SUBJECT_SALT"), authenticatedUserId);
+  String basic = Base64.getEncoder().encodeToString(
+      (System.getenv("KOKO_CLIENT_ID") + ":" + System.getenv("KOKO_CLIENT_SECRET"))
+          .getBytes(StandardCharsets.UTF_8));
+  String body = objectMapper.writeValueAsString(Map.of(
+      "app_id", System.getenv("KOKO_APP_ID"), "subject", subject));
+  HttpRequest request = HttpRequest.newBuilder(URI.create(kokoGateway + "/v1/sdk/token"))
+      .timeout(Duration.ofSeconds(5)).header("Authorization", "Basic " + basic)
+      .header("Content-Type", "application/json")
+      .POST(HttpRequest.BodyPublishers.ofString(body)).build();
+  HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+  if (response.statusCode() != 200) throw new IllegalStateException("Koko token unavailable");
+  KokoToken token = objectMapper.readValue(response.body(), KokoToken.class);
+  return new AppToken(token.access_token(), token.expires_at() * 1000L);
+}
+```
+
+Spring Controller 必须从 `Principal` / SecurityContext 取得 `authenticatedUserId`，并返回 `Cache-Control: no-store`。
+
+## Go（net/http）
+
+```go
+func exchangeKokoToken(ctx context.Context, authenticatedUserID string) (string, int64, error) {
+    mac := hmac.New(sha256.New, []byte(os.Getenv("KOKO_SUBJECT_SALT")))
+    mac.Write([]byte(authenticatedUserID))
+    body, _ := json.Marshal(map[string]string{
+        "app_id": os.Getenv("KOKO_APP_ID"), "subject": hex.EncodeToString(mac.Sum(nil)),
+    })
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second); defer cancel()
+    req, _ := http.NewRequestWithContext(ctx, http.MethodPost, kokoGateway+"/v1/sdk/token", bytes.NewReader(body))
+    req.SetBasicAuth(os.Getenv("KOKO_CLIENT_ID"), os.Getenv("KOKO_CLIENT_SECRET"))
+    req.Header.Set("Content-Type", "application/json")
+    resp, err := http.DefaultClient.Do(req); if err != nil { return "", 0, err }
+    defer resp.Body.Close()
+    if resp.StatusCode != http.StatusOK { return "", 0, fmt.Errorf("koko token: %s", resp.Status) }
+    var out struct { AccessToken string `json:"access_token"`; ExpiresAt int64 `json:"expires_at"` }
+    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil { return "", 0, err }
+    return out.AccessToken, out.ExpiresAt * 1000, nil
+}
+```
+
+## Python（FastAPI + HTTPX）
+
+```python
+import hashlib, hmac, os
+import httpx
+from fastapi import Depends, HTTPException, Response
+
+@app.get('/koko/access-token')
+async def koko_token(response: Response, user=Depends(require_host_user)):
+    subject = hmac.new(os.environ['KOKO_SUBJECT_SALT'].encode(), str(user.id).encode(), hashlib.sha256).hexdigest()
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        upstream = await client.post(
+            f'{KOKO_GATEWAY}/v1/sdk/token',
+            auth=(os.environ['KOKO_CLIENT_ID'], os.environ['KOKO_CLIENT_SECRET']),
+            json={'app_id': os.environ['KOKO_APP_ID'], 'subject': subject},
+        )
+    if upstream.status_code != 200:
+        raise HTTPException(502, 'Koko token unavailable')
+    token = upstream.json()
+    response.headers['Cache-Control'] = 'no-store'
+    return {'accessToken': token['access_token'], 'expiresAt': token['expires_at'] * 1000}
+```
+
+## PHP（Laravel）
+
+```php
+public function token(Request $request): JsonResponse
+{
+    $userId = (string) $request->user()->getAuthIdentifier(); // auth middleware 已验证
+    $subject = hash_hmac('sha256', $userId, env('KOKO_SUBJECT_SALT'));
+    $upstream = Http::timeout(5)
+        ->withBasicAuth(env('KOKO_CLIENT_ID'), env('KOKO_CLIENT_SECRET'))
+        ->post(config('services.koko.gateway').'/v1/sdk/token', [
+            'app_id' => env('KOKO_APP_ID'), 'subject' => $subject,
+        ]);
+    abort_unless($upstream->successful(), 502, 'Koko token unavailable');
+    return response()->json([
+        'accessToken' => $upstream['access_token'],
+        'expiresAt' => $upstream['expires_at'] * 1000,
+    ])->header('Cache-Control', 'no-store');
+}
+```
+
+## C#（ASP.NET Core）
+
+```csharp
+app.MapGet("/koko/access-token", async (ClaimsPrincipal user, IHttpClientFactory factory) => {
+    var userId = user.FindFirstValue(ClaimTypes.NameIdentifier)
+        ?? throw new UnauthorizedAccessException();
+    var subject = Convert.ToHexString(HMACSHA256.HashData(
+        Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("KOKO_SUBJECT_SALT")!),
+        Encoding.UTF8.GetBytes(userId))).ToLowerInvariant();
+    var clientId = Environment.GetEnvironmentVariable("KOKO_CLIENT_ID")!;
+    var clientSecret = Environment.GetEnvironmentVariable("KOKO_CLIENT_SECRET")!;
+    var appId = Environment.GetEnvironmentVariable("KOKO_APP_ID")!;
+    var request = new HttpRequestMessage(HttpMethod.Post, $"{kokoGateway}/v1/sdk/token");
+    var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
+        $"{clientId}:{clientSecret}"));
+    request.Headers.Authorization = new("Basic", credentials);
+    request.Content = JsonContent.Create(new { app_id = appId, subject });
+    var upstream = await factory.CreateClient("koko").SendAsync(request);
+    if (!upstream.IsSuccessStatusCode) return Results.Problem(statusCode: 502, title: "Koko token unavailable");
+    var token = await upstream.Content.ReadFromJsonAsync<KokoToken>();
+    return Results.Json(new { accessToken = token!.access_token, expiresAt = token.expires_at * 1000 },
+        headers: new Dictionary<string, string> { ["Cache-Control"] = "no-store" });
+}).RequireAuthorization();
+```
+
+## App 端
+
+```tsx
+const tokenProvider = React.useCallback(async () => {
+  const response = await hostApi.get('/koko/access-token');
+  return response.data as { accessToken: string; expiresAt: number };
+}, []);
+
+<KokoProvider config={{
+  gateway: {
+    baseUrl: 'https://sdk.intentcomputing.cn',
+    tokenProvider,
+  },
+}}>{children}</KokoProvider>
+```
+
+不要把 token 写入 AsyncStorage、日志或分析事件。SDK 自己在内存中缓存，到期前刷新；如果网关返回 401，会清除缓存并强制调用一次 `tokenProvider`。

package/docs/INTEGRATION.md

@@ -8,14 +8,14 @@ For React Native host apps. After installing the package you must link native co
 
 - React Native ≥ 0.73 (or Expo Dev Client / `expo prebuild` — **not Expo Go**)
 - iOS deployment target ≥ 15; ability to run `pod install`
-- An **app token** from Intent Computing (`gateway.token` — not a DeepSeek / OpenAI key)
+- An Intent Computing `clientId` and `clientSecret`; keep the secret on the host backend only
 
 ## Checklist
 
 1. Install the npm package
 2. iOS: `pod install` (Android usually autolinks)
 3. **Rebuild native** (Debug or Release)
-4. Wrap the root tree with `KokoProvider` and set `token`
+4. Exchange credentials on the host backend and provide short-lived tokens to `KokoProvider`
 5. Launch and send a natural-language goal
 
 JS-only config changes can hot-reload via Metro. **First integration or any native SDK change requires a native rebuild.**
@@ -65,11 +65,15 @@ Wrap at the app root (or outermost navigation shell):
 import { KokoProvider } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const tokenProvider = React.useCallback(async () => {
+    const response = await hostApi.get('/koko/access-token');
+    return response.data as { accessToken: string; expiresAt: number };
+  }, []);
   return (
     <KokoProvider
       config={{
         gateway: {
-          token: 'YOUR_APP_TOKEN',
+          tokenProvider,
           // Default: https://sdk.intentcomputing.net
           // China: https://sdk.intentcomputing.cn
           // baseUrl: 'https://sdk.intentcomputing.cn',
@@ -85,9 +89,11 @@ export default function App() {
 }
 ```
 
+`tokenProvider` calls your backend, never Koko's exchange endpoint directly: the `clientSecret` must not enter the app. The SDK caches credentials using `expiresAt` or JWT `exp` and refreshes once after a 401. See the [backend demos](BACKEND_AUTH_DEMOS.md) for complete examples. Static `gateway.token` remains available only for local development and migration.
+
 `KokoProvider` will:
 
-- Initialize the agent with `gateway.token`
+- Initialize the agent with `gateway.tokenProvider`
 - Mount cursor, progress, and chat sheet (optional — see below)
 
 Open chat from host UI:
@@ -138,7 +144,7 @@ For custom private UIs, declare the gate before navigation or reveal and keep it
 
 1. Launch the app and use your host button wired to `openKokoChat()`. The provider does not create a host entry button.
 2. Send a verifiable goal; you should see dump → tap with a visible cursor.
-3. Check that requests use the selected official gateway and a token bound to this app. Do not bundle an LLM API key. Validate privacy gates and outbound payloads using synthetic data.
+3. Check that requests use the selected official gateway and a short-lived token bound to this app. Do not bundle a client secret, long-lived token or LLM API key. Validate privacy gates and outbound payloads using synthetic data.
 
 ---
 
@@ -157,7 +163,7 @@ Not supported. Use a Dev Client, bare RN, or a production host binary.
 Use `portal:` / `file:`. If the package lives **outside** the monorepo, Metro may need `watchFolders` + `extraNodeModules` (usually unnecessary after npm publish).
 
 **Where does the token come from?**
-Intent Computing console / commercial onboarding — not a model-vendor API key.
+Your backend exchanges its server-only Intent Computing client credentials for a short-lived token. It is not a model-vendor API key.
 
 ---
 
@@ -166,3 +172,4 @@ Intent Computing console / commercial onboarding — not a model-vendor API key.
 - Package overview: [../README.md](../README.md)
 - npm publish: [PUBLISH.md](./PUBLISH.md)
 - 中文接入指南: [INTEGRATION.zh-CN.md](./INTEGRATION.zh-CN.md)
+- Backend authentication demos: [BACKEND_AUTH_DEMOS.md](./BACKEND_AUTH_DEMOS.md)

package/docs/INTEGRATION.zh-CN.md

@@ -8,14 +8,14 @@
 
 - React Native ≥ 0.73（或 Expo Dev Client / `expo prebuild`，**不支持 Expo Go**）
 - iOS 部署目标 ≥ 15；需本机可 `pod install`
-- 从 Intent Computing 拿到 **应用 token**（`gateway.token`，不是 DeepSeek / OpenAI Key）
+- 从 Intent Computing 拿到 `clientId` / `clientSecret`；`clientSecret` 只放宿主后端
 
 ## 步骤一览
 
 1. 安装 npm 包
 2. iOS `pod install`（Android 一般靠 autolinking）
 3. **重新编译原生**（Debug / Release 均可）
-4. 根组件包一层 `KokoProvider` 并配置 token
+4. 宿主后端换取短期 token，App 用 `tokenProvider` 提供给 `KokoProvider`
 5. 将 `openKokoChat()` 对接宿主入口，再发自然语言任务
 
 之后若只改 JS 配置或升级包的纯 JS 部分，Metro 热更新即可；**SDK 含原生改动或首次接入，必须再编原生。**
@@ -63,11 +63,15 @@ npx react-native run-android
 import { KokoProvider } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const tokenProvider = React.useCallback(async () => {
+    const response = await hostApi.get('/koko/access-token');
+    return response.data as { accessToken: string; expiresAt: number };
+  }, []);
   return (
     <KokoProvider
       config={{
         gateway: {
-          token: 'YOUR_APP_TOKEN',
+          tokenProvider,
           // 默认 https://sdk.intentcomputing.net（OpenAI）
           // 国内：https://sdk.intentcomputing.cn（DeepSeek）
           baseUrl: 'https://sdk.intentcomputing.cn',
@@ -82,6 +86,8 @@ export default function App() {
 }
 ```
 
+`tokenProvider` 应调用宿主后端，不能直接调用 Koko 换 token 接口，因为 `clientSecret` 绝不能进入 App。SDK 会按 `expiresAt` 或 JWT `exp` 缓存凭证，并在 401 后刷新一次。宿主后端完整实现见[六种主流语言 Demo](BACKEND_AUTH_DEMOS.zh-CN.md)。`gateway.token` 仅保留给本地开发和迁移，不建议用于正式包。
+
 宿主也可主动打开会话：
 
 ```tsx
@@ -113,7 +119,7 @@ getKokoAgent().openChat();
 
 1. 启动 App，通过接有 `openKokoChat()` 的宿主按钮打开助手；Provider 不会自动创建宿主入口。
 2. 输入可核验目标，应看到 dump → tap 与光标。
-3. 请求打到官网网关（或 `baseUrl`），App 内无任何 LLM API Key。
+3. 请求打到官网网关（或 `baseUrl`），App 内无 `clientSecret`、长期 token 或任何 LLM API Key。
 
 ---
 
@@ -138,3 +144,4 @@ getKokoAgent().openChat();
 - 英文总览：[../README.md](../README.md)
 - 中文总览：[../README.zh-CN.md](../README.zh-CN.md)
 - 发布：[PUBLISH.zh-CN.md](./PUBLISH.zh-CN.md)
+- 后端鉴权 Demo：[BACKEND_AUTH_DEMOS.zh-CN.md](./BACKEND_AUTH_DEMOS.zh-CN.md)

package/lib/commonjs/KokoAgent.js

@@ -29,8 +29,7 @@ var _ExecutionGuard = require("./commercial/ExecutionGuard.js");
 var _AgentDebug = require("./commercial/AgentDebug.js");
 var _index = require("./i18n/index.js");
 var _ocrTarget = require("./assist/ocrTarget.js");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
  * Koko Agent SDK runtime — dump / find / tap / swipe / pinch / type + cursor + confirm gate + task log.
  */
@@ -173,14 +172,18 @@ class KokoAgent {
     if (this.activeSession || this.claimingCheckpoint) {
       throw new Error((0, _index.runtimeText)('runtime.alreadyRunning', undefined, this.config?.locale));
     }
-    const token = opts?.token ?? this.config.gateway?.token;
-    if (!token) {
+    const gateway = {
+      token: opts?.token ?? this.config.gateway?.token,
+      tokenProvider: opts?.tokenProvider ?? this.config.gateway?.tokenProvider,
+      appId: opts?.appId ?? this.config.gateway?.appId
+    };
+    if (!gateway.token && !gateway.tokenProvider) {
       throw new Error(this.text('runtime.missingToken'));
     }
     const baseUrl = opts?.baseUrl ?? this.config.gateway?.baseUrl;
     const locale = (0, _index.gatewayLocale)((0, _index.currentLocale)(opts?.locale ?? this.config.locale));
     void _AccountStore.AccountStore.refresh({
-      token,
+      ...gateway,
       baseUrl
     });
     const session = this.createSession({
@@ -191,7 +194,7 @@ class KokoAgent {
       onAskUser: opts?.onAskUser,
       onNarration: opts?.onNarration,
       baseUrl,
-      token
+      ...gateway
     });
     this.activeSession = session;
     // An action can take down the context running it (locale/theme/RTL change,
@@ -206,7 +209,7 @@ class KokoAgent {
       await _RunCheckpoint.RunCheckpoint.clear().catch(() => {});
       if (this.activeSession === session) this.activeSession = null;
       void _AccountStore.AccountStore.refresh({
-        token,
+        ...gateway,
         baseUrl
       });
     }
@@ -263,11 +266,10 @@ class KokoAgent {
 
   /** Refresh plan / quota / entitlements from gateway. */
   async refreshAccount() {
-    const token = this.config.gateway?.token;
-    if (!token) return null;
+    const gateway = this.config.gateway;
+    if (!gateway?.token && !gateway?.tokenProvider) return null;
     return _AccountStore.AccountStore.refresh({
-      token,
-      baseUrl: this.config.gateway?.baseUrl
+      ...gateway
     });
   }
   getAccount() {