@acosmi/sdk-ts 1.2.0 → 1.3.0

package/docs/compliance.md

@@ -0,0 +1,265 @@
+# Compliance SDK Guide
+
+This guide covers the public TypeScript SDK surface for compliance workflows:
+timestamps, evidence assets, evidence packages, reports, signing envelopes, seal
+approvals, and provider request polling.
+
+The SDK exposes Acosmi domain objects only. It does not expose provider
+credentials, provider endpoints, raw provider payloads, certificates, private
+keys, signing containers, or billing commit internals.
+
+## Quick Start
+
+```ts
+import {
+  Client,
+  ScopeComplianceEvidenceRead,
+  ScopeComplianceEvidenceWrite,
+  ScopeComplianceTimestampIssue,
+  ScopeComplianceTimestampVerify,
+} from '@acosmi/sdk-ts';
+
+const client = await Client.create({
+  serverURL: process.env.ACOSMI_SERVER_URL!,
+  // Defaults to `${serverURL}/admin-api` when omitted.
+  complianceBaseURL: process.env.ACOSMI_COMPLIANCE_BASE_URL,
+});
+
+await client.login('Compliance Example', [
+  ScopeComplianceEvidenceRead,
+  ScopeComplianceEvidenceWrite,
+  ScopeComplianceTimestampIssue,
+  ScopeComplianceTimestampVerify,
+]);
+
+const idempotencyKey = await loadOrCreateIdempotencyKey('timestamp:order-123');
+
+const asset = await client.compliance.createEvidenceAsset(
+  {
+    assetType: 'HASH_ONLY',
+    name: 'release-manifest',
+    hashAlgorithm: 'sha256',
+    declaredHash: process.env.RELEASE_MANIFEST_SHA256!,
+    digestSource: 'CLIENT',
+    privacyLevel: 'private',
+  },
+  { idempotencyKey },
+);
+
+const token = await client.compliance.issueTimestampForAsset(asset.id, {
+  idempotencyKey: await loadOrCreateIdempotencyKey(`timestamp:${asset.evidenceNo}`),
+});
+
+const verified = await client.compliance.waitForTimestampVerified(token.id, {
+  timeoutMs: 60_000,
+});
+
+console.log(verified.verificationStatus);
+```
+
+## Scopes
+
+Request the smallest scope set that matches the workflow. `complianceScopes()`
+returns all compliance scopes, but production apps should usually choose a
+subset:
+
+```ts
+import {
+  ScopeComplianceEvidenceRead,
+  ScopeComplianceReportsRead,
+  ScopeComplianceTimestampVerify,
+} from '@acosmi/sdk-ts';
+
+await client.login('Read-only Compliance App', [
+  ScopeComplianceEvidenceRead,
+  ScopeComplianceTimestampVerify,
+  ScopeComplianceReportsRead,
+]);
+```
+
+Compliance scopes are independent from `ScopeAI`, `ScopeSkills`, and
+`ScopeAccount`. Holding the general scopes does not grant compliance access.
+
+## Base URL
+
+`Client` keeps the existing model gateway path under `/api/v4`. Compliance uses
+`client.complianceURL(path)` and defaults to `${serverURL}/admin-api`, so it does
+not collide with the existing API path.
+
+Set `Config.complianceBaseURL` only when compliance is exposed through a
+separate ingress:
+
+```ts
+const client = new Client({
+  serverURL: process.env.ACOSMI_SERVER_URL!,
+  complianceBaseURL: process.env.ACOSMI_COMPLIANCE_BASE_URL,
+});
+```
+
+## Idempotency And Retry Rules
+
+Every compliance write method accepts `ComplianceWriteOptions`:
+
+```ts
+await client.compliance.publishReport(reportId, {
+  idempotencyKey,
+  signal,
+});
+```
+
+Persist idempotency keys outside the process before sending a write request.
+After a restart, timeout, network failure, or 401, reuse the same key for the
+same business action.
+
+Compliance write methods intentionally do not use automatic retry:
+
+- POST/PUT/DELETE write calls do not retry 5xx, 429, timeouts, or transport
+  errors.
+- Write calls do not refresh and replay on 401.
+- GET read calls can perform one safe 401 refresh retry.
+- The caller owns user re-authentication and must reuse the same idempotency key
+  when resuming the same business action.
+
+## Evidence, Timestamp, And Report Flow
+
+```ts
+const asset = await client.compliance.createEvidenceAsset(
+  {
+    assetType: 'HASH_ONLY',
+    name: 'artifact-manifest',
+    hashAlgorithm: 'sha256',
+    declaredHash: sha256Hex,
+    digestSource: 'CLIENT',
+    privacyLevel: 'private',
+  },
+  { idempotencyKey: assetKey },
+);
+
+const token = await client.compliance.issueTimestampForAsset(asset.id, {
+  idempotencyKey: timestampKey,
+});
+
+await client.compliance.waitForTimestampVerified(token.id);
+
+const pkg = await client.compliance.buildEvidencePackage(asset.id, token.id, {
+  idempotencyKey: packageKey,
+});
+
+const report = await client.compliance.createReport(
+  { assetId: asset.id, packageId: pkg.id },
+  { idempotencyKey: reportKey },
+);
+
+const download = await client.compliance.downloadReport(report.id);
+console.log(download.reportNo, download.packageHash);
+```
+
+`downloadReport` returns an offline verification view: report hash, asset hash,
+package hash, and timestamp summary. It does not include contract body content,
+storage keys, provider raw payloads, or subject snapshots.
+
+## Public Verification
+
+`verifyEvidencePublic` returns a privacy-preserving verification result:
+
+```ts
+const result = await client.compliance.verifyEvidencePublic({
+  evidenceNo: process.env.EVIDENCE_NO,
+});
+
+console.log(result.manifestOfflineVerify);
+```
+
+The public result includes stable evidence and hash fields only. It excludes PII,
+contract originals, storage bucket/key values, subject snapshot IDs, provider raw
+payloads, and timestamp authority internals.
+
+## Signing And Provider Request Polling
+
+Signing envelope methods expose the Acosmi workflow state, not provider-specific
+fields. `signEnvelope` and `createH5SigningUrl` can return step-up or gate-closed
+business errors; callers should surface those states instead of retrying.
+
+```ts
+import { BusinessError, classifyComplianceError, isComplianceBusinessError } from '@acosmi/sdk-ts';
+
+try {
+  await client.compliance.signEnvelope(envelopeId, request, { idempotencyKey });
+} catch (err) {
+  if (err instanceof BusinessError && isComplianceBusinessError(err)) {
+    const info = classifyComplianceError(err);
+    if (info.stepUpRequired) {
+      await promptUserToReauthenticate();
+      return;
+    }
+    if (info.terminal) {
+      showTerminalComplianceState(info.key);
+      return;
+    }
+  }
+  throw err;
+}
+```
+
+Provider request polling is read-only and exposes a public status view:
+
+```ts
+const view = await client.compliance.waitForProviderRequestTerminal(
+  providerRequestId,
+  { timeoutMs: 30_000 },
+);
+
+if (view.status === 'SUCCESS') {
+  // Provider success is not a billing commit. Check the envelope/report state.
+}
+```
+
+## Error Classification
+
+Compliance business errors are returned as numeric Java error codes in the
+standard `BusinessError.code` field. The SDK maps those codes to symbolic keys:
+
+```ts
+const info = classifyComplianceError(err);
+switch (info.key) {
+  case 'COMPLIANCE_STEP_UP_REQUIRED':
+    await promptUserToReauthenticate();
+    break;
+  case 'ENVELOPE_GATE_CLOSED':
+  case 'PROVIDER_NOT_CONFIGURED':
+    showTerminalComplianceState(info.key);
+    break;
+}
+```
+
+`CompliancePollError` is used by polling helpers for terminal failure, timeout,
+abort, and unknown states.
+
+## Safety Boundary
+
+Do not place any of the following in SDK code, tests, examples, docs, git
+history, environment templates, or package tarballs:
+
+- Provider endpoints or provider raw request/response payloads.
+- Certificates, private keys, keystores, signing containers, or passwords.
+- Provider product IDs, provider user IDs, transaction codes, project codes, or
+  provider seal IDs.
+- Contract originals, PII, storage bucket/key values, subject snapshots, or
+  callback billing commit payloads.
+
+The Java compliance backend owns provider integration, controlled materials,
+local verification, billing state transitions, and OAuth/JWKS validation. The
+Go OAuth/JWKS layer owns token issuance and introspection. The TypeScript SDK
+only requests scopes, sends Acosmi public DTOs, classifies public errors, and
+polls safe public status views.
+
+## Packaged Examples
+
+The npm package includes these examples:
+
+- `examples/compliance-read.ts`
+- `examples/compliance-evidence-timestamp.ts`
+- `examples/compliance-envelope.ts`
+
+They require caller-provided environment variables and do not contain real
+endpoints, secrets, provider materials, or raw provider payloads.

package/examples/compliance-envelope.ts

@@ -0,0 +1,112 @@
+// examples/compliance-envelope.ts — Signing envelope + step-up / gate 错误处理示例。
+//
+// 演示：
+//   1. 创建合同签署 envelope
+//   2. 查询 envelope 状态
+//   3. 正确处理 step-up / gate closed 错误（不重试、不伪成功）
+//   4. 查询 provider request 脱敏状态（SUCCESS 不等于扣费 commit）
+//
+// 红线：
+//   - 不传 provider 侧印章、项目或主体字段；这些由后端归一映射。
+//   - sign / h5-url 在后端闸门关闭时会返回稳定错误，SDK 不重试、不伪成功。
+//   - provider success 不等于 billing committed；最终扣费状态以 envelope 业务字段为准。
+
+import {
+  BusinessError,
+  Client,
+  CompliancePollError,
+  ScopeComplianceContractSigningRead,
+  ScopeComplianceContractSigningWrite,
+  ScopeComplianceSealApprovalRequest,
+  classifyComplianceError,
+  isComplianceBusinessError,
+} from '@acosmi/sdk-ts';
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+  const client = await Client.create({
+    serverURL,
+    complianceBaseURL: process.env.ACOSMI_COMPLIANCE_BASE_URL,
+  });
+
+  await client.login('Envelope Example', [
+    ScopeComplianceContractSigningRead,
+    ScopeComplianceContractSigningWrite,
+    ScopeComplianceSealApprovalRequest,
+  ]);
+
+  // 1) 创建 envelope (DRAFT)
+  const envelopeKey = `envelope-${Date.now()}`;
+  const envelopeId = await client.compliance.createSigningEnvelope(
+    {
+      envelopeNo: `EV-${Date.now()}`,
+      requestId: envelopeKey,
+      billingGroupId: `BG-${Date.now()}`,
+    },
+    { idempotencyKey: envelopeKey },
+  );
+  console.log('[envelope created] id=', envelopeId);
+
+  // 2) 查询 envelope 详情
+  const envelope = await client.compliance.getSigningEnvelope(envelopeId);
+  console.log('[envelope detail]', envelope.envelopeNo,
+    'status=', envelope.status,
+    'pendingReason=', envelope.pendingReason);
+
+  // 3) 试调用 sign — 后端闸门关闭时会失败（ENVELOPE_GATE_CLOSED）
+  try {
+    await client.compliance.signEnvelope(envelopeId, {
+      contractHash: 'dummy-hash',
+      idempotencyKey: `sign-${envelopeKey}`,
+    });
+  } catch (e) {
+    if (e instanceof BusinessError && isComplianceBusinessError(e)) {
+      const info = classifyComplianceError(e);
+      if (info.stepUpRequired) {
+        console.warn('[sign] step-up required — 请引导用户重新做 OAuth introspection / 重登录后用同一 idempotency-key 重试');
+      } else if (info.key === 'ENVELOPE_GATE_CLOSED') {
+        console.warn('[sign] gate closed — 后端闸门未开放，不要重试，向用户展示"功能开放中"');
+      } else if (info.terminal) {
+        console.warn('[sign] terminal:', info.key, '— 重试无用');
+      } else {
+        console.warn('[sign] business error:', info.key, info.message);
+      }
+    } else {
+      console.error('[sign] unexpected error:', e);
+    }
+  }
+
+  // 4) 查询 provider request 状态 (脱敏)
+  const providerRequestId = Number(process.env.PROVIDER_REQUEST_ID ?? 0);
+  if (providerRequestId) {
+    try {
+      const view = await client.compliance.waitForProviderRequestTerminal(providerRequestId, {
+        timeoutMs: 30_000,
+      });
+      console.log('[provider request terminal] status=', view.status,
+        'terminal=', view.terminal,
+        'retryable=', view.retryable);
+      if (view.status === 'SUCCESS') {
+        console.log('NOTE: provider SUCCESS 不等于 billing committed；以 envelope 的 committedAt 字段为准。');
+      }
+    } catch (e) {
+      if (e instanceof CompliancePollError) {
+        if (e.kind === 'timeout') {
+          console.warn('[provider request] still pending — DO NOT 重发原请求；下次查询/对账');
+        } else if (e.kind === 'terminal_failure') {
+          console.warn('[provider request] FAILED — 走人工对账');
+        }
+      } else {
+        throw e;
+      }
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('envelope example failed:', err);
+  process.exit(1);
+});

package/examples/compliance-evidence-timestamp.ts

@@ -0,0 +1,130 @@
+// examples/compliance-evidence-timestamp.ts — hash-only evidence + timestamp 链路示例。
+//
+// 演示：
+//   1. 本地对普通业务内容做 sha256 (不传原文)
+//   2. 创建 hash-only evidence asset
+//   3. 给资产申请时间章 (持久化 Idempotency-Key)
+//   4. polling 等到本地 verify 通过
+//   5. 构建 evidence package
+//   6. 下载报告所需的离线复核 VO
+//
+// 红线：
+//   - 不传 provider 字段；服务端按配置选 provider。
+//   - 不读取证书/密钥材料或 provider 签名材料；这些是后端实现细节。
+//   - Idempotency-Key 必须在内存外持久化，重启 / 重试时复用同一 key。
+
+import { createHash } from 'node:crypto';
+import {
+  Client,
+  CompliancePollError,
+  ScopeComplianceEvidenceRead,
+  ScopeComplianceEvidenceWrite,
+  ScopeComplianceTimestampIssue,
+  ScopeComplianceTimestampVerify,
+  ScopeComplianceReportsRead,
+} from '@acosmi/sdk-ts';
+
+// 模拟持久化的 Idempotency-Key 存储；生产环境应落 DB / 本地文件 / 业务订单表。
+const KEY_STORE = new Map<string, string>();
+
+function loadOrCreateKey(slot: string): string {
+  let key = KEY_STORE.get(slot);
+  if (!key) {
+    key = `${slot}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    KEY_STORE.set(slot, key);
+  }
+  return key;
+}
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+  const client = await Client.create({
+    serverURL,
+    complianceBaseURL: process.env.ACOSMI_COMPLIANCE_BASE_URL,
+  });
+
+  await client.login('Evidence + Timestamp Example', [
+    ScopeComplianceEvidenceRead,
+    ScopeComplianceEvidenceWrite,
+    ScopeComplianceTimestampIssue,
+    ScopeComplianceTimestampVerify,
+    ScopeComplianceReportsRead,
+  ]);
+
+  // 1) 本地 sha256 (用户业务内容)
+  const content = Buffer.from('release v1.2.3 manifest line-1\nrelease v1.2.3 manifest line-2', 'utf8');
+  const sha256 = createHash('sha256').update(content).digest('hex');
+
+  // 2) 创建 hash-only evidence asset
+  const assetKey = loadOrCreateKey('asset:release-v1.2.3');
+  const asset = await client.compliance.createEvidenceAsset(
+    {
+      assetType: 'HASH_ONLY',
+      name: 'release-v1.2.3.manifest',
+      hashAlgorithm: 'sha256',
+      declaredHash: sha256,
+      digestSource: 'CLIENT',
+      privacyLevel: 'private',
+    },
+    { idempotencyKey: assetKey },
+  );
+  console.log('[asset]', asset.id, asset.evidenceNo);
+
+  // 3) 申请时间章 — Idempotency-Key 持久化复用
+  const tsKey = loadOrCreateKey('ts:release-v1.2.3');
+  const token = await client.compliance.issueTimestampForAsset(asset.id, {
+    idempotencyKey: tsKey,
+  });
+  console.log('[timestamp issued]', token.id, 'status=', token.verificationStatus);
+
+  // 4) polling 到本地 verify 通过
+  try {
+    const verified = await client.compliance.waitForTimestampVerified(token.id, {
+      timeoutMs: 60_000,
+      initialIntervalMs: 1_000,
+      maxIntervalMs: 5_000,
+    });
+    console.log('[timestamp verified] serial=', verified.serialNumber,
+      'genTime=', verified.genTime);
+  } catch (e) {
+    if (e instanceof CompliancePollError && e.kind === 'terminal_failure') {
+      console.error('time stamp local verify failed — DO NOT retry with same key; 起新链路');
+      throw e;
+    }
+    if (e instanceof CompliancePollError && e.kind === 'timeout') {
+      console.warn('timestamp still UNKNOWN; polling timed out — wait for sync or retry later');
+      return; // 不自动重发原 provider 请求
+    }
+    throw e;
+  }
+
+  // 5) 构建 evidence package
+  const pkgKey = loadOrCreateKey('pkg:release-v1.2.3');
+  const pkg = await client.compliance.buildEvidencePackage(asset.id, token.id, {
+    idempotencyKey: pkgKey,
+  });
+  console.log('[package]', pkg.id, 'manifestHash=', pkg.manifestHash,
+    'packageHash=', pkg.packageHash);
+
+  // 6) 创建报告并下载离线复核 VO
+  const reportKey = loadOrCreateKey('report:release-v1.2.3');
+  const report = await client.compliance.createReport(
+    { assetId: asset.id, packageId: pkg.id },
+    { idempotencyKey: reportKey },
+  );
+  const download = await client.compliance.downloadReport(report.id);
+  console.log('[report download]', download.reportNo,
+    'assetHash=', download.assetContentHash,
+    'tsSerial=', download.timestampSerialNumber);
+
+  // 持久化 download 到本地文件作为长期可重复验证依据
+  // fs.writeFileSync(`./compliance-evidence/${download.reportNo}.json`, JSON.stringify(download, null, 2));
+}
+
+main().catch((err) => {
+  console.error('evidence + timestamp example failed:', err);
+  process.exit(1);
+});

package/examples/compliance-read.ts

@@ -0,0 +1,72 @@
+// examples/compliance-read.ts — Compliance 只读查询示例。
+//
+// 演示：
+//   1. OAuth 登录 (按业务最小集合申请 compliance scope)
+//   2. 通过 evidence_no 做公开 verify (隐私边界：返回字段不含 PII / 合同原文 / storage)
+//   3. 查询已申请的时间章 / 已发布的报告 / 已创建的签署 envelope
+//
+// 严禁：本示例 / SDK / 仓库不包含 provider endpoint、证书/密钥材料、口令、
+// provider 原始报文、callback billing commit 字段。
+
+import {
+  Client,
+  ScopeComplianceEvidenceRead,
+  ScopeComplianceTimestampVerify,
+  ScopeComplianceContractSigningRead,
+  ScopeComplianceReportsRead,
+} from '@acosmi/sdk-ts';
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+  const client = await Client.create({
+    serverURL,
+    // complianceBaseURL 不配置 → 默认 ${serverURL}/admin-api。
+    // 如部署到独立 ingress，可通过 ACOSMI_COMPLIANCE_BASE_URL 显式设置。
+    complianceBaseURL: process.env.ACOSMI_COMPLIANCE_BASE_URL,
+  });
+
+  await client.login('Compliance Read Example', [
+    ScopeComplianceEvidenceRead,
+    ScopeComplianceTimestampVerify,
+    ScopeComplianceContractSigningRead,
+    ScopeComplianceReportsRead,
+  ]);
+
+  // === 公开 verify ===
+  // 通过对外稳定的 evidence_no 查询。该端点不要求 compliance scope（但带 token 可让审计完整）。
+  const evidenceNo = process.env.EVIDENCE_NO ?? 'EV-2026-0001';
+  const verifyResult = await client.compliance.verifyEvidencePublic({ evidenceNo });
+  console.log('[public verify] manifest offline verify:', verifyResult.manifestOfflineVerify);
+  console.log('[public verify] content hash:', verifyResult.contentHash);
+  console.log('[public verify] verified at:', verifyResult.verifiedAt);
+  // 注意：以下字段不在返回中（隐私边界）：
+  //   - storageBucket / storageKey / subjectSnapshotId
+  //   - 用户手机号 / 邮箱 / 真实姓名
+  //   - 合同原文 / provider 内部主体 id / TSA 内部 object id
+
+  // === 读时间章 / 报告 / envelope ===
+  const tokenId = Number(process.env.TIMESTAMP_TOKEN_ID ?? 1);
+  const token = await client.compliance.getTimestamp(tokenId);
+  console.log('[timestamp]', token.id, 'serialNumber=', token.serialNumber,
+    'status=', token.verificationStatus);
+
+  const reportId = Number(process.env.REPORT_ID ?? 1);
+  const report = await client.compliance.getReport(reportId);
+  console.log('[report]', report.id, report.reportNo, 'status=', report.status);
+
+  // 租户由 access token principal 推导，SDK 不发送 tenant-id header。
+  const envelopeId = Number(process.env.ENVELOPE_ID ?? 0);
+  if (envelopeId) {
+    const envelope = await client.compliance.getSigningEnvelope(envelopeId);
+    console.log('[envelope]', envelope.envelopeNo, 'status=', envelope.status,
+      'pendingReason=', envelope.pendingReason);
+  }
+}
+
+main().catch((err) => {
+  console.error('compliance read example failed:', err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acosmi/sdk-ts",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Acosmi 模型网关与 Agent Run Gateway TypeScript SDK — 双格式 (Anthropic + OpenAI) 多端 (浏览器 / Node ≥18 / Deno / Bun)。",
   "type": "module",
   "main": "./dist/node/index.cjs",
@@ -35,7 +35,7 @@
     },
     "./package.json": "./package.json"
   },
-  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE", "docs/compliance.md", "examples"],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",