@acosmi/sdk-ts 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -9,6 +9,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.4.0] — 2026-05-21
+
+> csign `/login` Web OAuth 接入复核审计（`docs/audit/csign-login-oauth-audit-result-2026-05-21`）
+> Phase A：在 SDK 增补浏览器 Web OAuth 原语。本版本为**纯增量、向后兼容**——
+> 不改任何既有导出符号的签名或行为，桌面 loopback `login()` 流程完全不受影响。
+
+### Added
+
+- **`discoverWebOAuthMetadata(serverURL, signal?)`** — 发现 Web OAuth 服务元数据，
+  请求 `/.well-known/oauth-authorization-server/web`。与既有 `discover()`
+  （`/desktop`）共用内部 `discoverWithProfile(serverURL, profile, signal?)`，URL 解析、
+  fetch、错误处理与字段校验完全一致。`discoverWithProfile` 与
+  `OAuthMetadataProfile`（`'web' | 'desktop'`）一并导出。
+- **`registerWebOAuthClient(meta, opts, signal?)`** — 动态注册浏览器 Web OAuth
+  客户端。与 `register()`（桌面 loopback，硬编码 `redirect_uri=127.0.0.1`）的区别在于
+  允许传入任意 Web `redirectURIs`；`opts = { clientName, redirectURIs, scopes? }`，
+  注册体 `token_endpoint_auth_method: 'none'`、
+  `grant_types: ['authorization_code','refresh_token']`、`response_types: ['code']`，
+  接受 HTTP 200/201。
+- **`createWebAuthorizationRequest(meta, opts)`** — 构造 Web OAuth 授权请求：生成
+  PKCE verifier + S256 challenge + CSRF `state`，按 OAuth 2.1 拼装 authUrl
+  （`response_type=code`、`code_challenge_method=S256`、`state`、空格连接的 `scope`、
+  可选 `login_hint`）。返回 `WebAuthorizationRequest`
+  （`{ authUrl, state, verifier, clientID, redirectURI, serverURL, createdAt }`），
+  发起方应整体持久化为 pending 状态。
+- **`completeWebAuthorizationRequest(pending, params, signal?)`** — 完成 Web OAuth：
+  校验 `params.state === pending.state`（CSRF 防护，不匹配抛 `ErrStateMismatch`），
+  依次 `discoverWebOAuthMetadata` → `exchangeCode` → `newTokenSet`，返回可持久化的
+  `TokenSet`。
+- **`generateState()`** — 生成 32 字节加密随机 `state`（base64url 无填充），与
+  `generateCodeVerifier` 共用随机源。
+- **`ErrStateMismatch`（`'state_mismatch'`）** — Web OAuth callback `state` 不匹配
+  错误码，加入 `LoginErrCode` 联合类型。
+- **`Config.oauthMetadataProfile?: 'web' | 'desktop'`** — 新增客户端配置项，决定
+  **所有 token 生命周期的 metadata 发现**走哪个 well-known 端点，覆盖
+  `ensureToken()` 刷新、`forceRefresh()`（401 强制刷新）以及 `logout()` 吊销
+  （revoke）三条路径——不止 `ensureToken`。默认 `'desktop'`，未设置时对既有调用方
+  零影响；浏览器 Web OAuth 签发的 token 其 refresh / revoke 必须走 Web token /
+  revocation 端点，否则会打到桌面 loopback 端点导致刷新失败或吊销无效，故 csign 等
+  Web 应用应显式配 `'web'`。`login()` 桌面 loopback 授权路径仍固定走 `'desktop'`
+  发现，不受此配置影响。
+
+---
+
 ## [1.3.2] — 2026-05-20
 
 > 生产闭环实施计划（`Acosmi-Compliance-SDK-Csign-PC-CrabCode-生产闭环实施计划-2026-05-20`）

package/dist/browser/index.mjs

@@ -1056,7 +1056,7 @@ init_adapters();
 
 // src/auth.ts
 var authTimeoutMs = 3e4;
-async function discover(serverURL, signal) {
+async function discoverWithProfile(serverURL, profile, signal) {
   let parsed;
   try {
     parsed = new URL(serverURL.replace(/\/+$/, ""));
@@ -1064,7 +1064,7 @@ async function discover(serverURL, signal) {
     throw new Error(`discover: invalid server URL: ${e instanceof Error ? e.message : String(e)}`);
   }
   const origin = `${parsed.protocol}//${parsed.host}`;
-  const endpoint = `${origin}/.well-known/oauth-authorization-server/desktop`;
+  const endpoint = `${origin}/.well-known/oauth-authorization-server/${profile}`;
   const ctl = withTimeout(authTimeoutMs, signal);
   let resp;
   try {
@@ -1090,6 +1090,12 @@ async function discover(serverURL, signal) {
   }
   return meta;
 }
+async function discover(serverURL, signal) {
+  return discoverWithProfile(serverURL, "desktop", signal);
+}
+async function discoverWebOAuthMetadata(serverURL, signal) {
+  return discoverWithProfile(serverURL, "web", signal);
+}
 async function register(meta, appName, signal) {
   const regReq = {
     client_name: appName,
@@ -1121,12 +1127,50 @@ async function register(meta, appName, signal) {
     throw new Error(`register: decode: ${e instanceof Error ? e.message : String(e)}`);
   }
 }
-async function generateCodeVerifier() {
+async function registerWebOAuthClient(meta, opts, signal) {
+  const regReq = {
+    client_name: opts.clientName,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    redirect_uris: opts.redirectURIs,
+    response_types: ["code"],
+    ...opts.scopes ? { scope: opts.scopes.join(" ") } : {}
+  };
+  const ctl = withTimeout(authTimeoutMs, signal);
+  let resp;
+  try {
+    resp = await fetch(meta.registration_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(regReq),
+      signal: ctl.signal
+    });
+  } catch (e) {
+    throw new Error(`register: ${e instanceof Error ? e.message : String(e)}`);
+  } finally {
+    ctl.dispose();
+  }
+  if (resp.status !== 200 && resp.status !== 201) {
+    throw new Error(`register: HTTP ${resp.status}`);
+  }
+  try {
+    return await resp.json();
+  } catch (e) {
+    throw new Error(`register: decode: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+async function randomBase64Url32() {
   const c = await getCrypto();
   const b = new Uint8Array(32);
   c.getRandomValues(b);
   return base64urlNoPad(b);
 }
+async function generateCodeVerifier() {
+  return randomBase64Url32();
+}
+async function generateState() {
+  return randomBase64Url32();
+}
 async function codeChallenge(verifier) {
   const c = await getCrypto();
   const buf = await c.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
@@ -1160,6 +1204,7 @@ var ErrAuthDenied = "auth_denied";
 var ErrTimeout = "auth_timeout";
 var ErrTokenExchange = "token_exchange_failed";
 var ErrSSLProxy = "ssl_proxy_detected";
+var ErrStateMismatch = "state_mismatch";
 function isSSLError(err) {
   const msg = err instanceof Error ? err.message : String(err);
   return msg.includes("tls:") || msg.includes("x509:") || msg.includes("certificate");
@@ -1273,6 +1318,51 @@ async function authorize(meta, clientID, scopes, opts = {}) {
 function htmlEscape(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+async function createWebAuthorizationRequest(meta, opts) {
+  const verifier = await generateCodeVerifier();
+  const challenge = await codeChallenge(verifier);
+  const state = await generateState();
+  const authURL = new URL(meta.authorization_endpoint);
+  authURL.searchParams.set("response_type", "code");
+  authURL.searchParams.set("client_id", opts.clientID);
+  authURL.searchParams.set("redirect_uri", opts.redirectURI);
+  authURL.searchParams.set("code_challenge", challenge);
+  authURL.searchParams.set("code_challenge_method", "S256");
+  authURL.searchParams.set("state", state);
+  authURL.searchParams.set("scope", opts.scopes.join(" "));
+  if (opts.loginHint) {
+    authURL.searchParams.set("login_hint", opts.loginHint);
+  }
+  return {
+    authUrl: authURL.toString(),
+    state,
+    verifier,
+    clientID: opts.clientID,
+    redirectURI: opts.redirectURI,
+    serverURL: opts.serverURL,
+    createdAt: Date.now()
+  };
+}
+async function completeWebAuthorizationRequest(pending, params, signal) {
+  if (!params.code) {
+    throw new Error("completeWebAuthorizationRequest: missing authorization code");
+  }
+  if (params.state !== pending.state) {
+    throw new Error(
+      `completeWebAuthorizationRequest: ${ErrStateMismatch}: callback state does not match pending state (possible CSRF)`
+    );
+  }
+  const meta = await discoverWebOAuthMetadata(pending.serverURL, signal);
+  const resp = await exchangeCode(
+    meta,
+    pending.clientID,
+    params.code,
+    pending.redirectURI,
+    pending.verifier,
+    signal
+  );
+  return newTokenSet(resp, pending.clientID, pending.serverURL);
+}
 async function exchangeCode(meta, clientID, code, redirectURI, codeVerifier, signal) {
   const data = new URLSearchParams({
     grant_type: "authorization_code",
@@ -2165,6 +2255,8 @@ var Client = class _Client {
   serverURL;
   /** Compliance API 根地址 (已 trim 尾随 /); null = 走默认 ${serverURL}/admin-api */
   complianceBaseURL;
+  /** OAuth metadata profile — 刷新 token 时发现 metadata 用 (默认 'desktop') */
+  oauthMetadataProfile;
   /** OAuth metadata (lazy loaded) */
   meta = null;
   /** 当前 token (内存) */
@@ -2199,6 +2291,7 @@ var Client = class _Client {
   constructor(cfg = {}) {
     this.serverURL = (cfg.serverURL ?? "https://acosmi.com").replace(/\/+$/, "");
     this.complianceBaseURL = cfg.complianceBaseURL ? cfg.complianceBaseURL.replace(/\/+$/, "") : null;
+    this.oauthMetadataProfile = cfg.oauthMetadataProfile ?? "desktop";
     this.store = cfg.store ?? defaultTokenStore();
     this.fetchImpl = cfg.fetchImpl ?? globalThis.fetch.bind(globalThis);
     this.retryPolicy = effectivePolicy(cfg.retryPolicy ?? null);
@@ -2373,7 +2466,7 @@ var Client = class _Client {
     if (tokens) {
       if (!meta) {
         try {
-          meta = await discover(this.serverURL, signal);
+          meta = await discoverWithProfile(this.serverURL, this.oauthMetadataProfile, signal);
         } catch (e) {
           console.warn(`[acosmi-sdk] warning: discover for revocation failed: ${e instanceof Error ? e.message : String(e)}`);
         }
@@ -2444,7 +2537,7 @@ var Client = class _Client {
         }
         if (this.meta == null) {
           try {
-            this.meta = await discover(this.serverURL, signal);
+            this.meta = await discoverWithProfile(this.serverURL, this.oauthMetadataProfile, signal);
           } catch (e) {
             throw new Error(
               `discover for refresh: ${e instanceof Error ? e.message : String(e)}`
@@ -2476,7 +2569,7 @@ var Client = class _Client {
           throw new Error("no tokens to refresh");
         }
         if (this.meta == null) {
-          this.meta = await discover(this.serverURL, signal);
+          this.meta = await discoverWithProfile(this.serverURL, this.oauthMetadataProfile, signal);
         }
         const tokenResp = await refreshToken(
           this.meta,
@@ -5369,6 +5462,6 @@ Client.prototype.getBugReport = async function(bugID, signal) {
   return resp.data;
 };
 
-export { AgentRunStreamError, AgentRunsClient, AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, ComplianceClient, CompliancePollError, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, classifyComplianceError, commerceScopes, complianceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, getAdapter, getAdapterForModel, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
+export { AgentRunStreamError, AgentRunsClient, AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, ComplianceClient, CompliancePollError, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map