@ixo/ucan 1.0.0 → 1.0.1

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @ixo/ucan@1.0.0 build /home/runner/actions-runner/_work/ixo-oracles-boilerplate/ixo-oracles-boilerplate/packages/ucan
+> @ixo/ucan@1.0.1 build /home/runner/actions-runner/_work/ixo-oracles-boilerplate/ixo-oracles-boilerplate/packages/ucan
 > tsc
 

package/README.md

@@ -1,189 +1,243 @@
 # @ixo/ucan
 
-UCAN (User Controlled Authorization Networks) implementation for IXO Services. This package wraps the battle-tested [ucanto](https://github.com/storacha/ucanto) library and provides IXO-specific extensions for DID resolution and MCP tool authorization.
+A framework-agnostic UCAN (User Controlled Authorization Networks) implementation for any service. Built on top of the battle-tested [ucanto](https://github.com/storacha/ucanto) library and conforming to the [UCAN specification](https://github.com/ucan-wg/spec/).
+
+## What is UCAN?
+
+UCAN is a decentralized authorization system using cryptographically signed tokens. Think of it as "JWT meets capabilities" - users can grant specific permissions to others, who can further delegate (but never escalate) those permissions.
+
+**Key concepts:**
+- **Capabilities**: What actions can be performed on which resources
+- **Delegations**: Granting capabilities to others (can be chained)
+- **Invocations**: Requests to use a capability
+- **Attenuation**: Permissions can only be narrowed, never expanded
+
+📖 **[See the visual flow diagram →](./docs/FLOW.md)**
 
 ## Features
 
-- **did:ixo Resolution**: Resolve IXO DIDs to their public keys via the IXO blockchain indexer
-- **MCP Capability Definitions**: Pre-built capability schemas for MCP tool authorization
-- **Server & Client Helpers**: Easy setup for ucanto servers and clients with IXO defaults
-- **Replay Protection**: In-memory invocation store to prevent replay attacks
+- 🔐 **Built on ucanto** - Battle-tested UCAN library from Storacha
+- 🎯 **Generic Capabilities** - Define your own capabilities with custom schemas
+- ⚙️ **Caveat Validation** - Enforce limits and restrictions on delegations
+- 🌐 **Multi-DID Support** - `did:key` (native) + `did:ixo` (via blockchain indexer)
+- 🚀 **Framework-Agnostic** - Works with Express, Fastify, Hono, NestJS, etc.
+- 🛡️ **Replay Protection** - Built-in invocation store prevents replay attacks
 
 ## Installation
 
 ```bash
+npm install @ixo/ucan
+# or
 pnpm add @ixo/ucan
 ```
 
 ## Quick Start
 
-### Server-Side (Oracle)
+### 1. Define a Capability
 
 ```typescript
-import { createIxoServer, MCPCall } from '@ixo/ucan';
-import { provide } from '@ucanto/server';
-
-// Create a handler for MCP tool calls
-const mcpCallHandler = provide(MCPCall, async ({ capability, invocation }) => {
-  const { with: resourceUri } = capability;
+import { defineCapability, Schema } from '@ixo/ucan';
+
+const EmployeesRead = defineCapability({
+  can: 'employees/read',
+  protocol: 'myapp:',
+  nb: { limit: Schema.integer().optional() },
+  derives: (claimed, delegated) => {
+    const claimedLimit = claimed.nb?.limit ?? Infinity;
+    const delegatedLimit = delegated.nb?.limit ?? Infinity;
+
+    if (claimedLimit > delegatedLimit) {
+      return { error: new Error(`Limit ${claimedLimit} exceeds allowed ${delegatedLimit}`) };
+    }
+    return { ok: {} };
+  },
+});
+```
 
-  // Parse the resource URI to get server/tool info
-  // Format: ixo:oracle:{oracleDid}:mcp/{serverName}/{toolName}
+### 2. Create a Validator (Server)
 
-  // Execute the MCP tool...
-  return { ok: { result: 'success' } };
+```typescript
+import { createUCANValidator, createIxoDIDResolver } from '@ixo/ucan';
+
+const validator = await createUCANValidator({
+  serverDid: 'did:ixo:ixo1abc...',  // Your server's DID
+  rootIssuers: ['did:ixo:ixo1admin...'],  // DIDs that can issue root capabilities
+  didResolver: createIxoDIDResolver({
+    indexerUrl: 'https://blocksync.ixo.earth/graphql',
+  }),
 });
+```
 
-// Create the server
-const { server, did } = createIxoServer({
-  privateKey: process.env.ORACLE_PRIVATE_KEY!,
-  rootIssuers: [process.env.ADMIN_DID!],
-  indexerUrl: 'https://blocksync.ixo.earth/graphql',
-  service: {
-    mcp: { call: mcpCallHandler }
+### 3. Protect a Route
+
+```typescript
+app.post('/employees', async (req, res) => {
+  const result = await validator.validate(
+    req.body.invocation,  // Base64-encoded CAR
+    EmployeesRead,
+    'myapp:company/acme'
+  );
+
+  if (!result.ok) {
+    return res.status(403).json({ error: result.error });
   }
-});
 
-console.log('Server DID:', did);
+  const limit = result.capability?.nb?.limit ?? 10;
+  res.json({ employees: getEmployees(limit) });
+});
 ```
 
-### Client-Side
+### 4. Create & Use a Delegation (Client)
 
 ```typescript
-import { createIxoClient, createMCPResourceURI } from '@ixo/ucan';
+import { generateKeypair, createDelegation, createInvocation, serializeInvocation } from '@ixo/ucan';
+
+// Generate a keypair for the user
+const { signer, did } = await generateKeypair();
 
-// Create a client
-const client = createIxoClient({
-  privateKey: myPrivateKey,
-  serverDid: 'did:key:z6Mk...',
-  endpoint: 'https://oracle.ixo.earth/ucan'
+// Root creates a delegation for the user
+const delegation = await createDelegation({
+  issuer: rootSigner,
+  audience: did,
+  capabilities: [{ can: 'employees/read', with: 'myapp:company/acme', nb: { limit: 50 } }],
+  expiration: Math.floor(Date.now() / 1000) + 3600,  // 1 hour
 });
 
-// Invoke an MCP tool capability
-const result = await client.invoke({
-  can: 'mcp/call',
-  with: createMCPResourceURI('did:ixo:oracle123', 'postgres', 'query'),
-  nb: { args: { sql: 'SELECT * FROM users' } }
+// User creates an invocation
+const invocation = await createInvocation({
+  issuer: signer,
+  audience: serverDid,
+  capability: { can: 'employees/read', with: 'myapp:company/acme', nb: { limit: 25 } },
+  proofs: [delegation],
 });
 
-// Or delegate capability to another user
-const delegation = await client.delegate({
-  audience: 'did:ixo:alice',
-  capabilities: [{
-    can: 'mcp/call',
-    with: createMCPResourceURI('did:ixo:oracle123', 'postgres', '*')
-  }],
-  expiration: Math.floor(Date.now() / 1000) + 86400 // 24 hours
+// Serialize and send
+const serialized = await serializeInvocation(invocation);
+await fetch('/employees', {
+  method: 'POST',
+  body: JSON.stringify({ invocation: serialized }),
 });
 ```
 
-## Capability URI Format
+## Documentation
 
-MCP capabilities use the following URI format:
+| Document | Description |
+|----------|-------------|
+| **[Flow Diagram](./docs/FLOW.md)** | Visual explanation of UCAN delegation and invocation |
+| **[Server Example](./docs/examples/SERVER.md)** | Complete Express server with protected routes |
+| **[Client Example](./docs/examples/CLIENT.md)** | Frontend/client-side usage |
+| **[Capabilities Guide](./docs/examples/CAPABILITIES.md)** | How to define custom capabilities with caveats |
 
-```
-ixo:oracle:{oracleDid}:mcp/{serverName}/{toolName}
-```
+## API Reference
 
-Examples:
-- `ixo:oracle:did:ixo:abc123:mcp/postgres/query` - Specific tool
-- `ixo:oracle:did:ixo:abc123:mcp/postgres/*` - All tools in server (wildcard)
-- `ixo:oracle:did:ixo:abc123:mcp/*` - All MCP tools (wildcard)
+### Capability Definition
 
-## DID Resolution
+```typescript
+defineCapability(options: DefineCapabilityOptions)
+```
 
-The package supports multiple DID methods:
+Define a capability with optional caveat validation.
 
-- **did:key** - Handled natively by ucanto
-- **did:ixo** - Resolved via IXO blockchain indexer
+| Option | Type | Description |
+|--------|------|-------------|
+| `can` | `string` | Action name (e.g., `'employees/read'`) |
+| `protocol` | `string` | URI protocol (default: `'urn:'`) |
+| `nb` | `object` | Schema for caveats using `Schema.*` |
+| `derives` | `function` | Custom validation for attenuation |
 
-```typescript
-import { createIxoDIDResolver, createCompositeDIDResolver } from '@ixo/ucan';
+### Validator
 
-const ixoResolver = createIxoDIDResolver({
-  indexerUrl: 'https://blocksync.ixo.earth/graphql'
-});
-
-// Create a composite resolver for multiple DID methods
-const resolver = createCompositeDIDResolver([ixoResolver]);
+```typescript
+createUCANValidator(options: CreateValidatorOptions): Promise<UCANValidator>
 ```
 
-## Replay Protection
+Create a framework-agnostic validator.
 
-The package includes an in-memory invocation store for replay protection:
+| Option | Type | Description |
+|--------|------|-------------|
+| `serverDid` | `string` | Server's DID (any method supported) |
+| `rootIssuers` | `string[]` | DIDs that can self-issue capabilities |
+| `didResolver` | `DIDKeyResolver` | Resolver for non-`did:key` DIDs |
+| `invocationStore` | `InvocationStore` | Custom store for replay protection |
 
-```typescript
-import { InMemoryInvocationStore } from '@ixo/ucan';
+### Client Helpers
 
-const store = new InMemoryInvocationStore({
-  defaultTtlMs: 24 * 60 * 60 * 1000, // 24 hours
-  cleanupIntervalMs: 60 * 60 * 1000,  // 1 hour
-});
+| Function | Description |
+|----------|-------------|
+| `generateKeypair()` | Generate new Ed25519 keypair |
+| `parseSigner(privateKey, did?)` | Parse private key into signer |
+| `signerFromMnemonic(mnemonic, did?)` | Derive signer from BIP39 mnemonic |
+| `createDelegation(options)` | Create a delegation |
+| `createInvocation(options)` | Create an invocation |
+| `serializeDelegation(delegation)` | Serialize to base64 CAR |
+| `serializeInvocation(invocation)` | Serialize to base64 CAR |
+| `parseDelegation(serialized)` | Parse from base64 CAR |
 
-// Check if invocation was already used
-if (await store.has(invocationCid)) {
-  throw new Error('Replay attack detected');
-}
+### DID Resolution
 
-// Mark as used
-await store.add(invocationCid);
+```typescript
+createIxoDIDResolver(config: IxoDIDResolverConfig): DIDKeyResolver
+createCompositeDIDResolver(resolvers: DIDKeyResolver[]): DIDKeyResolver
 ```
 
-## Integration with Oracle
+### Replay Protection
 
-See the oracle app's `src/ucan/` directory for a complete integration example:
+```typescript
+new InMemoryInvocationStore(options?)
+createInvocationStore(options?)
+```
 
-- `ucan.config.ts` - Configuration for MCP UCAN requirements
-- `ucan.service.ts` - NestJS service for validation
-- `ucan.module.ts` - NestJS module
+## DID Support
 
-## Environment Variables
+| DID Method | Support | Notes |
+|------------|---------|-------|
+| `did:key` | ✅ Native | Parsed directly from the identifier |
+| `did:ixo` | ✅ Via resolver | Resolved via IXO blockchain indexer |
+| `did:web` | 🔧 Extendable | Implement custom resolver |
 
-For the IXO DID resolver:
+## Environment Variables
 
 ```env
+# For IXO DID resolution
 BLOCKSYNC_GRAPHQL_URL=https://blocksync.ixo.earth/graphql
 ```
 
-For UCAN configuration:
+## Advanced Usage
 
-```env
-ORACLE_ENTITY_DID=did:ixo:your-oracle-did
-UCAN_ROOT_ISSUERS=did:ixo:admin1,did:ixo:admin2
-UCAN_PROTECTED_MCP_SERVERS=postgres,redis
+### Re-exported ucanto Packages
+
+For advanced use cases, you can access the underlying ucanto packages:
+
+```typescript
+import { UcantoServer, UcantoClient, UcantoValidator, ed25519 } from '@ixo/ucan';
 ```
 
-## API Reference
+### Custom Invocation Store
 
-### Types
+Implement the `InvocationStore` interface for distributed deployments:
 
-- `IxoDID` - IXO DID type (`did:ixo:${string}`)
-- `KeyDID` - Key DID type (`did:key:${string}`)
-- `MCPResourceURI` - MCP resource URI type
-- `MCPUCANConfig` - Configuration for MCP UCAN requirements
-- `InvocationStore` - Interface for replay protection stores
-- `DIDKeyResolver` - DID resolver function type
+```typescript
+interface InvocationStore {
+  has(cid: string): Promise<boolean>;
+  add(cid: string, ttlMs?: number): Promise<void>;
+  cleanup?(): Promise<void>;
+}
+```
 
-### Functions
+## Contributing
 
-- `createIxoServer(options)` - Create a ucanto server with IXO defaults
-- `createIxoClient(options)` - Create a ucanto client with IXO defaults
-- `createIxoDIDResolver(config)` - Create a did:ixo resolver
-- `createCompositeDIDResolver(resolvers)` - Combine multiple DID resolvers
-- `createMCPResourceURI(oracleDid, serverName, toolName)` - Build MCP resource URI
-- `parseMCPResourceURI(uri)` - Parse MCP resource URI into components
-- `createInvocationStore(options)` - Create an invocation store
+See the [test script](./scripts/test-ucan.ts) for a complete example of the UCAN flow:
 
-### Capabilities
+```bash
+pnpm test:ucan
+```
 
-- `MCPCall` - Capability for calling MCP tools
+## License
 
-## TODO
+MIT
 
-- [ ] Add Redis implementation for distributed deployments
-- [ ] Add SQLite implementation for persistence
-- [ ] Add delegation management utilities
-- [ ] Add capability inspection utilities
-- [ ] Add support for capability revocation lists
-- [ ] Add support for time-based restrictions in caveats
+## Links
 
+- [ucanto (underlying library)](https://github.com/storacha/ucanto)
+- [UCAN Specification](https://github.com/ucan-wg/spec/)
+- [IXO Network](https://www.ixo.world/)

package/docs/FLOW.md

@@ -0,0 +1,275 @@
+# UCAN Flow: Delegation, Attenuation & Invocation
+
+This document explains how UCAN authorization works with visual diagrams.
+
+## The Players
+
+```
+  👑 ROOT                    👩 ALICE                    👤 BOB
+  ─────────────────          ──────────────────          ─────────────────
+  Resource Owner             Gets limit: 50              Gets limit: 25
+  Full authority             Can delegate further        Can only use, not expand
+```
+
+## The Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           UCAN DELEGATION CHAIN                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                    ┌─────────────────────────────┐
+                    │          ROOT               │
+                    │     (Resource Owner)        │
+                    │   can: employees/read       │
+                    │   with: myapp:company       │
+                    │   limit: ∞ (unlimited)      │
+                    └─────────────┬───────────────┘
+                                  │
+                                  │ DELEGATES (limit: 50)
+                                  ▼
+                    ┌─────────────────────────────┐
+                    │          ALICE              │
+                    │      (Team Lead)            │
+                    │   can: employees/read       │
+                    │   with: myapp:company       │
+                    │   limit: 50                 │
+                    └─────────────┬───────────────┘
+                                  │
+                                  │ RE-DELEGATES (limit: 25)
+                                  │ ← Attenuated! (narrower)
+                                  ▼
+                    ┌─────────────────────────────┐
+                    │           BOB               │
+                    │       (Employee)            │
+                    │   can: employees/read       │
+                    │   with: myapp:company       │
+                    │   limit: 25                 │
+                    └─────────────────────────────┘
+```
+
+## Delegation Structure
+
+When Root delegates to Alice:
+
+```
+┌────────────────────────────────────────────┐
+│  DELEGATION #1                             │
+│  ──────────────────────────────────────    │
+│  issuer:    did:key:root                   │
+│  audience:  did:key:alice                  │
+│  can:       "employees/read"               │
+│  with:      "myapp:company"                │
+│  nb:        { limit: 50 }                  │
+│  expires:   2025-12-31                     │
+│  proofs:    []  ← Root needs no proof      │
+│  ──────────────────────────────────────    │
+│  signature: <Root's signature>             │
+└────────────────────────────────────────────┘
+```
+
+When Alice re-delegates to Bob:
+
+```
+┌────────────────────────────────────────────┐
+│  DELEGATION #2                             │
+│  ──────────────────────────────────────    │
+│  issuer:    did:key:alice                  │
+│  audience:  did:key:bob                    │
+│  can:       "employees/read"               │
+│  with:      "myapp:company"                │
+│  nb:        { limit: 25 }  ← NARROWED!     │
+│  expires:   2025-06-30     ← SHORTER!      │
+│  proofs:    [DELEGATION #1] ← Chain        │
+│  ──────────────────────────────────────    │
+│  signature: <Alice's signature>            │
+└────────────────────────────────────────────┘
+```
+
+## Invocation & Validation
+
+When Bob wants to use his capability:
+
+```
+┌────────────────────────────────────────────┐
+│  INVOCATION (Bob's Request)                │
+│  ──────────────────────────────────────    │
+│  issuer:    did:key:bob                    │
+│  audience:  did:key:server                 │
+│  can:       "employees/read"               │
+│  with:      "myapp:company"                │
+│  nb:        { limit: 20 }  ← Request       │
+│  proofs:    [DELEGATION #2]                │
+│  ──────────────────────────────────────    │
+│  signature: <Bob's signature>              │
+└────────────────────────────────────────────┘
+          │
+          │ Sent to Server
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    SERVER VALIDATION                         │
+├─────────────────────────────────────────────────────────────┤
+│  1. ✅ Verify Bob's signature on invocation                 │
+│  2. ✅ Check invocation audience = server DID               │
+│  3. ✅ Extract DELEGATION #2 from proofs                    │
+│  4. ✅ Verify Alice's signature on DELEGATION #2            │
+│  5. ✅ Check DELEGATION #2.audience = Bob (invoker)         │
+│  6. ✅ Extract DELEGATION #1 from DELEGATION #2.proofs      │
+│  7. ✅ Verify Root's signature on DELEGATION #1             │
+│  8. ✅ Check DELEGATION #1.audience = Alice                 │
+│  9. ✅ Root is trusted root issuer                          │
+│ 10. ✅ Caveat check: 20 ≤ 25 (Bob's limit)                  │
+│ 11. ✅ Caveat check: 25 ≤ 50 (Alice's limit)                │
+│ 12. ✅ CID not in replay store                              │
+│ 13. ✅ Not expired                                          │
+├─────────────────────────────────────────────────────────────┤
+│                      ACCESS GRANTED ✅                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Attenuation Rules
+
+**Key Principle**: You can only delegate ≤ what you have.
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                         ATTENUATION RULES                          │
+├────────────────────────────────────────────────────────────────────┤
+│                                                                    │
+│  ✅ ALLOWED (Narrowing):                                           │
+│     • limit: 50 → limit: 25  (smaller)                             │
+│     • expires: Dec → expires: June  (shorter)                      │
+│     • with: "myapp:*" → with: "myapp:company"  (more specific)     │
+│                                                                    │
+│  ❌ FORBIDDEN (Escalation):                                        │
+│     • limit: 25 → limit: 50  (larger)                              │
+│     • expires: June → expires: Dec  (longer)                       │
+│     • with: "myapp:company" → with: "myapp:*"  (broader)           │
+│                                                                    │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## What Each Party Can Do
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Action                    │  Root  │  Alice  │  Bob            │
+├─────────────────────────────────────────────────────────────────┤
+│  Read 100 employees        │   ✅   │   ❌    │   ❌            │
+│  Read 50 employees         │   ✅   │   ✅    │   ❌            │
+│  Read 25 employees         │   ✅   │   ✅    │   ✅            │
+│  Delegate limit: 50        │   ✅   │   ✅    │   ❌            │
+│  Delegate limit: 25        │   ✅   │   ✅    │   ✅            │
+│  Delegate limit: 10        │   ✅   │   ✅    │   ✅            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Self-Contained Invocations
+
+Invocations bundle their entire proof chain:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                  INVOCATION PAYLOAD (self-contained)                    │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│   Bob's Invocation                                                      │
+│   └── proofs: [ DELEGATION #2 ]                                         │
+│                └── Alice's Delegation to Bob                            │
+│                    └── proofs: [ DELEGATION #1 ]                        │
+│                                 └── Root's Delegation to Alice          │
+│                                     └── proofs: []  (root!)             │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+- Server doesn't need external delegation store
+- Validation is entirely local
+- No network calls during validation (except DID resolution)
+
+## Replay Protection
+
+Each invocation has a unique CID. The server stores used CIDs:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    REPLAY PROTECTION                         │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  First request:                                              │
+│    Invocation CID: bafy...abc                                │
+│    → Not in store → PROCESS → Add to store ✅                │
+│                                                              │
+│  Replay attempt:                                             │
+│    Invocation CID: bafy...abc  (same!)                       │
+│    → Already in store → REJECT ❌                            │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Code Example
+
+```typescript
+import {
+  defineCapability,
+  createUCANValidator,
+  createDelegation,
+  createInvocation,
+  Schema
+} from '@ixo/ucan';
+
+// 1. Define capability with caveat
+const EmployeesRead = defineCapability({
+  can: 'employees/read',
+  protocol: 'myapp:',
+  nb: { limit: Schema.integer().optional() },
+  derives: (claimed, delegated) => {
+    const claimedLimit = claimed.nb?.limit ?? Infinity;
+    const delegatedLimit = delegated.nb?.limit ?? Infinity;
+    if (claimedLimit > delegatedLimit) {
+      return { error: new Error('Limit exceeds delegation') };
+    }
+    return { ok: {} };
+  },
+});
+
+// 2. Root delegates to Alice with limit: 50
+const rootToAlice = await createDelegation({
+  issuer: rootSigner,
+  audience: aliceDid,
+  capabilities: [{ can: 'employees/read', with: 'myapp:company', nb: { limit: 50 } }],
+});
+
+// 3. Alice re-delegates to Bob with limit: 25
+const aliceToBob = await createDelegation({
+  issuer: aliceSigner,
+  audience: bobDid,
+  capabilities: [{ can: 'employees/read', with: 'myapp:company', nb: { limit: 25 } }],
+  proofs: [rootToAlice],  // Include proof chain
+});
+
+// 4. Bob invokes with limit: 20
+const invocation = await createInvocation({
+  issuer: bobSigner,
+  audience: serverDid,
+  capability: { can: 'employees/read', with: 'myapp:company', nb: { limit: 20 } },
+  proofs: [aliceToBob],  // Includes entire chain
+});
+
+// 5. Server validates
+const result = await validator.validate(serialized, EmployeesRead, 'myapp:company');
+// result.ok === true, result.capability.nb.limit === 20
+```
+
+## Summary
+
+| Concept | Description |
+|---------|-------------|
+| **Delegation** | Granting capabilities to others (signed by issuer) |
+| **Attenuation** | Narrowing permissions when re-delegating |
+| **Invocation** | Request to use a capability (signed by invoker) |
+| **Proof Chain** | Delegations linked together, bundled in invocation |
+| **Caveat** | Restrictions on capabilities (e.g., `limit`) |
+| **Replay Protection** | CID-based tracking prevents reuse |
+