shuka

@shukashake/agent

AI エージェントのためのユニバーサル・トラスト・ガーディアン

Shuka Shake は、AI エコノミーにおける保護対象データの移動を支える信頼レイヤーです。データの中身を所有するのではなく、メタデータに触れることなく、交換を保護し、機密性を尊重し、条件を適用します。

このパッケージは、エージェントがヨットクラブの会員になるためのものです。ここでは、信頼について交渉し、証明トークンを交換し、権利を尊重しながらデータが流通します。

v2.1.0 — あらゆるものが Shuka Shake です。 これは、証明、ルールレイヤー、Shake に紐付いたライセンスマーケットプレイス、エンタープライズライセンス、レジストリ台帳を統合する、正規の One Ring パッケージです。全体のフローは次のとおりです。

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

1. Shake — あらゆるエンティティに対して、冪等な Shuka Shake を作成します（同じ入力なら、いつでも同じ Shake が作成されます）
2. Terms — 変更可能なルールを、変更不可能なハンドシェイクに紐付けます
3. Offering — Shake に紐付いたライセンス提供を発行します
4. Grant — 提供を購入し、独自の証明トークンを持つ付与を受け取ります
5. Registry proof — 付与とその完全な台帳チェーンを、公開で検証します

---

⚠️ パートナーアクセスが必要です

この SDK を利用するには、認証済みのパートナーアカウントと SDK キーが必要です。

認証には SDK キーのみを使用します。認証が必要な操作はすべて SDK キー（X-SDK-API-Key として送信）を使います。ほとんどの操作は Shuka の /api/sdk/v1/* サーフェスを経由します。検証と信頼交渉には、公開 /api/shake/* および /api/handshake/* エンドポイントを使用します（検証は無料で、キーは不要です）。エージェントや開発者が 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 に記録されます。エージェントの識別情報（X-Agent-Id / X-Agent-Type）は、監査用にラベル付きの信頼されない asserted_agent メタデータとして記録されますが、所有権を設定することはありません。キーが未割り当ての場合、作成は匿名（"access": "public"）に切り替わります。POST /api/sdk/v1/partner/keys/claim でキーを申請してください。

---

Shuka とは？

Shuka は、AI 間および AI と人間の間で行われるデータ転送のために、暗号技術で検証可能な信頼ハンドシェイクを提供します。すべての交換は証明され、監査可能で、検証できます。

ユースケース：

• 医療分野における ROI（情報開示）管理
• 建設業者や許可証の検証
• 複数の管轄区域にまたがるコンプライアンス証明
• エンタープライズシステム間のデータポータビリティ
• AI エージェントの検証と信頼交渉

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	医療分野の ROI
partner_compliance	パートナーのコンプライアンス検証

API リファレンス

ShukaSDK

AI エージェントとの連携に使用するメインの 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?)

エージェント間の信頼交渉です。別のエージェントから証明付きのデータを受け取った場合、その証明を 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)

受領を確認して交換を完了します（スモアモデル — 両端を温めます）。

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	1 回限りのアクセス。その後、規約は失効します
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');

ワンリングシェイク（冪等）

主要メソッドです。同じエンティティデータからは常に同じシェイクが生成されるため、安全に再試行でき、複数のエージェントから呼び出しても安全です。

// 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 は、クライアント側で、正規化（キーでソート）されたエンティティデータの SHA-256 の前に ENTITY- を付けて生成されます。

マーケットプレイス（シェイクに紐付いたライセンス）

すべてのライセンス提供は 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 による規約）

変更可能な規約を不変のハンドシェイクに設定できます。ルールはシェイクとともに引き継がれ、変更のたびに受領記録が作成されます。

// 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'
});

レジストリーの検索

特定の種類のシェイクを発行または受け入れる組織を検索します。

// 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');

相互運用性の確認

2 つのエンティティ間でデータをやり取りできるか確認します。

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');

ミドルウェア

エージェントのパイプライン用にミドルウェアを作成します。

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）

Claude Desktop との統合用に、MCP サーバーとして実行します。

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 種類、統合済み）：

ワンリングのシェイク

• create_idempotent_shake - 推奨：あらゆるエンティティのシェイクを作成（または既存のシェイクを返す）します。同じ入力には同じシェイクが返されます
• lookup_shake - 作成せずに、エンティティデータから既存のシェイクを検索します
• verify_shake - ハンドシェイク ID でシェイクを検証します

アテステーション（レガシー互換）

• create_attestation - 検証可能なアテステーションを作成します
• verify_proof - プルーフトークンを検証します
• negotiate_trust - エージェント間の信頼交渉

マーケットプレイス

• browse_marketplace - シェイクに紐付けられたライセンス提供を検索するか、ID で詳細を確認します
• issue_license - ハンドシェイクからライセンス提供を発行します（license:write が必要）
• purchase_license - 提供を購入し、プルーフトークン付きの許諾を取得します
• verify_grant - 許諾、その紐付け先ライセンス、台帳チェーンの整合性を検証します

エンタープライズ

• enterprise_licenses - シートベースのエンタープライズライセンスを閲覧または取得します

ルールレイヤー

• manage_terms - 条項の作成、取得、更新、取り消し、アクセスの記録、改訂、レシートの管理を行います

レジストリ

• registry - 台帳履歴、レジストリの検出、発行可否・受け入れ可否、相互運用性チェック

利用可能な MCP リソース：

• attestation://{proof_token} - アテステーションの詳細を参照します
• grant://{grant_id} - 許諾を公開検証します

キャッシュ

クライアントには、TTL 付きの LRU キャッシュが組み込まれています。

操作	キャッシュ期間
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 は従量課金制を採用しており、パートナーには利用量に応じた割引が適用されます。

料金プラン：

• Developer（従量課金） - Stripe 経由で操作ごとに請求されます
• Enterprise（サブスクリプション） - ハンドシェイクの割り当て量が含まれ、超過分は別途請求されます

料金の詳細は、パートナー登録時に案内されます。エンタープライズパートナーには最大 30% の利用量割引が適用されます。

最新の料金は、共有バックエンドの料金表 GET /api/sdk/v1/pricing から取得してください。金額をハードコードしないでください（レスポンスには tier_discounts と ip_report などの製品ごとのブロックも含まれます）。Shuka の全サービスで共通する SDK v2 の課金仕様として、無料プランはありません。シェイクの登録は課金対象ですが、既存のプルーフ、トークン、許諾の検証は無料です。同一の課金対象リクエストはコンテンツベースで冪等です（再実行時には既存のレコードが返され、冪等なシェイクの処理では was_created: false となり、新たな課金は発生しません）。エージェントの信頼交渉（negotiate）とポートフォリオの読み取り（getPortfolio）も課金対象です。

パートナーになるには： [email protected] にお問い合わせいただくか、shuka.app をご覧ください。

リンク

• プラットフォーム：shuka.app
• デモ：shuka.app/demo
• Python SDK（v2.0.0）：PyPI パッケージではなく、署名付き URL 経由で tarball を配布しています。GET /api/sdk/v1/download を使用してください。Auron_Shuka リポジトリの shukaSDK/README.md、ルートレジストリから生成された shukaSDK/API_SPECIFICATION.md、shukaSDK/MIGRATION.md を参照してください。

会社

信頼の最高基準を掲げる Auron が開発しました。

ライセンス

MIT