shuka

@shukashake/agent

AI Agent 的通用信任守护者

Shuka Shake 是 AI 经济中传递受保护数据的信任层。它不拥有数据内容，而是守护交换过程、尊重机密性，并在完全不触及其中元数据的情况下强制执行条款。

这个软件包是你的 Agent 加入游艇俱乐部的通行证——在这里协商信任、交换证明令牌，并以尊重权利的方式传递数据。

v2.1.0 — 一切皆是 Shuka Shake。 这是规范的 One Ring 软件包：一个 SDK 和一个 MCP 服务，整合了证明、规则层、以 Shake 为锚点的许可证市场、企业许可和注册表账本。完整流程：

shake → terms (rules layer) → license offering → grant → registry proof

1. Shake — 为任意实体创建幂等的 Shuka Shake（相同输入，永远得到相同的 shake）
2. 条款 — 将可修改的规则附加到不可变的握手上
3. 提供项 — 创建以 shake 为锚点的许可证提供项
4. 授权 — 购买提供项；获得带有独立证明令牌的授权
5. 注册表证明 — 公开验证授权及其完整账本链

---

⚠️ 需要合作伙伴权限

此 SDK 需要经过验证的合作伙伴账户和 SDK 密钥。

身份验证仅使用 SDK 密钥：每个经过身份验证的操作都会使用你的 SDK 密钥（通过 X-SDK-API-Key 发送）。大多数操作通过 Shuka 的 /api/sdk/v1/* 接口处理；验证和信任协商则使用公开的 /api/shake/* 和 /api/handshake/* 端点（验证免费且无需密钥）。Agent 和开发者无需处理 JWT 或平台原始 API 密钥。签发密钥时会为其配置相应的权限范围（例如 license:read、license:write、transaction:write）。

你可以安装此软件包，但没有 Auron 签发的授权 SDK 密钥便无法使用。

成为合作伙伴：

• 发送邮件至 [email protected]
• 通过 shuka.app 联系管理团队

获批后，你将收到用于启用 SDK 的 API 凭证。

**归属模式：**密钥的用户绑定即为归属。此 SDK 创建的每个 shake 都归属于分配给该密钥的合作伙伴用户 （user_id / partner_id），并记录创建它的密钥（api_key_id）。 应用内的最终用户归属由你的客户端引用标识（attest 调用中的 id 字段），该标识会写入幂等命名空间和 handshake_metadata。Agent 身份（X-Agent-Id / X-Agent-Type）会作为带标签且不受信任的 asserted_agent 元数据 记录下来以供审计——它绝不会决定所有权。如果你的密钥未分配给用户，创建操作将降级为匿名 （"access": "public"）；请通过 POST /api/sdk/v1/partner/keys/claim 认领密钥。

---

什么是 Shuka？

Shuka 为 AI 对 AI 以及 AI 对人的数据传输提供经过加密验证的信任握手。每次交换都有证明记录，可供审计和验证。

使用场景：

• 医疗保健 ROI（信息披露）管理
• 建筑承包商／许可证验证
• 跨司法辖区的合规证明
• 企业系统之间的数据可移植性
• AI Agent 验证与信任协商

Shuka Shake 的特点：

• 与架构无关——支持任意数据格式
• 与行业无关——适用于医疗保健、建筑、金融、法律和政府领域
• 与司法辖区无关——可跨境并适用于不同监管框架

安装

npm install @shukashake/agent

快速入门

const { ShukaSDK } = require('@shukashake/agent');

const shuka = new ShukaSDK({
  apiKey: process.env.SHUKA_API_KEY  // your SDK key
});

// Create an attestation (the Shuka Shake)
const result = await shuka.attest(
  'Patient John Doe consents to release records to Dr. Smith',
  { industry: 'healthcare', jurisdiction: 'US' }
);

// Share the proof token - portable, verifiable, universal
console.log(result.proof_token); // shk_v1.xxx.yyy

快速入门：统一流程

// 1. SHAKE — idempotent: same entity data always yields the same shake
const shake = await shuka.shake('brand', {
  name: 'ACME Studios',
  registration: 'US-TM-12345'
}, { purpose: 'brand identity attestation', industry: 'universal' });

// 2. TERMS — attach modifiable rules to the immutable handshake
await shuka.createTerms(shake.handshake_id, {
  accessType: 'time_limited',
  permittedPurposes: ['licensing', 'verification']
});

// 3. OFFERING — issue a license offering anchored to the shake
const offering = await shuka.issueLicense({
  anchorHandshakeId: shake.handshake_id,
  brand: 'ACME Studios',
  rightsHolder: 'ACME Holdings LLC',
  validUntil: '2027-12-31T23:59:59Z',
  buyToOpenPrice: 500
});

// 4. GRANT — purchase the offering (buyer side)
const grant = await shuka.purchaseLicense(offering.license.id, 500);

// 5. REGISTRY PROOF — verify the grant and its ledger chain
const proof = await shuka.verifyGrant(grant.grant_id);

核心概念

证明令牌

创建证明后，Shuka 会返回一个证明令牌：

shk_v1.YWJjMTIzZGVm.a1b2c3d4

此令牌具有以下特点：

• 可移植——可在任何地方分享，也可在任何地方验证
• 可验证——任何拥有 API 访问权限的人都可以验证
• 持久——证明记录不可变

信任评分

每项证明都有一个信任评分（0.0 - 1.0）：

• 0.8+——可以安全地继续
• 0.6-0.8——谨慎继续
• 低于 0.6——建议进行额外验证

握手类型

Shuka 支持多种握手类型，以适用于不同场景：

类型	用途
attestation	通用证明（默认）
license	许可证验证
compliance	合规证明
compliance_attestation	带证明的合规
release_of_information	医疗信息披露授权
partner_compliance	合作伙伴合规验证

API 参考

ShukaSDK

用于集成 AI Agent 的主要 SDK 类。

const { ShukaSDK } = require('@shukashake/agent');

const shuka = new ShukaSDK({
  apiKey: 'your-api-key',
  agentName: 'my-agent'  // For audit trails
});

attest(description, options?)

创建可验证的证明。

const result = await shuka.attest(
  'Contractor ABC Corp is licensed for electrical work in Texas',
  {
    industry: 'construction',
    jurisdiction: 'US-TX',
    metadata: {
      contractor_id: 'ABC-123',
      license_number: 'TX-ELEC-456'
    }
  }
);

// Returns:
// {
//   success: true,
//   proof_token: 'shk_v1.xxx.yyy',
//   handshake_id: 'uuid',
//   trust_score: 0.85
// }

verify(proofToken)

验证证明令牌。

const result = await shuka.verify('shk_v1.xxx.yyy');

// Returns:
// {
//   verified: true,
//   trust_score: 0.85,
//   handshake_id: 'uuid',
//   created_at: '2024-01-01T00:00:00Z'
// }

negotiate(proofToken, purpose?)

Agent 间信任协商。当你收到来自其他 Agent 且附带证明的数据时，请 Shuka 为其证明背书。

const trust = await shuka.negotiate(
  incomingProofToken,
  'processing patient data for care coordination'
);

if (trust.recommendation === 'safe_to_proceed') {
  // The data exchange is trusted - proceed
} else if (trust.recommendation === 'proceed_with_caution') {
  // Consider additional verification
} else {
  // Do not proceed
}

acknowledgeReceipt(envelopeId)

通过确认收件来完成交换（S'more 模型——双方都暖洋洋的）。

await shuka.acknowledgeReceipt('ENV-xxx');

条款和条件

条款层用于让数据所有者设置其数据的使用限制，并帮助接收方了解并接受这些限制。

创建带条款的证明

创建证明时附加条款，以控制数据的访问方式：

const result = await shuka.attest(
  'Patient John Doe (US, healthcare) consents to release records to Dr. Smith',
  {
    terms: {
      accessType: 'time_limited',           // How data can be accessed
      validityDays: 365,                    // Days the terms remain valid
      requireReceipt: true,                 // Accesses must be receipted
      permittedPurposes: ['care_coordination', 'treatment'],
      prohibitedPurposes: ['marketing', 'research']
    }
  }
);

在证明文本中包含行业／司法管辖区背景信息—— quick-attest 端点会记录文本和条款。若要设置更丰富的限制 （最大使用次数、下游规则、定价），可在之后通过 createTerms(handshakeId, terms) 附加完整条款（参见下文规则层）。

访问类型

类型	说明
single_use	一次性访问，之后条款失效
time_limited	在指定时段内有效的访问
use_limited	有效访问次数为 N 次
perpetual	无限访问（罕见，信任度高）
session_bound	访问权限与活动会话绑定
windowed	仅可在特定时间窗口内访问

getTerms(handshakeId)

在处理握手数据之前，获取附加到握手上的条款：

const result = await shuka.getTerms('handshake-uuid');

console.log(result.terms.access_type);         // 'time_limited'
console.log(result.terms.permitted_purposes);  // ['care_coordination', 'treatment']
console.log(result.terms.id);                  // terms_id for the ID-based methods

在 2.1.1 中移除： acceptTerms、checkAccess、revokeAccess、 updateTerms、getTermsHistory 和 getTermsAcceptors 调用的是遗留 路由，这些路由在服务端从未存在（每次调用都会返回 404）。现在它们会抛出 NOT_SUPPORTED，并指向规则层中可用的对应方法：recordTermsAccess、 revokeTermsById、updateTermsById、 getTermsRevisions 和 getTermsReceipts——这些方法都以 getTerms(handshakeId) 或 createTerms() 返回的 terms_id 为键。

getChainOfTrust(handshakeId)

获取证明的完整来源链。

const chain = await shuka.getChainOfTrust('handshake-uuid');

一次 Ring Shake（幂等）

核心方法。相同的实体数据始终会产生相同的 shake——可安全重试，也可由多个 Agent 调用。

// Create (or return the existing) shake for an entity
const shake = await shuka.shake('vehicle', {
  registration: 'ABC123',
  emission_standard: 'euro6'
}, {
  purpose: 'ULEZ compliance attestation',
  industry: 'construction',      // healthcare | construction | finance | legal | government | sdk | universal
  handshakeType: 'attestation',  // attestation | verification | transfer | consent
  expiresInDays: 365
});

// Look up an existing shake without creating one
const existing = await shuka.lookupShake('vehicle', { registration: 'ABC123', emission_standard: 'euro6' });

// Verify a shake by ID
const status = await shuka.verifyShake(shake.handshake_id);

确定性实体 ID 在客户端生成，格式为 ENTITY- + 实体规范化（按键排序）数据的 SHA-256 哈希值。

市场（以 Shake 为锚定的许可证）

每项许可证都以 Shuka Shake 为锚定；每次购买都会生成一项授权，并附带其专属证明令牌和注册表条目。

// Browse offerings
const results = await shuka.searchLicenses({ q: 'ACME', brand: 'ACME Studios', page: 1 });

// Inspect and validate a specific offering
const details = await shuka.getLicense(licenseId);
const validity = await shuka.validateLicense(licenseId);

// Issue an offering FROM a handshake (requires SDK key with license:write + issuer role)
const offering = await shuka.issueLicense({
  anchorHandshakeId: 'handshake-uuid',   // required
  brand: 'ACME Studios',                 // required
  rightsHolder: 'ACME Holdings LLC',     // required
  validUntil: '2027-12-31T23:59:59Z',    // required
  buyToOpenPrice: 500,
  permittedUses: ['merchandising'],
  prohibitedUses: ['resale'],
  maxGrants: 100,
  royaltyPercentage: 5
});

// Purchase → grant (alias: acquireLicense). Idempotent per buyer+license:
// replays and already-owned licenses return 409 with no double charge;
// a stale payment amount returns 400 carrying the current license_price.
// (Escrow is not available.)
const grant = await shuka.purchaseLicense(licenseId, 500);

// Verify a grant + its ledger chain integrity (public)
const proof = await shuka.verifyGrant('GRANT-xxx');

// Your holdings and any entity's ledger history
const portfolio = await shuka.getPortfolio();
const history = await shuka.getHistory('license', licenseId);

企业许可证

面向团队的席位许可证：

const offers = await shuka.browseEnterpriseLicenses({ brand: 'ACME', minSeats: 50 });

暂不支持获取： 企业席位模型尚未在服务端实现—— acquireEnterpriseSeats 目前对所有请求都会返回 501 not_implemented。单项授权请使用 purchaseLicense。

规则层（按 ID 管理条款）

在不可变握手上修改条款——规则随 shake 一同传递，每次更改都会生成回执：

// Create terms bound to a handshake
const terms = await shuka.createTerms('handshake-uuid', {
  accessType: 'use_limited',
  accessConfig: { max_uses: 10 },
  permittedPurposes: ['care_coordination'],
  prohibitedPurposes: ['marketing']
});

// Read / amend / revoke
await shuka.getTermsById(terms.terms_id);
await shuka.amendTerms(terms.terms_id, { permitted_purposes: ['care_coordination', 'billing'] });
await shuka.revokeTermsById(terms.terms_id, { reason: 'Consent withdrawn', cascadeDownstream: true });

// Record an access against the terms (creates a receipt)
await shuka.recordAccess(terms.terms_id, { purpose: 'care_coordination' });

// Full audit trail
await shuka.getTermsRevisions(terms.terms_id);
await shuka.getTermsReceipts(terms.terms_id);
await shuka.getHandshakeTerms('handshake-uuid');  // all terms on a handshake

注册表发现（SDK 直通方法）

也可直接通过 ShukaSDK 使用：

await shuka.discoverRegistries({ industry: 'healthcare', verifiedOnly: true });
await shuka.lookupRegistry('hospital-abc');
await shuka.canIssue('hospital-abc', 'release_of_information');
await shuka.willAccept('clinic-xyz', 'release_of_information');
await shuka.checkInteroperability('hospital-abc', 'clinic-xyz', 'release_of_information');

ShukaClient

提供直接 API 访问、缓存和去重功能的底层客户端。

const { ShukaClient } = require('@shukashake/agent/client');

const client = new ShukaClient({
  apiKey: 'your-api-key',
  agentId: 'my-agent',
  agentType: 'claude'
});

注册表发现

查找签发或接受特定 shake 类型的组织：

// Discover healthcare organizations
const registries = await client.discoverRegistries({
  industry: 'healthcare',
  shakeType: 'release_of_information',
  verifiedOnly: true
});

// Check if an entity can issue a shake type
const canIssue = await client.canIssue('hospital-abc', 'release_of_information');

// Check if an entity will accept a shake type
const willAccept = await client.willAccept('clinic-xyz', 'release_of_information');

互操作性检查

检查数据是否可以在两个实体之间流转：

const interop = await client.checkInteroperability(
  'hospital-abc',      // issuer
  'clinic-xyz',        // receiver
  'release_of_information'
);

if (interop.interoperable) {
  // Clinic XYZ will accept ROI from Hospital ABC
}

AI 平台集成

Claude 集成

const { ClaudeIntegration } = require('@shukashake/agent');

const claude = new ClaudeIntegration({ apiKey: '...' });

// Returns Claude-formatted responses
const result = await claude.attestForClaude('My claim');
const verified = await claude.verifyForClaude('shk_v1.xxx.yyy');
const trust = await claude.negotiateForClaude(proofToken, 'purpose');

ChatGPT 集成

const { ChatGPTIntegration } = require('@shukashake/agent');

const gpt = new ChatGPTIntegration({ apiKey: '...' });

// Returns GPT function-calling formatted responses
const result = await gpt.attestForGPT('My claim');
const verified = await gpt.verifyForGPT('shk_v1.xxx.yyy');
const trust = await gpt.negotiateForGPT(proofToken, 'purpose');

中间件

为你的 Agent 流水线创建中间件：

const { createShukaMiddleware, createAttestationMiddleware } = require('@shukashake/agent');

// Verification middleware for incoming data
const verifyTrust = createShukaMiddleware({ apiKey: '...' });

const trust = await verifyTrust(incomingProofToken, 'processing request');
if (trust.shouldProceed) {
  // Safe to act on the data
}

// Attestation middleware for outbound data
const createProof = createAttestationMiddleware({ apiKey: '...' });

const proof = await createProof('My claim', { industry: 'healthcare' });
// Include proof.proofToken in your response

MCP 服务（Claude Desktop）

作为 MCP 服务运行，以集成 Claude Desktop：

npx @shukashake/agent/mcp

或者在 Claude Desktop 的 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "shuka": {
      "command": "npx",
      "args": ["@shukashake/agent/mcp"],
      "env": {
        "SHUKA_API_KEY": "your-api-key"
      }
    }
  }
}

可用的 MCP 工具（13 个，统一）：

One Ring 摇动

• create_idempotent_shake - 推荐：为任意实体创建 shake（或返回已有 shake）——相同输入，相同 shake
• lookup_shake - 根据实体数据查找已有 shake，但不创建新的 shake
• verify_shake - 使用其握手 ID 验证 shake

证明（兼容旧版）

• create_attestation - 创建可验证的证明
• verify_proof - 验证证明令牌
• negotiate_trust - Agent 之间的信任协商

市场

• browse_marketplace - 搜索以 shake 为锚定的许可，或按 ID 查看某项许可
• issue_license - 从握手签发许可（需要 license:write）
• purchase_license - 购买许可 → 获得附带证明令牌的授权
• verify_grant - 验证授权、其锚定许可以及账本链完整性

企业

• enterprise_licenses - 浏览或获取基于席位的企业许可

规则层

• manage_terms - 创建／获取／更新／撤销条款，记录访问、修订和收据

注册表

• registry - 账本历史、注册表发现、可否签发／是否接受、互操作性检查

可用的 MCP 资源：

• attestation://{proof_token} - 查询证明详情
• grant://{grant_id} - 公开验证授权

缓存

客户端内置 LRU 缓存，并支持 TTL：

操作	缓存时长
verify()	5 分钟（成功），30 秒（失败）
getChainOfTrust()	10 分钟
discoverRegistries()	15 分钟
checkInteroperability()	10 分钟
getTerms()	5 分钟
checkAccess()	2.5 分钟
verifyShake()	5 分钟（成功），30 秒（失败）
verifyGrant()	5 分钟（成功），30 秒（失败）

自动对重复的进行中请求进行去重。

// Check cache stats
const stats = shuka.getCacheStats();
console.log(stats);
// {
//   verify: { size: 5, hits: 10, misses: 2, hitRate: '83.3%' },
//   chain: { size: 2, ... },
//   ...
// }

// Clear cache
shuka.clearCache();

// Invalidate specific token
shuka.invalidate('shk_v1.xxx.yyy');

TypeScript

全面支持 TypeScript，并提供类型声明：

import {
  ShukaSDK,
  HandshakeType,
  TrustRecommendation,
  Industry,
  AccessType,
  TermsStatus,
  type AttestationResult,
  type NegotiationResult,
  type TermsResult,
  type AccessCheckResult
} from '@shukashake/agent';

const shuka = new ShukaSDK({ apiKey: process.env.SHUKA_API_KEY });

// Create attestation with terms
const result: AttestationResult = await shuka.attest('My claim', {
  industry: Industry.HEALTHCARE,
  terms: {
    accessType: AccessType.TIME_LIMITED,
    validUntil: '2026-12-31T23:59:59Z',
    permittedPurposes: ['care_coordination'],
    requiresAcceptance: true
  }
});

// Check terms before processing
const terms: TermsResult = await shuka.getTerms(result.proof_token!);
if (terms.requires_acceptance) {
  await shuka.acceptTerms(result.proof_token!, { purpose: 'care_coordination' });
}

// Verify access is permitted
const access: AccessCheckResult = await shuka.checkAccess(result.proof_token!, {
  purpose: 'care_coordination'
});

if (access.permitted) {
  const trust: NegotiationResult = await shuka.negotiate(result.proof_token!);
  if (trust.recommendation === TrustRecommendation.SAFE_TO_PROCEED) {
    // Proceed with data
  }
}

环境变量

变量	描述
SHUKA_API_KEY	你的 Shuka SDK API 密钥
SHUKA_API_URL	API 基础 URL（默认：生产环境）

定价

Shuka 按使用量付费，并为合作伙伴提供批量折扣。

定价层级：

• 开发者（按使用量付费） - 通过 Stripe 按操作计费
• 企业（订阅） - 包含握手配额，超额部分另行计费

定价详情将在合作伙伴入驻期间提供。企业合作伙伴可享受最高 30% 的批量折扣。

实时价格来自共享后端价格表 GET /api/sdk/v1/pricing——切勿对金额进行硬编码（响应中还包含 tier_discounts 以及 ip_report 等按产品划分的区块）。与整个 Shuka 产品体系一致（SDK v2 计费语义）：没有免费层，注册 shake 需要付费，验证现有证明／令牌／授权免费；相同的计费请求具有内容幂等性（重放会返回现有记录——幂等 shake 接口会返回 was_created: false——不会产生新费用）。Agent 信任协商（negotiate）和投资组合读取（getPortfolio）也需要付费。

成为合作伙伴： [email protected]，或访问 shuka.app

链接

• 平台：shuka.app
• 演示：shuka.app/demo
• Python SDK（v2.0.0）：通过预签名 tarball 分发，使用 GET /api/sdk/v1/download 获取——没有 PyPI 包。请参阅 Auron_Shuka 仓库中的 shukaSDK/README.md、shukaSDK/API_SPECIFICATION.md（根据路由注册表生成）和 shukaSDK/MIGRATION.md。

公司

由 Auron 打造——信任领域的黄金标准。

许可证

MIT