iflow-engine-base 3.9.20 → 3.9.21

package/README.md

@@ -22,10 +22,128 @@ import { createEngine } from 'iflow-engine-base';
 ```javascript
 const engine = createEngine({
   container: document.getElementById('app'),
+  sdkAuth: {
+    endpoint: 'https://api.example.com/openapi',
+    token: 'sdk_token_xxx'
+  },
   // ... other options
 });
 ```
 
+`sdkAuth` 现在是必填项。不传时，SDK 会直接拒绝初始化。
+
+推荐生产环境由你自己的后端先使用 `AppId/AppKey/AppSecret` 调用 `POST /openapi/oauth/sdk-token`，再把短期 `sdkToken` 下发给浏览器。开发联调时也可以直接给 `sdkAuth.appId/appKey/appSecret`，但不建议在公网前端长期暴露 `AppSecret`。
+
+### `sdkAuth.appId/appKey/appSecret` 认证方式说明
+
+当你这样传参时：
+
+```ts
+const engine = await createEngine({
+  containerId: 'viewer',
+  sdkAuth: {
+    endpoint: 'https://api.example.com/openapi',
+    appId: 'app_xxx',
+    appKey: 'key_xxx',
+    appSecret: 'sk_xxx'
+  }
+});
+```
+
+SDK 内部会自动执行两步：
+
+1. 调用 `POST /openapi/oauth/sdk-token/secure`
+   SDK 先使用 `appSecret` 计算密钥材料，再结合当前 UTC 年月日、时间戳、nonce 派生当日密钥，对 `appKey/appSecret` 做 AES-GCM 加密后发给服务端
+2. 调用 `POST /openapi/oauth/sdk-verify`
+   使用上一步返回的 `sdkToken` 做二次校验，校验通过后才继续初始化引擎
+
+服务端收到后，会：
+
+1. 按明文 `appId` 找到应用
+2. 读取平台保存的安全密钥材料
+3. 按同一天的日期重新派生密钥并解密
+4. 解密出 `appKey/appSecret` 后，再走原有的应用凭证校验
+5. 校验通过才签发短期 `sdkToken`
+
+也就是说，`sdkAuth.appId/appKey/appSecret` 本质上仍然是“SDK 代替你的服务端去换票”，但传输时不再直接明文发送 `appKey/appSecret`。
+
+补充说明：
+
+- `appId` 仍然会明文发送，因为服务端必须先知道是哪个应用，才能取出对应的安全材料解密
+- 当前年月日已经参与密钥派生
+- 同时还加入了时间戳和 `nonce`，避免“只有日期、整天可重放”的问题
+- 老应用如果是在这套安全方案上线前创建的，需要先在控制台重置一次 `AppSecret`，让平台补齐安全密钥材料后才能使用该模式
+
+适用场景：
+
+- 本地开发
+- 内网环境联调
+- 受控测试环境
+
+不建议用于公网生产前端，原因是：
+
+- `AppSecret` 会下发到浏览器
+- 用户可以在 DevTools、抓包工具或源码中拿到密钥
+- 一旦泄露，第三方可以伪造你的应用去申请新的 `sdkToken`
+
+生产环境推荐方式：
+
+1. 你的业务后端安全保存 `AppId/AppKey/AppSecret`
+2. 业务后端调用 `POST /openapi/oauth/sdk-token`
+3. 业务后端把短期 `sdkToken` 返回给前端
+4. 前端 SDK 只传 `sdkAuth.token`
+
+这样浏览器侧永远不会接触 `AppSecret`，安全边界才是正确的。
+
+### 权限与校验结果
+
+- 运营后台现在只给团队成员配置引擎权限，如 `3d`、`2d`、`720`、`gis`、`gaussian`
+- OpenAPI 在签发 `sdkToken`，以及后续执行 `sdk-verify` 时，都会重新计算当前有效权限：
+  - `effectiveScopes = 应用 scopes`
+  - `effectiveEnginePermissions = 成员引擎权限`
+- 这意味着：
+  - 去掉成员的某个引擎权限后，即使 `appKey/appSecret` 正确，也不能再初始化对应引擎
+- `POST /openapi/oauth/sdk-verify` 的返回会带上 `enginePermissions`，可作为当前 SDK 会话最终生效引擎权限的结果。
+
+### 使用 viewToken 加载
+
+除了原有的 URL 加载方式，现在还支持通过 `viewToken` 让 SDK 自行去 OpenAPI 解析真实加载地址：
+
+```ts
+const engine = await createEngine({
+  containerId: 'viewer',
+  sdkAuth: {
+    endpoint: 'https://api.example.com/openapi',
+    token: 'sdk_token_xxx'
+  }
+});
+
+await engine.loadModelByViewToken('vt_xxx');
+```
+
+目前支持的方法：
+
+- `createEngine(...).loadModelByViewToken(viewToken, options?)`
+- `createEngine2d(...).loadModelByViewToken(viewToken, options?)`
+- `createEngineGIS(...).loadModelByViewToken(viewToken, options?)`
+- `createEngineGaussian(...).loadModelByViewToken(viewToken, options?)`
+- `createEngine720(...).loadPanoramaByViewToken(viewToken)`
+
+SDK 会自动请求 `POST /openapi/models/view-token/resolve`，并带上：
+
+- `sdkToken`
+- `viewToken`
+- `engineType`
+
+服务端会同时校验：
+
+- `sdkToken` 是否有效
+- 当前应用是否仍具备 `sdk:use`
+- 当前成员是否仍具备对应引擎权限
+- `viewToken` 所属模型是否与当前 `sdkToken` 对应的是同一个应用
+
+最后这一条是强制限制：A 应用的 `sdkToken` 不能去解析 B 应用下的 `viewToken`。
+
 ## Important Notes
 
 - CSS样式已自动包含，无需手动导入

package/dist/bim-engine-sdk.es.js

@@ -1,5 +1,5 @@
-import { s as t } from "./chunks/sdk-assets-F7qFhuao.js";
-import { g as f, r as u } from "./chunks/sdk-assets-F7qFhuao.js";
+import { s as t } from "./chunks/sdk-assets-1SXx8Tbf.js";
+import { g as f, r as u } from "./chunks/sdk-assets-1SXx8Tbf.js";
 const i = {
   Initialized: "gis:initialized",
   CameraChanged: "gis:camera-changed",
@@ -16,27 +16,27 @@ function r(e) {
 }
 async function d(e) {
   r(e);
-  const { EngineKernelV2: n } = await import("./chunks/engine-3d-CeUaONqH.js").then((a) => a.E);
+  const { EngineKernelV2: n } = await import("./chunks/engine-3d-CdsLfd0i.js").then((a) => a.E);
   return new n(e);
 }
 async function o(e) {
   r(e);
-  const { EngineKernel2d: n } = await import("./chunks/engine-2d-mQsokiAx.js").then((a) => a.a);
+  const { EngineKernel2d: n } = await import("./chunks/engine-2d-DAiE1uAy.js").then((a) => a.a);
   return new n(e);
 }
 async function c(e) {
   r(e);
-  const { EngineKernel720: n } = await import("./chunks/engine-720-BrYzIaAW.js");
+  const { EngineKernel720: n } = await import("./chunks/engine-720-K9uF9wMA.js");
   return new n(e);
 }
 async function g(e) {
   r(e);
-  const { EngineKernelGaussian: n } = await import("./chunks/engine-gaussian-BDphGvln.js");
+  const { EngineKernelGaussian: n } = await import("./chunks/engine-gaussian-x3jsCp15.js");
   return new n(e);
 }
 async function l(e) {
   r(e);
-  const { EngineKernelGIS: n } = await import("./chunks/engine-gis-nj5ISJb2.js");
+  const { EngineKernelGIS: n } = await import("./chunks/engine-gis-BStgPU0Q.js");
   return new n(e);
 }
 export {