@acosmi/sdk-ts 1.3.1 → 1.4.0

package/dist/node/index.d.cts

@@ -1,5 +1,5 @@
-import { M as ManagedModel, I as InputModality, S as ServerMetadata, T as TokenResponse, a as TokenSet, C as ClientRegistration, B as BusinessError, b as ModelCoefficient, Q as QuotaSummary, c as ModelCapabilities, d as ChatRequest, P as ProviderAdapter, e as ChatResponse, A as AnthropicResponse, f as StreamEvent, g as SourcesEvent, h as StreamSettlement, E as EntitlementBalance, i as BalanceDetail, j as EntitlementItem, k as ConsumeRecordPage, l as ModelByQuotaResponse, m as ModelBucket, n as TokenPackage, o as PayPayload, O as Order, p as OrderStatus, W as WalletStats, q as Transaction, r as SkillStoreQuery, s as SkillStoreItem, t as SkillBrowseResponse, u as SkillBrowseListResponse, v as SkillSummary, w as CertificationStatus, G as GenerateSkillRequest, x as GenerateSkillResult, y as OptimizeSkillRequest, z as OptimizeSkillResult, D as ToolView, N as NotificationList, F as DeviceRegistration, H as NotificationPreference, J as WSEvent } from './index-28x02ITB.cjs';
-export { K as APIResponse, L as AnthropicContentBlock, R as AnthropicUsage, U as BucketClassCommercial, V as BucketClassGeneric, X as BucketInfo, Y as BucketRow, Z as ChatContentBlock, _ as ChatMessage, $ as ChatUsage, a0 as ConsumeRecord, a1 as EffortConfig, a2 as GeoLoc, a3 as HTTPError, a4 as ModelNotFoundError, a5 as NetworkError, a6 as Notification, a7 as NotificationUnreadCount, a8 as OpenAIChatChoice, a9 as OpenAIChatMessage, aa as OpenAIChatResponse, ab as OpenAIFunctionCall, ac as OpenAIStreamChoice, ad as OpenAIStreamChunk, ae as OpenAIStreamDelta, af as OpenAIStreamToolCall, ag as OpenAIToolCall, ah as OpenAIUsage, ai as OrderTerminalError, aj as OutputConfig, ak as ProviderFormat, al as RateLimitError, am as ServerTool, an as ServerToolTypeWebSearch, ao as SkillStoreListItem, ap as StreamError, aq as ThinkingConfig, ar as ThinkingHigh, as as ThinkingHighMinMaxTokens, at as ThinkingMax, au as ThinkingMaxFallbackMaxTokens, av as ThinkingOff, aw as ToolListResponse, ax as ToolProvider, ay as WebSearchConfig, az as WebSearchSource, aA as YudaoPageResult, aB as anthropicResponseTextContent, aC as anthropicResponseThinkingContent, aD as anthropicResponseToolUseBlocks, aE as apiResponseBusinessError, aF as apiResponseGetMessage, aG as bucketInfoIsCommercial, aH as bucketRowIsCommercial, aI as getAdapter, aJ as getAdapterForModel, aK as newThinkingConfig, aL as newWebSearchTool, aM as parseNotificationEvent, aN as parseSettlement, aO as parseSourcesEvent, aP as tokenSetIsExpired } from './index-28x02ITB.cjs';
+import { M as ManagedModel, I as InputModality, S as ServerMetadata, T as TokenSet, a as TokenResponse, C as ClientRegistration, B as BusinessError, b as ModelCoefficient, Q as QuotaSummary, c as ModelCapabilities, d as ChatRequest, P as ProviderAdapter, e as ChatResponse, A as AnthropicResponse, f as StreamEvent, g as SourcesEvent, h as StreamSettlement, E as EntitlementBalance, i as BalanceDetail, j as EntitlementItem, k as ConsumeRecordPage, l as ModelByQuotaResponse, m as ModelBucket, n as TokenPackage, o as PayPayload, O as Order, p as OrderStatus, W as WalletStats, q as Transaction, r as SkillStoreQuery, s as SkillStoreItem, t as SkillBrowseResponse, u as SkillBrowseListResponse, v as SkillSummary, w as CertificationStatus, G as GenerateSkillRequest, x as GenerateSkillResult, y as OptimizeSkillRequest, z as OptimizeSkillResult, D as ToolView, N as NotificationList, F as DeviceRegistration, H as NotificationPreference, J as WSEvent } from './index-CbG9NqE-.cjs';
+export { K as APIResponse, L as AnthropicContentBlock, R as AnthropicUsage, U as BucketClassCommercial, V as BucketClassGeneric, X as BucketInfo, Y as BucketRow, Z as ChatContentBlock, _ as ChatMessage, $ as ChatUsage, a0 as ConsumeRecord, a1 as EffortConfig, a2 as GeoLoc, a3 as HTTPError, a4 as ModelNotFoundError, a5 as NetworkError, a6 as Notification, a7 as NotificationUnreadCount, a8 as OpenAIChatChoice, a9 as OpenAIChatMessage, aa as OpenAIChatResponse, ab as OpenAIFunctionCall, ac as OpenAIStreamChoice, ad as OpenAIStreamChunk, ae as OpenAIStreamDelta, af as OpenAIStreamToolCall, ag as OpenAIToolCall, ah as OpenAIUsage, ai as OrderTerminalError, aj as OutputConfig, ak as ProviderFormat, al as RateLimitError, am as ServerTool, an as ServerToolTypeWebSearch, ao as SkillStoreListItem, ap as StreamError, aq as ThinkingConfig, ar as ThinkingHigh, as as ThinkingHighMinMaxTokens, at as ThinkingMax, au as ThinkingMaxFallbackMaxTokens, av as ThinkingOff, aw as ToolListResponse, ax as ToolProvider, ay as WebSearchConfig, az as WebSearchSource, aA as YudaoPageResult, aB as anthropicResponseTextContent, aC as anthropicResponseThinkingContent, aD as anthropicResponseToolUseBlocks, aE as apiResponseBusinessError, aF as apiResponseGetMessage, aG as bucketInfoIsCommercial, aH as bucketRowIsCommercial, aI as getAdapter, aJ as getAdapterForModel, aK as newThinkingConfig, aL as newWebSearchTool, aM as parseNotificationEvent, aN as parseSettlement, aO as parseSourcesEvent, aP as tokenSetIsExpired } from './index-CbG9NqE-.cjs';
 import { M as MinimalSanitizeConfig } from './index-nvLKgCm9.cjs';
 export { i as sanitize } from './index-nvLKgCm9.cjs';
 export { AnthropicAdapter } from './adapters/anthropic.cjs';
@@ -48,6 +48,19 @@ declare function findFirstModelByInputModality(models: ManagedModel[], modality:
  */
 declare function findDesktopVisualUnderstandingModel(models: ManagedModel[]): ManagedModel | null;
 
+/** OAuth metadata profile — 决定 well-known 端点的路径后缀 */
+type OAuthMetadataProfile = 'web' | 'desktop';
+/**
+ * 从 well-known 端点获取指定 profile 的 OAuth 服务元数据。
+ *
+ * serverURL 可能含路径 (如 "https://acosmi.ai/api/v4")，
+ * well-known 端点按 RFC 8414 必须在 origin 根路径:
+ *   https://acosmi.ai/.well-known/oauth-authorization-server/<profile>
+ *
+ * profile='desktop' 对应桌面 loopback OAuth；profile='web' 对应浏览器 Web OAuth。
+ * 内部 helper — `discover` / `discoverWebOAuthMetadata` 是其薄包装。
+ */
+declare function discoverWithProfile(serverURL: string, profile: OAuthMetadataProfile, signal?: AbortSignal): Promise<ServerMetadata>;
 /**
  * 从 well-known 端点获取 Desktop OAuth 服务元数据。
  *
@@ -56,13 +69,48 @@ declare function findDesktopVisualUnderstandingModel(models: ManagedModel[]): Ma
  *   https://acosmi.ai/.well-known/oauth-authorization-server/desktop
  */
 declare function discover(serverURL: string, signal?: AbortSignal): Promise<ServerMetadata>;
+/**
+ * 从 well-known 端点获取 Web OAuth 服务元数据。
+ *
+ * 与 `discover` 行为一致, 但请求路径为
+ *   https://acosmi.com/.well-known/oauth-authorization-server/web
+ *
+ * 浏览器侧 Web OAuth (csign 等第一方 Web 应用) 必须用此 profile，
+ * 它返回 Web authorize/token 端点; `discover` 的 desktop profile 返回的是
+ * 桌面 loopback 端点, 不可混用。
+ */
+declare function discoverWebOAuthMetadata(serverURL: string, signal?: AbortSignal): Promise<ServerMetadata>;
 /** 动态注册桌面客户端，获取 client_id */
 declare function register(meta: ServerMetadata, appName: string, signal?: AbortSignal): Promise<ClientRegistration>;
+/** Web OAuth 动态注册参数 */
+interface RegisterWebOAuthClientOptions {
+    /** 客户端展示名 (RFC 7591 client_name) */
+    clientName: string;
+    /** 浏览器 Web OAuth 的 redirect_uri 列表 (如 ["https://sign.zhonglvbao.com/login/callback"]) */
+    redirectURIs: string[];
+    /** 可选 scope 列表 — 提供时以空格连接写入 RFC 7591 scope 字段 */
+    scopes?: string[];
+}
+/**
+ * 动态注册 Web OAuth (浏览器) 客户端，获取 client_id。
+ *
+ * 与 `register` (桌面 loopback, 硬编码 redirect_uri=127.0.0.1) 的区别:
+ * 本函数允许传入任意 Web redirect_uri，供 csign 等第一方 Web 应用使用。
+ * `token_endpoint_auth_method` 仍为 `none` (PKCE public client)。
+ */
+declare function registerWebOAuthClient(meta: ServerMetadata, opts: RegisterWebOAuthClientOptions, signal?: AbortSignal): Promise<ClientRegistration>;
+/**
+ * 生成 OAuth `state` 参数 — 32 字节加密随机数, base64url 无填充。
+ *
+ * 与 `generateCodeVerifier` 共用随机源 (`randomBase64Url32`)。Web OAuth 流程
+ * 用它做 CSRF 防护: 授权请求带上 state, callback 回来必须逐字符比对。
+ */
+declare function generateState(): Promise<string>;
 type LoginEventType = 'auth_url' | 'complete' | 'error';
 declare const EventAuthURL: "auth_url";
 declare const EventComplete: "complete";
 declare const EventError: "error";
-type LoginErrCode = 'discovery_failed' | 'registration_failed' | 'browser_open_failed' | 'auth_denied' | 'auth_timeout' | 'token_exchange_failed' | 'ssl_proxy_detected';
+type LoginErrCode = 'discovery_failed' | 'registration_failed' | 'browser_open_failed' | 'auth_denied' | 'auth_timeout' | 'token_exchange_failed' | 'ssl_proxy_detected' | 'state_mismatch';
 declare const ErrDiscovery: "discovery_failed";
 declare const ErrRegistration: "registration_failed";
 declare const ErrBrowserOpen: "browser_open_failed";
@@ -70,6 +118,8 @@ declare const ErrAuthDenied: "auth_denied";
 declare const ErrTimeout: "auth_timeout";
 declare const ErrTokenExchange: "token_exchange_failed";
 declare const ErrSSLProxy: "ssl_proxy_detected";
+/** Web OAuth callback 的 state 与发起时不一致 (CSRF 防护) */
+declare const ErrStateMismatch: "state_mismatch";
 /** 登录流程事件 */
 interface LoginEvent {
     type: LoginEventType;
@@ -112,6 +162,76 @@ declare function authorize(meta: ServerMetadata, clientID: string, scopes: strin
     result: AuthorizeResult;
     verifier: string;
 }>;
+/**
+ * Web OAuth 授权请求 — `createWebAuthorizationRequest` 的返回结构。
+ *
+ * 发起方 (csign Next Route Handler 等) 应把整个对象作为 pending 状态持久化
+ * (HttpOnly cookie 等)，callback 回来时取出供 `completeWebAuthorizationRequest` 校验。
+ */
+interface WebAuthorizationRequest {
+    /** 完整授权 URL — 浏览器整页跳转到此地址 */
+    authUrl: string;
+    /** CSRF state — callback 必须回传同值 */
+    state: string;
+    /** PKCE code_verifier — 换 token 时使用, 切勿泄露给浏览器 URL */
+    verifier: string;
+    /** 动态注册得到的 client_id */
+    clientID: string;
+    /** 本次授权使用的 redirect_uri */
+    redirectURI: string;
+    /** OAuth issuer / SDK 业务域名 (用于 callback 阶段重新发现 metadata) */
+    serverURL: string;
+    /** 创建时间戳 (Date.now())，发起方可据此实现 TTL 过期判定 */
+    createdAt: number;
+}
+/** `createWebAuthorizationRequest` 参数 */
+interface CreateWebAuthorizationRequestOptions {
+    /** 动态注册得到的 client_id */
+    clientID: string;
+    /** redirect_uri (须与动态注册登记的一致) */
+    redirectURI: string;
+    /** 请求的 scope 列表 — 以空格连接写入 authUrl */
+    scopes: string[];
+    /** OAuth issuer / SDK 业务域名 */
+    serverURL: string;
+    /** 可选 — SSO 场景下预填邮箱 */
+    loginHint?: string;
+}
+/**
+ * 构造 Web OAuth 授权请求。
+ *
+ * 生成 PKCE verifier + S256 challenge + CSRF state，按 OAuth 2.1 拼装授权 URL
+ * (含 `state` 参数 — SDK 桌面 `authorize` 不带 state, Web 流程必须带)。
+ *
+ * 返回的 `WebAuthorizationRequest` 应整体持久化为 pending 状态，
+ * callback 阶段交给 `completeWebAuthorizationRequest`。
+ */
+declare function createWebAuthorizationRequest(meta: ServerMetadata, opts: CreateWebAuthorizationRequestOptions): Promise<WebAuthorizationRequest>;
+/** `completeWebAuthorizationRequest` 的 pending 状态 (即 WebAuthorizationRequest 的子集) */
+interface WebAuthorizationPending {
+    state: string;
+    verifier: string;
+    clientID: string;
+    redirectURI: string;
+    serverURL: string;
+}
+/** `completeWebAuthorizationRequest` 的 callback 参数 */
+interface WebAuthorizationCallbackParams {
+    /** 授权服务器回传的 authorization code */
+    code: string;
+    /** 授权服务器回传的 state — 必须与 pending.state 一致 */
+    state: string;
+}
+/**
+ * 完成 Web OAuth 授权 — 校验 state → 换 token → 返回可持久化的 TokenSet。
+ *
+ * `pending` 为 `createWebAuthorizationRequest` 返回对象 (或其等价持久化结构);
+ * `params` 为 callback URL 解析出的 `code` / `state`。
+ *
+ * state 不匹配时抛错 (CSRF 防护)。内部依次:
+ *   discoverWebOAuthMetadata(pending.serverURL) → exchangeCode(...) → newTokenSet(...)。
+ */
+declare function completeWebAuthorizationRequest(pending: WebAuthorizationPending, params: WebAuthorizationCallbackParams, signal?: AbortSignal): Promise<TokenSet>;
 declare function exchangeCode(meta: ServerMetadata, clientID: string, code: string, redirectURI: string, codeVerifier: string, signal?: AbortSignal): Promise<TokenResponse>;
 /** 刷新 access_token */
 declare function refreshToken(meta: ServerMetadata, clientID: string, refreshTokenValue: string, signal?: AbortSignal): Promise<TokenResponse>;
@@ -159,9 +279,10 @@ declare const ScopeComplianceSealApprovalRequest = "compliance:seal_approval:req
 declare const ScopeComplianceSealApprovalApprove = "compliance:seal_approval:approve";
 declare const ScopeComplianceSealUseExecute = "compliance:seal_use:execute";
 declare const ScopeComplianceReportsRead = "compliance:reports:read";
+declare const ScopeComplianceReportsWrite = "compliance:reports:write";
 declare const ScopeComplianceReportsPublish = "compliance:reports:publish";
 /** 类型联合：合规域细粒度 scope。Java compliance verifier 只按细粒度匹配, 不做分组展开。 */
-type ComplianceScope = typeof ScopeComplianceEvidenceRead | typeof ScopeComplianceEvidenceWrite | typeof ScopeComplianceTimestampIssue | typeof ScopeComplianceTimestampVerify | typeof ScopeComplianceContractSigningRead | typeof ScopeComplianceContractSigningWrite | typeof ScopeComplianceSealManage | typeof ScopeComplianceSealApprovalRequest | typeof ScopeComplianceSealApprovalApprove | typeof ScopeComplianceSealUseExecute | typeof ScopeComplianceReportsRead | typeof ScopeComplianceReportsPublish;
+type ComplianceScope = typeof ScopeComplianceEvidenceRead | typeof ScopeComplianceEvidenceWrite | typeof ScopeComplianceTimestampIssue | typeof ScopeComplianceTimestampVerify | typeof ScopeComplianceContractSigningRead | typeof ScopeComplianceContractSigningWrite | typeof ScopeComplianceSealManage | typeof ScopeComplianceSealApprovalRequest | typeof ScopeComplianceSealApprovalApprove | typeof ScopeComplianceSealUseExecute | typeof ScopeComplianceReportsRead | typeof ScopeComplianceReportsWrite | typeof ScopeComplianceReportsPublish;
 /** 全部分组 scope (推荐) */
 declare function allScopes(): string[];
 /** 全部合规域 scope。OAuth 申请合规权限时使用; 谨慎一次性申请全部, 推荐按业务最小集合申请。 */
@@ -719,6 +840,20 @@ interface Config {
      * `client.compliance.*`，不与既有模型网关 API 冲突。
      */
     complianceBaseURL?: string;
+    /**
+     * OAuth metadata profile — 决定 `ensureToken` 刷新 token 时
+     * 发现 metadata 走哪个 well-known 端点。
+     *
+     * - `'desktop'` (默认): `/.well-known/oauth-authorization-server/desktop`
+     *   — 桌面 loopback OAuth (`login()`) 流程。
+     * - `'web'`: `/.well-known/oauth-authorization-server/web`
+     *   — 浏览器 Web OAuth (csign 等第一方 Web 应用) 签发的 token，
+     *   其 refresh 必须走 Web token 端点。
+     *
+     * 未设置时默认 `'desktop'`，对既有调用方行为完全无影响。
+     * `login()` 桌面 loopback 路径不受此配置影响。
+     */
+    oauthMetadataProfile?: OAuthMetadataProfile;
 }
 interface Deferred<T> {
     promise: Promise<T>;
@@ -745,6 +880,8 @@ declare class Client {
     serverURL: string;
     /** Compliance API 根地址 (已 trim 尾随 /); null = 走默认 ${serverURL}/admin-api */
     complianceBaseURL: string | null;
+    /** OAuth metadata profile — 刷新 token 时发现 metadata 用 (默认 'desktop') */
+    oauthMetadataProfile: OAuthMetadataProfile;
     /** OAuth metadata (lazy loaded) */
     meta: ServerMetadata | null;
     /** 当前 token (内存) */
@@ -1014,7 +1151,11 @@ declare class ComplianceClient {
     getEvidenceAsset(id: number, signal?: AbortSignal): Promise<EvidenceAsset>;
     /**
      * 公开 verify。隐私边界：返回字段不含 PII / 合同原文 / storage / provider raw。
-     * 服务端不要求 compliance scope（公开端点）；但 SDK 仍带上 token 以便审计。
+     *
+     * 匿名可调用：未 login 时走匿名请求，不会抛 `not authorized, call login() first`。
+     * 已 login / 已持有 token 时附带 `Authorization` 以保留审计上下文。public 端点不
+     * 应要求认证 — 收到 401 直接抛 HTTPError，不触发 `forceRefresh`，也不做 refresh
+     * replay。
      */
     verifyEvidencePublic(params: {
         evidenceNo?: string;
@@ -1045,9 +1186,10 @@ declare class ComplianceClient {
     /**
      * 发布报告（写，step-up 必须）。
      *
-     * 缺少 step-up 时服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`（数值码
-     * 1031000013）。SDK 不会自动重试；调用方需要引导用户重新做 OAuth introspection 或
-     * 重新登录后再次调用本方法（使用同一 idempotency-key）。
+     * `@status gated` — step-up 闸门未闭合前服务端会一致返回
+     * `COMPLIANCE_STEP_UP_REQUIRED`（数值码 1031000013）。SDK 不会自动重试、不伪成功；
+     * 调用方需要引导用户重新做 OAuth introspection 或重新登录后再次调用本方法
+     *（使用同一 idempotency-key）。方法状态分级见 `docs/compliance.md` Method Status。
      */
     publishReport(id: number, opts?: ComplianceWriteOptions): Promise<ComplianceReport>;
     /**
@@ -1063,19 +1205,32 @@ declare class ComplianceClient {
     /**
      * 正式签署（写，step-up 必须）。
      *
-     * 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
+     * `@status gated` — 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
      * SDK 不重试、不伪成功；调用方应该将该错误展示为"功能未开放"。
      */
     signEnvelope(envelopeId: number, req: SignEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<void>;
     /**
      * 创建 H5 签署短链（写，step-up 必须）。
      *
-     * 同上：服务端闸门关闭时 SDK 不重试。
+     * `@status gated` — 同 {@link signEnvelope}：服务端闸门关闭时 SDK 不重试、不伪成功。
      */
     createH5SigningUrl(envelopeId: number, req: CreateH5SigningUrlRequest, opts?: ComplianceWriteOptions): Promise<string>;
     /** 同步 provider 状态（写但只读对账，不创建新 provider 请求）。 */
     syncSigningEnvelopeStatus(envelopeId: number, opts?: ComplianceWriteOptions): Promise<void>;
+    /**
+     * 提交用印审批申请（写）。
+     *
+     * `@status production-ready` — 服务端以 `Idempotency-Key` + 业务请求指纹做重放保护：
+     * 同 key + 同请求 → 返回原审批 id；同 key + 不同请求 → 拒绝复用幂等键。强烈建议调用方
+     * 持久化 `idempotencyKey`，网络重试 / 任务恢复时复用，避免重复创建审批单。
+     */
     submitSealApproval(req: SubmitSealApprovalRequest, opts?: ComplianceWriteOptions): Promise<number>;
+    /**
+     * 审批通过用印申请（写，step-up 必须）。
+     *
+     * `@status gated` — step-up 未闭合前服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`。
+     * SDK 不重试、不伪成功。方法状态分级见 `docs/compliance.md` Method Status。
+     */
     approveSealApproval(id: number, query: ApproveSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
     rejectSealApproval(id: number, query: RejectSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
     cancelSealApproval(id: number, query: CancelSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
@@ -1097,6 +1252,18 @@ declare class ComplianceClient {
      * 与 client.doJSONFullInternal 行为一致；不复用其代码因为 base URL 不同。
      */
     private read;
+    /**
+     * 公开读路径：public verify。
+     *
+     * 与 {@link read} 的区别 — public 端点不应要求认证：
+     *   - 无 token 时匿名请求：ensureToken 抛 `not authorized` 会被吞掉，继续匿名发送。
+     *   - 有 token 时附带 `Authorization`，保留后端审计上下文。
+     *   - 不做 401 refresh replay：401 直接抛 HTTPError，不触发 `forceRefresh`。
+     *
+     * URL 仍走 `client.complianceURL(path)`，不复用 `/api/v4`；底层复用
+     * `client.doRequest`，不新增 fetch/axios 直连。
+     */
+    private publicRead;
     /**
      * 写路径：POST。
      * - 发送前 ensureToken 一次确保 token fresh。
@@ -1573,4 +1740,4 @@ declare module '@acosmi/sdk-ts' {
     }
 }
 
-export { type AgentRun, type AgentRunArtifact, type AgentRunArtifactList, type AgentRunArtifactPolicy, type AgentRunCreateRequest, type AgentRunCreateResponse, type AgentRunDownload, type AgentRunErrorPayload, type AgentRunLocalContextPolicy, type AgentRunLocalToolHandler, type AgentRunLocalToolHandlerContext, type AgentRunLocalToolResult, type AgentRunRunOptions, type AgentRunSettlement, type AgentRunStatus, AgentRunStreamError, type AgentRunStreamEvent, type AgentRunStreamOptions, type AgentRunUsage, type AgentRunWithLocalToolsOptions, AgentRunsClient, AnthropicResponse, type ApproveSealApprovalQuery, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, BusinessError, type CancelSealApprovalQuery, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type ComplianceAssetType, type ComplianceBillingDisplayStatus, ComplianceClient, type ComplianceClientErrorCode, type ComplianceDigestSource, type ComplianceEnvelopeStatus, type ComplianceErrorInfo, type ComplianceErrorKey, type ComplianceHashAlgorithm, CompliancePollError, type CompliancePollOptions, type CompliancePrivacyLevel, type ComplianceProviderRequestStatus, type ComplianceProviderStatus, type ComplianceReport, type ComplianceScope, type ComplianceSealApprovalStatus, type ComplianceTimestampVerificationStatus, type ComplianceWriteOptions, type Config, ConsumeRecordPage, type CreateEvidenceAssetRequest, type CreateH5SigningUrlRequest, type CreateReportRequest, type CreateSigningEnvelopeRequest, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, 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, type EvidenceAsset, type EvidencePackage, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, InputModality, type IssueTimestampRequest, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, type ProviderRequestStatusView, type PublicEvidenceVerifyResult, QuotaSummary, type RejectSealApprovalQuery, type ReportDownload, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, type SealApproval, ServerMetadata, type SignEnvelopeRequest, type SigningEnvelope, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, type SubmitSealApprovalRequest, type TimestampToken, type TimestampVerifyResult, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type VerifyTimestampRequest, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, classifyComplianceError, commerceScopes, complianceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };
+export { type AgentRun, type AgentRunArtifact, type AgentRunArtifactList, type AgentRunArtifactPolicy, type AgentRunCreateRequest, type AgentRunCreateResponse, type AgentRunDownload, type AgentRunErrorPayload, type AgentRunLocalContextPolicy, type AgentRunLocalToolHandler, type AgentRunLocalToolHandlerContext, type AgentRunLocalToolResult, type AgentRunRunOptions, type AgentRunSettlement, type AgentRunStatus, AgentRunStreamError, type AgentRunStreamEvent, type AgentRunStreamOptions, type AgentRunUsage, type AgentRunWithLocalToolsOptions, AgentRunsClient, AnthropicResponse, type ApproveSealApprovalQuery, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, BusinessError, type CancelSealApprovalQuery, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type ComplianceAssetType, type ComplianceBillingDisplayStatus, ComplianceClient, type ComplianceClientErrorCode, type ComplianceDigestSource, type ComplianceEnvelopeStatus, type ComplianceErrorInfo, type ComplianceErrorKey, type ComplianceHashAlgorithm, CompliancePollError, type CompliancePollOptions, type CompliancePrivacyLevel, type ComplianceProviderRequestStatus, type ComplianceProviderStatus, type ComplianceReport, type ComplianceScope, type ComplianceSealApprovalStatus, type ComplianceTimestampVerificationStatus, type ComplianceWriteOptions, type Config, ConsumeRecordPage, type CreateEvidenceAssetRequest, type CreateH5SigningUrlRequest, type CreateReportRequest, type CreateSigningEnvelopeRequest, type CreateWebAuthorizationRequestOptions, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, 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, type EvidenceAsset, type EvidencePackage, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, InputModality, type IssueTimestampRequest, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, type OAuthMetadataProfile, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, type ProviderRequestStatusView, type PublicEvidenceVerifyResult, QuotaSummary, type RegisterWebOAuthClientOptions, type RejectSealApprovalQuery, type ReportDownload, type RetryPolicy, type RetryRequestInfo, 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, type SealApproval, ServerMetadata, type SignEnvelopeRequest, type SigningEnvelope, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, type SubmitSealApprovalRequest, type TimestampToken, type TimestampVerifyResult, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type VerifyTimestampRequest, type WSConfig, WSEvent, WalletStats, type WebAuthorizationCallbackParams, type WebAuthorizationPending, type WebAuthorizationRequest, allScopes, authorize, buildBetas, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newTokenSet, refreshToken, register, registerWebOAuthClient, revokeToken, skillScopes, uniqueMerge };

package/dist/node/index.d.ts

@@ -1,5 +1,5 @@
-import { M as ManagedModel, I as InputModality, S as ServerMetadata, T as TokenResponse, a as TokenSet, C as ClientRegistration, B as BusinessError, b as ModelCoefficient, Q as QuotaSummary, c as ModelCapabilities, d as ChatRequest, P as ProviderAdapter, e as ChatResponse, A as AnthropicResponse, f as StreamEvent, g as SourcesEvent, h as StreamSettlement, E as EntitlementBalance, i as BalanceDetail, j as EntitlementItem, k as ConsumeRecordPage, l as ModelByQuotaResponse, m as ModelBucket, n as TokenPackage, o as PayPayload, O as Order, p as OrderStatus, W as WalletStats, q as Transaction, r as SkillStoreQuery, s as SkillStoreItem, t as SkillBrowseResponse, u as SkillBrowseListResponse, v as SkillSummary, w as CertificationStatus, G as GenerateSkillRequest, x as GenerateSkillResult, y as OptimizeSkillRequest, z as OptimizeSkillResult, D as ToolView, N as NotificationList, F as DeviceRegistration, H as NotificationPreference, J as WSEvent } from './index-28x02ITB.js';
-export { K as APIResponse, L as AnthropicContentBlock, R as AnthropicUsage, U as BucketClassCommercial, V as BucketClassGeneric, X as BucketInfo, Y as BucketRow, Z as ChatContentBlock, _ as ChatMessage, $ as ChatUsage, a0 as ConsumeRecord, a1 as EffortConfig, a2 as GeoLoc, a3 as HTTPError, a4 as ModelNotFoundError, a5 as NetworkError, a6 as Notification, a7 as NotificationUnreadCount, a8 as OpenAIChatChoice, a9 as OpenAIChatMessage, aa as OpenAIChatResponse, ab as OpenAIFunctionCall, ac as OpenAIStreamChoice, ad as OpenAIStreamChunk, ae as OpenAIStreamDelta, af as OpenAIStreamToolCall, ag as OpenAIToolCall, ah as OpenAIUsage, ai as OrderTerminalError, aj as OutputConfig, ak as ProviderFormat, al as RateLimitError, am as ServerTool, an as ServerToolTypeWebSearch, ao as SkillStoreListItem, ap as StreamError, aq as ThinkingConfig, ar as ThinkingHigh, as as ThinkingHighMinMaxTokens, at as ThinkingMax, au as ThinkingMaxFallbackMaxTokens, av as ThinkingOff, aw as ToolListResponse, ax as ToolProvider, ay as WebSearchConfig, az as WebSearchSource, aA as YudaoPageResult, aB as anthropicResponseTextContent, aC as anthropicResponseThinkingContent, aD as anthropicResponseToolUseBlocks, aE as apiResponseBusinessError, aF as apiResponseGetMessage, aG as bucketInfoIsCommercial, aH as bucketRowIsCommercial, aI as getAdapter, aJ as getAdapterForModel, aK as newThinkingConfig, aL as newWebSearchTool, aM as parseNotificationEvent, aN as parseSettlement, aO as parseSourcesEvent, aP as tokenSetIsExpired } from './index-28x02ITB.js';
+import { M as ManagedModel, I as InputModality, S as ServerMetadata, T as TokenSet, a as TokenResponse, C as ClientRegistration, B as BusinessError, b as ModelCoefficient, Q as QuotaSummary, c as ModelCapabilities, d as ChatRequest, P as ProviderAdapter, e as ChatResponse, A as AnthropicResponse, f as StreamEvent, g as SourcesEvent, h as StreamSettlement, E as EntitlementBalance, i as BalanceDetail, j as EntitlementItem, k as ConsumeRecordPage, l as ModelByQuotaResponse, m as ModelBucket, n as TokenPackage, o as PayPayload, O as Order, p as OrderStatus, W as WalletStats, q as Transaction, r as SkillStoreQuery, s as SkillStoreItem, t as SkillBrowseResponse, u as SkillBrowseListResponse, v as SkillSummary, w as CertificationStatus, G as GenerateSkillRequest, x as GenerateSkillResult, y as OptimizeSkillRequest, z as OptimizeSkillResult, D as ToolView, N as NotificationList, F as DeviceRegistration, H as NotificationPreference, J as WSEvent } from './index-CbG9NqE-.js';
+export { K as APIResponse, L as AnthropicContentBlock, R as AnthropicUsage, U as BucketClassCommercial, V as BucketClassGeneric, X as BucketInfo, Y as BucketRow, Z as ChatContentBlock, _ as ChatMessage, $ as ChatUsage, a0 as ConsumeRecord, a1 as EffortConfig, a2 as GeoLoc, a3 as HTTPError, a4 as ModelNotFoundError, a5 as NetworkError, a6 as Notification, a7 as NotificationUnreadCount, a8 as OpenAIChatChoice, a9 as OpenAIChatMessage, aa as OpenAIChatResponse, ab as OpenAIFunctionCall, ac as OpenAIStreamChoice, ad as OpenAIStreamChunk, ae as OpenAIStreamDelta, af as OpenAIStreamToolCall, ag as OpenAIToolCall, ah as OpenAIUsage, ai as OrderTerminalError, aj as OutputConfig, ak as ProviderFormat, al as RateLimitError, am as ServerTool, an as ServerToolTypeWebSearch, ao as SkillStoreListItem, ap as StreamError, aq as ThinkingConfig, ar as ThinkingHigh, as as ThinkingHighMinMaxTokens, at as ThinkingMax, au as ThinkingMaxFallbackMaxTokens, av as ThinkingOff, aw as ToolListResponse, ax as ToolProvider, ay as WebSearchConfig, az as WebSearchSource, aA as YudaoPageResult, aB as anthropicResponseTextContent, aC as anthropicResponseThinkingContent, aD as anthropicResponseToolUseBlocks, aE as apiResponseBusinessError, aF as apiResponseGetMessage, aG as bucketInfoIsCommercial, aH as bucketRowIsCommercial, aI as getAdapter, aJ as getAdapterForModel, aK as newThinkingConfig, aL as newWebSearchTool, aM as parseNotificationEvent, aN as parseSettlement, aO as parseSourcesEvent, aP as tokenSetIsExpired } from './index-CbG9NqE-.js';
 import { M as MinimalSanitizeConfig } from './index-nvLKgCm9.js';
 export { i as sanitize } from './index-nvLKgCm9.js';
 export { AnthropicAdapter } from './adapters/anthropic.js';
@@ -48,6 +48,19 @@ declare function findFirstModelByInputModality(models: ManagedModel[], modality:
  */
 declare function findDesktopVisualUnderstandingModel(models: ManagedModel[]): ManagedModel | null;
 
+/** OAuth metadata profile — 决定 well-known 端点的路径后缀 */
+type OAuthMetadataProfile = 'web' | 'desktop';
+/**
+ * 从 well-known 端点获取指定 profile 的 OAuth 服务元数据。
+ *
+ * serverURL 可能含路径 (如 "https://acosmi.ai/api/v4")，
+ * well-known 端点按 RFC 8414 必须在 origin 根路径:
+ *   https://acosmi.ai/.well-known/oauth-authorization-server/<profile>
+ *
+ * profile='desktop' 对应桌面 loopback OAuth；profile='web' 对应浏览器 Web OAuth。
+ * 内部 helper — `discover` / `discoverWebOAuthMetadata` 是其薄包装。
+ */
+declare function discoverWithProfile(serverURL: string, profile: OAuthMetadataProfile, signal?: AbortSignal): Promise<ServerMetadata>;
 /**
  * 从 well-known 端点获取 Desktop OAuth 服务元数据。
  *
@@ -56,13 +69,48 @@ declare function findDesktopVisualUnderstandingModel(models: ManagedModel[]): Ma
  *   https://acosmi.ai/.well-known/oauth-authorization-server/desktop
  */
 declare function discover(serverURL: string, signal?: AbortSignal): Promise<ServerMetadata>;
+/**
+ * 从 well-known 端点获取 Web OAuth 服务元数据。
+ *
+ * 与 `discover` 行为一致, 但请求路径为
+ *   https://acosmi.com/.well-known/oauth-authorization-server/web
+ *
+ * 浏览器侧 Web OAuth (csign 等第一方 Web 应用) 必须用此 profile，
+ * 它返回 Web authorize/token 端点; `discover` 的 desktop profile 返回的是
+ * 桌面 loopback 端点, 不可混用。
+ */
+declare function discoverWebOAuthMetadata(serverURL: string, signal?: AbortSignal): Promise<ServerMetadata>;
 /** 动态注册桌面客户端，获取 client_id */
 declare function register(meta: ServerMetadata, appName: string, signal?: AbortSignal): Promise<ClientRegistration>;
+/** Web OAuth 动态注册参数 */
+interface RegisterWebOAuthClientOptions {
+    /** 客户端展示名 (RFC 7591 client_name) */
+    clientName: string;
+    /** 浏览器 Web OAuth 的 redirect_uri 列表 (如 ["https://sign.zhonglvbao.com/login/callback"]) */
+    redirectURIs: string[];
+    /** 可选 scope 列表 — 提供时以空格连接写入 RFC 7591 scope 字段 */
+    scopes?: string[];
+}
+/**
+ * 动态注册 Web OAuth (浏览器) 客户端，获取 client_id。
+ *
+ * 与 `register` (桌面 loopback, 硬编码 redirect_uri=127.0.0.1) 的区别:
+ * 本函数允许传入任意 Web redirect_uri，供 csign 等第一方 Web 应用使用。
+ * `token_endpoint_auth_method` 仍为 `none` (PKCE public client)。
+ */
+declare function registerWebOAuthClient(meta: ServerMetadata, opts: RegisterWebOAuthClientOptions, signal?: AbortSignal): Promise<ClientRegistration>;
+/**
+ * 生成 OAuth `state` 参数 — 32 字节加密随机数, base64url 无填充。
+ *
+ * 与 `generateCodeVerifier` 共用随机源 (`randomBase64Url32`)。Web OAuth 流程
+ * 用它做 CSRF 防护: 授权请求带上 state, callback 回来必须逐字符比对。
+ */
+declare function generateState(): Promise<string>;
 type LoginEventType = 'auth_url' | 'complete' | 'error';
 declare const EventAuthURL: "auth_url";
 declare const EventComplete: "complete";
 declare const EventError: "error";
-type LoginErrCode = 'discovery_failed' | 'registration_failed' | 'browser_open_failed' | 'auth_denied' | 'auth_timeout' | 'token_exchange_failed' | 'ssl_proxy_detected';
+type LoginErrCode = 'discovery_failed' | 'registration_failed' | 'browser_open_failed' | 'auth_denied' | 'auth_timeout' | 'token_exchange_failed' | 'ssl_proxy_detected' | 'state_mismatch';
 declare const ErrDiscovery: "discovery_failed";
 declare const ErrRegistration: "registration_failed";
 declare const ErrBrowserOpen: "browser_open_failed";
@@ -70,6 +118,8 @@ declare const ErrAuthDenied: "auth_denied";
 declare const ErrTimeout: "auth_timeout";
 declare const ErrTokenExchange: "token_exchange_failed";
 declare const ErrSSLProxy: "ssl_proxy_detected";
+/** Web OAuth callback 的 state 与发起时不一致 (CSRF 防护) */
+declare const ErrStateMismatch: "state_mismatch";
 /** 登录流程事件 */
 interface LoginEvent {
     type: LoginEventType;
@@ -112,6 +162,76 @@ declare function authorize(meta: ServerMetadata, clientID: string, scopes: strin
     result: AuthorizeResult;
     verifier: string;
 }>;
+/**
+ * Web OAuth 授权请求 — `createWebAuthorizationRequest` 的返回结构。
+ *
+ * 发起方 (csign Next Route Handler 等) 应把整个对象作为 pending 状态持久化
+ * (HttpOnly cookie 等)，callback 回来时取出供 `completeWebAuthorizationRequest` 校验。
+ */
+interface WebAuthorizationRequest {
+    /** 完整授权 URL — 浏览器整页跳转到此地址 */
+    authUrl: string;
+    /** CSRF state — callback 必须回传同值 */
+    state: string;
+    /** PKCE code_verifier — 换 token 时使用, 切勿泄露给浏览器 URL */
+    verifier: string;
+    /** 动态注册得到的 client_id */
+    clientID: string;
+    /** 本次授权使用的 redirect_uri */
+    redirectURI: string;
+    /** OAuth issuer / SDK 业务域名 (用于 callback 阶段重新发现 metadata) */
+    serverURL: string;
+    /** 创建时间戳 (Date.now())，发起方可据此实现 TTL 过期判定 */
+    createdAt: number;
+}
+/** `createWebAuthorizationRequest` 参数 */
+interface CreateWebAuthorizationRequestOptions {
+    /** 动态注册得到的 client_id */
+    clientID: string;
+    /** redirect_uri (须与动态注册登记的一致) */
+    redirectURI: string;
+    /** 请求的 scope 列表 — 以空格连接写入 authUrl */
+    scopes: string[];
+    /** OAuth issuer / SDK 业务域名 */
+    serverURL: string;
+    /** 可选 — SSO 场景下预填邮箱 */
+    loginHint?: string;
+}
+/**
+ * 构造 Web OAuth 授权请求。
+ *
+ * 生成 PKCE verifier + S256 challenge + CSRF state，按 OAuth 2.1 拼装授权 URL
+ * (含 `state` 参数 — SDK 桌面 `authorize` 不带 state, Web 流程必须带)。
+ *
+ * 返回的 `WebAuthorizationRequest` 应整体持久化为 pending 状态，
+ * callback 阶段交给 `completeWebAuthorizationRequest`。
+ */
+declare function createWebAuthorizationRequest(meta: ServerMetadata, opts: CreateWebAuthorizationRequestOptions): Promise<WebAuthorizationRequest>;
+/** `completeWebAuthorizationRequest` 的 pending 状态 (即 WebAuthorizationRequest 的子集) */
+interface WebAuthorizationPending {
+    state: string;
+    verifier: string;
+    clientID: string;
+    redirectURI: string;
+    serverURL: string;
+}
+/** `completeWebAuthorizationRequest` 的 callback 参数 */
+interface WebAuthorizationCallbackParams {
+    /** 授权服务器回传的 authorization code */
+    code: string;
+    /** 授权服务器回传的 state — 必须与 pending.state 一致 */
+    state: string;
+}
+/**
+ * 完成 Web OAuth 授权 — 校验 state → 换 token → 返回可持久化的 TokenSet。
+ *
+ * `pending` 为 `createWebAuthorizationRequest` 返回对象 (或其等价持久化结构);
+ * `params` 为 callback URL 解析出的 `code` / `state`。
+ *
+ * state 不匹配时抛错 (CSRF 防护)。内部依次:
+ *   discoverWebOAuthMetadata(pending.serverURL) → exchangeCode(...) → newTokenSet(...)。
+ */
+declare function completeWebAuthorizationRequest(pending: WebAuthorizationPending, params: WebAuthorizationCallbackParams, signal?: AbortSignal): Promise<TokenSet>;
 declare function exchangeCode(meta: ServerMetadata, clientID: string, code: string, redirectURI: string, codeVerifier: string, signal?: AbortSignal): Promise<TokenResponse>;
 /** 刷新 access_token */
 declare function refreshToken(meta: ServerMetadata, clientID: string, refreshTokenValue: string, signal?: AbortSignal): Promise<TokenResponse>;
@@ -159,9 +279,10 @@ declare const ScopeComplianceSealApprovalRequest = "compliance:seal_approval:req
 declare const ScopeComplianceSealApprovalApprove = "compliance:seal_approval:approve";
 declare const ScopeComplianceSealUseExecute = "compliance:seal_use:execute";
 declare const ScopeComplianceReportsRead = "compliance:reports:read";
+declare const ScopeComplianceReportsWrite = "compliance:reports:write";
 declare const ScopeComplianceReportsPublish = "compliance:reports:publish";
 /** 类型联合：合规域细粒度 scope。Java compliance verifier 只按细粒度匹配, 不做分组展开。 */
-type ComplianceScope = typeof ScopeComplianceEvidenceRead | typeof ScopeComplianceEvidenceWrite | typeof ScopeComplianceTimestampIssue | typeof ScopeComplianceTimestampVerify | typeof ScopeComplianceContractSigningRead | typeof ScopeComplianceContractSigningWrite | typeof ScopeComplianceSealManage | typeof ScopeComplianceSealApprovalRequest | typeof ScopeComplianceSealApprovalApprove | typeof ScopeComplianceSealUseExecute | typeof ScopeComplianceReportsRead | typeof ScopeComplianceReportsPublish;
+type ComplianceScope = typeof ScopeComplianceEvidenceRead | typeof ScopeComplianceEvidenceWrite | typeof ScopeComplianceTimestampIssue | typeof ScopeComplianceTimestampVerify | typeof ScopeComplianceContractSigningRead | typeof ScopeComplianceContractSigningWrite | typeof ScopeComplianceSealManage | typeof ScopeComplianceSealApprovalRequest | typeof ScopeComplianceSealApprovalApprove | typeof ScopeComplianceSealUseExecute | typeof ScopeComplianceReportsRead | typeof ScopeComplianceReportsWrite | typeof ScopeComplianceReportsPublish;
 /** 全部分组 scope (推荐) */
 declare function allScopes(): string[];
 /** 全部合规域 scope。OAuth 申请合规权限时使用; 谨慎一次性申请全部, 推荐按业务最小集合申请。 */
@@ -719,6 +840,20 @@ interface Config {
      * `client.compliance.*`，不与既有模型网关 API 冲突。
      */
     complianceBaseURL?: string;
+    /**
+     * OAuth metadata profile — 决定 `ensureToken` 刷新 token 时
+     * 发现 metadata 走哪个 well-known 端点。
+     *
+     * - `'desktop'` (默认): `/.well-known/oauth-authorization-server/desktop`
+     *   — 桌面 loopback OAuth (`login()`) 流程。
+     * - `'web'`: `/.well-known/oauth-authorization-server/web`
+     *   — 浏览器 Web OAuth (csign 等第一方 Web 应用) 签发的 token，
+     *   其 refresh 必须走 Web token 端点。
+     *
+     * 未设置时默认 `'desktop'`，对既有调用方行为完全无影响。
+     * `login()` 桌面 loopback 路径不受此配置影响。
+     */
+    oauthMetadataProfile?: OAuthMetadataProfile;
 }
 interface Deferred<T> {
     promise: Promise<T>;
@@ -745,6 +880,8 @@ declare class Client {
     serverURL: string;
     /** Compliance API 根地址 (已 trim 尾随 /); null = 走默认 ${serverURL}/admin-api */
     complianceBaseURL: string | null;
+    /** OAuth metadata profile — 刷新 token 时发现 metadata 用 (默认 'desktop') */
+    oauthMetadataProfile: OAuthMetadataProfile;
     /** OAuth metadata (lazy loaded) */
     meta: ServerMetadata | null;
     /** 当前 token (内存) */
@@ -1014,7 +1151,11 @@ declare class ComplianceClient {
     getEvidenceAsset(id: number, signal?: AbortSignal): Promise<EvidenceAsset>;
     /**
      * 公开 verify。隐私边界：返回字段不含 PII / 合同原文 / storage / provider raw。
-     * 服务端不要求 compliance scope（公开端点）；但 SDK 仍带上 token 以便审计。
+     *
+     * 匿名可调用：未 login 时走匿名请求，不会抛 `not authorized, call login() first`。
+     * 已 login / 已持有 token 时附带 `Authorization` 以保留审计上下文。public 端点不
+     * 应要求认证 — 收到 401 直接抛 HTTPError，不触发 `forceRefresh`，也不做 refresh
+     * replay。
      */
     verifyEvidencePublic(params: {
         evidenceNo?: string;
@@ -1045,9 +1186,10 @@ declare class ComplianceClient {
     /**
      * 发布报告（写，step-up 必须）。
      *
-     * 缺少 step-up 时服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`（数值码
-     * 1031000013）。SDK 不会自动重试；调用方需要引导用户重新做 OAuth introspection 或
-     * 重新登录后再次调用本方法（使用同一 idempotency-key）。
+     * `@status gated` — step-up 闸门未闭合前服务端会一致返回
+     * `COMPLIANCE_STEP_UP_REQUIRED`（数值码 1031000013）。SDK 不会自动重试、不伪成功；
+     * 调用方需要引导用户重新做 OAuth introspection 或重新登录后再次调用本方法
+     *（使用同一 idempotency-key）。方法状态分级见 `docs/compliance.md` Method Status。
      */
     publishReport(id: number, opts?: ComplianceWriteOptions): Promise<ComplianceReport>;
     /**
@@ -1063,19 +1205,32 @@ declare class ComplianceClient {
     /**
      * 正式签署（写，step-up 必须）。
      *
-     * 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
+     * `@status gated` — 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
      * SDK 不重试、不伪成功；调用方应该将该错误展示为"功能未开放"。
      */
     signEnvelope(envelopeId: number, req: SignEnvelopeRequest, opts?: ComplianceWriteOptions): Promise<void>;
     /**
      * 创建 H5 签署短链（写，step-up 必须）。
      *
-     * 同上：服务端闸门关闭时 SDK 不重试。
+     * `@status gated` — 同 {@link signEnvelope}：服务端闸门关闭时 SDK 不重试、不伪成功。
      */
     createH5SigningUrl(envelopeId: number, req: CreateH5SigningUrlRequest, opts?: ComplianceWriteOptions): Promise<string>;
     /** 同步 provider 状态（写但只读对账，不创建新 provider 请求）。 */
     syncSigningEnvelopeStatus(envelopeId: number, opts?: ComplianceWriteOptions): Promise<void>;
+    /**
+     * 提交用印审批申请（写）。
+     *
+     * `@status production-ready` — 服务端以 `Idempotency-Key` + 业务请求指纹做重放保护：
+     * 同 key + 同请求 → 返回原审批 id；同 key + 不同请求 → 拒绝复用幂等键。强烈建议调用方
+     * 持久化 `idempotencyKey`，网络重试 / 任务恢复时复用，避免重复创建审批单。
+     */
     submitSealApproval(req: SubmitSealApprovalRequest, opts?: ComplianceWriteOptions): Promise<number>;
+    /**
+     * 审批通过用印申请（写，step-up 必须）。
+     *
+     * `@status gated` — step-up 未闭合前服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`。
+     * SDK 不重试、不伪成功。方法状态分级见 `docs/compliance.md` Method Status。
+     */
     approveSealApproval(id: number, query: ApproveSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
     rejectSealApproval(id: number, query: RejectSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
     cancelSealApproval(id: number, query: CancelSealApprovalQuery, opts?: ComplianceWriteOptions): Promise<void>;
@@ -1097,6 +1252,18 @@ declare class ComplianceClient {
      * 与 client.doJSONFullInternal 行为一致；不复用其代码因为 base URL 不同。
      */
     private read;
+    /**
+     * 公开读路径：public verify。
+     *
+     * 与 {@link read} 的区别 — public 端点不应要求认证：
+     *   - 无 token 时匿名请求：ensureToken 抛 `not authorized` 会被吞掉，继续匿名发送。
+     *   - 有 token 时附带 `Authorization`，保留后端审计上下文。
+     *   - 不做 401 refresh replay：401 直接抛 HTTPError，不触发 `forceRefresh`。
+     *
+     * URL 仍走 `client.complianceURL(path)`，不复用 `/api/v4`；底层复用
+     * `client.doRequest`，不新增 fetch/axios 直连。
+     */
+    private publicRead;
     /**
      * 写路径：POST。
      * - 发送前 ensureToken 一次确保 token fresh。
@@ -1573,4 +1740,4 @@ declare module '@acosmi/sdk-ts' {
     }
 }
 
-export { type AgentRun, type AgentRunArtifact, type AgentRunArtifactList, type AgentRunArtifactPolicy, type AgentRunCreateRequest, type AgentRunCreateResponse, type AgentRunDownload, type AgentRunErrorPayload, type AgentRunLocalContextPolicy, type AgentRunLocalToolHandler, type AgentRunLocalToolHandlerContext, type AgentRunLocalToolResult, type AgentRunRunOptions, type AgentRunSettlement, type AgentRunStatus, AgentRunStreamError, type AgentRunStreamEvent, type AgentRunStreamOptions, type AgentRunUsage, type AgentRunWithLocalToolsOptions, AgentRunsClient, AnthropicResponse, type ApproveSealApprovalQuery, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, BusinessError, type CancelSealApprovalQuery, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type ComplianceAssetType, type ComplianceBillingDisplayStatus, ComplianceClient, type ComplianceClientErrorCode, type ComplianceDigestSource, type ComplianceEnvelopeStatus, type ComplianceErrorInfo, type ComplianceErrorKey, type ComplianceHashAlgorithm, CompliancePollError, type CompliancePollOptions, type CompliancePrivacyLevel, type ComplianceProviderRequestStatus, type ComplianceProviderStatus, type ComplianceReport, type ComplianceScope, type ComplianceSealApprovalStatus, type ComplianceTimestampVerificationStatus, type ComplianceWriteOptions, type Config, ConsumeRecordPage, type CreateEvidenceAssetRequest, type CreateH5SigningUrlRequest, type CreateReportRequest, type CreateSigningEnvelopeRequest, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, 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, type EvidenceAsset, type EvidencePackage, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, InputModality, type IssueTimestampRequest, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, type ProviderRequestStatusView, type PublicEvidenceVerifyResult, QuotaSummary, type RejectSealApprovalQuery, type ReportDownload, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, type SealApproval, ServerMetadata, type SignEnvelopeRequest, type SigningEnvelope, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, type SubmitSealApprovalRequest, type TimestampToken, type TimestampVerifyResult, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type VerifyTimestampRequest, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, classifyComplianceError, commerceScopes, complianceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };
+export { type AgentRun, type AgentRunArtifact, type AgentRunArtifactList, type AgentRunArtifactPolicy, type AgentRunCreateRequest, type AgentRunCreateResponse, type AgentRunDownload, type AgentRunErrorPayload, type AgentRunLocalContextPolicy, type AgentRunLocalToolHandler, type AgentRunLocalToolHandlerContext, type AgentRunLocalToolResult, type AgentRunRunOptions, type AgentRunSettlement, type AgentRunStatus, AgentRunStreamError, type AgentRunStreamEvent, type AgentRunStreamOptions, type AgentRunUsage, type AgentRunWithLocalToolsOptions, AgentRunsClient, AnthropicResponse, type ApproveSealApprovalQuery, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, BusinessError, type CancelSealApprovalQuery, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type ComplianceAssetType, type ComplianceBillingDisplayStatus, ComplianceClient, type ComplianceClientErrorCode, type ComplianceDigestSource, type ComplianceEnvelopeStatus, type ComplianceErrorInfo, type ComplianceErrorKey, type ComplianceHashAlgorithm, CompliancePollError, type CompliancePollOptions, type CompliancePrivacyLevel, type ComplianceProviderRequestStatus, type ComplianceProviderStatus, type ComplianceReport, type ComplianceScope, type ComplianceSealApprovalStatus, type ComplianceTimestampVerificationStatus, type ComplianceWriteOptions, type Config, ConsumeRecordPage, type CreateEvidenceAssetRequest, type CreateH5SigningUrlRequest, type CreateReportRequest, type CreateSigningEnvelopeRequest, type CreateWebAuthorizationRequestOptions, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, 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, type EvidenceAsset, type EvidencePackage, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, InputModality, type IssueTimestampRequest, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, type OAuthMetadataProfile, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, type ProviderRequestStatusView, type PublicEvidenceVerifyResult, QuotaSummary, type RegisterWebOAuthClientOptions, type RejectSealApprovalQuery, type ReportDownload, type RetryPolicy, type RetryRequestInfo, 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, type SealApproval, ServerMetadata, type SignEnvelopeRequest, type SigningEnvelope, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, type SubmitSealApprovalRequest, type TimestampToken, type TimestampVerifyResult, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type VerifyTimestampRequest, type WSConfig, WSEvent, WalletStats, type WebAuthorizationCallbackParams, type WebAuthorizationPending, type WebAuthorizationRequest, allScopes, authorize, buildBetas, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newTokenSet, refreshToken, register, registerWebOAuthClient, revokeToken, skillScopes, uniqueMerge };