movehat 0.1.9 → 0.2.0

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,16 +29,49 @@ 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;
+
+    // Create API client (with optional Authorization header)
+    this.apiClient = new MovementApiClient(nodeUrl, this.apiKey);
 
     // Fetch network info
     const ledgerInfo = await this.apiClient.getLedgerInfo();
@@ -46,7 +97,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,7 +107,7 @@ export class ForkManager {
     }
 
     this.metadata = this.storage.loadMetadata();
-    this.apiClient = new MovementApiClient(this.metadata.nodeUrl);
+    this.apiClient = new MovementApiClient(this.metadata.nodeUrl, this.apiKey);
   }
 
   /**
@@ -72,7 +125,7 @@ export class ForkManager {
    */
   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);
@@ -103,7 +156,7 @@ export class ForkManager {
    * 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);
@@ -123,8 +176,9 @@ export class ForkManager {
         // 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;
@@ -138,7 +192,7 @@ export class ForkManager {
    * 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);
@@ -168,8 +222,8 @@ export class ForkManager {
   /**
    * 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}`);
   }
@@ -178,16 +232,21 @@ export class ForkManager {
    * Fund an account with coins (adds to existing balance)
    */
   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;
       }
 
@@ -229,7 +288,7 @@ export class ForkManager {
     if (!account) {
       account = {
         sequenceNumber: '0',
-        authenticationKey: normalizedAddress.padEnd(66, '0'),
+        authenticationKey: forkAuthKeyPlaceholder(normalizedAddress),
       };
       this.storage.saveAccount(normalizedAddress, account);
     }
@@ -237,24 +296,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
    */
@@ -267,7 +308,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 +321,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 +340,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,7 +362,7 @@ 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 {
@@ -326,7 +371,7 @@ export class ForkManager {
       // 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

package/src/fork/test.ts

@@ -1,13 +1,17 @@
-import { execFile } from 'child_process';
-import { promisify } from 'util';
 import { join } from 'path';
 import { existsSync } from 'fs';
-
-const execFileAsync = promisify(execFile);
+import { runCli } from '../utils/runCli.js';
+import type { ChildProcessAdapter } from '../utils/childProcessAdapter.js';
 
 export interface SnapshotOptions {
   path?: string;
   name?: string;
+  /**
+   * Override the child-process adapter. Test-only — production callers
+   * leave this undefined so the default spawn-based adapter is used.
+   * Mirrors the M1.3c pattern on `runtime.deployContract`.
+   */
+  adapter?: ChildProcessAdapter;
 }
 
 export interface ForkInfo {
@@ -40,15 +44,22 @@ export async function snapshot(options: SnapshotOptions = {}): Promise<string> {
   console.log(`📸 Creating snapshot: ${name}...`);
 
   try {
-    // Initialize fork/snapshot using aptos CLI
-    // Use execFile with argument array to prevent command injection
-    const { stdout, stderr } = await execFileAsync('aptos', [
-      'move',
-      'sim',
-      'init',
-      '--path',
-      snapshotPath
-    ]);
+    // Initialize fork/snapshot using aptos CLI.
+    // runCli uses spawn-with-args under the hood (no shell), preventing
+    // command injection. Pass throwOnNonZeroExit:false so the exitCode is
+    // observable below — the stderr/dir defenses are belt-and-suspenders
+    // on top of the exitCode check.
+    const { stdout, stderr, exitCode } = await runCli(
+      {
+        command: 'aptos',
+        args: ['move', 'sim', 'init', '--path', snapshotPath],
+      },
+      { throwOnNonZeroExit: false, adapter: options.adapter }
+    );
+
+    if (exitCode !== 0) {
+      throw new Error(stderr || `fork snapshot init failed with exit code ${exitCode}`);
+    }
 
     if (stderr && !stderr.includes('Success')) {
       throw new Error(stderr);
@@ -60,8 +71,9 @@ export async function snapshot(options: SnapshotOptions = {}): Promise<string> {
 
     console.log(`   ✓ Snapshot created at ${snapshotPath}`);
     return snapshotPath;
-  } catch (error: any) {
-    throw new Error(`Failed to create snapshot: ${error.message}`);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to create snapshot: ${msg}`);
   }
 }
 
@@ -122,21 +134,34 @@ export async function getForkInfo(path: string): Promise<ForkInfo> {
 export async function viewForkResource(
   sessionPath: string,
   account: string,
-  resourceType: string
+  resourceType: string,
+  options: { adapter?: ChildProcessAdapter } = {}
 ): Promise<any> {
   try {
-    // Use execFile with argument array to prevent command injection
-    const { stdout } = await execFileAsync('aptos', [
-      'move',
-      'sim',
-      'view-resource',
-      '--session',
-      sessionPath,
-      '--account',
-      account,
-      '--resource',
-      resourceType
-    ]);
+    // runCli uses spawn-with-args (no shell) to prevent command injection.
+    const { stdout, stderr, exitCode } = await runCli(
+      {
+        command: 'aptos',
+        args: [
+          'move',
+          'sim',
+          'view-resource',
+          '--session',
+          sessionPath,
+          '--account',
+          account,
+          '--resource',
+          resourceType,
+        ],
+      },
+      { throwOnNonZeroExit: false, adapter: options.adapter }
+    );
+
+    if (exitCode !== 0) {
+      throw new Error(
+        stderr || `fork view-resource failed with exit code ${exitCode}`
+      );
+    }
 
     const result = JSON.parse(stdout);
 
@@ -145,8 +170,9 @@ export async function viewForkResource(
     }
 
     return result.Result;
-  } catch (error: any) {
-    throw new Error(`Failed to view resource: ${error.message}`);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to view resource: ${msg}`);
   }
 }
 
@@ -164,8 +190,8 @@ export async function compareForkState(
   forkPath: string,
   account: string,
   resourceType: string,
-  currentValue: any
-): Promise<{ fork: any; current: any; changed: boolean }> {
+  currentValue: unknown
+): Promise<{ fork: unknown; current: unknown; changed: boolean }> {
   const forkValue = await viewForkResource(forkPath, account, resourceType);
 
   return {