@shukashake/agent

Universal Trust Guardian for AI Agents

The Shuka Shake is the trust layer for moving protected data in the AI economy. It doesn't own what's inside - it guards the exchange, respects confidentiality, and enforces terms without ever touching the metadata within.

This package is your agent's membership to the yacht club - where trust is negotiated, proof tokens are exchanged, and data flows with respect for rights.

What is Shuka?

Shuka provides cryptographically verified trust handshakes for AI-to-AI and AI-to-human data transfers. Every exchange is attested, auditable, and verifiable.

Use cases:

• Healthcare ROI (Release of Information) management
• Construction contractor/permit verification
• Cross-jurisdiction compliance attestation
• Data portability between enterprise systems
• AI agent verification and trust negotiation

The Shuka Shake is:

• Schema-agnostic - any data format works
• Industry-agnostic - healthcare, construction, finance, legal, government
• Jurisdiction-agnostic - works across borders and regulatory frameworks

Install

npm install @shukashake/agent

Quick Start

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

const shuka = new ShukaSDK({
  apiKey: process.env.SHUKA_API_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

Core Concepts

Proof Tokens

When you create an attestation, Shuka returns a proof token:

shk_v1.YWJjMTIzZGVm.a1b2c3d4

This token is:

• Portable - share it anywhere, verify it anywhere
• Verifiable - anyone with API access can verify it
• Persistent - the attestation record is immutable

Trust Scores

Every attestation has a trust score (0.0 - 1.0):

• 0.8+ - Safe to proceed
• 0.6-0.8 - Proceed with caution
• Below 0.6 - Additional verification recommended

Handshake Types

Shuka supports multiple handshake types for different use cases:

| Type | Use Case | |------|----------| | attestation | General attestations (default) | | license | License verification | | compliance | Compliance attestation | | compliance_attestation | Compliance with attestation | | release_of_information | Healthcare ROI | | partner_compliance | Partner compliance verification |

API Reference

ShukaSDK

Main SDK class for AI agent integration.

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

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

attest(description, options?)

Create a verifiable attestation.

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)

Verify a proof token.

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-to-agent trust negotiation. When you receive data with a proof from another agent, ask Shuka to vouch for their attestation.

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)

Complete the exchange by acknowledging receipt (the S'more model - both ends warm).

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

Terms and Conditions

The terms layer is how data owners set constraints on how their data can be used, and how recipients understand and accept those constraints.

Creating Attestations with Terms

Attach terms when creating attestations to control how data can be accessed:

const result = await shuka.attest(
  'Patient John Doe consents to release records to Dr. Smith',
  {
    industry: 'healthcare',
    jurisdiction: 'US',
    terms: {
      accessType: 'time_limited',           // How data can be accessed
      validUntil: '2026-12-31T23:59:59Z',   // Access expires on this date
      maxUses: 10,                          // Maximum 10 accesses
      permittedPurposes: ['care_coordination', 'treatment'],
      prohibitedPurposes: ['marketing', 'research'],
      allowDownstreamTransfer: false,       // Cannot share with third parties
      requiresAcceptance: true,             // Recipient must explicitly accept
      termsText: 'This data is provided solely for care coordination.'
    }
  }
);

Access Types

| Type | Description | |------|-------------| | single_use | One-time access, then terms expire | | time_limited | Access valid for a time period | | use_limited | Access valid for N uses | | perpetual | Unlimited access (rare, high trust) | | session_bound | Access tied to active session | | windowed | Access only during specific time windows |

getTerms(proofToken)

Get the terms attached to data before processing it:

const terms = await shuka.getTerms('shk_v1.abc123.xyz');

console.log(terms.access_type);         // 'time_limited'
console.log(terms.requires_acceptance); // true
console.log(terms.permitted_purposes);  // ['care_coordination', 'treatment']
console.log(terms.valid_until);         // '2026-12-31T23:59:59Z'

acceptTerms(proofToken, options)

When terms require explicit acceptance, formally accept before processing:

const acceptance = await shuka.acceptTerms('shk_v1.abc123.xyz', {
  purpose: 'care_coordination',
  agreeToDownstreamRestrictions: true
});

console.log(acceptance.accepted);    // true
console.log(acceptance.receipt_id);  // 'RECEIPT-xxx'

checkAccess(proofToken, options)

Verify you can still access data under current terms:

const access = await shuka.checkAccess('shk_v1.abc123.xyz', {
  purpose: 'billing'
});

if (access.permitted) {
  // Proceed with the data
  console.log('Remaining uses:', access.remaining_uses);
} else {
  console.log('Cannot proceed:', access.reason);
  // Reason: 'Purpose not in permitted_purposes'
}

revokeAccess(proofToken, options)

As data owner, revoke access when consent is withdrawn or terms violated:

await shuka.revokeAccess('shk_v1.abc123.xyz', {
  reason: 'Patient withdrew consent',
  cascadeDownstream: true  // Also revoke any downstream transfers
});

updateTerms(proofToken, updates)

Update terms for data you control (maintains full audit trail):

await shuka.updateTerms('shk_v1.abc123.xyz', {
  validUntil: '2027-06-30T23:59:59Z',
  permittedPurposes: ['care_coordination', 'billing', 'treatment']
});

getTermsHistory(proofToken)

Get the complete audit trail of terms changes:

const history = await shuka.getTermsHistory('shk_v1.abc123.xyz');
// Returns all terms versions, acceptances, and revocations

getChainOfTrust(handshakeId)

Get the full provenance chain for an attestation.

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

ShukaClient

Low-level client with direct API access, caching, and deduplication.

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

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

Registry Discovery

Find organizations that issue or accept specific shake types:

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

Interoperability Checking

Check if data can flow between two entities:

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 Platform Integrations

Claude Integration

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 Integration

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

Middleware

Create middleware for your agent pipeline:

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 Server (Claude Desktop)

Run as an MCP server for Claude Desktop integration:

npx @shukashake/agent/mcp

Or configure in Claude Desktop's claude_desktop_config.json:

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

Available MCP Tools:

• create_attestation - Create a verifiable attestation
• verify_proof - Verify a proof token
• negotiate_trust - Agent-to-agent trust negotiation

Available MCP Resources:

• attestation://{proof_token} - Look up attestation details

Caching

The client includes built-in LRU caching with TTL:

| Operation | Cache Duration | |-----------|---------------| | verify() | 5 minutes (success), 30 seconds (failure) | | getChainOfTrust() | 10 minutes | | discoverRegistries() | 15 minutes | | checkInteroperability() | 10 minutes | | getTerms() | 5 minutes | | checkAccess() | 2.5 minutes |

Duplicate in-flight requests are automatically deduplicated.

// 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

Full TypeScript support with type declarations:

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
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | SHUKA_API_KEY | Your Shuka SDK API key | | SHUKA_API_URL | API base URL (default: production) |

Pricing

Shuka uses pay-per-use pricing:

| Operation | Cost | |-----------|------| | Create attestation | $0.01 | | Verify attestation | $0.005 | | Generate proof | $0.005 | | Agent negotiation | $0.01 |

Free tier: 10 handshakes/month for authenticated users.

Get your API key at shuka.app/partner/sdk

Links

• Platform: shuka.app
• Documentation: docs.shuka.app
• Demo: shuka.app/demo

Company

Built by Auron - the gold standard of trust.

License

MIT