@qoniai/qoni 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.8.0 - Unreleased
+
+### Added
+
+- `qoni.genauth.delegateAgent(input)` returns the grant directly (`grant.token`),
+  or an interactive authorization request, through the existing signed endpoint.
+- `agentKey` is an alias for `agent`. Existing root and `qoni.qoni` entries keep
+  their `QoniResponse` envelopes. Conflicting Agent labels are rejected;
+  the existing top-level `userId` precedence is unchanged.
+
+### Fixed
+
+- Expiry strings such as `"15m"` are converted to integer seconds; valid
+  durations are 60–86400 seconds, matching the GenAuth DTO.
+- Unsupported `deniedScopes` is rejected rather than forwarding an unenforced
+  deny policy. Legacy `mailbox.*`, `web.search`, and `web.extract` scopes are rejected without mapping to product scopes.
+
+### Changed
+
+- Expiry validation now happens locally before signing. Invalid formats and
+  values outside 60–86400 seconds throw `QoniValidationError`; numeric seconds
+  strings are sent as integers.
+
 ## 0.7.0 - 2026-10-02
 
 ### Changed
@@ -136,8 +159,8 @@ compatible fixes.
 
 ### Changed
 
-- The default Qoni host is now `https://dashboard.qoni.ai` (was
-  `https://anima.eazo.ai/dashboard`). Callers that never passed an explicit `host`
+- The default Qoni host is now `https://dashboard.qoni.ai`.
+  Callers that never passed an explicit `host`
   reach a different control plane after upgrading. Note that the new default has
   no `/dashboard` path segment — pass `host` explicitly for private or local
   deployments.

package/README.md

@@ -251,7 +251,7 @@ Silent product calls receive `token: delegation.data.token`. If that token is an
 
 - **Silent** (`mode: "silent"`, the default) — acts for one end user, so a user
   is **required**: pass `user: { id: <genauthUserId> }` (preferred) or the
-  deprecated top-level `userId`. Omitting it throws `QoniValidationError`
+  top-level `userId`. Omitting it throws `QoniValidationError`
   locally before any request. Authorize with the `products` sugar and/or
   explicit `scopes`.
 - **Interactive** (`mode: "interactive"`) — pass `redirectUri`, `state`,
@@ -306,7 +306,35 @@ await qoni.gumem.recall({
 });
 ```
 
-`completeDelegateToken` is the recommended server callback helper. `delegateAgent` and `completeDelegateAgent` remain as deprecated compatibility names, but the current callback contract is `{ grantId, code, state }`; old `{ code, state }` completion is not supported.
+`completeDelegateToken` is the recommended server callback helper. Root `qoni.delegateAgent` and `qoni.completeDelegateAgent` remain as deprecated compatibility names, but the current callback contract is `{ grantId, code, state }`; old `{ code, state }` completion is not supported.
+
+## Original delegation style (0.8.0, unreleased)
+
+```ts
+const grant = await qoni.genauth.delegateAgent({
+  userId: process.env.QONI_USER_ID!, // The current user's GenAuth ID
+  agentKey: "email-assistant", // Agent audit label; alias for agent
+  scopes: [
+    "webagent.do_anything:read", // Read status, events, and artifacts
+    "webagent.do_anything:manage", // Start/cancel tasks and respond to interactions
+  ],
+  expiresIn: "15m", // Converted to 900 seconds before signing
+});
+console.log(grant.grantId, grant.auditId);
+```
+
+This entry returns the grant directly; root `delegateToken` still returns
+`QoniResponse`, with the token in `response.data.token`. Interactive mode returns
+the authorization request directly; use `completeDelegateToken()` in the server
+callback after consent. `agentKey` aliases `agent`; both labels must agree when
+supplied together. Top-level `userId` retains precedence over `user.id`.
+Expiry accepts integer seconds or whole-number
+`s/m/h/d` durations, between 60 and 86400 seconds. Until published, use the 0.8.0
+source build for these additions.
+
+Legacy `mailbox.*`, `web.search`, and `web.extract` scopes, and `deniedScopes`, are unsupported and rejected.
+They are never expanded into broader product permissions. Product scopes do not
+prohibit email sending or deletion; a prompt is not an enforced deny policy.
 
 ## Choosing Scopes
 

package/README.zh-CN.md

@@ -227,7 +227,7 @@ silent 产品能力方法传入 `token: delegation.data.token`。如果这个 to
 
 **入参形态。** `delegateToken` 用 `mode` 判别：
 
-- **Silent**（`mode: "silent"`，默认）——代表某个终端用户,所以 user **必填**：传 `user: { id: <genauthUserId> }`（推荐）或已废弃的顶层 `userId`。不传会在请求发出前本地抛 `QoniValidationError`。授权用 `products` 语法糖和/或显式 `scopes`。
+- **Silent**（`mode: "silent"`，默认）——代表某个终端用户,所以 user **必填**：传 `user: { id: <genauthUserId> }`（推荐）或顶层 `userId`。不传会在请求发出前本地抛 `QoniValidationError`。授权用 `products` 语法糖和/或显式 `scopes`。
 - **Interactive**（`mode: "interactive"`）——传 `redirectUri`、`state`、`agent`、`scopes`，**不传** user（Qoni Console 在授权时解析登录）。返回 `data.authorizationUrl` 而非 token；在服务端用 `completeDelegateToken({ grantId, code, state })` 完成。
 
 `agent` 可选，默认 `"sdk"`。
@@ -277,7 +277,32 @@ await qoni.gumem.recall({
 });
 ```
 
-`completeDelegateToken` 是推荐的服务端 callback helper。`delegateAgent` 和 `completeDelegateAgent` 仍保留为 deprecated 兼容命名，但当前 callback 契约是 `{ grantId, code, state }`；旧的 `{ code, state }` complete 签名不再兼容。
+`completeDelegateToken` 是推荐的服务端 callback helper。顶层 `qoni.delegateAgent` 和 `qoni.completeDelegateAgent` 仍保留为 deprecated 兼容命名，但当前 callback 契约是 `{ grantId, code, state }`；旧的 `{ code, state }` complete 签名不再兼容。
+
+## 原始委托写法（0.8.0，尚未发布）
+
+```ts
+const grant = await qoni.genauth.delegateAgent({
+  userId: process.env.QONI_USER_ID!, // 当前用户的 GenAuth ID
+  agentKey: "email-assistant", // Agent 审计标签，兼容 agent 参数
+  scopes: [
+    "webagent.do_anything:read", // 读取任务状态、事件和产物
+    "webagent.do_anything:manage", // 启动、取消任务和提交交互响应
+  ],
+  expiresIn: "15m", // 签名前转换为 900 秒
+});
+console.log(grant.grantId, grant.auditId);
+```
+
+此入口直接返回 grant；顶层 `delegateToken` 仍返回 `QoniResponse`，token 在
+`response.data.token` 中。交互式模式直接返回授权请求；用户同意后，在服务端回调
+用 `completeDelegateToken()` 兑换 token。`agentKey`、`userId` 分别兼容 `agent`、
+`user.id`；同时提供两个 Agent 标签时必须一致，顶层 `userId` 保持原有的优先级。
+有效期支持整数秒或整数 `s/m/h/d` 时长，
+范围为 60–86400 秒。这些新增能力在发布前需要使用 0.8.0 源码构建。
+
+旧版 `mailbox.*`、`web.search`、`web.extract` scope 和 `deniedScopes` 不受支持，SDK 会拒绝，不会将它们
+扩展成更宽的产品权限。产品 scope 不限制发送、删除邮件；任务描述不能代替禁止策略。
 
 ## Scope 怎么选
 

package/dist/index.cjs

@@ -1612,7 +1612,14 @@ function createQoniNamespace(_transport, delegateToken, completeDelegateToken) {
 
 // src/genauth.ts
 function createGenAuthNamespace(transport, options = {}) {
+  async function delegateAgent(input) {
+    if (!options.delegateTokenFor) {
+      throw new QoniValidationError("GenAuth delegateAgent requires a Qoni delegation provider");
+    }
+    return (await options.delegateTokenFor(input)).data;
+  }
   return {
+    delegateAgent,
     userInfo: (input) => transport.genauthJson("GET", "/oidc/me", input.accessToken),
     jwks: () => transport.genauthJson("GET", "/oidc/.well-known/jwks.json"),
     discovery: () => transport.genauthJson("GET", "/oidc/.well-known/openid-configuration"),
@@ -2248,7 +2255,8 @@ var Qoni = class {
       webAgentSSE: (...args) => this.webAgentSSE(...args)
     };
     this.genauth = createGenAuthNamespace(transport, {
-      adminTokenFor: () => this.genauthAdminTokenFor()
+      adminTokenFor: () => this.genauthAdminTokenFor(),
+      delegateTokenFor: (input) => this.delegateToken(input)
     });
     this.qoni = createQoniNamespace(
       transport,
@@ -2961,19 +2969,43 @@ function toRecord(value) {
 }
 function normalizeDelegateTokenInput(input) {
   const body = toRecord(input);
+  if (input.deniedScopes !== void 0) {
+    throw new QoniValidationError(
+      "delegateToken: deniedScopes is not supported by the delegation service. Do not rely on this field to prevent mailbox or browser actions."
+    );
+  }
+  if (input.agent !== void 0 && input.agentKey !== void 0 && input.agent !== input.agentKey) {
+    throw new QoniValidationError("delegateToken: agent and agentKey must identify the same Agent");
+  }
   if (!body.userId && isJsonObject(input.user) && typeof input.user.id === "string") {
     body.userId = input.user.id;
   }
   if (input.mode !== "interactive" && !body.userId) {
     throw new QoniValidationError(
-      'delegateToken: silent mode requires a user \u2014 pass `user: { id: <genauthUserId> }` (or the deprecated top-level `userId`). Interactive mode (`mode: "interactive"`) does not need one.'
+      'delegateToken: silent mode requires a user \u2014 pass `user: { id: <genauthUserId> }` (or the top-level `userId`). Interactive mode (`mode: "interactive"`) does not need one.'
     );
   }
-  body.agent = input.agent ?? "sdk";
+  body.agent = input.agent ?? input.agentKey ?? "sdk";
+  delete body.agentKey;
+  if (input.expiresIn !== void 0) body.expiresIn = delegationDurationSeconds(input.expiresIn);
   body.scopes = resolveDelegationScopes(input.scopes, input.products);
   delete body.products;
   return body;
 }
+function delegationDurationSeconds(value) {
+  let seconds = value;
+  if (typeof value === "string") {
+    const duration = /^(\d+)(s|m|h|d)?$/.exec(value);
+    const units = { s: 1, m: 60, h: 3600, d: 86400 };
+    seconds = duration ? Number(duration[1]) * units[duration[2] ?? "s"] : NaN;
+  }
+  if (typeof seconds !== "number" || !Number.isInteger(seconds) || seconds < 60 || seconds > 86400) {
+    throw new QoniValidationError(
+      'delegateToken: expiresIn must be 60\u201386400 integer seconds or a whole-number duration such as "15m"'
+    );
+  }
+  return seconds;
+}
 function resolveDelegationScopes(scopes, products) {
   const resolved = /* @__PURE__ */ new Set();
   for (const product of products ?? []) {
@@ -2997,6 +3029,11 @@ function resolveDelegationScopes(scopes, products) {
   return [...resolved];
 }
 function validateScopeFormat(scope) {
+  if (scope.startsWith("mailbox.") || scope === "web.search" || scope === "web.extract") {
+    throw new QoniValidationError(
+      `delegateToken: legacy action scope "${scope}" has no enforced mapping in this delegation service. It will not be expanded into broader product permissions.`
+    );
+  }
   if (KNOWN_SCOPES.includes(scope)) return;
   const prefixed = KNOWN_SCOPES.find((known) => known.endsWith(`.${scope}`) || known === `webagent.${scope}`);
   if (prefixed) {