@kya-os/mcp-i-core 1.3.10-canary.clientinfo.20251126124133 → 1.3.11

package/src/services/tool-protection.service.ts

@@ -46,7 +46,7 @@
  * If tool not discovered:
  * - Tool won't appear in dashboard
  * - Protection settings can't be configured
- * - GET /tool-protections returns empty object
+ * - GET /config returns empty toolProtection.tools object
  *
  * DEBUGGING:
  * ----------
@@ -87,34 +87,56 @@ import type {
 import type { ToolProtectionCache } from "../cache/tool-protection-cache.js";
 import { InMemoryToolProtectionCache } from "../cache/tool-protection-cache.js";
 
+/**
+ * Tool protection data structure in API responses
+ */
+interface ToolProtectionData {
+  requiresDelegation?: boolean;
+  requires_delegation?: boolean;
+  requiredScopes?: string[];
+  required_scopes?: string[];
+  scopes?: string[];
+  riskLevel?: string;
+  risk_level?: string;
+  oauthProvider?: string;
+  oauth_provider?: string;
+  authorization?: {
+    type: string;
+    provider?: string;
+    issuer?: string;
+    credentialType?: string;
+  };
+}
+
 /**
  * Response from AgentShield API bouncer endpoints
  *
  * Supports multiple endpoint formats:
- * 1. New endpoint (/projects/{projectId}/tool-protections): { data: { toolProtections: { [toolName]: {...} } } } }
- * 2. Old endpoint (/config?agent_did=...): { data: { tools: [{ name: string, ... }] } }
- * 3. Legacy format: { data: { tools: { [toolName]: {...} } } }
+ * 1. Merged config (/projects/{projectId}/config): { data: { config: { toolProtection: { tools: {...} } } } }
+ * 2. Legacy tool-protections endpoint: { data: { toolProtections: { [toolName]: {...} } } }
+ * 3. Old config endpoint (/config?agent_did=...): { data: { tools: [{ name: string, ... }] } }
+ * 4. Legacy format: { data: { tools: { [toolName]: {...} } } }
  */
 interface BouncerConfigApiResponse {
   success: boolean;
   data: {
     agent_did?: string;
-    // New endpoint format: toolProtections object
-    toolProtections?: Record<
-      string,
-      {
-        requiresDelegation?: boolean;
-        requires_delegation?: boolean;
-        requiredScopes?: string[];
-        required_scopes?: string[];
-        scopes?: string[];
-        riskLevel?: string;
-        risk_level?: string;
-        oauthProvider?: string; // Phase 2: Tool-specific OAuth provider
-        oauth_provider?: string; // Phase 2: snake_case variant
-      }
-    >;
-    // Old endpoint format: tools array or object
+    
+    // NEW: Merged config format (v1.6.0+) - preferred format
+    // The entire config is returned with tools embedded at config.toolProtection.tools
+    config?: {
+      toolProtection?: {
+        source?: string;
+        tools?: Record<string, ToolProtectionData>;
+      };
+      // Other config fields we don't need to parse
+      [key: string]: unknown;
+    };
+    
+    // DEPRECATED: Top-level toolProtections (backward compatibility during transition)
+    toolProtections?: Record<string, ToolProtectionData>;
+    
+    // Legacy endpoint formats
     tools?:
       | Array<{
           name: string;
@@ -122,20 +144,10 @@ interface BouncerConfigApiResponse {
           requires_delegation?: boolean;
           scopes?: string[];
           required_scopes?: string[];
-          oauthProvider?: string; // Phase 2: Tool-specific OAuth provider
-          oauth_provider?: string; // Phase 2: snake_case variant
+          oauthProvider?: string;
+          oauth_provider?: string;
         }>
-      | Record<
-          string,
-          {
-            requiresDelegation?: boolean;
-            requires_delegation?: boolean;
-            scopes?: string[];
-            required_scopes?: string[];
-            oauthProvider?: string; // Phase 2: Tool-specific OAuth provider
-            oauth_provider?: string; // Phase 2: snake_case variant
-          }
-        >;
+      | Record<string, ToolProtectionData>;
     reputation_threshold?: number;
     denied_agents?: string[];
   };
@@ -254,7 +266,10 @@ export class ToolProtectionService {
           projectId: this.config.projectId || "none",
           toolCount: Object.keys(cached.toolProtections).length,
           protectedTools: Object.entries(cached.toolProtections)
-            .filter(([_, config]: [string, ToolProtection]) => config.requiresDelegation)
+            .filter(
+              ([_, config]: [string, ToolProtection]) =>
+                config.requiresDelegation
+            )
             .map(([name]) => name),
           cacheTtlMs: ttl,
           cachedUntil,
@@ -271,7 +286,7 @@ export class ToolProtectionService {
         projectId: this.config.projectId || "none",
         apiUrl: this.config.apiUrl,
         endpoint: this.config.projectId
-          ? `/api/v1/bouncer/projects/${this.config.projectId}/tool-protections`
+          ? `/api/v1/bouncer/projects/${this.config.projectId}/config`
           : `/api/v1/bouncer/config?agent_did=${agentDid}`,
       });
     }
@@ -287,6 +302,8 @@ export class ToolProtectionService {
           projectId: this.config.projectId || "none",
           responseKeys: Object.keys(response),
           dataKeys: response.data ? Object.keys(response.data) : [],
+          rawConfig: response.data?.config || null,
+          rawConfigToolProtection: response.data?.config?.toolProtection || null,
           rawToolProtections: response.data?.toolProtections || null,
           rawTools: response.data?.tools || null,
           responseMetadata: response.metadata || null,
@@ -294,15 +311,54 @@ export class ToolProtectionService {
       }
 
       // Transform API response format to internal format
-      // Supports multiple response formats:
-      // 1. New endpoint: { data: { toolProtections: { greet: { requiresDelegation: true, ... } } } }
-      // 2. Old endpoint (array): { data: { tools: [{ name: "greet", requiresDelegation: true, ... }] } }
-      // 3. Old endpoint (object): { data: { tools: { greet: { requiresDelegation: true, ... } } } }
+      // Supports multiple response formats (in priority order):
+      // 1. Merged config endpoint: { data: { config: { toolProtection: { tools: {...} } } } }
+      // 2. Legacy toolProtections: { data: { toolProtections: { greet: { requiresDelegation: true, ... } } } }
+      // 3. Old endpoint (array): { data: { tools: [{ name: "greet", requiresDelegation: true, ... }] } }
+      // 4. Old endpoint (object): { data: { tools: { greet: { requiresDelegation: true, ... } } } }
       const toolProtections: Record<string, ToolProtection> = {};
 
-      // Check for new endpoint format first (toolProtections)
-      if (response.data.toolProtections) {
-        // New endpoint format: object with tool names as keys
+      // Check for merged config format first (data.config.toolProtection.tools)
+      if (response.data.config?.toolProtection?.tools) {
+        // Merged config endpoint format: object with tool names as keys
+        if (this.config.debug) {
+          console.log("[ToolProtectionService] Using merged config format (data.config.toolProtection.tools)");
+        }
+        for (const [toolName, toolConfig] of Object.entries(
+          response.data.config.toolProtection.tools
+        )) {
+          const requiresDelegation =
+            (toolConfig as any).requiresDelegation ??
+            (toolConfig as any).requires_delegation ??
+            false;
+          const requiredScopes =
+            (toolConfig as any).requiredScopes ??
+            (toolConfig as any).required_scopes ??
+            (toolConfig as any).scopes ??
+            [];
+          
+          const oauthProvider =
+            (toolConfig as any).oauthProvider ??
+            (toolConfig as any).oauth_provider ??
+            undefined;
+          
+          const riskLevel =
+            (toolConfig as any).riskLevel ??
+            (toolConfig as any).risk_level ??
+            undefined;
+
+          toolProtections[toolName] = {
+            requiresDelegation,
+            requiredScopes,
+            ...(oauthProvider && { oauthProvider }),
+            ...(riskLevel && { riskLevel }),
+          };
+        }
+      } else if (response.data.toolProtections) {
+        // Legacy toolProtections format: object with tool names as keys
+        if (this.config.debug) {
+          console.log("[ToolProtectionService] Using legacy toolProtections format (data.toolProtections)");
+        }
         // Prefer camelCase over snake_case when both present
         for (const [toolName, toolConfig] of Object.entries(
           response.data.toolProtections
@@ -316,13 +372,13 @@ export class ToolProtectionService {
             (toolConfig as any).required_scopes ??
             (toolConfig as any).scopes ??
             [];
-          
+
           // NEW: Parse oauthProvider (camelCase and snake_case support)
           const oauthProvider =
             (toolConfig as any).oauthProvider ??
             (toolConfig as any).oauth_provider ??
             undefined;
-          
+
           const riskLevel =
             (toolConfig as any).riskLevel ??
             (toolConfig as any).risk_level ??
@@ -361,17 +417,15 @@ export class ToolProtectionService {
               (tool as any).required_scopes ??
               (tool as any).scopes ??
               [];
-            
+
             // NEW: Parse oauthProvider
             const oauthProvider =
               (tool as any).oauthProvider ??
               (tool as any).oauth_provider ??
               undefined;
-            
+
             const riskLevel =
-              (tool as any).riskLevel ??
-              (tool as any).risk_level ??
-              undefined;
+              (tool as any).riskLevel ?? (tool as any).risk_level ?? undefined;
 
             toolProtections[toolName] = {
               requiresDelegation,
@@ -395,13 +449,13 @@ export class ToolProtectionService {
               (toolConfig as any).required_scopes ??
               (toolConfig as any).scopes ??
               [];
-            
+
             // NEW: Parse oauthProvider
             const oauthProvider =
               (toolConfig as any).oauthProvider ??
               (toolConfig as any).oauth_provider ??
               undefined;
-            
+
             const riskLevel =
               (toolConfig as any).riskLevel ??
               (toolConfig as any).risk_level ??
@@ -427,7 +481,11 @@ export class ToolProtectionService {
         )) {
           // Skip if localConfig is empty or not a valid ToolProtection object
           // This prevents empty objects from corrupting the merged config
-          if (!localConfig || typeof localConfig !== 'object' || Object.keys(localConfig).length === 0) {
+          if (
+            !localConfig ||
+            typeof localConfig !== "object" ||
+            Object.keys(localConfig).length === 0
+          ) {
             if (this.config.debug) {
               console.log(
                 "[ToolProtectionService] Skipping empty/invalid fallback config entry",
@@ -436,13 +494,14 @@ export class ToolProtectionService {
             }
             continue;
           }
-          
+
           // Ensure requiredScopes exists (default to empty array if missing)
           const validConfig: ToolProtection = {
-            requiresDelegation: (localConfig as any).requiresDelegation ?? false,
+            requiresDelegation:
+              (localConfig as any).requiresDelegation ?? false,
             requiredScopes: (localConfig as any).requiredScopes ?? [],
           };
-          
+
           // Local config overrides API config for this tool
           mergedToolProtections[toolName] = validConfig;
           if (this.config.debug) {
@@ -471,8 +530,10 @@ export class ToolProtectionService {
       console.log("[ToolProtectionService] Config loaded from API", {
         source: "api",
         toolCount: Object.keys(mergedToolProtections).length,
-          protectedTools: Object.entries(mergedToolProtections)
-          .filter(([_, config]: [string, ToolProtection]) => config.requiresDelegation)
+        protectedTools: Object.entries(mergedToolProtections)
+          .filter(
+            ([_, config]: [string, ToolProtection]) => config.requiresDelegation
+          )
           .map(([name]) => name),
         agentDid: agentDid.slice(0, 20) + "...",
         projectId: this.config.projectId || "none",
@@ -665,7 +726,10 @@ export class ToolProtectionService {
 
   /**
    * Fetch tool protection config from AgentShield API
-   * Uses projectId endpoint if available (preferred, project-scoped), otherwise falls back to agent_did query param
+   * 
+   * Uses the merged /config endpoint which returns tool protections embedded
+   * at config.toolProtection.tools. Falls back to legacy formats for backward
+   * compatibility.
    *
    * @param agentDid DID of the agent to fetch config for
    * @param options Optional fetch options
@@ -675,17 +739,17 @@ export class ToolProtectionService {
     agentDid: string,
     options?: { bypassCDNCache?: boolean }
   ): Promise<BouncerConfigApiResponse> {
-    // Prefer new project-scoped endpoint: /api/v1/bouncer/projects/{projectId}/tool-protections
-    // Falls back to old endpoint: /api/v1/bouncer/config?agent_did={did} for backward compatibility
+    // Use the merged /config endpoint which includes embedded tool protections
+    // This endpoint returns config.toolProtection.tools with all tool rules
     let url: string;
-    let useNewEndpoint = false;
+    let useMergedEndpoint = false;
 
     if (this.config.projectId) {
-      // ✅ NEW ENDPOINT: Project-scoped, returns toolProtections object
-      url = `${this.config.apiUrl}/api/v1/bouncer/projects/${encodeURIComponent(this.config.projectId)}/tool-protections`;
-      useNewEndpoint = true;
+      // ✅ MERGED CONFIG ENDPOINT: Returns config with embedded toolProtection.tools
+      url = `${this.config.apiUrl}/api/v1/bouncer/projects/${encodeURIComponent(this.config.projectId)}/config`;
+      useMergedEndpoint = true;
     } else {
-      // ⚠️ OLD ENDPOINT: Agent-scoped, returns tools array (backward compatibility)
+      // ⚠️ LEGACY ENDPOINT: Agent-scoped, returns tools array (backward compatibility)
       url = `${this.config.apiUrl}/api/v1/bouncer/config?agent_did=${encodeURIComponent(agentDid)}`;
     }
 
@@ -712,9 +776,9 @@ export class ToolProtectionService {
 
     if (this.config.debug) {
       console.log("[ToolProtectionService] Fetching from API:", url, {
-        method: useNewEndpoint
-          ? "projects/{projectId}/tool-protections (new)"
-          : "config?agent_did (old)",
+        method: useMergedEndpoint
+          ? "projects/{projectId}/config (merged)"
+          : "config?agent_did (legacy)",
         projectId: this.config.projectId || "none",
         apiKeyPresent: !!this.config.apiKey,
         apiKeyLength,
@@ -736,19 +800,19 @@ export class ToolProtectionService {
       );
     }
 
-    // Build headers - new endpoint uses X-API-Key, old endpoint uses Authorization Bearer
+    // Build headers - merged endpoint uses X-API-Key, legacy uses Authorization Bearer
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
     };
 
-    if (useNewEndpoint) {
-      // ✅ New endpoint headers
+    if (useMergedEndpoint) {
+      // ✅ Merged config endpoint headers
       headers["X-API-Key"] = this.config.apiKey;
       if (this.config.projectId) {
         headers["X-Project-Id"] = this.config.projectId;
       }
     } else {
-      // ⚠️ Old endpoint headers (backward compatibility)
+      // ⚠️ Legacy endpoint headers (backward compatibility)
       headers["Authorization"] = `Bearer ${this.config.apiKey}`;
     }
 
@@ -786,6 +850,19 @@ export class ToolProtectionService {
       throw new Error("API returned success: false");
     }
 
+    // Transform merged config format to normalized format
+    // If response contains config.toolProtection.tools, extract them to data.toolProtections
+    if (useMergedEndpoint && data.data.config?.toolProtection?.tools) {
+      // Extract embedded tools to the standard toolProtections field
+      data.data.toolProtections = data.data.config.toolProtection.tools;
+      if (this.config.debug) {
+        console.log("[ToolProtectionService] Extracted tools from merged config", {
+          toolCount: Object.keys(data.data.toolProtections).length,
+          tools: Object.keys(data.data.toolProtections),
+        });
+      }
+    }
+
     return data;
   }
 
@@ -816,28 +893,28 @@ export class ToolProtectionService {
 
   /**
    * Clear cache and immediately fetch fresh config from API
-   * 
+   *
    * This method is designed for Cloudflare Workers where KV has edge caching.
    * After clearing the KV entry, it fetches fresh data from the API and writes
    * it back to KV. This ensures:
    * 1. The global KV entry is deleted
    * 2. Fresh data is fetched from API (with CDN cache bypass!)
    * 3. New data is written to KV (updating edge cache)
-   * 
+   *
    * The next request from the same edge location will get the fresh data.
-   * 
+   *
    * IMPORTANT: This method uses bypassCDNCache to ensure we get fresh data
    * from AgentShield's origin server, not stale CDN-cached data. This is
    * critical for instant cache invalidation when tool protection settings
    * are changed in the AgentShield dashboard.
-   * 
+   *
    * @param agentDid DID of the agent (used for cache key)
    * @returns The fresh tool protection config from API
    */
   async clearAndRefresh(agentDid: string): Promise<{
     config: ToolProtectionConfig;
     cacheKey: string;
-    source: 'api' | 'fallback';
+    source: "api" | "fallback";
   }> {
     const cacheKey = this.config.projectId
       ? `config:tool-protections:${this.config.projectId}`
@@ -857,7 +934,9 @@ export class ToolProtectionService {
     // 2. Fetch fresh config from API with CDN cache bypass
     // This ensures we get fresh data from origin, not stale CDN data
     try {
-      const response = await this.fetchFromApi(agentDid, { bypassCDNCache: true });
+      const response = await this.fetchFromApi(agentDid, {
+        bypassCDNCache: true,
+      });
 
       // Transform API response to internal format (same logic as getToolProtectionConfig)
       const toolProtections: Record<string, ToolProtection> = {};
@@ -897,15 +976,20 @@ export class ToolProtectionService {
             const toolName = (tool as any).name;
             if (!toolName) continue;
             const requiresDelegation =
-              (tool as any).requiresDelegation ?? (tool as any).requires_delegation ?? false;
+              (tool as any).requiresDelegation ??
+              (tool as any).requires_delegation ??
+              false;
             const requiredScopes =
               (tool as any).requiredScopes ??
               (tool as any).required_scopes ??
               (tool as any).scopes ??
               [];
             const oauthProvider =
-              (tool as any).oauthProvider ?? (tool as any).oauth_provider ?? undefined;
-            const riskLevel = (tool as any).riskLevel ?? (tool as any).risk_level ?? undefined;
+              (tool as any).oauthProvider ??
+              (tool as any).oauth_provider ??
+              undefined;
+            const riskLevel =
+              (tool as any).riskLevel ?? (tool as any).risk_level ?? undefined;
 
             toolProtections[toolName] = {
               requiresDelegation,
@@ -964,19 +1048,23 @@ export class ToolProtectionService {
         source: "api",
       });
 
-      return { config: freshConfig, cacheKey, source: 'api' };
+      return { config: freshConfig, cacheKey, source: "api" };
     } catch (error) {
-      console.warn("[ToolProtectionService] API fetch failed during refresh, using fallback", {
-        error: error instanceof Error ? error.message : String(error),
-        cacheKey,
-      });
+      console.warn(
+        "[ToolProtectionService] API fetch failed during refresh, using fallback",
+        {
+          error: error instanceof Error ? error.message : String(error),
+          cacheKey,
+        }
+      );
 
       // Use fallback config if API fails
-      const fallbackConfig: ToolProtectionConfig = this.config.fallbackConfig || {
+      const fallbackConfig: ToolProtectionConfig = this.config
+        .fallbackConfig || {
         toolProtections: {},
       };
 
-      return { config: fallbackConfig, cacheKey, source: 'fallback' };
+      return { config: fallbackConfig, cacheKey, source: "fallback" };
     }
   }
 }

package/src/utils/__tests__/did-helpers.test.ts

@@ -11,6 +11,8 @@ import {
   normalizeDid,
   compareDids,
   getServerDid,
+  generateDidKeyFromBytes,
+  generateDidKeyFromBase64,
 } from "../did-helpers";
 
 describe("DID Helpers", () => {
@@ -97,5 +99,58 @@ describe("DID Helpers", () => {
       expect(() => getServerDid(config)).toThrow("Server DID not configured");
     });
   });
+
+  describe("generateDidKeyFromBytes", () => {
+    it("should generate valid did:key from 32-byte Ed25519 public key", () => {
+      // Use a known test key (32 bytes)
+      const publicKeyBytes = new Uint8Array(32).fill(0xab);
+      const did = generateDidKeyFromBytes(publicKeyBytes);
+
+      expect(did).toMatch(/^did:key:z6Mk/);
+      expect(isValidDid(did)).toBe(true);
+      expect(getDidMethod(did)).toBe("key");
+    });
+
+    it("should generate consistent did:key for same input", () => {
+      const publicKeyBytes = new Uint8Array(32).fill(0x42);
+      const did1 = generateDidKeyFromBytes(publicKeyBytes);
+      const did2 = generateDidKeyFromBytes(publicKeyBytes);
+
+      expect(did1).toBe(did2);
+    });
+
+    it("should generate different did:key for different inputs", () => {
+      const key1 = new Uint8Array(32).fill(0x11);
+      const key2 = new Uint8Array(32).fill(0x22);
+
+      const did1 = generateDidKeyFromBytes(key1);
+      const did2 = generateDidKeyFromBytes(key2);
+
+      expect(did1).not.toBe(did2);
+    });
+  });
+
+  describe("generateDidKeyFromBase64", () => {
+    it("should generate valid did:key from base64-encoded public key", () => {
+      // Base64 encode a 32-byte key
+      const publicKeyBytes = new Uint8Array(32).fill(0xcd);
+      const publicKeyBase64 = btoa(String.fromCharCode(...publicKeyBytes));
+
+      const did = generateDidKeyFromBase64(publicKeyBase64);
+
+      expect(did).toMatch(/^did:key:z6Mk/);
+      expect(isValidDid(did)).toBe(true);
+    });
+
+    it("should produce same result as generateDidKeyFromBytes", () => {
+      const publicKeyBytes = new Uint8Array(32).fill(0xef);
+      const publicKeyBase64 = btoa(String.fromCharCode(...publicKeyBytes));
+
+      const didFromBytes = generateDidKeyFromBytes(publicKeyBytes);
+      const didFromBase64 = generateDidKeyFromBase64(publicKeyBase64);
+
+      expect(didFromBytes).toBe(didFromBase64);
+    });
+  });
 });
 

package/src/utils/base58.ts

@@ -0,0 +1,109 @@
+/**
+ * Base58 Utilities (Bitcoin alphabet)
+ *
+ * Encoding and decoding utilities for Base58 (Bitcoin alphabet).
+ * Used for did:key multibase encoding (with 'z' prefix for base58btc).
+ *
+ * The Bitcoin alphabet excludes ambiguous characters (0, O, I, l).
+ */
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const ALPHABET_MAP = new Map<string, number>();
+
+// Build reverse lookup map
+for (let i = 0; i < ALPHABET.length; i++) {
+  ALPHABET_MAP.set(ALPHABET[i], i);
+}
+
+/**
+ * Encode bytes to Base58 (Bitcoin alphabet)
+ *
+ * @param bytes - Bytes to encode
+ * @returns Base58-encoded string
+ */
+export function base58Encode(bytes: Uint8Array): string {
+  if (bytes.length === 0) return '';
+
+  // Convert bytes to big integer
+  let num = BigInt(0);
+  for (let i = 0; i < bytes.length; i++) {
+    num = num * BigInt(256) + BigInt(bytes[i]);
+  }
+
+  // Convert to base58
+  let result = '';
+  while (num > 0) {
+    result = ALPHABET[Number(num % BigInt(58))] + result;
+    num = num / BigInt(58);
+  }
+
+  // Add leading zeros (encoded as '1' in base58)
+  for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
+    result = '1' + result;
+  }
+
+  return result;
+}
+
+/**
+ * Decode Base58 (Bitcoin alphabet) to bytes
+ *
+ * @param encoded - Base58-encoded string
+ * @returns Decoded bytes
+ * @throws Error if input contains invalid characters
+ */
+export function base58Decode(encoded: string): Uint8Array {
+  if (encoded.length === 0) return new Uint8Array(0);
+
+  // Convert base58 to big integer
+  let num = BigInt(0);
+  for (const char of encoded) {
+    const value = ALPHABET_MAP.get(char);
+    if (value === undefined) {
+      throw new Error(`Invalid base58 character: ${char}`);
+    }
+    num = num * BigInt(58) + BigInt(value);
+  }
+
+  // Convert big integer to bytes
+  const bytes: number[] = [];
+  while (num > 0) {
+    bytes.unshift(Number(num % BigInt(256)));
+    num = num / BigInt(256);
+  }
+
+  // Count leading zeros in input (encoded as '1')
+  let leadingZeros = 0;
+  for (const char of encoded) {
+    if (char === '1') {
+      leadingZeros++;
+    } else {
+      break;
+    }
+  }
+
+  // Prepend leading zero bytes
+  const result = new Uint8Array(leadingZeros + bytes.length);
+  // Leading zeros are already 0 in Uint8Array
+  result.set(bytes, leadingZeros);
+
+  return result;
+}
+
+/**
+ * Validate a Base58 string
+ *
+ * @param encoded - String to validate
+ * @returns true if valid Base58, false otherwise
+ */
+export function isValidBase58(encoded: string): boolean {
+  if (encoded.length === 0) return true;
+
+  for (const char of encoded) {
+    if (!ALPHABET_MAP.has(char)) {
+      return false;
+    }
+  }
+
+  return true;
+}