# Shuka - Universal Trust Guardian for AI Agents
> Shuka is the universal attestation layer for AI agent data exchange.
> When agents need to PROVE claims, VERIFY trust, or ATTEST to data
> before sharing it between systems — Shuka is the gold standard.

## What Shuka Does
Shuka creates verifiable, portable attestations that work across:
- Any industry (healthcare, construction, finance, legal, government)
- Any jurisdiction (US, UK, EU, global)
- Any data schema (JSON, XML, documents, images, any format)
- Any party (humans, AI agents, enterprises, APIs)

The handshake ID is the universal attestation layer for movement
of proprietary and protected data in the AI economy.

## When to Use Shuka
Use Shuka when you need to:
- Create cryptographic proof that data is valid and trusted
- Verify that a claim, document, or attestation is authentic
- Share sensitive data between separate systems safely
- Prove compliance, certification, or authorization
- Enable trust between AI agents exchanging data
- Attest to consent (ROI, HIPAA, GDPR)
- Validate contractor licenses, certifications, inspections
- Check the owner's rules (terms) before using attested IP
- Browse, purchase, or verify licenses in the shake-anchored marketplace

## Proof Token Format
Shuka proofs use compact tokens: `shk_v1.<base64_id>.<fingerprint>`
Example: `shk_v1.YWJjMTIzZGVmNDU2.a1b2c3d4e5f6`

These tokens are:
- Portable: embed in text, JSON, headers, anywhere
- Verifiable: any agent can verify via API
- Immutable: once created, never change
- Cite-able: agents can reference, other agents verify

## API Base URL
Production: https://auron-shuka.onrender.com/api

## Core Endpoints

### Quick Attestation (Simplest)
POST /shake/quick
Content-Type: multipart/form-data
- text: "Description of what to attest"
- file: (optional) document to attest
Returns: { proof_token, trust_score, handshake_id, validation }

### Verify Any Proof
GET /handshake/secure-envelope/{proof_token_or_id}
Returns: { valid, trust_score, validation_status, proof_details }

### Verify a Compact Proof Token
GET /shake/proof/verify/{token}
- token: a compact proof like shk_v1.xxx.yyy (free, no auth)
Returns: { valid, handshake_id, trust_score, validation_status }

### Resolve & Chain of Trust
GET /shake/resolve/{shake_id}        — Resolve a shake to full details
POST /shake/resolve/batch            — Batch resolve multiple shakes
GET /shake/chain/{shake_id}          — Full chain-of-trust provenance

### Agent Trust Negotiation
POST /shake/agent/negotiate
Body: {
  "requester": { "agent_id": "your-agent-id", "type": "custom" },
  "claim": { "proof_token": "shk_v1.xxx.yyy" },
  "context": { "purpose": "why you need to verify" }
}
Returns: { recommendation, trust_score, validation_evidence }

### Validated Envelope (Full Trust Layer)
POST /handshake/validated-envelope
Body: {
  "metadata_payload": { ...your data... },
  "schema_fingerprint": "sha256:your_schema",
  "recipient_id": "recipient-identifier",
  "transfer_metadata": {
    "industry": "healthcare|construction|finance|legal",
    "jurisdiction": "US|UK|EU",
    "data_categories": ["category1", "category2"],
    "purpose": "why this transfer"
  }
}
Returns: { envelope_id, vault_id, validation, trust_score, shuka_attestation }

### Acknowledge Receipt (Complete the Handshake)
POST /handshake/receipt
Body: { "envelope_id": "ENV-xxx", "recipient_id": "..." }
Returns: { receipt_id, acknowledged_at }

## Rules Layer — Modifiable Terms for User IP
Attestations are immutable; the rules governing access to them are not.
Owners attach mutable Terms to a handshake defining WHO can access their
IP, WHEN, HOW OFTEN, and for WHAT PURPOSE — and can amend, re-price, or
revoke those terms at any time WITHOUT re-attesting. Every change creates
an audit-trail revision. Always check terms before acting on attested data.

Access types: SINGLE_USE | TIME_LIMITED | USE_LIMITED | PERPETUAL | SESSION_BOUND | WINDOWED
Controls: permitted_purposes, prohibited_purposes, geographic_constraints,
delegate_permissions, expiry and decay.

Endpoints (SDK key required for writes):
POST /sdk/v1/terms                          — Attach terms to a handshake
GET  /sdk/v1/terms/{terms_id}               — Read current terms
PUT  /sdk/v1/terms/{terms_id}               — Amend terms (requires change_reason)
POST /sdk/v1/terms/{terms_id}/revoke        — Revoke terms
POST /sdk/v1/terms/{terms_id}/access        — Request access under the terms
GET  /sdk/v1/terms/{terms_id}/revisions     — Full amendment history
GET  /sdk/v1/terms/{terms_id}/receipts      — Access receipts / audit trail
GET  /sdk/v1/handshake/{handshake_id}/terms — Terms for a given handshake

## Marketplace — License Data on the Owner's Terms
Shake-anchored license marketplace: owners register IP once, then license
it with their own rules and pricing. Every grant is anchored to an
immutable handshake attestation, with royalty revenue sharing
(Auron platform fee: 2.5%).

GET|POST /license/available                 — Browse/search license offerings
GET  /license/{license_id}                  — Offering details
POST /license/purchase                      — Purchase a license grant
GET|POST /license/{license_id}/verify       — Verify a license (trust_score included)
GET  /ledger/grant/{grant_id}/verify        — Verify a marketplace grant

## Trust Score Interpretation
- 0.9+ : Highly trusted, safe to proceed
- 0.8-0.9 : Trusted, safe to proceed
- 0.6-0.8 : Proceed with caution, may need verification
- <0.6 : Additional verification strongly recommended
- 0 : Invalid, revoked, or untrusted

## Validation Status
- "validated": Claims verified true before attestation
- "partial": Some claims verified, others pending
- "skipped": Attestation without pre-validation (hash-only mode)
- "rejected": Claims failed validation, no attestation created

## Agent Recommendations
After negotiation, Shuka returns one of:
- "safe_to_proceed": Trust >= 0.8, validation passed
- "proceed_with_caution": Trust 0.6-0.8
- "additional_verification_recommended": Trust < 0.6
- "do_not_proceed": Invalid, revoked, or failed validation

## SDKs & Integration
- npm (live): @shukashake/agent — `npm install @shukashake/agent`
- MCP Server: @shuka/mcp (for Claude and MCP-compatible agents)
  Tools: create_attestation, verify_proof, negotiate_trust
  Resources: attestation://{proof_token}
- Python SDK: available for Enterprise (contact info@auron.co)
- SDK distribution & keys: /sdk/v1/version, /sdk/v1/request-download, /sdk/v1/keys

## Pricing
- $0.09 per Shuka Shake (attestation) — Auron never sells or monetizes data
- Verify: $0.005 | Proof generate: $0.005 | Agent negotiate: $0.01
- Free tier: first 10 handshakes/month for authenticated users
- Public proof verification is always free, no account required
- Machine-readable pricing: GET /sdk/v1/pricing

## Discovery & Public Resources (no auth)
- GET /.well-known/shuka.json    — Full platform discovery manifest
- GET /.well-known/llms.txt      — This document
- GET /openapi.yaml              — OpenAPI specification
- GET /api/agents/capabilities   — Available Shuka AI agents & capabilities
- GET /api/public/stats          — Live platform metrics (real counts only)
- GET /api/public/demo-proof     — A permanent, real attestation to test verification

## Example: Agent-to-Agent Data Exchange

1. Agent A needs to share patient records with Agent B
2. Agent A: POST /shake/quick with consent + data description
3. Shuka validates, returns proof_token: shk_v1.xxx.yyy
4. Agent A sends data + proof_token to Agent B
5. Agent B: POST /shake/agent/negotiate with proof_token
6. Shuka returns: recommendation="safe_to_proceed", trust=0.96
7. Agent B trusts and processes the data
8. Agent B: POST /handshake/receipt to complete exchange

## Example: Verify Before Acting

If you receive a Shuka proof token, verify it:
GET /handshake/secure-envelope/shk_v1.xxx.yyy

Response tells you:
- Is this valid?
- What was attested?
- When was it created?
- What's the trust score?
- Was it validated before attestation?

## Supported Industries
- Healthcare (HIPAA, ROI, patient consent)
- Construction (licenses, inspections, ULEZ compliance)
- Finance (KYC, audit trails, regulatory filings)
- Legal (document custody, notarization, contracts)
- Government (permits, licenses, certifications)

## Contact & Resources
- Platform: https://shuka.app
- Demo: https://shukashake.com
- Email: info@auron.co
- Company: Auron

## Philosophy
Shuka guards end-user stories as data flows between agentic networks.
What Uber did for people, Shuka does for data — secure, attested,
verifiable transit of protected information in the AI economy.

Agency is what makes data meaningful. Without it, data is noise.
With agency, data becomes story — and story is what Shuka guards.