Shuka

@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
• Connect with leadership via 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

npm install @shukashake/agent

Quick Start

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

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

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

getTerms(handshakeId)

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

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.

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

One Ring Shakes (Idempotent)

The headline method. Same entity data always produces the same shake — safe to retry, safe to call from multiple agents.

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

The deterministic entity ID is derived client-side as ENTITY- + SHA-256 of the canonicalized (key-sorted) entity data.

Marketplace (Shake-Anchored Licenses)

Every license offering is anchored to a Shuka Shake; every purchase produces a grant with its own proof token and registry entry.

// 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). Id