npm package: @shukashake/agent
Description: Universal Trust Guardian for AI Agents - The attestation layer for moving protected data in the AI economy
Author: Auron
Latest version: 2.0.0

# @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

```bash
npm install @shukashake/agent
```

## Quick Start

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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).

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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):

```javascript
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:

```javascript
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.

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

### ShukaClient

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

```javascript
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:

```javascript
// 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:

```javascript
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

```javascript
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

```javascript
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:

```javascript
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:

```bash
npx @shukashake/agent/mcp
```

Or configure in Claude Desktop's `claude_desktop_config.json`:

```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.

```javascript
// 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:

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

## 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](https://shuka.app/partner/sdk)

## Links

- **Platform**: [shuka.app](https://shuka.app)
- **Documentation**: [docs.shuka.app](https://docs.shuka.app)
- **Demo**: [shuka.app/demo](https://shuka.app/demo)

## Company

Built by **Auron** - the gold standard of trust.

## License

MIT