@ixo/ucan 1.0.0 → 1.1.0

package/docs/examples/SERVER.md

@@ -0,0 +1,419 @@
+# Server Example
+
+Complete Express.js server using `@ixo/ucan` for authorization.
+
+## Setup
+
+```bash
+npm install express @ixo/ucan
+```
+
+## Full Example
+
+```typescript
+import express, { Request, Response } from 'express';
+import {
+  createUCANValidator,
+  createIxoDIDResolver,
+  defineCapability,
+  Schema,
+  generateKeypair,
+  createDelegation,
+  serializeDelegation,
+  parseSigner,
+  SupportedDID,
+} from '@ixo/ucan';
+
+const app = express();
+app.use(express.json());
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+// Server identity (use did:key for simplicity, or did:ixo for production)
+const SERVER_DID = 'did:ixo:ixo1abc...'; // Your server's DID
+const ROOT_DID = 'did:ixo:ixo1admin...'; // Admin who can delegate
+const ROOT_PRIVATE_KEY = 'MgCY...'; // Admin's private key
+
+// =============================================================================
+// Define Capabilities
+// =============================================================================
+
+/**
+ * Capability with caveat validation (limit)
+ *
+ * The `derives` function enforces attenuation:
+ * - A delegation with limit: 100 can create sub-delegations with limit ≤ 100
+ * - An invocation can only request up to the delegated limit
+ */
+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(
+          `Cannot request limit=${claimedLimit}, delegation only allows limit=${delegatedLimit}`,
+        ),
+      };
+    }
+    return { ok: {} };
+  },
+});
+
+/**
+ * Simple capability without caveats
+ */
+const EmployeesWrite = defineCapability({
+  can: 'employees/write',
+  protocol: 'myapp:',
+});
+
+// =============================================================================
+// Initialize Validator
+// =============================================================================
+
+let validator: Awaited<ReturnType<typeof createUCANValidator>>;
+
+async function initializeServer() {
+  // Create DID resolver for did:ixo
+  const didResolver = createIxoDIDResolver({
+    indexerUrl: 'https://blocksync.ixo.earth/graphql',
+  });
+
+  // Create validator (async to resolve non-did:key DIDs at startup)
+  validator = await createUCANValidator({
+    serverDid: SERVER_DID,
+    rootIssuers: [ROOT_DID],
+    didResolver,
+  });
+
+  console.log('Server DID:', SERVER_DID);
+  console.log('Root Issuer:', ROOT_DID);
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+function buildResourceUri(serverDid: string): `myapp:${string}` {
+  return `myapp:${serverDid}`;
+}
+
+function buildEmployees(limit: number) {
+  return Array.from({ length: limit }, (_, i) => ({
+    id: i + 1,
+    name: `Employee ${i + 1}`,
+  }));
+}
+
+// =============================================================================
+// Routes
+// =============================================================================
+
+/**
+ * Health check
+ */
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok' });
+});
+
+/**
+ * Server info and available capabilities
+ */
+app.get('/info', (_req, res) => {
+  res.json({
+    serverDid: SERVER_DID,
+    rootIssuers: [ROOT_DID],
+    capabilities: {
+      'employees/read': {
+        description: 'Read employee data',
+        caveats: { limit: 'Maximum number of employees to return' },
+      },
+      'employees/write': {
+        description: 'Write employee data',
+        caveats: null,
+      },
+    },
+  });
+});
+
+/**
+ * Protected route - requires valid UCAN invocation
+ *
+ * Send: POST /protected
+ * Body: { "invocation": "<base64 CAR>" }
+ */
+app.post('/protected', async (req: Request, res: Response) => {
+  const invocationBase64 = req.body?.invocation;
+
+  if (!invocationBase64) {
+    res.status(400).json({
+      error: 'Missing invocation in request body',
+      hint: 'Send { "invocation": "<base64 CAR>" }',
+    });
+    return;
+  }
+
+  // Validate with capability (includes caveat validation!)
+  const result = await validator.validate(
+    invocationBase64,
+    EmployeesRead,
+    buildResourceUri(SERVER_DID),
+  );
+
+  if (!result.ok) {
+    res.status(403).json({
+      error: 'Unauthorized',
+      details: result.error,
+    });
+    return;
+  }
+
+  // Extract limit from validated capability
+  const limit = (result.capability?.nb?.limit as number) ?? 10;
+
+  res.json({
+    message: 'Access granted!',
+    invoker: result.invoker,
+    capability: result.capability,
+    employees: buildEmployees(limit),
+  });
+});
+
+/**
+ * Create delegation for a user
+ *
+ * Send: POST /delegate
+ * Body: {
+ *   "audience": "did:key:z6Mk...",
+ *   "capabilities": [{ "can": "employees/read", "nb": { "limit": 50 } }],
+ *   "expiration": 1735689600  // Optional, defaults to 24h
+ * }
+ */
+app.post('/delegate', async (req: Request, res: Response) => {
+  const { audience, capabilities, expiration } = req.body;
+
+  if (!audience) {
+    res.status(400).json({
+      error: 'Missing audience DID',
+      hint: 'Send { "audience": "did:key:..." }',
+    });
+    return;
+  }
+
+  if (!capabilities || !Array.isArray(capabilities)) {
+    res.status(400).json({
+      error: 'Missing or invalid capabilities',
+      hint: 'Send { "capabilities": [{ "can": "employees/read", "nb": { "limit": 50 } }] }',
+    });
+    return;
+  }
+
+  try {
+    const rootSigner = parseSigner(ROOT_PRIVATE_KEY, ROOT_DID as SupportedDID);
+
+    // Build full capabilities with resource URI
+    const fullCapabilities = capabilities.map((cap: any) => ({
+      can: cap.can,
+      with: buildResourceUri(SERVER_DID),
+      nb: cap.nb,
+    }));
+
+    // Default expiration: 24 hours
+    const exp = expiration ?? Math.floor(Date.now() / 1000) + 86400;
+
+    const delegation = await createDelegation({
+      issuer: rootSigner,
+      audience,
+      capabilities: fullCapabilities as any,
+      expiration: exp,
+    });
+
+    const serialized = await serializeDelegation(delegation);
+
+    res.json({
+      success: true,
+      delegation: serialized,
+      details: {
+        cid: delegation.cid.toString(),
+        issuer: delegation.issuer.did(),
+        audience: delegation.audience.did(),
+        expiration: exp,
+      },
+    });
+  } catch (error: any) {
+    res.status(500).json({
+      error: 'Failed to create delegation',
+      details: error.message,
+    });
+  }
+});
+
+// =============================================================================
+// Start Server
+// =============================================================================
+
+initializeServer().then(() => {
+  const PORT = process.env.PORT || 3000;
+  app.listen(PORT, () => {
+    console.log(`Server listening on http://localhost:${PORT}`);
+    console.log('\nEndpoints:');
+    console.log('  GET  /health     - Health check');
+    console.log('  GET  /info       - Server info');
+    console.log(
+      '  POST /protected  - Protected endpoint (requires invocation)',
+    );
+    console.log('  POST /delegate   - Create delegation for a user');
+  });
+});
+```
+
+## Testing with cURL
+
+### 1. Get server info
+
+```bash
+curl http://localhost:3000/info
+```
+
+### 2. Create a delegation
+
+```bash
+curl -X POST http://localhost:3000/delegate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "audience": "did:key:z6MkUserKey...",
+    "capabilities": [{ "can": "employees/read", "nb": { "limit": 50 } }]
+  }'
+```
+
+### 3. Use the delegation (invocation)
+
+The client needs to create and sign an invocation. See [CLIENT.md](./CLIENT.md) for how to do this.
+
+```bash
+curl -X POST http://localhost:3000/protected \
+  -H "Content-Type: application/json" \
+  -d '{ "invocation": "<base64 CAR from client>" }'
+```
+
+## Validation Results
+
+### Success Response
+
+```json
+{
+  "message": "Access granted!",
+  "invoker": "did:key:z6MkUserKey...",
+  "capability": {
+    "can": "employees/read",
+    "with": "myapp:did:ixo:ixo1abc...",
+    "nb": { "limit": 25 }
+  },
+  "employees": [...]
+}
+```
+
+### Error Responses
+
+**Missing invocation:**
+
+```json
+{
+  "error": "Missing invocation in request body",
+  "hint": "Send { \"invocation\": \"<base64 CAR>\" }"
+}
+```
+
+**Invalid signature:**
+
+```json
+{
+  "error": "Unauthorized",
+  "details": { "code": "INVALID_SIGNATURE", "message": "..." }
+}
+```
+
+**Caveat violation:**
+
+```json
+{
+  "error": "Unauthorized",
+  "details": {
+    "code": "CAVEAT_VIOLATION",
+    "message": "Cannot request limit=100, delegation only allows limit=50"
+  }
+}
+```
+
+**Replay attack:**
+
+```json
+{
+  "error": "Unauthorized",
+  "details": { "code": "REPLAY", "message": "Invocation has already been used" }
+}
+```
+
+## Using with Other Frameworks
+
+The validator is framework-agnostic. Here's how to use it with other frameworks:
+
+### Fastify
+
+```typescript
+fastify.post('/protected', async (request, reply) => {
+  const result = await validator.validate(
+    request.body.invocation,
+    EmployeesRead,
+    'myapp:server'
+  );
+
+  if (!result.ok) {
+    return reply.code(403).send({ error: result.error });
+  }
+
+  return { employees: [...] };
+});
+```
+
+### Hono
+
+```typescript
+app.post('/protected', async (c) => {
+  const { invocation } = await c.req.json();
+  const result = await validator.validate(invocation, EmployeesRead, 'myapp:server');
+
+  if (!result.ok) {
+    return c.json({ error: result.error }, 403);
+  }
+
+  return c.json({ employees: [...] });
+});
+```
+
+### NestJS
+
+```typescript
+@Controller('employees')
+export class EmployeesController {
+  constructor(private readonly ucanService: UCANService) {}
+
+  @Post()
+  async getEmployees(@Body('invocation') invocation: string) {
+    const result = await this.ucanService.validate(invocation, EmployeesRead);
+
+    if (!result.ok) {
+      throw new ForbiddenException(result.error);
+    }
+
+    return { employees: [...] };
+  }
+}
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixo/ucan",
   "description": "UCAN authorization for any service - built on ucanto",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -38,15 +38,13 @@
   "devDependencies": {
     "@cosmjs/crypto": "0.32.4",
     "@cosmjs/encoding": "0.32.4",
-    "@types/jest": "^29.5.14",
     "@types/node": "^22.10.5",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.2.5",
     "tsx": "^4.7.0",
     "typescript": "^5.5.4",
-    "@ixo/eslint-config": "0.0.0",
-    "@ixo/jest-config": "0.0.0",
-    "@ixo/typescript-config": "0.0.0"
+    "vitest": "^3.2.4",
+    "@ixo/eslint-config": "2.0.0",
+    "@ixo/typescript-config": "1.0.0",
+    "@ixo/vitest-config": "1.0.0"
   },
   "dependencies": {
     "@ucanto/client": "9.0.2",
@@ -72,7 +70,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "jest",
+    "test": "vitest run",
     "test:ucan": "tsx scripts/test-ucan.ts"
   }
 }

package/scripts/test-ucan.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 /**
  * UCAN Test Script
  *
@@ -23,11 +24,8 @@ import {
 // CONFIGURATION - Change this to test different scenarios
 // ============================================================================
 
-const ACTION:
-  | 'generate-keys'
-  | 'create-delegation'
-  | 'full-flow'
-  | 'validate' = 'full-flow';
+const ACTION: 'generate-keys' | 'create-delegation' | 'full-flow' | 'validate' =
+  'full-flow';
 
 // ============================================================================
 // CAPABILITY DEFINITION
@@ -66,7 +64,9 @@ function log(title: string, data?: unknown) {
   console.log(`│ ${title}`);
   console.log('─'.repeat(70));
   if (data !== undefined) {
-    console.log(typeof data === 'string' ? data : JSON.stringify(data, null, 2));
+    console.log(
+      typeof data === 'string' ? data : JSON.stringify(data, null, 2),
+    );
   }
 }
 
@@ -97,11 +97,17 @@ async function generateKeys() {
   const did = signer.did();
   const privateKey = ed25519.Signer.format(signer);
 
-  console.log(JSON.stringify({
-    did,
-    privateKey,
-    note: 'Save the privateKey securely! The DID is public.',
-  }, null, 2));
+  console.log(
+    JSON.stringify(
+      {
+        did,
+        privateKey,
+        note: 'Save the privateKey securely! The DID is public.',
+      },
+      null,
+      2,
+    ),
+  );
 
   return { signer, did, privateKey };
 }
@@ -233,7 +239,7 @@ async function fullFlow() {
   });
 
   success(`Delegation created: ${aliceToBob.cid.toString().slice(0, 20)}...`);
-  info('Bob can now read up to 25 employees (attenuated from Alice\'s 50)');
+  info("Bob can now read up to 25 employees (attenuated from Alice's 50)");
 
   // ─────────────────────────────────────────────────────────────────────────
   // STEP 4: Alice invokes with limit: 50 (should succeed)
@@ -261,10 +267,12 @@ async function fullFlow() {
   );
 
   if (aliceResult.ok) {
-    success('Alice\'s invocation PASSED');
+    success("Alice's invocation PASSED");
     console.log(`   Requested: ${aliceResult.capability?.nb?.limit} employees`);
   } else {
-    fail(`Alice's invocation failed unexpectedly: ${aliceResult.error?.message}`);
+    fail(
+      `Alice's invocation failed unexpectedly: ${aliceResult.error?.message}`,
+    );
   }
 
   // ─────────────────────────────────────────────────────────────────────────
@@ -293,11 +301,11 @@ async function fullFlow() {
   );
 
   if (!bobBadResult.ok) {
-    success('Bob\'s excessive request correctly REJECTED');
+    success("Bob's excessive request correctly REJECTED");
     console.log(`   Error: ${bobBadResult.error?.message}`);
     console.log(`   Code: ${bobBadResult.error?.code}`);
   } else {
-    fail('Bob\'s excessive request should have been rejected!');
+    fail("Bob's excessive request should have been rejected!");
   }
 
   // ─────────────────────────────────────────────────────────────────────────
@@ -326,11 +334,15 @@ async function fullFlow() {
   );
 
   if (bobGoodResult.ok) {
-    success('Bob\'s valid request PASSED');
-    console.log(`   Requested: ${bobGoodResult.capability?.nb?.limit} employees`);
+    success("Bob's valid request PASSED");
+    console.log(
+      `   Requested: ${bobGoodResult.capability?.nb?.limit} employees`,
+    );
     console.log(`   Invoker: ${bobGoodResult.invoker?.slice(0, 40)}...`);
   } else {
-    fail(`Bob's valid request failed unexpectedly: ${bobGoodResult.error?.message}`);
+    fail(
+      `Bob's valid request failed unexpectedly: ${bobGoodResult.error?.message}`,
+    );
   }
 
   // ─────────────────────────────────────────────────────────────────────────

package/src/capabilities/capability.ts

@@ -23,7 +23,9 @@ export { Schema };
  * Extracts the output type O from a Reader/Schema
  * A Reader<O, I> has a read method that returns { ok: O } | { error: ... }
  */
-type Infer<T> = T extends { read(input: unknown): { ok: infer O } | { error: unknown } }
+type Infer<T> = T extends {
+  read(input: unknown): { ok: infer O } | { error: unknown };
+}
   ? O
   : never;
 
@@ -66,8 +68,7 @@ type InferStruct<U extends Record<string, unknown>> = {
  */
 export interface DefineCapabilityOptions<
   // NBSchema is the schema SHAPE, e.g., { limit: Schema<number | undefined> }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  NBSchema extends Record<string, any> = Record<string, never>,
+  NBSchema extends Record<string, unknown> = Record<string, never>,
 > {
   /**
    * The action this capability authorizes
@@ -166,10 +167,10 @@ export interface DefineCapabilityOptions<
  * });
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function defineCapability<NBSchema extends Record<string, any> = Record<string, never>>(
-  options: DefineCapabilityOptions<NBSchema>,
-) {
+
+export function defineCapability<
+  NBSchema extends Record<string, unknown> = Record<string, never>,
+>(options: DefineCapabilityOptions<NBSchema>) {
   const protocol = (options.protocol ?? 'urn:') as `${string}:`;
   const supportWildcards = options.supportWildcards ?? true;