@ixo/ucan 1.0.0

package/src/client/create-client.ts

@@ -0,0 +1,329 @@
+/**
+ * @fileoverview Client helpers for creating UCAN invocations and delegations
+ *
+ * These helpers are used by front-ends to create invocations that can be
+ * sent alongside regular API requests (e.g., in the mcpInvocations field).
+ *
+ * Supports any DID method for audience (did:key, did:ixo, did:web, etc.)
+ */
+
+import * as Client from '@ucanto/client';
+import { ed25519 } from '@ucanto/principal';
+import type { Signer, Delegation, Capability, Principal } from '@ucanto/interface';
+import type { SupportedDID } from '../types.js';
+
+/**
+ * Create a principal from any DID string
+ *
+ * For did:key - parses the key from the DID (full verification support)
+ * For other DIDs - creates a simple principal that just holds the DID
+ *
+ * This allows delegations and invocations to be addressed to any DID method.
+ */
+function createPrincipal(did: string): Principal {
+  // did:key can be fully parsed (contains the public key)
+  if (did.startsWith('did:key:')) {
+    return ed25519.Verifier.parse(did);
+  }
+
+  // For other DID methods (did:ixo, did:web, etc.), create a simple principal
+  // The audience doesn't need key material - they just need to be identified
+  return {
+    did: () => did as `did:${string}:${string}`,
+  };
+}
+
+/**
+ * Generate a new Ed25519 keypair
+ *
+ * @returns The generated signer with its DID and private key
+ *
+ * @example
+ * ```typescript
+ * const { signer, did, privateKey } = await generateKeypair();
+ * console.log('New DID:', did);
+ * // Store privateKey securely for future use
+ * ```
+ */
+export async function generateKeypair(): Promise<{
+  signer: Signer;
+  did: string;
+  privateKey: string;
+}> {
+  const signer = await ed25519.Signer.generate();
+  return {
+    signer,
+    did: signer.did(),
+    privateKey: ed25519.Signer.format(signer),
+  };
+}
+
+/**
+ * Parse a private key into a signer
+ *
+ * @param privateKey - The private key (multibase encoded)
+ * @param did - The DID to use for the signer (optional) will override the did:key if provided
+ * @returns The signer
+ */
+export function parseSigner(privateKey: string, did?: SupportedDID): Signer {
+  const signer =  ed25519.Signer.parse(privateKey);
+  if (did) {
+    return signer.withDID(did);
+  }
+  return signer;
+}
+
+/**
+ * Create a signer from a BIP39 mnemonic
+ *
+ * Uses the same derivation as IXO verification methods:
+ * SHA256(mnemonic) → first 32 bytes as Ed25519 seed
+ *
+ * This ensures the derived key matches the verification method on-chain.
+ *
+ * @param mnemonic - BIP39 mnemonic phrase (12-24 words)
+ * @param did - The DID to use for the signer (optional) will override the did:key if provided
+ * @returns The signer and formatted private key
+ *
+ * @example
+ * ```typescript
+ * const { signer, did, privateKey } = await signerFromMnemonic('word1 word2 ...');
+ * console.log('DID:', did);
+ * console.log('Private Key (for server config):', privateKey);
+ * ```
+ */
+export async function signerFromMnemonic(mnemonic: string, did?: SupportedDID): Promise<{
+  signer: Signer;
+  did: string;
+  privateKey: string;
+}> {
+  // Use @cosmjs/crypto - same as IXO frontend for verification methods
+  // This ensures the derived key matches what's registered on-chain
+  const { Ed25519, sha256 } = await import('@cosmjs/crypto');
+  const { toUtf8 } = await import('@cosmjs/encoding');
+
+  // Derive Ed25519 keypair using same method as IXO verification methods:
+  // SHA256(mnemonic UTF-8 bytes) → first 32 bytes as seed → Ed25519 keypair
+  const seed = sha256(toUtf8(mnemonic.trim())).slice(0, 32);
+  const keypair = await Ed25519.makeKeypair(seed);
+
+  // Note: cosmjs returns keypair.privkey as 64 bytes (seed + pubkey concatenated)
+  // but ucanto expects just the 32-byte seed, so we use `seed` directly
+
+  // Build ucanto's private key format (68 bytes total):
+  // M + base64( [0x80, 0x26] + seed(32) + [0xed, 0x01] + pubkey(32) )
+  // where:
+  //   [0x80, 0x26] = varint for 0x1300 (ed25519-priv multicodec)
+  //   [0xed, 0x01] = varint for 0xed (ed25519-pub multicodec, 237 decimal)
+  const ED25519_PRIV_MULTICODEC = new Uint8Array([0x80, 0x26]); // 2 bytes
+  const ED25519_PUB_MULTICODEC = new Uint8Array([0xed, 0x01]); // 2 bytes (varint of 237)
+
+  // Total: 2 + 32 + 2 + 32 = 68 bytes (matches ucanto expectation)
+  const keyMaterial = new Uint8Array(
+    ED25519_PRIV_MULTICODEC.length + // 2
+      seed.length + // 32
+      ED25519_PUB_MULTICODEC.length + // 2
+      keypair.pubkey.length, // 32
+  );
+  keyMaterial.set(ED25519_PRIV_MULTICODEC, 0);
+  keyMaterial.set(seed, ED25519_PRIV_MULTICODEC.length);
+  keyMaterial.set(ED25519_PUB_MULTICODEC, ED25519_PRIV_MULTICODEC.length + seed.length);
+  keyMaterial.set(
+    keypair.pubkey,
+    ED25519_PRIV_MULTICODEC.length + seed.length + ED25519_PUB_MULTICODEC.length,
+  );
+
+  // Encode as base64pad multibase (prefix 'M')
+  const base64 = Buffer.from(keyMaterial).toString('base64');
+  const multibasePrivateKey = 'M' + base64;
+
+  // Parse using ucanto's parser to get a proper Signer
+  let signer = ed25519.Signer.parse(multibasePrivateKey);
+  const finalSigner = did ? signer.withDID(did) : signer;
+
+  return {
+    signer: finalSigner,
+    did: finalSigner.did(),
+    privateKey: multibasePrivateKey,
+  };
+}
+
+/**
+ * Create a delegation (grant capabilities to someone)
+ *
+ * Supports any DID method for the audience (did:key, did:ixo, did:web, etc.)
+ *
+ * @param options - Delegation options
+ * @returns The delegation object
+ *
+ * @example
+ * ```typescript
+ * // Delegate to a did:key
+ * const delegation = await createDelegation({
+ *   issuer: mySigner,
+ *   audience: 'did:key:z6Mk...',
+ *   capabilities: [{ can: 'employees/read', with: 'myapp:server' }],
+ * });
+ *
+ * // Delegate to a did:ixo
+ * const delegation = await createDelegation({
+ *   issuer: mySigner,
+ *   audience: 'did:ixo:ixo1abc...',
+ *   capabilities: [{ can: 'employees/read', with: 'myapp:server' }],
+ * });
+ * ```
+ */
+export async function createDelegation(options: {
+  /** The issuer's signer (private key) */
+  issuer: Signer;
+  /** The audience's DID (who receives the capability) - any DID method supported */
+  audience: string;
+  /** The capabilities being delegated */
+  capabilities: Capability[];
+  /** Expiration timestamp (Unix seconds) */
+  expiration?: number;
+  /** Not before timestamp (Unix seconds) */
+  notBefore?: number;
+  /** Parent delegations (proof chain) */
+  proofs?: Delegation[];
+}): Promise<Delegation> {
+  // Create principal from any DID (did:key, did:ixo, did:web, etc.)
+  const audiencePrincipal = createPrincipal(options.audience);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return Client.delegate({
+    issuer: options.issuer,
+    audience: audiencePrincipal,
+    capabilities: options.capabilities as any,
+    expiration: options.expiration,
+    proofs: options.proofs,
+    notBefore: options.notBefore,
+  });
+}
+
+/**
+ * Create an invocation (request to use a capability)
+ *
+ * Supports any DID method for the audience (did:key, did:ixo, did:web, etc.)
+ *
+ * @param options - Invocation options
+ * @returns The invocation object
+ *
+ * @example
+ * ```typescript
+ * // Invoke on a did:key server
+ * const invocation = await createInvocation({
+ *   issuer: mySigner,
+ *   audience: 'did:key:z6Mk...',
+ *   capability: { can: 'employees/read', with: 'myapp:server' },
+ *   proofs: [myDelegation],
+ * });
+ *
+ * // Invoke on a did:ixo server
+ * const invocation = await createInvocation({
+ *   issuer: mySigner,
+ *   audience: 'did:ixo:ixo1oracle...',
+ *   capability: { can: 'mcp/call', with: 'ixo:oracle:...' },
+ *   proofs: [myDelegation],
+ * });
+ * ```
+ */
+export async function createInvocation(options: {
+  /** The invoker's signer (private key) */
+  issuer: Signer;
+  /** The service's DID (audience) - any DID method supported */
+  audience: string;
+  /** The capability being invoked */
+  capability: Capability;
+  /** Delegation proofs */
+  proofs?: Delegation[];
+}) {
+  // Create principal from any DID (did:key, did:ixo, did:web, etc.)
+  const audiencePrincipal = createPrincipal(options.audience);
+
+  return Client.invoke({
+    issuer: options.issuer,
+    audience: audiencePrincipal,
+    capability: options.capability,
+    proofs: options.proofs ?? [],
+  });
+}
+
+/**
+ * Serialize an invocation to CAR format base64 (for sending in request body)
+ *
+ * @param invocation - The invocation to serialize
+ * @returns Base64-encoded CAR data
+ */
+export async function serializeInvocation(
+  invocation: Awaited<ReturnType<typeof createInvocation>>,
+): Promise<string> {
+  // Build the invocation into an IPLD view
+  const built = await invocation.buildIPLDView();
+
+  // Archive the invocation
+  const archive = await built.archive();
+  // Check for error
+  if (archive.error) {
+    throw new Error(
+      `Failed to archive invocation: ${archive.error?.message ?? 'unknown'}`,
+    );
+  }
+  // Get the bytes
+  if (!archive.ok) {
+    throw new Error('Failed to archive invocation: no data returned');
+  }
+
+  // Convert to base64
+  return Buffer.from(archive.ok).toString('base64');
+}
+
+/**
+ * Serialize a delegation to CAR format base64 (for storage/transport)
+ *
+ * @param delegation - The delegation to serialize
+ * @returns Base64-encoded CAR data
+ */
+export async function serializeDelegation(delegation: Delegation): Promise<string> {
+  // Archive the delegation (returns Result type)
+  const archive = await delegation.archive();
+
+  // Check for error (archive returns { ok: bytes } or { error: Error })
+  if (archive.error) {
+    throw new Error(`Failed to archive delegation: ${archive.error.message}`);
+  }
+  // Get the bytes
+  if (!archive.ok) {
+    throw new Error('Failed to archive delegation: no data returned');
+  }
+
+  // Convert to base64
+  return Buffer.from(archive.ok).toString('base64');
+}
+
+/**
+ * Parse a serialized delegation from CAR format
+ *
+ * @param serialized - Base64-encoded CAR data
+ * @returns The parsed delegation
+ */
+export async function parseDelegation(serialized: string): Promise<Delegation> {
+  const { extract } = await import('@ucanto/core/delegation');
+  const bytes = new Uint8Array(Buffer.from(serialized, 'base64'));
+
+  const result = await extract(bytes);
+  if (result.error) {
+    throw new Error(
+      `Failed to parse delegation: ${result.error?.message ?? 'unknown error'}`,
+    );
+  }
+
+  if (!result.ok) {
+    throw new Error('Failed to parse delegation: no data returned');
+  }
+
+  return result.ok as Delegation;
+}
+
+// Re-export useful types
+export type { Signer, Delegation, Capability };

package/src/did/ixo-resolver.ts

@@ -0,0 +1,325 @@
+/**
+ * @fileoverview did:ixo resolver for UCAN validation
+ *
+ * This module provides a DID resolver that can resolve did:ixo identifiers
+ * to their associated did:key identifiers by querying the IXO blockchain
+ * indexer for the DID document.
+ */
+
+import type { DID } from '@ucanto/interface';
+import type { DIDKeyResolver, KeyDID } from '../types.js';
+import { base58Encode, hexDecode, base58Decode } from './utils.js';
+
+/**
+ * Configuration for the IXO DID resolver
+ */
+export interface IxoDIDResolverConfig {
+  /**
+   * URL of the IXO GraphQL indexer
+   * @example 'https://blocksync.ixo.earth/graphql'
+   */
+  indexerUrl: string;
+
+  /**
+   * Optional fetch implementation (for testing or custom environments)
+   */
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * GraphQL query to fetch DID document from IXO indexer
+ */
+const DID_DOCUMENT_QUERY = `
+  query GetDIDDocument($id: String!) {
+    iids(filter: { id: { equalTo: $id } }) {
+      nodes {
+        id
+        verificationMethod
+      }
+    }
+  }
+`;
+
+/**
+ * Verification method from IXO DID document
+ */
+interface VerificationMethod {
+  id: string;
+  type: string;
+  controller: string;
+  publicKeyMultibase?: string;
+  publicKeyHex?: string;
+  publicKeyBase58?: string;
+}
+
+/**
+ * IXO DID document structure (partial)
+ */
+interface IxoDIDDocument {
+  id: string;
+  verificationMethod: VerificationMethod[];
+}
+
+
+
+// =============================================================================
+// did:key Conversion
+// =============================================================================
+
+/**
+ * Ed25519 multicodec prefix (0xed)
+ * When creating a did:key, we prepend this to the raw public key
+ */
+const ED25519_MULTICODEC_PREFIX = new Uint8Array([0xed, 0x01]);
+
+/**
+ * Convert raw Ed25519 public key bytes to did:key format
+ *
+ * did:key format for Ed25519:
+ * - Prefix with multicodec 0xed01
+ * - Encode with base58btc (multibase 'z' prefix)
+ * - Result: did:key:z6Mk...
+ */
+function rawPublicKeyToDidKey(publicKeyBytes: Uint8Array): KeyDID | null {
+  // Ed25519 public keys should be 32 bytes
+  if (publicKeyBytes.length !== 32) {
+    console.warn(
+      `[IxoDIDResolver] Expected 32-byte Ed25519 key, got ${publicKeyBytes.length} bytes`,
+    );
+    return null;
+  }
+
+  // Prepend the Ed25519 multicodec prefix
+  const prefixedKey = new Uint8Array(
+    ED25519_MULTICODEC_PREFIX.length + publicKeyBytes.length,
+  );
+  prefixedKey.set(ED25519_MULTICODEC_PREFIX, 0);
+  prefixedKey.set(publicKeyBytes, ED25519_MULTICODEC_PREFIX.length);
+
+  // Encode with base58btc and add 'z' multibase prefix
+  const multibaseEncoded = 'z' + base58Encode(prefixedKey);
+
+  return `did:key:${multibaseEncoded}` as KeyDID;
+}
+
+/**
+ * Convert a public key to did:key format
+ * Supports Ed25519 keys in multibase, hex, or base58 format
+ */
+function publicKeyToDidKey(vm: VerificationMethod): KeyDID | null {
+  // console.log('vm', vm);
+  // Handle multibase format (preferred)
+  if (vm.publicKeyMultibase) {
+    // Multibase Ed25519 public keys start with 'z' (base58btc)
+    // The did:key format for Ed25519 is did:key:z6Mk...
+    if (vm.publicKeyMultibase.startsWith('z')) {
+      // Already in the correct format for did:key
+      return `did:key:${vm.publicKeyMultibase}` as KeyDID;
+    }
+
+    // Handle other multibase prefixes if needed
+    console.warn(
+      `[IxoDIDResolver] Unsupported multibase prefix for ${vm.id}: ${vm.publicKeyMultibase.charAt(0)}`,
+    );
+    return null;
+  }
+
+  // Handle hex format
+  if (vm.publicKeyHex) {
+    try {
+      const publicKeyBytes = hexDecode(vm.publicKeyHex);
+      const didKey = rawPublicKeyToDidKey(publicKeyBytes);
+      return didKey;
+    } catch (error) {
+      console.warn(
+        `[IxoDIDResolver] Failed to decode publicKeyHex for ${vm.id}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
+  // Handle base58 format
+  if (vm.publicKeyBase58) {
+    try {
+      const publicKeyBytes = base58Decode(vm.publicKeyBase58);
+      const didKey = rawPublicKeyToDidKey(publicKeyBytes);
+      return didKey;
+    } catch (error) {
+      console.warn(
+        `[IxoDIDResolver] Failed to decode publicKeyBase58 for ${vm.id}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Creates a DID resolver for did:ixo identifiers
+ *
+ * This resolver queries the IXO blockchain indexer to fetch DID documents
+ * and extracts the verification methods that can be used to verify signatures.
+ *
+ * @param config - Configuration for the resolver
+ * @returns A DIDKeyResolver function compatible with ucanto
+ *
+ * @example
+ * ```typescript
+ * const resolver = createIxoDIDResolver({
+ *   indexerUrl: 'https://blocksync.ixo.earth/graphql'
+ * });
+ *
+ * const result = await resolver('did:ixo:abc123');
+ * if (result.ok) {
+ *   console.log('Keys:', result.ok); // ['did:key:z6Mk...']
+ * }
+ * ```
+ */
+export function createIxoDIDResolver(
+  config: IxoDIDResolverConfig,
+): DIDKeyResolver {
+  const fetchFn = config.fetch ?? globalThis.fetch;
+
+  return async (
+    did: DID,
+  ): Promise<
+    { ok: KeyDID[] } | { error: { name: string; did: string; message: string } }
+    > => {
+    // Only handle did:ixo
+    if (!did.startsWith('did:ixo:')) {
+      return {
+        error: {
+          name: 'DIDKeyResolutionError',
+          did,
+          message: `Cannot resolve ${did}: not a did:ixo identifier`,
+        },
+      };
+    }
+
+    try {
+      // Query the IXO indexer
+      const response = await fetchFn(config.indexerUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          query: DID_DOCUMENT_QUERY,
+          variables: { id: did },
+        }),
+      });
+
+      if (!response.ok) {
+        return {
+          error: {
+            name: 'DIDKeyResolutionError',
+            did,
+            message: `Failed to fetch DID document: HTTP ${response.status}`,
+          },
+        };
+      }
+
+      const data = (await response.json()) as {
+        data?: { iids?: { nodes?: IxoDIDDocument[] } };
+        errors?: Array<{ message: string }>;
+      };
+
+      if (data.errors && data.errors.length > 0) {
+        return {
+          error: {
+            name: 'DIDKeyResolutionError',
+            did,
+            message: `GraphQL error: ${data.errors[0]?.message ?? 'Unknown error'}`,
+          },
+        };
+      }
+
+      const didDoc = data.data?.iids?.nodes?.[0];
+      if (!didDoc) {
+        return {
+          error: {
+            name: 'DIDKeyResolutionError',
+            did,
+            message: `DID document not found for ${did}`,
+          },
+        };
+      }
+
+      // Extract verification methods and convert to did:key
+      const keys: KeyDID[] = [];
+
+      for (const vm of didDoc.verificationMethod || []) {
+        // Look for Ed25519 verification methods
+        // Common types: Ed25519VerificationKey2018, Ed25519VerificationKey2020, JsonWebKey2020
+        if (
+          vm.type.includes('Ed25519') ||
+          vm.type === 'JsonWebKey2020' ||
+          vm.id.includes('signing')
+        ) {
+          const keyDid = publicKeyToDidKey(vm);
+          if (keyDid) {
+            keys.push(keyDid);
+          }
+        }
+      }
+
+      if (keys.length === 0) {
+        return {
+          error: {
+            name: 'DIDKeyResolutionError',
+            did,
+            message: `No valid Ed25519 verification methods found in DID document for ${did}`,
+          },
+        };
+      }
+
+      return { ok: keys };
+    } catch (error) {
+      return {
+        error: {
+          name: 'DIDKeyResolutionError',
+          did,
+          message: `Failed to resolve ${did}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        },
+      };
+    }
+  };
+}
+
+/**
+ * Creates a composite DID resolver that tries multiple resolvers in order
+ *
+ * @param resolvers - Array of DID resolvers to try
+ * @returns A DIDKeyResolver that tries each resolver until one succeeds
+ */
+export function createCompositeDIDResolver(
+  resolvers: DIDKeyResolver[],
+): DIDKeyResolver {
+  return async (did: DID) => {
+    for (const resolver of resolvers) {
+      const result = await resolver(did);
+      if ('ok' in result) {
+        return result;
+      }
+      // If this resolver doesn't handle this DID method, try the next one
+      if (result.error.message.includes('not a did:')) {
+        continue;
+      }
+      // If it's a different error, return it
+      return result;
+    }
+
+    return {
+      error: {
+        name: 'DIDKeyResolutionError',
+        did,
+        message: `No resolver could handle ${did}`,
+      },
+    };
+  };
+}
+
+// TODO: Add caching layer for resolved DIDs
+// TODO: Add support for resolving from local DID document store
+