@ixo/ucan 1.0.0

package/src/did/utils.ts

@@ -0,0 +1,141 @@
+// =============================================================================
+// Base58 Encoding/Decoding (Bitcoin alphabet)
+// =============================================================================
+
+const BASE58_ALPHABET =
+  '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+// Create lookup table for faster decoding
+const BASE58_MAP: Record<string, number> = {};
+for (let i = 0; i < BASE58_ALPHABET.length; i++) {
+  BASE58_MAP[BASE58_ALPHABET[i]!] = i;
+}
+
+/**
+ * Decode a Base58-encoded string to bytes
+ *
+ * Algorithm: Treat input as base-58 number, convert to base-256
+ */
+export function base58Decode(str: string): Uint8Array {
+  if (str.length === 0) {
+    return new Uint8Array(0);
+  }
+
+  // Count leading '1's (which represent leading zero bytes)
+  let leadingZeros = 0;
+  for (const char of str) {
+    if (char === '1') {
+      leadingZeros++;
+    } else {
+      break;
+    }
+  }
+
+  // Allocate enough space for the result
+  // Base58 uses ~5.86 bits per character, so we need at most ceil(len * log(58) / log(256)) bytes
+  const size = Math.ceil((str.length * Math.log(58)) / Math.log(256));
+  const bytes = new Uint8Array(size);
+
+  // Process each character
+  for (const char of str) {
+    const value = BASE58_MAP[char];
+    if (value === undefined) {
+      throw new Error(`Invalid Base58 character: ${char}`);
+    }
+
+    // Multiply existing bytes by 58 and add the new value
+    let carry = value;
+    for (let i = size - 1; i >= 0; i--) {
+      const current = bytes[i]! * 58 + carry;
+      bytes[i] = current % 256;
+      carry = Math.floor(current / 256);
+    }
+  }
+
+  // Find where the actual data starts (skip leading zeros in result)
+  let start = 0;
+  while (start < bytes.length && bytes[start] === 0) {
+    start++;
+  }
+
+  // Combine leading zero bytes with the decoded data
+  const result = new Uint8Array(leadingZeros + (bytes.length - start));
+  // Leading zeros are already 0 in a new Uint8Array
+  result.set(bytes.subarray(start), leadingZeros);
+
+  return result;
+}
+
+/**
+ * Encode bytes to Base58 string
+ *
+ * Algorithm: Treat input as base-256 number, convert to base-58
+ */
+export function base58Encode(bytes: Uint8Array): string {
+  if (bytes.length === 0) {
+    return '';
+  }
+
+  // Count leading zeros
+  let leadingZeros = 0;
+  for (const byte of bytes) {
+    if (byte === 0) {
+      leadingZeros++;
+    } else {
+      break;
+    }
+  }
+
+  // Allocate enough space for the result
+  // We need at most ceil(len * log(256) / log(58)) digits
+  const size = Math.ceil((bytes.length * Math.log(256)) / Math.log(58));
+  const digits = new Uint8Array(size);
+
+  // Process each byte
+  for (const byte of bytes) {
+    let carry = byte;
+    for (let i = size - 1; i >= 0; i--) {
+      const current = digits[i]! * 256 + carry;
+      digits[i] = current % 58;
+      carry = Math.floor(current / 58);
+    }
+  }
+
+  // Find where the actual data starts
+  let start = 0;
+  while (start < digits.length && digits[start] === 0) {
+    start++;
+  }
+
+  // Build result string
+  let result = '1'.repeat(leadingZeros);
+  for (let i = start; i < digits.length; i++) {
+    result += BASE58_ALPHABET[digits[i]!];
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Hex Encoding/Decoding
+// =============================================================================
+
+/**
+ * Decode a hex string to bytes
+ */
+export function hexDecode(hex: string): Uint8Array {
+  // Remove optional 0x prefix
+  const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+
+  if (cleanHex.length % 2 !== 0) {
+    throw new Error('Invalid hex string: odd length');
+  }
+
+  const bytes = new Uint8Array(cleanHex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(cleanHex.slice(i * 2, i * 2 + 2), 16);
+  }
+
+  return bytes;
+}
+

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview @ixo/ucan - UCAN authorization for any service
+ *
+ * This package provides UCAN (User Controlled Authorization Networks) support
+ * built on top of the battle-tested ucanto library.
+ *
+ * Features:
+ * - Generic capability definitions (define your own)
+ * - Framework-agnostic validator (works with Express, Fastify, etc.)
+ * - Client helpers for creating delegations and invocations
+ * - did:ixo resolution via IXO blockchain indexer (optional)
+ * - In-memory invocation store for replay protection
+ *
+ * @example
+ * ```typescript
+ * // 1. Define your capabilities
+ * import { defineCapability, createUCANValidator, generateKeypair } from '@ixo/ucan';
+ *
+ * const EmployeesRead = defineCapability({
+ *   can: 'employees/read',
+ *   protocol: 'myapp:'
+ * });
+ *
+ * // 2. Create validator
+ * const validator = createUCANValidator({
+ *   serverDid: 'did:key:z6Mk...',
+ *   rootIssuers: ['did:key:z6MkAdmin...'],
+ * });
+ *
+ * // 3. Validate in your route (any framework)
+ * app.post('/protected', async (req, res) => {
+ *   const result = await validator.validate(req.body.invocation, {
+ *     can: 'employees/read',
+ *     with: 'myapp:employees'
+ *   });
+ *
+ *   if (!result.ok) {
+ *     return res.status(403).json({ error: result.error });
+ *   }
+ *
+ *   res.json({ employees: [...] });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Re-export ucanto packages for advanced usage
+// =============================================================================
+
+export * as UcantoServer from '@ucanto/server';
+export * as UcantoClient from '@ucanto/client';
+export * as UcantoValidator from '@ucanto/validator';
+export * as UcantoPrincipal from '@ucanto/principal';
+export { ed25519, Verifier } from '@ucanto/principal';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  IxoDID,
+  KeyDID,
+  SupportedDID,
+  DIDKeyResolutionResult,
+  DIDKeyResolver,
+  InvocationStore,
+  ValidationResult,
+  SerializedInvocation,
+} from './types.js';
+
+// =============================================================================
+// Capability Definition
+// =============================================================================
+
+export {
+  defineCapability,
+  Schema,
+  type DefineCapabilityOptions,
+} from './capabilities/capability.js';
+
+// =============================================================================
+// Validator
+// =============================================================================
+
+export {
+  createUCANValidator,
+  type CreateValidatorOptions,
+  type ValidateResult,
+  type UCANValidator,
+} from './validator/validator.js';
+
+// =============================================================================
+// Client Helpers (for creating delegations and invocations)
+// =============================================================================
+
+export {
+  generateKeypair,
+  parseSigner,
+  signerFromMnemonic,
+  createDelegation,
+  createInvocation,
+  serializeInvocation,
+  serializeDelegation,
+  parseDelegation,
+  type Signer,
+  type Delegation,
+  type Capability,
+} from './client/create-client.js';
+
+// =============================================================================
+// DID Resolution (optional, for did:ixo support)
+// =============================================================================
+
+export {
+  createIxoDIDResolver,
+  createCompositeDIDResolver,
+  type IxoDIDResolverConfig,
+} from './did/ixo-resolver.js';
+
+// =============================================================================
+// Store (for replay protection)
+// =============================================================================
+
+export {
+  InMemoryInvocationStore,
+  createInvocationStore,
+} from './store/memory.js';
+
+// =============================================================================
+// Version
+// =============================================================================
+
+export const VERSION = '1.0.0';

package/src/store/memory.ts

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview In-memory invocation store for replay protection
+ *
+ * This module provides a simple in-memory implementation of the InvocationStore
+ * interface for tracking used invocation CIDs to prevent replay attacks.
+ *
+ * For production use with multiple instances, consider using a distributed
+ * store like Redis.
+ */
+
+import type { InvocationStore } from '../types.js';
+
+/**
+ * Entry in the invocation store
+ */
+interface StoreEntry {
+  /** Timestamp when this entry expires */
+  expiresAt: number;
+}
+
+/**
+ * In-memory implementation of InvocationStore for replay protection
+ *
+ * Features:
+ * - Automatic TTL-based expiration
+ * - Periodic cleanup of expired entries
+ * - Thread-safe (single-threaded JS)
+ *
+ * Limitations:
+ * - Data is lost on process restart
+ * - Not suitable for distributed deployments
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryInvocationStore();
+ *
+ * // Check if invocation was already used
+ * if (await store.has(invocationCid)) {
+ *   throw new Error('Replay attack detected');
+ * }
+ *
+ * // Mark invocation as used
+ * await store.add(invocationCid);
+ * ```
+ */
+export class InMemoryInvocationStore implements InvocationStore {
+  private store = new Map<string, StoreEntry>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  /** Default TTL: 24 hours */
+  private readonly defaultTtlMs: number;
+
+  /** Cleanup interval: 1 hour */
+  private readonly cleanupIntervalMs: number;
+
+  /**
+   * Create a new in-memory invocation store
+   *
+   * @param options - Configuration options
+   * @param options.defaultTtlMs - Default TTL for entries (default: 24 hours)
+   * @param options.cleanupIntervalMs - Interval for cleanup (default: 1 hour)
+   * @param options.enableAutoCleanup - Whether to enable automatic cleanup (default: true)
+   */
+  constructor(
+    options: {
+      defaultTtlMs?: number;
+      cleanupIntervalMs?: number;
+      enableAutoCleanup?: boolean;
+    } = {},
+  ) {
+    this.defaultTtlMs = options.defaultTtlMs ?? 24 * 60 * 60 * 1000; // 24 hours
+    this.cleanupIntervalMs = options.cleanupIntervalMs ?? 60 * 60 * 1000; // 1 hour
+
+    if (options.enableAutoCleanup !== false) {
+      this.startAutoCleanup();
+    }
+  }
+
+  /**
+   * Check if an invocation CID has already been used
+   *
+   * @param cid - The CID of the invocation
+   * @returns True if the CID has been used and is not expired
+   */
+  async has(cid: string): Promise<boolean> {
+    const entry = this.store.get(cid);
+    if (!entry) {
+      return false;
+    }
+
+    // Check if expired
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(cid);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Mark an invocation CID as used
+   *
+   * @param cid - The CID of the invocation
+   * @param ttlMs - Time-to-live in milliseconds (default: 24 hours)
+   */
+  async add(cid: string, ttlMs?: number): Promise<void> {
+    const ttl = ttlMs ?? this.defaultTtlMs;
+    this.store.set(cid, {
+      expiresAt: Date.now() + ttl,
+    });
+  }
+
+  /**
+   * Remove all expired entries from the store
+   */
+  async cleanup(): Promise<void> {
+    const now = Date.now();
+    let cleaned = 0;
+
+    for (const [cid, entry] of this.store.entries()) {
+      if (now > entry.expiresAt) {
+        this.store.delete(cid);
+        cleaned++;
+      }
+    }
+
+    if (cleaned > 0) {
+      console.log(`[InMemoryInvocationStore] Cleaned up ${cleaned} expired entries`);
+    }
+  }
+
+  /**
+   * Get the current size of the store
+   */
+  get size(): number {
+    return this.store.size;
+  }
+
+  /**
+   * Clear all entries from the store
+   */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /**
+   * Start automatic cleanup interval
+   */
+  private startAutoCleanup(): void {
+    if (this.cleanupInterval) {
+      return;
+    }
+
+    this.cleanupInterval = setInterval(() => {
+      void this.cleanup();
+    }, this.cleanupIntervalMs);
+
+    // Don't prevent process from exiting
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  /**
+   * Stop automatic cleanup and release resources
+   */
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.store.clear();
+  }
+}
+
+/**
+ * Create an invocation store instance
+ * Factory function for easier testing and dependency injection
+ *
+ * @param options - Store configuration
+ * @returns An InvocationStore implementation
+ */
+export function createInvocationStore(options?: {
+  defaultTtlMs?: number;
+  cleanupIntervalMs?: number;
+  enableAutoCleanup?: boolean;
+}): InvocationStore {
+  return new InMemoryInvocationStore(options);
+}
+
+// TODO: Add Redis implementation for distributed deployments
+// TODO: Add SQLite implementation for persistence across restarts
+// TODO: Add metrics/monitoring for store size and cleanup operations
+

package/src/types.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Core type definitions for @ixo/ucan
+ *
+ * This module provides type definitions that extend ucanto's types
+ * for general use in any service that needs UCAN authorization.
+ */
+
+import type { DID, Capability as UcantoCapability } from '@ucanto/interface';
+
+// =============================================================================
+// DID Types
+// =============================================================================
+
+/**
+ * IXO DID type (for IXO blockchain identities)
+ */
+export type IxoDID = `did:ixo:${string}`;
+
+/**
+ * Key DID type (self-describing public key DIDs)
+ */
+export type KeyDID = `did:key:${string}`;
+
+/**
+ * DIDs supported by this package
+ */
+export type SupportedDID = IxoDID | KeyDID;
+
+// =============================================================================
+// DID Resolution
+// =============================================================================
+
+/**
+ * Result of DID key resolution
+ */
+export interface DIDKeyResolutionResult {
+  /** Array of did:key identifiers that can verify signatures for this DID */
+  keys: KeyDID[];
+}
+
+/**
+ * DID key resolver function type
+ * Takes a DID and returns the associated did:key identifiers
+ */
+export type DIDKeyResolver = (
+  did: DID,
+) => Promise<
+  { ok: KeyDID[] } | { error: { name: string; did: string; message: string } }
+>;
+
+// =============================================================================
+// Invocation Store (Replay Protection)
+// =============================================================================
+
+/**
+ * Invocation store for replay protection
+ *
+ * Implementations can use in-memory, Redis, database, etc.
+ */
+export interface InvocationStore {
+  /**
+   * Check if an invocation CID has already been used
+   * @param cid - The CID of the invocation
+   */
+  has(cid: string): Promise<boolean>;
+
+  /**
+   * Mark an invocation CID as used
+   * @param cid - The CID of the invocation
+   * @param ttlMs - Time-to-live in milliseconds (for cleanup)
+   */
+  add(cid: string, ttlMs?: number): Promise<void>;
+
+  /**
+   * Remove expired entries (optional cleanup method)
+   */
+  cleanup?(): Promise<void>;
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+/**
+ * Result of UCAN validation
+ */
+export interface ValidationResult {
+  /** Whether the validation succeeded */
+  valid: boolean;
+
+  /** Error message if validation failed */
+  error?: string;
+
+  /** The DID of the invoker (if valid) */
+  invokerDid?: string;
+
+  /** The validated capability (if valid) */
+  capability?: UcantoCapability;
+}
+
+// =============================================================================
+// Client Configuration
+// =============================================================================
+
+/**
+ * Serialized invocation that can be sent in HTTP requests
+ */
+export type SerializedInvocation = string;