@heybox/hb-sdk 0.6.9 → 0.7.0-alpha.1

package/skill/references/examples.md

@@ -9,40 +9,52 @@
 - apps/docs/hb-sdk/recipes/**
 ## Positive examples
 
-### Minimal user info
+### Local identity for a network-disabled mini-program
 
 ```ts
-import { ready, user } from '@heybox/hb-sdk';
+import { ready, user, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
-await ready();
+export async function getLocalIdentityFromUserAction() {
+  await ready();
 
-const result = await user.getInfo();
-if (result.isLogin && result.userInfo) {
-  console.log(result.userInfo.nickname);
+  try {
+    return await user.getLocalIdentity();
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return undefined;
+    }
+    throw error;
+  }
 }
 ```
 
-### Login gate
+### Developer server session for a network-enabled mini-program
 
 ```ts
-import { auth, ready, user, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+import { auth, network, ready, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
-export async function ensureLogin() {
+export async function createServerSessionFromUserAction() {
   await ready();
 
-  const current = await user.getInfo();
-  if (current.isLogin && current.userInfo) return current.userInfo;
-
   try {
-    const loginResult = await auth.login();
-    return loginResult.userInfo;
+    const result = await auth.login({ scopes: ['profile'] });
+    await exchangeCodeWithDeveloperServer(result.code);
+    return { status: 'ready' as const };
   } catch (error) {
-    if (error instanceof HbMiniProgramSDKError) {
-      console.warn(error.code, error.message);
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return { status: 'cancelled' as const };
     }
-    return null;
+    throw error;
   }
 }
+
+async function exchangeCodeWithDeveloperServer(code: string) {
+  await network.request({
+    url: 'https://api.example.com/session/heybox',
+    method: 'POST',
+    data: { code },
+  });
+}
 ```
 
 ### Network request

package/skill/references/recipes.md

@@ -26,157 +26,196 @@
 
 # 快速开始
 
-如果页面不需要小黑盒开放能力，可以不接入 SDK。这是最短接入路径：等待 SDK 就绪，然后读取当前用户登录态。
+如果页面不需要小黑盒开放能力，可以不接入 SDK。需要开放能力时，先等待 `ready()`，再根据小程序是否开通网络权限选择身份流程。
+
+## 未开通网络权限
+
+无网络小程序可以在本地能力中使用按小程序隔离的 `appUserId`：
 
 ```ts
-import hbSDK from '@heybox/hb-sdk'
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
-async function bootstrap() {
+async function getLocalIdentityFromUserAction() {
   await hbSDK.ready()
 
-  const result = await hbSDK.user.getInfo()
-  if (result.isLogin && result.userInfo) {
-    console.log(result.userInfo.nickname)
-    return
+  try {
+    const { appUserId } = await hbSDK.user.getLocalIdentity()
+    return appUserId
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return undefined
+    }
+    throw error
   }
-
-  console.log('当前用户未登录')
 }
-
-bootstrap()
 ```
 
-## 推荐业务写法
+把 `getLocalIdentityFromUserAction` 绑定到按钮点击等可信用户操作。首次登录或 identity consent 需要 UI 而缺少可信手势时返回 `USER_GESTURE_REQUIRED`；取消或关闭时返回 `AUTHORIZATION_CANCELLED`，不会确认或改变授权状态。这条路径不能获取授权码或调用 OpenAPI，也不要把 `appUserId` 发送到外部服务。
 
-业务页通常还需要监听登录态变化。下面以 Vue 3 为例：初始化只读取状态，登录必须由按钮等明确的用户操作触发，监听在组件卸载时清理。
+## 已开通网络权限
 
-```ts
-import { onUnmounted } from 'vue'
-import hbSDK from '@heybox/hb-sdk'
+有网络小程序通过 `auth.login()` 获取短期授权码。登录可能展示 UI，因此应绑定到按钮点击等明确的用户操作：
 
-const stopAuthChange = hbSDK.on('authChange', result => {
-  if (result.isLogin) {
-    console.log('用户已登录', result.userInfo?.heybox_id)
-  }
-})
+```ts
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
 await hbSDK.ready()
 
-const initialUser = await hbSDK.user.getInfo()
-
 async function loginFromUserAction() {
-  const result = await hbSDK.auth.login()
-  if (!result.isLogin || !result.userInfo) {
-    return
-  }
+  try {
+    const result = await hbSDK.auth.login({ scopes: ['profile'] })
 
-  console.log('用户已登录', result.userInfo.heybox_id)
+    await hbSDK.network.request({
+      url: 'https://api.example.com/session/heybox',
+      method: 'POST',
+      data: { code: result.code },
+    })
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return
+    }
+    throw error
+  }
 }
-
-onUnmounted(stopAuthChange)
 ```
 
-把 `loginFromUserAction` 绑定到登录按钮；不要在页面 bootstrap 阶段自动调用 `auth.login()`。
+返回值与边界以[用户身份与登录](/guide/auth)为准。页面只把 `code` 提交给自己的服务端。不要在页面初始化阶段自动调用 `auth.login()`。
 
 ## ready 的含义
 
-`ready()` 表示 SDK 已就绪，可以安全调用开放能力。如果当前不在可用的小程序运行环境中，它会抛出公开错误。`ready()` 不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
+`ready()` 只表示 SDK 已就绪，可以安全调用开放能力。它不表示已经取得用户授权，也不返回用户身份。
 
-## 默认单例适合什么场景
+## 默认单例
 
 大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
 
 ## User and login
 
 
-# 用户与登录
+# 用户身份与登录
 
-用户与授权模块当前分工：
+用户身份接入取决于小程序是否已开通 `network.request`。两类小程序使用不同的身份入口：
 
-- `user.getInfo()`：静默读取当前登录态与公开基础资料。
-- `auth.login()`：唤起黑盒登录流程，并返回登录后的最新公开用户资料。
-- `user.getCurrentUserDetail()`：读取当前用户展示详情。
-- `user.getCurrentUserProfile()`：读取当前用户敏感资料，需要对应平台权限。
-- `user.getPlatformAccountOverview()` / `getPlatformAccountInfo()`：读取平台账号概览或指定平台详情。
-- `user.getSteamGameList()`：读取当前用户 Steam 游戏库。
+| 小程序类型     | 身份入口                  | 结果用途                                               |
+| -------------- | ------------------------- | ------------------------------------------------------ |
+| 已开通网络权限 | `auth.login({ scopes? })` | 获取短期授权码，由开发者服务端换取 OpenAPI token       |
+| 未开通网络权限 | `user.getLocalIdentity()` | 在当前小程序页面和平台代管能力中使用隔离的 `appUserId` |
 
-## 静默读取用户信息
+不要混用两条路径。SDK 不向小程序页面提供 token、cookie、黑盒用户 ID 或平台私有凭据。
 
-`getInfo` 不会触发登录流程。用户未登录时，返回 `isLogin: false` 和 `userInfo: null`。
+## 已开通网络权限
+
+在登录、绑定账号或读取资料等明确的用户操作中调用 `auth.login()`：
 
 ```ts
-import { ready, user } from '@heybox/hb-sdk'
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
-await ready()
+async function loginFromUserAction() {
+  await hbSDK.ready()
 
-const result = await user.getInfo()
-if (result.isLogin) {
-  console.log(result.userInfo?.nickname)
+  try {
+    const { code, expiresIn, scopes } = await hbSDK.auth.login({ scopes: ['profile'] })
+    // expiresIn 以服务端返回为准，单位秒；当前后端签发 300 秒一次性 code
+
+    await hbSDK.network.request({
+      url: 'https://api.example.com/session/heybox',
+      method: 'POST',
+      data: { code },
+    })
+
+    console.log(expiresIn, scopes)
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return
+    }
+    throw error
+  }
 }
 ```
 
-## 主动唤起登录
+返回值固定为 `{ code, expiresIn: 300, scopes }`：
 
-当业务动作必须登录才能继续时，再调用 `login`。
+- `code` 是一次性短期授权码，只能提交给当前小程序的开发者服务端。
+- `expiresIn` 固定为 `300` 秒，服务端应尽快使用，失败或过期后重新获取。
+- `scopes` 是本次授权码实际包含的 scope。
 
-```ts
-import hbSDK from '@heybox/hb-sdk'
+`identity` 始终隐式包含，不需要也不能通过省略它来申请匿名授权。`scopes` 只填写业务确实需要的可选资料，例如 `profile`；不需要额外资料时直接调用 `auth.login()`。
 
-async function ensureLogin() {
-  await hbSDK.ready()
+小程序页面只把 `code` 发送到自己的服务端。开发者服务端再按后端 OpenAPI 文档，用服务端保存的应用凭据交换 token；页面不得自行交换，也不得持有应用私密凭据。`auth.login()` 不返回 user、profile、`appUserId` 或 token。
 
-  const current = await hbSDK.user.getInfo()
-  if (current.isLogin) {
-    return current.userInfo
-  }
+开发者服务端用 access token 调用 `GET /user_miniprogram/openapi/v1/user` 读取当前用户。响应始终包含 `app_user_id`；token 含 `profile` 时还会返回 `nickname` 和 `avatar`。不要再请求已下线的 `/user/identity` 或 `/user/profile`。
+
+## 用户操作和错误
+
+需要展示登录或授权 UI 时，调用必须来自按钮点击等可信用户手势，否则返回 `USER_GESTURE_REQUIRED`。用户取消、拒绝或关闭授权页面时返回 `AUTHORIZATION_CANCELLED`，业务应停留在当前页面并允许稍后重试。
+
+用户已授权所需 scope 时，`auth.login()` 可以不展示 UI，静默返回新的短期授权码。业务仍应把可能出现的授权 UI 设计在明确的用户操作之后，不要在页面初始化阶段自动调用。
+
+## 撤销当前小程序授权
+
+已开通和未开通网络权限的小程序都可以在明确的用户操作中撤销授权：
 
-  const next = await hbSDK.auth.login()
-  return next.userInfo
+```ts
+async function revokeAuthorizationFromUserAction() {
+  const confirmed = window.confirm('确定撤销当前小程序的用户授权吗？')
+  if (!confirmed) return
+
+  await hbSDK.user.revokeAuthorization()
+  clearLocalUserState()
 }
 ```
 
-## 基础资料与扩展资料
+`user.revokeAuthorization()` 不接收参数。小程序页面不能提交小程序 ID、黑盒用户 ID 或手势标记；Runtime 从 Host 启动上下文和用户操作状态注入可信值。调用缺少可信用户手势时返回 `USER_GESTURE_REQUIRED`。
+
+撤销成功后，后续 `auth.login()` 或 `user.getLocalIdentity()` 会重新进入授权流程。业务必须立即停止使用并清理此前保存的 `appUserId`、用户资料和开发者服务端会话；SDK 不会删除业务自己的 localStorage、数据库或 cookie。
+
+## 当前用户资料由服务端读取
+
+已开通网络权限后，页面不再直接读取 Host 当前用户资料。`@heybox/hb-sdk` 根包实际导出的以下调用统一返回 `SERVER_API_REQUIRED`：
 
-`user.getInfo()` 和 `auth.login()` 的 `userInfo` 只包含三项公开基础字段：
+- `user.getInfo()`
+- `user.getSteamGameList(options)`
+- `user.getLocalIdentity()`
 
-| 字段        | 类型     | 说明         |
-| ----------- | -------- | ------------ |
-| `heybox_id` | `string` | 黑盒用户 ID  |
-| `nickname`  | `string` | 用户昵称     |
-| `avatar`    | `string` | 用户头像 URL |
+其他 Host current-user capabilities 属于 Host/runtime 集成边界，不是小程序可从 SDK 根包调用的方法。需要对应数据时，先取得授权码，再由开发者服务端按后端 OpenAPI 文档换取 token 并调用对应接口。不要把 `SERVER_API_REQUIRED` 当作未登录或权限弹窗失败。
 
-不会暴露 token、cookie、手机号或任何可用于调用主站私有接口的凭据。
+`user.revokeAuthorization()` 是例外：它是授权变更操作，在两种网络模式下都可用，但始终要求可信用户手势。
 
-current-user scoped API 返回独立的 `UserScopedResult<T>`。未登录时是 `{ isLogin: false, data: null }`；已登录时才有 `data`。其中 `getCurrentUserProfile()` 可能返回生日、邮箱、教育和职业等敏感资料，必须按最小必要原则使用，并以平台权限结果为准；不要把这些字段理解为 `getInfo()` 的默认返回值。
+## 未开通网络权限
+
+未开通网络权限的小程序不走授权码流程。需要当前用户在本小程序内的稳定隔离身份时调用：
 
 ```ts
-const profile = await user.getCurrentUserProfile()
-if (profile.isLogin) {
-  console.log(profile.data.email)
-}
+import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+
+async function getLocalIdentityFromUserAction() {
+  await hbSDK.ready()
 
-const platforms = await user.getPlatformAccountOverview()
-if (platforms.isLogin) {
-  console.log(platforms.data)
+  try {
+    const { appUserId } = await hbSDK.user.getLocalIdentity()
+    return appUserId
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return undefined
+    }
+    throw error
+  }
 }
 ```
 
-## 监听登录态变化
+`user.getLocalIdentity()` 返回 `{ appUserId }`。同一用户在同一小程序中保持稳定，在不同小程序中取值不同；应把它当作不透明字符串，不要解析、跨小程序关联或当作黑盒用户 ID。
 
-如果页面上同时存在登录按钮、权限态 UI 和业务数据，建议监听 `authChange`。
+首次登录或尚未授予 identity 时，该调用可能展示 UI，因此 `getLocalIdentityFromUserAction` 必须绑定到按钮点击等可信用户操作；缺少可信手势时返回 `USER_GESTURE_REQUIRED`。用户取消、拒绝或关闭时返回 `AUTHORIZATION_CANCELLED`，不会确认或改变授权状态；业务应正常结束当前操作并允许稍后重试。
 
-```ts
-import { onUnmounted } from 'vue'
-import { on } from '@heybox/hb-sdk'
+这类小程序无法获取授权码，也无法调用 OpenAPI；在未开通网络权限时调用 `auth.login()` 同样返回 `SERVER_API_REQUIRED`。Host 提供的 current-user APIs 与平台代管能力继续按各自权限工作，但页面不能把其中的身份或资料发送到外部服务。
 
-const stopAuthChange = on('authChange', result => {
-  if (result.isLogin) {
-    console.log('登录态更新', result.userInfo?.heybox_id)
-  }
-})
+## 网络请求边界
 
-onUnmounted(stopAuthChange)
-```
+`network.request()` 只用于访问开发者自己的业务服务。平台保留的 runtime auth 与 OpenAPI 内部路径不能通过该能力访问；身份交换必须由开发者服务端按公开后端文档完成。
+
+## CLI 登录与用户登录
+
+`hb-sdk login` 只给本地开发和远端管理命令建立 CLI 登录态，与小程序页面的 `auth.login()`、`user.getLocalIdentity()` 和用户授权完全无关。
 
 ## Lifecycle events
 
@@ -210,15 +249,15 @@ onUnmounted(stopLifecycleEvents)
 
 ## 事件列表
 
-| 事件         | 触发时机                 | 典型用途           |
-| ------------ | ------------------------ | ------------------ |
-| `launch`     | 小程序首次启动           | 初始化一次性数据   |
-| `ready`      | SDK 可安全调用开放能力 | 标记 SDK 可用      |
-| `show`       | 小程序页面展示           | 刷新可见态数据     |
-| `hide`       | 小程序页面隐藏           | 暂停轮询、暂停播放 |
-| `unload`     | 当前小程序运行环境终止 | 清理资源并停止请求 |
-| `error`      | 小程序或开放能力运行异常 | 统一错误上报       |
-| `authChange` | 登录状态变化             | 刷新用户信息和权限 |
+| 事件                      | 触发时机                 | 典型用途                         |
+| ------------------------- | ------------------------ | -------------------------------- |
+| `launch`                  | 小程序首次启动           | 初始化一次性数据                 |
+| `ready`                   | SDK 可安全调用开放能力   | 标记 SDK 可用                    |
+| `show`                    | 小程序页面展示           | 刷新可见态数据                   |
+| `hide`                    | 小程序页面隐藏           | 暂停轮询、暂停播放               |
+| `unload`                  | 当前小程序运行环境终止   | 清理资源并停止请求               |
+| `error`                   | 小程序或开放能力运行异常 | 统一错误上报                     |
+| `heybox_app_login_change` | 黑盒 APP 登录状态变化    | 刷新依赖 Host 当前用户的本地能力 |
 
 完整载荷与事件名见：
 
@@ -229,7 +268,7 @@ onUnmounted(stopLifecycleEvents)
 
 - 初始化开放能力前先 `await ready()`。
 - UI 可见性相关逻辑放在 `show`、`hide`。
-- 用户状态不要只在页面加载时读一次，登录入口附近要监听 `authChange`。
+- 使用 Host current-user APIs 的无网络小程序，可以在 `heybox_app_login_change` 后刷新本地状态。已开通网络权限的小程序使用 `auth.login()` 获取 code，并由开发者服务端维护业务会话。
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
 - 事件只派发给注册当时存在的监听器，不会重放；一次性 `launch`/`ready` 状态应以 `ready()` Promise 为准。
 - 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
@@ -245,11 +284,7 @@ SDK 公开两类标准错误：
 - `HbMiniProgramNetworkError`：网络请求已返回，但 HTTP 状态未通过 `validateStatus`。
 
 ```ts
-import {
-  HbMiniProgramNetworkError,
-  HbMiniProgramSDKError,
-  network,
-} from '@heybox/hb-sdk'
+import { HbMiniProgramNetworkError, HbMiniProgramSDKError, network } from '@heybox/hb-sdk'
 
 try {
   await network.request({ url: 'https://api.example.com/data' })
@@ -272,6 +307,9 @@ try {
 
 - 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
 - 权限失败时给出可理解的提示，不要将它当成未登录。
+- `USER_GESTURE_REQUIRED` 表示潜在授权 UI 缺少可信用户手势，应让用户点击按钮后重试。
+- `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
+- `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
 - 超时或运行环境不可用时，允许用户重试或退出当前流程。
 - 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
@@ -282,16 +320,22 @@ try {
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
-type UserViewState =
-  | { status: 'ready'; user: Awaited<ReturnType<typeof hbSDK.user.getInfo>> }
+type LoginViewState =
+  | { status: 'ready' }
+  | { status: 'cancelled' }
   | { status: 'failed'; error: HbMiniProgramSDKError }
 
-async function loadUser(): Promise<UserViewState> {
+async function loginFromUserAction(): Promise<LoginViewState> {
   try {
     await hbSDK.ready()
-    return { status: 'ready', user: await hbSDK.user.getInfo() }
+    const result = await hbSDK.auth.login()
+    await exchangeCodeWithDeveloperServer(result.code)
+    return { status: 'ready' }
   } catch (error) {
     if (error instanceof HbMiniProgramSDKError) {
+      if (error.code === 'AUTHORIZATION_CANCELLED') {
+        return { status: 'cancelled' }
+      }
       reportSDKError(error.code, error.message, error.data)
       return { status: 'failed', error }
     }
@@ -300,39 +344,45 @@ async function loadUser(): Promise<UserViewState> {
   }
 }
 
-function reportSDKError(code: string, message: string, data?: unknown) {
-  console.log('[hb-sdk]', code, message, data)
+async function exchangeCodeWithDeveloperServer(code: string) {
+  await hbSDK.network.request({
+    url: 'https://api.example.com/session/heybox',
+    method: 'POST',
+    data: { code },
+  })
+}
+
+function reportSDKError(errorCode: string, message: string, data?: unknown) {
+  console.log('[hb-sdk]', errorCode, message, data)
 }
 ```
 
+授权码在取得后立即交给开发者服务端交换，不要写入页面状态、DOM、日志或持久化存储。UI 只处理服务端会话是否建立成功。
+
 ## Login gate recipe
 
 
-# 登录门禁
+# 服务端登录门禁
 
-当业务动作必须登录后才能继续时，可以把登录态判断收敛成 `ensureLogin`。
+已开通网络权限的小程序可以把“取得授权码并交给开发者服务端”收敛成一个用户操作函数：
 
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
-import type { MiniProgramUserInfo } from '@heybox/hb-sdk'
 
-export async function ensureLogin(): Promise<MiniProgramUserInfo | null> {
-  try {
-    await hbSDK.ready()
-
-    const current = await hbSDK.user.getInfo()
-    if (current.isLogin) {
-      return current.userInfo
-    }
+export async function createServerSessionFromUserAction() {
+  await hbSDK.ready()
 
-    const next = await hbSDK.auth.login()
-    return next.userInfo
+  try {
+    const { code } = await hbSDK.auth.login({ scopes: ['profile'] })
+    return await hbSDK.network.request({
+      url: 'https://api.example.com/session/heybox',
+      method: 'POST',
+      data: { code },
+    })
   } catch (error) {
-    if (error instanceof HbMiniProgramSDKError) {
-      console.log('[hb-sdk]', error.code, error.message)
-      return null
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return undefined
     }
-
     throw error
   }
 }
@@ -342,20 +392,16 @@ export async function ensureLogin(): Promise<MiniProgramUserInfo | null> {
 
 ```ts
 async function handleSubmit() {
-  const userInfo = await ensureLogin()
-  if (!userInfo) {
-    return
-  }
+  const session = await createServerSessionFromUserAction()
+  if (!session) return
 
-  // 继续执行需要登录的业务动作
+  // 继续执行需要开发者服务端身份的业务动作
 }
 ```
 
 ## 注意事项
 
-- 进入页面时可以用 `getInfo` 静默初始化 UI。
-- 用户主动点击登录、提交、收藏等动作时，再调用 `login`。
-- 登录态变化后，父容器应派发 `authChange`，页面可据此刷新用户相关 UI。
+完整授权契约见[用户身份与登录](/guide/auth)。本页只保留调用骨架。
 
 ## Community share recipe
 

package/skill/references/safety-boundaries.md

@@ -10,10 +10,16 @@
 
 ## 关键约束
 
-- `ready()` 不代表用户已登录；使用 `user.getInfo()` 判断登录状态。
-- `auth.login()` 只能由明确的用户操作触发，不要在页面初始化时自动登录。
+- `ready()` 只表示 SDK 可调用，不表示已取得用户授权。
+- `auth.login({ scopes? })` 只返回 `{ code, expiresIn: 300, scopes }`；identity 隐式强制包含，code 只能提交给开发者服务端。
+- 需要授权 UI 时，`auth.login()` 必须来自可信用户手势，否则返回 `USER_GESTURE_REQUIRED`；用户取消或关闭时返回 `AUTHORIZATION_CANCELLED`。已授权时可以静默返回新 code。
+- `user.getSteamGameList()` 仅供未开通网络权限的小程序通过 Host 读取；已开通网络权限时返回 `SERVER_API_REQUIRED`，且授权码与 OpenAPI 不提供 Steam 游戏库 scope 或资源接口。
+- 已开通网络权限时，公开的 `user.getInfo()` 和 `user.getLocalIdentity()` 返回 `SERVER_API_REQUIRED`；对应身份和资料数据应由开发者服务端通过 OpenAPI 获取。
+- 未开通网络权限时，只用 `user.getLocalIdentity()` 获取 `{ appUserId }`，不能获取 code 或调用 OpenAPI。
+- `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
 - 仅当远端已启用 `network.request` 且 `useOfficialDomain=true` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。
 - 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
@@ -23,7 +29,7 @@
 - Do not instruct mini-program code to read, extract, forward, store, or depend on token, cookie, phone number, or private credentials.
 - Negative safety statements that explain the SDK does not expose token/cookie/private credentials are correct and should be preserved.
 - Do not use raw share protocol fields, JS callbacks, activity reporting, direct post publishing, custom buttons, or upload-only flows. Public `share.*({ post })` options only preset an editable client post flow.
-- Do not use storage delete, clear, info listing, V2, or global Heybox client storage access.
+- Do not use storage delete, clear, info listing, or global Heybox client storage access.
 - Do not pass host-only protocol fields through `network.request`.
 - Do not build raw `postMessage` bridge flows in iframe business code.
 - Do not fetch deployed `dist/manifest.json` from business code; it is a build artifact for the release pipeline, not a CDN runtime asset.