shuka-agent

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

**v2.1.0 — Everything is a Shuka Shake.** This is the canonical One Ring package: one SDK and one MCP server uniting attestation, the rules layer, the shake-anchored license marketplace, enterprise licensing, and the registry ledger. The full flow:

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

1. **Shake** — create an idempotent Shuka Shake for any entity (same input, same shake, forever)
2. **Terms** — attach modifiable rules to the immutable handshake
3. **Offering** — issue a license offering anchored to the shake
4. **Grant** — purchase the offering; receive a grant with its own proof token
5. **Registry proof** — verify the grant and its full ledger chain, publicly

---

## ⚠️ Partner Access Required

**This SDK requires a verified partner account and an SDK key.**

Authentication is SDK-key-only: every authenticated operation uses your SDK key (sent as `X-SDK-API-Key`). Most operations route through Shuka's `/api/sdk/v1/*` surface; verification and trust-negotiation use the public `/api/shake/*` and `/api/handshake/*` endpoints (verification is free and needs no key). Agents and developers never handle JWTs or raw platform API keys. Scoped permissions (e.g. `license:read`, `license:write`, `transaction:write`) are attached to the key at issuance.

You can install this package, but it will not function without an authorized SDK key issued by Auron.

**To become a partner:**
- Email [info@auron.co](mailto:info@auron.co)
- Connect with leadership via [shuka.app](https://shuka.app)

Once approved, you'll receive API credentials to activate the SDK.

**Attribution model:** the key's user binding IS the attribution. Every shake
this SDK mints is owned by the partner user your key is assigned to
(`user_id` / `partner_id`) and stamped with the minting key (`api_key_id`).
Per-end-user attribution inside your app is your client reference (the `id`
field on attest calls), which lands in the idempotency namespace and
`handshake_metadata`. Agent identity (`X-Agent-Id` / `X-Agent-Type`) is
recorded as labeled-untrusted `asserted_agent` metadata for audit — it never
sets ownership. If your key is unassigned, creations degrade to anonymous
(`"access": "public"`); claim the key via `POST /api/sdk/v1/partner/keys/claim`.

---

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

### Quick Start: The United Flow

```javascript
// 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);
```

## 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 (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']
    }
  }
);
```

Include industry/jurisdiction context in the attested text itself — the
quick-attest endpoint records the text and terms. For richer constraints
(max uses, downstream rules, pricing), attach full terms afterwards with
`createTerms(handshakeId, terms)` (see Rules Layer below).

#### 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(handshakeId)

Get the terms attached to a handshake before processing its data:

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

> **Removed in 2.1.1:** `acceptTerms`, `checkAccess`, `revokeAccess`,
> `updateTerms`, `getTermsHistory`, and `getTermsAcceptors` called legacy
> routes that never existed server-side (every call 404'd). They now throw
> `NOT_SUPPORTED` with a pointer to the working equivalent in the Rules
> Layer: `recordTermsAccess`, `revokeTermsById`, `updateTermsById`,
> `getTermsRevisions`, and `getTermsReceipts` — all keyed by the `terms_id`
> returned from `getTerms(handshakeId)` or `createTerms()`.

#### getChainOfTrust(handshakeId)

Get the full provenance chain for an attestation.

```javascript
const chain