@qoniai/qoni 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.2 - 2026-09-23
+
+### Fixed
+
+- Keep permission errors concise instead of appending every known scope.
+- Explain how to enable a permission policy when an AccessKey has no allowed
+  scopes. Preserve the backend error code and request ID for diagnosis.
+
+## 0.5.1 - 2026-09-23
+
+### Fixed
+
+- Recheck access-key scope policy at token exchange before every SDK product
+  operation, including repeated calls with the same delegation token. Removing
+  a scope now blocks the next SDK operation instead of leaving a cached product
+  token usable until expiry.
+
 ## 0.5.0 - 2026-09-17
 
 ### Added

package/README.md

@@ -727,7 +727,7 @@ All error classes are exported and can be matched with `instanceof`:
 | --- | --- | --- |
 | `QoniValidationError` | Local input check failed before any request (bad scope string, silent delegation missing a user). | Fix the call — the message states the correct form. |
 | `QoniAuthError` | AK/SK signing rejected by Qoni (bad/rotated credentials). | Check `accessKey` / `secretKey`. |
-| `QoniPermissionDeniedError` | The delegation token lacks a required scope (403). | Re-`delegateToken` with the missing scope. |
+| `QoniPermissionDeniedError` | The AccessKey or delegation token lacks a required scope (403). | Check the AccessKey permission policy and request the missing scope with `delegateToken`. |
 | `QoniTokenExpiredError` | The delegation / product token expired. | Mint a fresh token and retry. |
 | `QoniDelegationRequiredError` | A product call was made without `token`, or with a raw token the gateway won't accept directly. | Pass `delegation.data.token` to the product call. |
 | `QoniRateLimitError` | Rate limited (429). | Back off and retry (`retryable === true`). |
@@ -777,6 +777,7 @@ Common first-run errors:
 | --- | --- | --- |
 | `agent must be a string` | The online delegation API currently expects `agent` to be a string id. | Pass `agent: "memory-agent"` rather than an object. |
 | `eak.delegation.user_not_bound` | The `userId` is not in the GenAuth userpool bound to this Qoni credential. | Use a real user id from `currentUser` or from the same bound userpool. |
+| `eak.delegation.no_allowed_scopes` | The AccessKey has no permission scopes enabled. | In Qoni Console, open its Permission scope settings and enable the policy required by this call. |
 | `eak.genauth.userpool_binding_missing` | The AK/SK is not bound to a GenAuth userpool, so `genauth.users.*` cannot obtain a management token. | Bind the Qoni credential to the target GenAuth userpool before calling user management APIs. |
 | `eak.genauth.userpool_owner_missing` | The bound GenAuth userpool has no resolvable owner user for management-token signing. | Fix the GenAuth userpool owner data or binding. |
 | `eak.token_exchange.upstream_failed` with `unauthorized_client` or `grant_type is not enabled` | Delegation succeeded, but the managed delegation app is missing token-exchange grant support or has drifted from the tenant binding. | Repair the managed delegation app binding before calling GUMem or WebAgent product capabilities. |
@@ -788,6 +789,9 @@ Common first-run errors:
 - Keep Qoni AK/SK on trusted servers only.
 - Do not expose delegation tokens to untrusted clients.
 - Request the smallest useful scope set for each Agent action.
+- Product methods exchange the delegation token on every call, so a change to
+  the access key's allowed scopes is checked before the next SDK operation.
+  Product tokens already obtained outside the SDK remain valid until expiry.
 - Prefer `interactive` mode for browser control, site login, long-running monitors, and sensitive artifacts.
 - Store `auditId`, `requestId`, and `traceId` with product logs when later investigation matters.
 - Rotate AK/SK through Qoni Console if a credential might have been exposed.

package/README.zh-CN.md

@@ -657,7 +657,7 @@ type QoniEvent<T = unknown> = {
 | --- | --- | --- |
 | `QoniValidationError` | 请求发出前的本地校验失败（scope 字符串格式错、silent 委托缺 user）。 | 按消息修正调用——消息里给出正确写法。 |
 | `QoniAuthError` | AK/SK 签名被 Qoni 拒绝（凭据错误/已轮换）。 | 检查 `accessKey` / `secretKey`。 |
-| `QoniPermissionDeniedError` | delegation token 缺所需 scope（403）。 | 带上缺失 scope 重新 `delegateToken`。 |
+| `QoniPermissionDeniedError` | AccessKey 或 delegation token 缺少所需 scope（403）。 | 检查 AccessKey 权限策略，并在 `delegateToken` 中申请所需 scope。 |
 | `QoniTokenExpiredError` | delegation / 产品 token 过期。 | 重新 mint token 再试。 |
 | `QoniDelegationRequiredError` | 产品调用没带 `token`，或带的是网关不接受的裸 token。 | 把 `delegation.data.token` 传给产品调用。 |
 | `QoniRateLimitError` | 被限流（429）。 | 退避后重试（`retryable === true`）。 |
@@ -706,6 +706,7 @@ try {
 | --- | --- | --- |
 | `agent must be a string` | 当前线上 delegation API 期望 `agent` 是字符串 ID。 | 使用 `agent: "memory-agent"`，不要传对象。 |
 | `eak.delegation.user_not_bound` | `userId` 不属于该 Qoni credential 绑定的 GenAuth userpool。 | 使用 `currentUser` 返回的真实用户 ID，或确认用户来自同一个绑定 userpool。 |
+| `eak.delegation.no_allowed_scopes` | AccessKey 没有启用任何权限 scope。 | 在 Qoni Console 的 Permission scope 设置中启用本次调用所需的策略。 |
 | `eak.genauth.userpool_binding_missing` | AK/SK 没有绑定 GenAuth userpool，`genauth.users.*` 无法换取 management token。 | 先把 Qoni credential 绑定到目标 GenAuth userpool。 |
 | `eak.genauth.userpool_owner_missing` | 绑定的 GenAuth userpool 找不到可用于签发 management token 的 owner 用户。 | 修复 GenAuth userpool owner 数据或绑定。 |
 | `eak.token_exchange.upstream_failed` 且包含 `unauthorized_client` 或 `grant_type is not enabled` | Delegation 已成功，但 managed delegation app 缺少 token-exchange grant，或租户绑定发生漂移。 | 先修复 managed delegation app 绑定，再调用 GUMem 或 WebAgent 产品能力。 |
@@ -717,6 +718,8 @@ try {
 - AK/SK 只保存在可信服务端。
 - 不要把 delegation token 暴露给不可信客户端。
 - 每次 Agent 行动只申请必要 scope。
+- SDK 的产品方法每次调用前都会重新兑换 delegation token，因此 AccessKey 的 scope
+  变更会在下一次 SDK 调用前重新校验。已经在 SDK 外取得的产品 token 仍会持续有效至过期。
 - 浏览器接管、站点登录、长期监控、敏感产物访问优先使用 `interactive`。
 - 在业务日志中记录 `auditId`、`requestId`、`traceId`，方便后续审计。
 - 如果怀疑 AK/SK 泄露，应在 Qoni Console 中轮换密钥。

package/dist/index.cjs

@@ -104,81 +104,6 @@ function buildSignedHeaders(credentials, method, pathname, payload) {
   return headers;
 }
 
-// src/scopes.ts
-var QoniScopes = {
-  GUMEM_SESSION_CREATE: "gumem.session:create",
-  GUMEM_MESSAGE_WRITE: "gumem.message:write",
-  GUMEM_MEMORY_READ: "gumem.memory:read",
-  GUMEM_MEMORY_WRITE: "gumem.memory:write",
-  GUMEM_MEMORY_DELETE: "gumem.memory:delete",
-  GUMEM_SEARCH_RUN: "gumem.search:run",
-  GUMEM_ADMIN_MANAGE: "gumem.admin:manage",
-  GUMEM_RESOURCE_WRITE: "gumem.resource:write",
-  GUMEM_ACTION_WRITE: "gumem.action:write",
-  GUMEM_ACTION_READ: "gumem.action:read",
-  GUMEM_PROFILE_READ: "gumem.profile:read",
-  // WebAgent products: exactly two verbs per product — `read` (observe) and
-  // `manage` (anything that changes execution state). See
-  // wa/docs/qoni-sdk-public-surface.md §3.
-  DO_ANYTHING_READ: "webagent.do_anything:read",
-  DO_ANYTHING_MANAGE: "webagent.do_anything:manage",
-  WEB_SEARCH_READ: "webagent.web_search:read",
-  WEB_SEARCH_MANAGE: "webagent.web_search:manage",
-  DEEP_RESEARCH_READ: "webagent.deep_research:read",
-  DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage",
-  TRACK_READ: "webagent.track:read",
-  TRACK_MANAGE: "webagent.track:manage"
-};
-var QoniProductScopes = {
-  doAnything: [
-    QoniScopes.DO_ANYTHING_READ,
-    QoniScopes.DO_ANYTHING_MANAGE
-  ],
-  webSearch: [
-    QoniScopes.WEB_SEARCH_READ,
-    QoniScopes.WEB_SEARCH_MANAGE
-  ],
-  deepResearch: [
-    QoniScopes.DEEP_RESEARCH_READ,
-    QoniScopes.DEEP_RESEARCH_MANAGE
-  ],
-  track: [
-    QoniScopes.TRACK_READ,
-    QoniScopes.TRACK_MANAGE
-  ]
-};
-var KNOWN_SCOPES = Object.values(QoniScopes);
-var QoniScopeBundles = {
-  GUMEM_READONLY: [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_PROFILE_READ],
-  GUMEM_SESSION_RECALL: [
-    QoniScopes.GUMEM_MEMORY_READ,
-    QoniScopes.GUMEM_MEMORY_WRITE,
-    QoniScopes.GUMEM_MESSAGE_WRITE
-  ],
-  GUMEM_WRITE: [
-    QoniScopes.GUMEM_SESSION_CREATE,
-    QoniScopes.GUMEM_MESSAGE_WRITE,
-    QoniScopes.GUMEM_ACTION_WRITE
-  ],
-  // One bundle per WebAgent product = [read, manage].
-  DO_ANYTHING: [
-    QoniScopes.DO_ANYTHING_READ,
-    QoniScopes.DO_ANYTHING_MANAGE
-  ],
-  WEB_SEARCH: [
-    QoniScopes.WEB_SEARCH_READ,
-    QoniScopes.WEB_SEARCH_MANAGE
-  ],
-  DEEP_RESEARCH: [
-    QoniScopes.DEEP_RESEARCH_READ,
-    QoniScopes.DEEP_RESEARCH_MANAGE
-  ],
-  TRACK: [
-    QoniScopes.TRACK_READ,
-    QoniScopes.TRACK_MANAGE
-  ]
-};
-
 // src/types.ts
 function isJsonObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -262,7 +187,7 @@ function errorFromPayload(status, payload, fallbackMessage) {
   const source = detailObject || (isJsonObject(payload) ? payload : {});
   const code = stringField(source, "code") || stringField(source, "apiCode") || statusCodeToCode(status);
   const rawMessage = stringField(source, "message") || stringField(source, "detail") || fallbackMessage;
-  const message = appendOnboardingHint(
+  const message = code === "eak.delegation.no_allowed_scopes" ? "This AccessKey has no permission scopes. In Qoni Console, open its Permission scope settings, enable the policy needed for this call, then retry." : appendOnboardingHint(
     appendDeniedScopes(appendUpstreamDescription(rawMessage, source), source),
     code
   );
@@ -279,7 +204,7 @@ function errorFromPayload(status, payload, fallbackMessage) {
   if (isDelegationRequired(code)) return new QoniDelegationRequiredError(message, options);
   if (status === 401) return new QoniAuthError(message, options);
   if (status === 403 || isPermissionDenied(code)) {
-    return new QoniPermissionDeniedError(appendKnownScopes(message), options);
+    return new QoniPermissionDeniedError(message, options);
   }
   if (status === 400 || status === 422) return new QoniValidationError(message, options);
   if (status === 429) return new QoniRateLimitError(message, options);
@@ -314,17 +239,14 @@ function appendUpstreamDescription(message, source) {
 }
 var ONBOARDING_HINTS = {
   "eak.delegation.user_not_bound": "Hint: the userId is not in the GenAuth userpool bound to this credential. Resolve a real user with qoni.resolveAnyBoundUser() (demo/smoke) or qoni.currentUser({ accessToken }).",
-  "eak.genauth.userpool_binding_missing": "Hint: bind the Qoni credential to a GenAuth userpool before calling genauth.users.*."
+  "eak.genauth.userpool_binding_missing": "Hint: bind the Qoni credential to a GenAuth userpool before calling genauth.users.*.",
+  "eak.delegation.scope_not_allowed": "Hint: enable the denied scopes in this AccessKey's Permission scope settings in Qoni Console."
 };
 function appendOnboardingHint(message, code) {
   const hint = ONBOARDING_HINTS[code];
   if (!hint || message.includes(hint)) return message;
   return `${message} ${hint}`;
 }
-function appendKnownScopes(message) {
-  if (message.includes("Known scopes:")) return message;
-  return `${message} (Known scopes: ${KNOWN_SCOPES.join(", ")})`;
-}
 function statusCodeToCode(status) {
   if (status === 401) return "auth.failed";
   if (status === 403) return "permission_denied";
@@ -1488,6 +1410,81 @@ function createQoniNamespace(_transport, delegateToken, completeDelegateToken) {
   };
 }
 
+// src/scopes.ts
+var QoniScopes = {
+  GUMEM_SESSION_CREATE: "gumem.session:create",
+  GUMEM_MESSAGE_WRITE: "gumem.message:write",
+  GUMEM_MEMORY_READ: "gumem.memory:read",
+  GUMEM_MEMORY_WRITE: "gumem.memory:write",
+  GUMEM_MEMORY_DELETE: "gumem.memory:delete",
+  GUMEM_SEARCH_RUN: "gumem.search:run",
+  GUMEM_ADMIN_MANAGE: "gumem.admin:manage",
+  GUMEM_RESOURCE_WRITE: "gumem.resource:write",
+  GUMEM_ACTION_WRITE: "gumem.action:write",
+  GUMEM_ACTION_READ: "gumem.action:read",
+  GUMEM_PROFILE_READ: "gumem.profile:read",
+  // WebAgent products: exactly two verbs per product — `read` (observe) and
+  // `manage` (anything that changes execution state). See
+  // wa/docs/qoni-sdk-public-surface.md §3.
+  DO_ANYTHING_READ: "webagent.do_anything:read",
+  DO_ANYTHING_MANAGE: "webagent.do_anything:manage",
+  WEB_SEARCH_READ: "webagent.web_search:read",
+  WEB_SEARCH_MANAGE: "webagent.web_search:manage",
+  DEEP_RESEARCH_READ: "webagent.deep_research:read",
+  DEEP_RESEARCH_MANAGE: "webagent.deep_research:manage",
+  TRACK_READ: "webagent.track:read",
+  TRACK_MANAGE: "webagent.track:manage"
+};
+var QoniProductScopes = {
+  doAnything: [
+    QoniScopes.DO_ANYTHING_READ,
+    QoniScopes.DO_ANYTHING_MANAGE
+  ],
+  webSearch: [
+    QoniScopes.WEB_SEARCH_READ,
+    QoniScopes.WEB_SEARCH_MANAGE
+  ],
+  deepResearch: [
+    QoniScopes.DEEP_RESEARCH_READ,
+    QoniScopes.DEEP_RESEARCH_MANAGE
+  ],
+  track: [
+    QoniScopes.TRACK_READ,
+    QoniScopes.TRACK_MANAGE
+  ]
+};
+var KNOWN_SCOPES = Object.values(QoniScopes);
+var QoniScopeBundles = {
+  GUMEM_READONLY: [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_PROFILE_READ],
+  GUMEM_SESSION_RECALL: [
+    QoniScopes.GUMEM_MEMORY_READ,
+    QoniScopes.GUMEM_MEMORY_WRITE,
+    QoniScopes.GUMEM_MESSAGE_WRITE
+  ],
+  GUMEM_WRITE: [
+    QoniScopes.GUMEM_SESSION_CREATE,
+    QoniScopes.GUMEM_MESSAGE_WRITE,
+    QoniScopes.GUMEM_ACTION_WRITE
+  ],
+  // One bundle per WebAgent product = [read, manage].
+  DO_ANYTHING: [
+    QoniScopes.DO_ANYTHING_READ,
+    QoniScopes.DO_ANYTHING_MANAGE
+  ],
+  WEB_SEARCH: [
+    QoniScopes.WEB_SEARCH_READ,
+    QoniScopes.WEB_SEARCH_MANAGE
+  ],
+  DEEP_RESEARCH: [
+    QoniScopes.DEEP_RESEARCH_READ,
+    QoniScopes.DEEP_RESEARCH_MANAGE
+  ],
+  TRACK: [
+    QoniScopes.TRACK_READ,
+    QoniScopes.TRACK_MANAGE
+  ]
+};
+
 // src/genauth.ts
 function createGenAuthNamespace(transport, options = {}) {
   return {
@@ -2114,7 +2111,6 @@ var Qoni = class {
   secretKey;
   host;
   runtimeConfigPromise;
-  productTokenCache = /* @__PURE__ */ new Map();
   genAuthAdminTokenCache;
   gumem;
   genauth;
@@ -2585,9 +2581,6 @@ var Qoni = class {
     const runtimeToken = requiredRuntimeToken(token);
     if (!isQoniDelegationToken(runtimeToken)) return runtimeToken;
     const scopes = [...requiredScopes || []].sort();
-    const cacheKey = [service, runtimeToken, scopes.join(" ")].join(":");
-    const cached = this.productTokenCache.get(cacheKey);
-    if (cached && cached.expiresAt > Date.now() + 3e4) return cached.token;
     const response = await this.signedPost("/api/v3/eak/token-exchange", {
       subjectToken: runtimeToken,
       resource: service === "gumem" ? "gumem" : "webagent",
@@ -2602,10 +2595,6 @@ var Qoni = class {
         "Qoni product token exchange response did not include an access token"
       );
     }
-    this.productTokenCache.set(cacheKey, {
-      token: accessToken,
-      expiresAt: Date.now() + Math.max(0, readExpiresIn(payload) ?? 3600) * 1e3
-    });
     return accessToken;
   }
   async genauthAdminTokenFor() {