movehat 0.1.9 → 0.2.1

package/src/fork/manager.ts

@@ -1,6 +1,24 @@
+import { createHash } from 'node:crypto';
 import { MovementApiClient } from './api.js';
 import { ForkStorage } from './storage.js';
 import type { ForkMetadata, AccountState } from '../types/fork.js';
+import { normalizeAddress } from '../utils/address.js';
+import { logger } from '../ui/index.js';
+
+/**
+ * Derive a deterministic 32-byte hex placeholder for the `authentication_key`
+ * of a fork-funded account. The real auth_key is `sha3_256(public_key || 0x00)`
+ * for Ed25519; the fork has no public key material, so we hash the address
+ * itself. This is NOT a real auth key — downstream code must not treat it as
+ * trustworthy key material. Distinguishable from the address by construction
+ * (#63 — prior code used `address.padEnd(66, '0')` which was a no-op since
+ * normalized addresses are already 66 chars).
+ */
+function forkAuthKeyPlaceholder(normalizedAddress: string): string {
+  const stripped = normalizedAddress.startsWith('0x') ? normalizedAddress.slice(2) : normalizedAddress;
+  const digest = createHash('sha3-256').update(stripped, 'hex').digest('hex');
+  return `0x${digest}`;
+}
 
 /**
  * Manager for fork operations
@@ -11,24 +29,53 @@ export class ForkManager {
   private apiClient: MovementApiClient | null = null;
   private metadata: ForkMetadata | null = null;
 
+  /**
+   * Optional API key sent as `Authorization: Bearer <key>` on every
+   * outgoing Movement API request. Not persisted to disk via
+   * {@link ForkMetadata} (keys stay in process memory). For the
+   * load-then-set pattern, call {@link setApiKey} after `load()`.
+   */
+  private apiKey?: string;
+
   constructor(forkPath: string) {
     this.storage = new ForkStorage(forkPath);
   }
 
   /**
-   * Initialize a new fork from a network
+   * Set or update the API key used for upstream Movement API requests.
+   * Reconstructs the internal `MovementApiClient` if one exists.
+   */
+  setApiKey(apiKey: string | undefined): void {
+    if (apiKey === undefined) {
+      delete this.apiKey;
+    } else {
+      this.apiKey = apiKey;
+    }
+    if (this.apiClient && this.metadata) {
+      this.apiClient = new MovementApiClient(this.metadata.nodeUrl, this.apiKey);
+    }
+  }
+
+  /**
+   * Initialize a new fork from a network.
+   *
+   * @param nodeUrl - Upstream JSON-RPC base URL.
+   * @param networkName - Logical network label (defaults to `'custom'`).
+   * @param apiKey - Optional API key for `Authorization: Bearer` header.
    */
-  async initialize(nodeUrl: string, networkName: string = 'custom'): Promise<void> {
-    // Create API client
-    this.apiClient = new MovementApiClient(nodeUrl);
+  async initialize(
+    nodeUrl: string,
+    networkName: string = 'custom',
+    apiKey?: string
+  ): Promise<void> {
+    if (apiKey !== undefined) this.apiKey = apiKey;
+
+    this.apiClient = new MovementApiClient(nodeUrl, this.apiKey);
 
-    // Fetch network info
     const ledgerInfo = await this.apiClient.getLedgerInfo();
 
-    // Create fork structure
     this.storage.initialize();
 
-    // Save metadata
     this.metadata = {
       network: networkName,
       nodeUrl,
@@ -46,7 +93,9 @@ export class ForkManager {
   }
 
   /**
-   * Load an existing fork
+   * Load an existing fork. The API key is NOT persisted to disk —
+   * callers needing authenticated upstream reads after `load()` must
+   * call {@link setApiKey} explicitly.
    */
   load(): void {
     if (!this.storage.exists()) {
@@ -54,12 +103,9 @@ export class ForkManager {
     }
 
     this.metadata = this.storage.loadMetadata();
-    this.apiClient = new MovementApiClient(this.metadata.nodeUrl);
+    this.apiClient = new MovementApiClient(this.metadata.nodeUrl, this.apiKey);
   }
 
-  /**
-   * Get fork metadata
-   */
   getMetadata(): ForkMetadata {
     if (!this.metadata) {
       this.metadata = this.storage.loadMetadata();
@@ -67,18 +113,12 @@ export class ForkManager {
     return this.metadata;
   }
 
-  /**
-   * Get account state (with lazy loading)
-   */
   async getAccount(address: string): Promise<AccountState> {
-    // Normalize address
-    const normalizedAddress = this.normalizeAddress(address);
+    const normalizedAddress = normalizeAddress(address);
 
-    // Check cache first
     let accountState = this.storage.getAccount(normalizedAddress);
 
     if (!accountState) {
-      // Fetch from network
       if (!this.apiClient) {
         throw new Error('Fork not initialized. Call initialize() or load() first.');
       }
@@ -91,7 +131,6 @@ export class ForkManager {
         authenticationKey: accountData.authentication_key,
       };
 
-      // Cache it
       this.storage.saveAccount(normalizedAddress, accountState);
       console.log(`  ✓ Cached account ${normalizedAddress}`);
     }
@@ -99,17 +138,12 @@ export class ForkManager {
     return accountState;
   }
 
-  /**
-   * Get a specific resource (with lazy loading)
-   */
   async getResource(address: string, resourceType: string): Promise<any> {
-    const normalizedAddress = this.normalizeAddress(address);
+    const normalizedAddress = normalizeAddress(address);
 
-    // Check cache first
     let resource = this.storage.getResource(normalizedAddress, resourceType);
 
     if (!resource) {
-      // Fetch from network
       if (!this.apiClient) {
         throw new Error('Fork not initialized. Call initialize() or load() first.');
       }
@@ -120,11 +154,11 @@ export class ForkManager {
         const resourceData = await this.apiClient.getAccountResource(normalizedAddress, resourceType);
         resource = resourceData.data;
 
-        // Cache it
         this.storage.saveResource(normalizedAddress, resourceType, resource);
         console.log(`  ✓ Cached resource ${resourceType}`);
-      } catch (error: any) {
-        if (error.message.includes('404')) {
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes('404')) {
           throw new Error(`Resource ${resourceType} not found for account ${normalizedAddress}`);
         }
         throw error;
@@ -134,16 +168,11 @@ export class ForkManager {
     return resource;
   }
 
-  /**
-   * Get all resources for an account (with lazy loading)
-   */
   async getAllResources(address: string): Promise<Record<string, any>> {
-    const normalizedAddress = this.normalizeAddress(address);
+    const normalizedAddress = normalizeAddress(address);
 
-    // Check if we have any cached resources
     let resources = this.storage.getAllResources(normalizedAddress);
 
-    // If no cached resources, fetch all from network
     if (Object.keys(resources).length === 0) {
       if (!this.apiClient) {
         throw new Error('Fork not initialized. Call initialize() or load() first.');
@@ -157,7 +186,6 @@ export class ForkManager {
         resources[resource.type] = resource.data;
       }
 
-      // Cache them
       this.storage.saveAllResources(normalizedAddress, resources);
       console.log(`  ✓ Cached ${Object.keys(resources).length} resources`);
     }
@@ -165,33 +193,32 @@ export class ForkManager {
     return resources;
   }
 
-  /**
-   * Set a resource value (for testing/mocking)
-   */
-  async setResource(address: string, resourceType: string, data: any): Promise<void> {
-    const normalizedAddress = this.normalizeAddress(address);
+  async setResource(address: string, resourceType: string, data: unknown): Promise<void> {
+    const normalizedAddress = normalizeAddress(address);
     this.storage.saveResource(normalizedAddress, resourceType, data);
     console.log(`  ✓ Updated resource ${resourceType} for ${normalizedAddress}`);
   }
 
-  /**
-   * Fund an account with coins (adds to existing balance)
-   */
+  /** Adds to the existing balance rather than replacing it. */
   async fundAccount(address: string, amount: number, coinType: string = '0x1::aptos_coin::AptosCoin'): Promise<void> {
-    const normalizedAddress = this.normalizeAddress(address);
+    const normalizedAddress = normalizeAddress(address);
     const resourceType = `0x1::coin::CoinStore<${coinType}>`;
 
-    // Try to get existing coin store
+    // Try to get existing coin store. The coin store is a CoinStore<T>
+    // resource whose `data` is Movement-side untyped JSON; we shape it
+    // locally as a structural object with `coin.value: string`.
+    // any: full CoinStore schema lives at the Movement REST boundary —
+    // proper validation deferred to the boundary-validation follow-up of #57.
     let coinStore: any;
     try {
       coinStore = await this.getResource(normalizedAddress, resourceType);
-    } catch (error: any) {
+    } catch (error) {
       // Only catch "not found" errors, rethrow others (network, API, etc.)
-      if (!error.message || !error.message.includes('not found')) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (!msg.includes('not found')) {
         throw error;
       }
 
-      // If doesn't exist, create new one
       coinStore = {
         coin: { value: '0' },
         deposit_events: {
@@ -216,20 +243,17 @@ export class ForkManager {
       };
     }
 
-    // Add to existing balance (instead of replacing it)
     const currentBalance = BigInt(coinStore.coin.value ?? '0');
     const newBalance = currentBalance + BigInt(amount);
     coinStore.coin.value = newBalance.toString();
 
-    // Save
     await this.setResource(normalizedAddress, resourceType, coinStore);
 
-    // Also ensure account exists
     let account = this.storage.getAccount(normalizedAddress);
     if (!account) {
       account = {
         sequenceNumber: '0',
-        authenticationKey: normalizedAddress.padEnd(66, '0'),
+        authenticationKey: forkAuthKeyPlaceholder(normalizedAddress),
       };
       this.storage.saveAccount(normalizedAddress, account);
     }
@@ -237,27 +261,6 @@ export class ForkManager {
     console.log(`  ✓ Funded ${normalizedAddress} with ${amount} coins`);
   }
 
-  /**
-   * Normalize address format
-   */
-  private normalizeAddress(address: string): string {
-    let normalized = address.toLowerCase();
-
-    if (!normalized.startsWith('0x')) {
-      normalized = `0x${normalized}`;
-    }
-
-    // Pad to 66 characters (0x + 64 hex chars)
-    if (normalized.length < 66) {
-      normalized = '0x' + normalized.slice(2).padStart(64, '0');
-    }
-
-    return normalized;
-  }
-
-  /**
-   * List all accounts in the fork
-   */
   listAccounts(): string[] {
     return this.storage.listAccounts();
   }
@@ -267,7 +270,7 @@ export class ForkManager {
    *
    * @param addresses Array of addresses to fund
    * @param amount Amount of coins per account
-   * @param coinType Coin type (defaults to AptosCoin)
+   * @param coinType Coin type (defaults to the chain's native coin)
    *
    * @example
    * await forkManager.fundMultipleAccounts(
@@ -280,13 +283,15 @@ export class ForkManager {
     amount: number,
     coinType: string = '0x1::aptos_coin::AptosCoin'
   ): Promise<void> {
-    console.log(`\n💰 Funding ${addresses.length} accounts with ${amount} coins each...`);
+    logger.newline();
+    logger.step(`Funding ${addresses.length} accounts with ${amount} coins each...`);
 
     for (const address of addresses) {
       await this.fundAccount(address, amount, coinType);
     }
 
-    console.log(`✓ All accounts funded successfully\n`);
+    logger.success("All accounts funded successfully");
+    logger.newline();
   }
 
   /**
@@ -297,13 +302,15 @@ export class ForkManager {
    * await forkManager.resetState();
    */
   async resetState(): Promise<void> {
-    console.log(`\n🔄 Resetting fork state...`);
+    logger.newline();
+    logger.step("Resetting fork state...");
 
     // Clear all accounts and resources from storage
     this.storage.clearAccounts();
     this.storage.clearResources();
 
-    console.log(`✓ Fork state reset to initial snapshot\n`);
+    logger.success("Fork state reset to initial snapshot");
+    logger.newline();
   }
 
   /**
@@ -317,16 +324,14 @@ export class ForkManager {
    * const account = await forkManager.getOrCreateAccount("0x123...");
    */
   async getOrCreateAccount(address: string): Promise<AccountState> {
-    const normalizedAddress = this.normalizeAddress(address);
+    const normalizedAddress = normalizeAddress(address);
 
-    // Try to get existing account
     try {
       return await this.getAccount(normalizedAddress);
     } catch (error) {
-      // If account doesn't exist, create a minimal one
       const newAccount: AccountState = {
         sequenceNumber: '0',
-        authenticationKey: normalizedAddress.padEnd(66, '0'),
+        authenticationKey: forkAuthKeyPlaceholder(normalizedAddress),
       };
 
       this.storage.saveAccount(normalizedAddress, newAccount);

package/src/fork/server.ts

@@ -3,17 +3,24 @@ import { URL } from 'url';
 import { ForkManager } from './manager.js';
 
 /**
- * Fork Server - Serves fork data via Movement/Aptos RPC API
+ * Fork Server - Serves fork data via Movement L1 RPC API
  * Emulates a Movement L1 node using local fork storage
  */
 export class ForkServer {
   private server: http.Server | null = null;
   private forkManager: ForkManager;
   private port: number;
+  private host: string;
 
-  constructor(forkPath: string, port: number = 8080) {
+  /**
+   * @param host Interface to bind. Defaults to `127.0.0.1` so cached fork
+   *   state (which may include sensitive resources) is not exposed on the LAN.
+   *   Pass `'0.0.0.0'` only if you intentionally need to expose the server.
+   */
+  constructor(forkPath: string, port: number = 8080, host: string = '127.0.0.1') {
     this.forkManager = new ForkManager(forkPath);
     this.port = port;
+    this.host = host;
   }
 
   /**
@@ -52,6 +59,12 @@ export class ForkServer {
       });
     });
 
+    // Capture the just-assigned server into a non-null local so we don't
+    // have to repeatedly assert `this.server!` (which TS forces because
+    // `http.createServer` returns an unrelated narrow that the field
+    // declaration doesn't track).
+    const server = this.server;
+
     return new Promise((resolve, reject) => {
       // Handle server errors (port in use, permission denied, etc.)
       const onError = (error: NodeJS.ErrnoException) => {
@@ -65,14 +78,26 @@ export class ForkServer {
       };
 
       // Listen for errors during startup
-      this.server!.once('error', onError);
+      server.once('error', onError);
 
-      this.server!.listen(this.port, () => {
+      server.listen(this.port, this.host, () => {
         // Remove error listener after successful start
-        this.server!.removeListener('error', onError);
-
-        console.log(`\nFork Server listening on http://localhost:${this.port}`);
-        console.log(`  Ledger Info: http://localhost:${this.port}/v1/`);
+        server.removeListener('error', onError);
+
+        // IPv6 literals must be wrapped in brackets in URLs (RFC 3986).
+        const isIpv6 = this.host.includes(':');
+        const displayHost =
+          this.host === '0.0.0.0'
+            ? 'localhost'
+            : isIpv6
+              ? `[${this.host}]`
+              : this.host;
+        console.log(`\nFork Server listening on http://${displayHost}:${this.port}`);
+        console.log(`  Bound interface: ${this.host}`);
+        console.log(`  Ledger Info: http://${displayHost}:${this.port}/v1/`);
+        if (this.host === '0.0.0.0') {
+          console.warn(`  Server is bound to 0.0.0.0 — fork state is reachable from the LAN.`);
+        }
         console.log(`\nPress Ctrl+C to stop`);
         resolve();
       });
@@ -143,11 +168,15 @@ export class ForkServer {
         const resourceIndex = parts.indexOf('resource') + 1;
         const address = parts[accountIndex];
         const resourceType = decodeURIComponent(parts.slice(resourceIndex).join('/'));
+        if (!address) {
+          this.send404(res, 'Malformed resource path', 'malformed_path');
+          return;
+        }
         await this.handleGetResource(address, resourceType, res);
       } else {
         // Use regex capture for resources endpoint
         const resourcesMatch = pathname.match(/^\/v1\/accounts\/(0x[a-fA-F0-9]{1,64})\/resources$/);
-        if (resourcesMatch) {
+        if (resourcesMatch && resourcesMatch[1]) {
           const address = resourcesMatch[1];
           await this.handleGetResources(address, res);
         } else {
@@ -156,7 +185,7 @@ export class ForkServer {
           this.send404(res, `Endpoint not found: ${safePath}`, 'endpoint_not_found');
         }
       }
-    } catch (error: any) {
+    } catch (error) {
       // Log full error server-side for diagnostics
       console.error('Error handling request:', error);
 
@@ -208,8 +237,9 @@ export class ForkServer {
         sequence_number: account.sequenceNumber,
         authentication_key: account.authenticationKey
       });
-    } catch (error: any) {
-      if (error.message.includes('not found')) {
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes('not found')) {
         this.send404(res, `Account not found: ${address}`);
       } else {
         throw error;
@@ -232,8 +262,9 @@ export class ForkServer {
         type: resourceType,
         data: resource
       });
-    } catch (error: any) {
-      if (error.message.includes('not found')) {
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes('not found')) {
         this.send404(res, `Resource not found: ${resourceType}`, 'resource_not_found');
       } else {
         throw error;
@@ -251,15 +282,16 @@ export class ForkServer {
     try {
       const resources = await this.forkManager.getAllResources(address);
 
-      // Convert to array format expected by Aptos API
+      // Convert to array format expected by the Movement L1 API
       const resourcesArray = Object.entries(resources).map(([type, data]) => ({
         type,
         data
       }));
 
       this.sendJSON(res, 200, resourcesArray);
-    } catch (error: any) {
-      if (error.message.includes('not found')) {
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes('not found')) {
         this.send404(res, `Account not found: ${address}`);
       } else {
         throw error;
@@ -268,12 +300,14 @@ export class ForkServer {
   }
 
   /**
-   * Send JSON response
+   * Send JSON response.
+   * unknown: arbitrary JSON-serializable payload; structural shape varies by
+   * endpoint (account metadata, resource arrays, error envelopes).
    */
   private sendJSON(
     res: http.ServerResponse,
     status: number,
-    data: any,
+    data: unknown,
     extraHeaders: Record<string, string> = {}
   ): void {
     const body = JSON.stringify(data, null, 2);

package/src/fork/storage.ts

@@ -1,25 +1,22 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import type { ForkMetadata, AccountState } from '../types/fork.js';
+import { isHexAddress } from '../utils/address.js';
 
 /**
- * Sanitize address to create a safe filename
- * Prevents path traversal by encoding the address
+ * Sanitize address to create a safe filename. Validates the address through
+ * the shared `isHexAddress` helper (length 1–64 hex chars, optional `0x`),
+ * then rebuilds a canonical `0x…` form. The trailing path-separator check is
+ * defense-in-depth: unreachable after `isHexAddress`, but cheap to keep.
  */
 function sanitizeAddressForFilename(address: string): string {
-  // Remove any path separators and normalize
-  const normalized = address.toLowerCase().replace(/^0x/, '');
-
-  // Validate that it's a valid hex string
-  if (!/^[0-9a-f]+$/.test(normalized)) {
+  if (!isHexAddress(address)) {
     throw new Error(`Invalid address format: ${address}. Expected hexadecimal string.`);
   }
 
-  // Encode to prevent any path traversal
-  // Use the normalized hex string directly as it's safe
+  const normalized = address.toLowerCase().replace(/^0x/, '');
   const safe = `0x${normalized}`;
 
-  // Validate no path separators in result
   if (safe.includes('/') || safe.includes('\\') || safe.includes('..')) {
     throw new Error(`Address contains invalid characters: ${address}`);
   }
@@ -141,7 +138,7 @@ export class ForkStorage {
   /**
    * Get resource for an account
    */
-  getResource(address: string, resourceType: string): any | null {
+  getResource(address: string, resourceType: string): unknown | null {
     const resourceFilePath = this.getResourceFilePath(address);
 
     if (!existsSync(resourceFilePath)) {
@@ -155,7 +152,7 @@ export class ForkStorage {
   /**
    * Get all resources for an account
    */
-  getAllResources(address: string): Record<string, any> {
+  getAllResources(address: string): Record<string, unknown> {
     const resourceFilePath = this.getResourceFilePath(address);
 
     if (!existsSync(resourceFilePath)) {
@@ -168,7 +165,7 @@ export class ForkStorage {
   /**
    * Save resource for an account
    */
-  saveResource(address: string, resourceType: string, data: any): void {
+  saveResource(address: string, resourceType: string, data: unknown): void {
     const resourceFilePath = this.getResourceFilePath(address);
 
     // Ensure resources directory exists
@@ -177,7 +174,7 @@ export class ForkStorage {
       mkdirSync(resourcesDir, { recursive: true });
     }
 
-    let resources: Record<string, any> = {};
+    let resources: Record<string, unknown> = {};
     if (existsSync(resourceFilePath)) {
       resources = JSON.parse(readFileSync(resourceFilePath, 'utf-8'));
     }
@@ -189,7 +186,7 @@ export class ForkStorage {
   /**
    * Save all resources for an account
    */
-  saveAllResources(address: string, resources: Record<string, any>): void {
+  saveAllResources(address: string, resources: Record<string, unknown>): void {
     const resourceFilePath = this.getResourceFilePath(address);
 
     // Ensure resources directory exists