@hardkas/accounts 0.2.2-alpha.1 → 0.4.0-alpha

package/dist/index.d.ts

@@ -110,6 +110,24 @@ declare function listHardkasAccounts(config?: HardkasConfig): HardkasAccount[];
 declare function resolveHardkasAccountAddress(accountOrAddress: string, config?: HardkasConfig): string;
 declare function describeAccount(account: HardkasAccount): Record<string, unknown>;
 
+interface EvmExportResult {
+    address: `0x${string}`;
+    privateKey?: `0x${string}`;
+    isSecret: boolean;
+    networkId: string;
+}
+/**
+ * Validates and prepares an account for EVM export.
+ *
+ * SECURITY CONSTRAINT:
+ * - Only explicit EVM/L2 accounts are exported.
+ * - No derivation from Kaspa L1 keys in this PR.
+ * - Fails on mainnet/testnet.
+ */
+declare function prepareEvmAccountExport(account: HardkasAccount, networkId: string, options?: {
+    includeSecret?: boolean;
+}): Promise<EvmExportResult>;
+
 declare function getRequiredEnv(name: string): string;
 
 /**
@@ -153,6 +171,34 @@ declare function loadKaspaWasm(): Promise<any>;
  */
 declare function getKaspaSigningBackendStatus(): Promise<KaspaSigningBackendStatus>;
 
+interface GeneratedKaspaDevAccount {
+    readonly address: string;
+    readonly publicKey?: string;
+    readonly privateKey: string;
+    readonly mnemonic?: string;
+}
+interface KaspaKeyGenerator {
+    generateAccount(options?: {
+        readonly networkId?: "simnet" | "testnet-10" | "mainnet";
+    }): Promise<GeneratedKaspaDevAccount>;
+}
+/**
+ * Placeholder implementation for Kaspa key generation.
+ * This ensures we don't implement custom crypto logic and wait for a verified SDK integration.
+ */
+declare class UnsupportedKaspaKeyGenerator implements KaspaKeyGenerator {
+    generateAccount(): Promise<GeneratedKaspaDevAccount>;
+}
+
+interface CreateKaspaWalletOptions {
+    networkId?: "simnet" | "testnet-10" | "mainnet";
+}
+/**
+ * Generates a new Kaspa L1 developer wallet.
+ * Strictly separate from EVM/L2 identities.
+ */
+declare function createLocalKaspaWallet(options?: CreateKaspaWalletOptions): Promise<GeneratedKaspaDevAccount>;
+
 /**
  * Real Kaspa signer using the official WASM SDK.
  * Only works if the 'kaspa' package is installed.
@@ -187,7 +233,10 @@ interface RealDevAccount {
     readonly name: string;
     readonly address: string;
     readonly publicKey?: string;
+    /** @deprecated Use keystoreRef for encrypted storage. Plaintext keys in this field are considered legacy/unsafe. */
     readonly privateKey?: string;
+    /** Reference to the encrypted keystore file in .hardkas/keystore/ */
+    readonly keystoreRef?: string;
     readonly createdAt: string;
 }
 declare function getDefaultRealAccountsPath(cwd?: string): string;
@@ -254,25 +303,6 @@ declare class KaspaSdkRealTxSigner implements RealTxSigner {
     sign(input: RealTxSigningInput): Promise<RealTxSigningResult>;
 }
 
-interface GeneratedKaspaDevAccount {
-    readonly address: string;
-    readonly publicKey?: string;
-    readonly privateKey: string;
-    readonly mnemonic?: string;
-}
-interface KaspaKeyGenerator {
-    generateAccount(options?: {
-        readonly networkId?: "simnet" | "testnet-10" | "mainnet";
-    }): Promise<GeneratedKaspaDevAccount>;
-}
-/**
- * Placeholder implementation for Kaspa key generation.
- * This ensures we don't implement custom crypto logic and wait for a verified SDK integration.
- */
-declare class UnsupportedKaspaKeyGenerator implements KaspaKeyGenerator {
-    generateAccount(): Promise<GeneratedKaspaDevAccount>;
-}
-
 interface KaspaSdkKeyGeneratorOptions {
     readonly networkId?: "simnet" | "testnet-10" | "mainnet";
     readonly sdkLoader?: () => Promise<any>;
@@ -335,4 +365,4 @@ declare class KeystoreManager {
     static saveEncryptedKeystore(filePath: string, keystore: EncryptedKeystoreV2): Promise<void>;
 }
 
-export { type EncryptedKeystoreV2, type GeneratedKaspaDevAccount, type HardkasAccount, type HardkasAccountKind, type HardkasBaseAccount, type HardkasEvmPrivateKeyAccount, type HardkasExternalWalletAccount, type HardkasKaspaPrivateKeyAccount, type HardkasSigner, type HardkasSignerKind, type HardkasSimulatedAccount, type HardkasTxPlanSigner, type KaspaKeyGenerator, KaspaSdkKeyGenerator, type KaspaSdkKeyGeneratorOptions, KaspaSdkRealTxSigner, type KaspaSdkRealTxSignerOptions, type KaspaSigningBackendStatus, KaspaWasmPrivateKeySigner, type KeystoreCipherParams, type KeystoreKdfParams, KeystoreManager, type KeystorePayload, type KeystoreUnlockResult, type RealAccountStore, type RealDevAccount, type RealTxSigner, type RealTxSigningInput, type RealTxSigningResult, type ResolveAccountOptions, type SignTxPlanInput, type SignTxPlanResult, SimulatedSigner, SimulatedTxPlanSigner, UnsupportedKaspaKeyGenerator, UnsupportedRealKaspaSigner, UnsupportedRealTxSigner, assertSigningNetworkAllowed, createEmptyRealAccountStore, describeAccount, getDefaultRealAccountsPath, getKaspaSigningBackendStatus, getRealDevAccount, getRequiredEnv, importRealDevAccount, listHardkasAccounts, listRealDevAccounts, loadKaspaWasm, loadOrCreateRealAccountStore, loadRealAccountStore, loadRealAccountStoreSync, removeRealDevAccount, resolveHardkasAccount, resolveHardkasAccountAddress, resolveRealAccountOrAddress, saveRealAccountStore, signTxPlanArtifact, validateAccountName, validateAddressPrefix };
+export { type CreateKaspaWalletOptions, type EncryptedKeystoreV2, type EvmExportResult, type GeneratedKaspaDevAccount, type HardkasAccount, type HardkasAccountKind, type HardkasBaseAccount, type HardkasEvmPrivateKeyAccount, type HardkasExternalWalletAccount, type HardkasKaspaPrivateKeyAccount, type HardkasSigner, type HardkasSignerKind, type HardkasSimulatedAccount, type HardkasTxPlanSigner, type KaspaKeyGenerator, KaspaSdkKeyGenerator, type KaspaSdkKeyGeneratorOptions, KaspaSdkRealTxSigner, type KaspaSdkRealTxSignerOptions, type KaspaSigningBackendStatus, KaspaWasmPrivateKeySigner, type KeystoreCipherParams, type KeystoreKdfParams, KeystoreManager, type KeystorePayload, type KeystoreUnlockResult, type RealAccountStore, type RealDevAccount, type RealTxSigner, type RealTxSigningInput, type RealTxSigningResult, type ResolveAccountOptions, type SignTxPlanInput, type SignTxPlanResult, SimulatedSigner, SimulatedTxPlanSigner, UnsupportedKaspaKeyGenerator, UnsupportedRealKaspaSigner, UnsupportedRealTxSigner, assertSigningNetworkAllowed, createEmptyRealAccountStore, createLocalKaspaWallet, describeAccount, getDefaultRealAccountsPath, getKaspaSigningBackendStatus, getRealDevAccount, getRequiredEnv, importRealDevAccount, listHardkasAccounts, listRealDevAccounts, loadKaspaWasm, loadOrCreateRealAccountStore, loadRealAccountStore, loadRealAccountStoreSync, prepareEvmAccountExport, removeRealDevAccount, resolveHardkasAccount, resolveHardkasAccountAddress, resolveRealAccountOrAddress, saveRealAccountStore, signTxPlanArtifact, validateAccountName, validateAddressPrefix };

package/dist/index.js

@@ -21,6 +21,7 @@ import { createDeterministicAccounts } from "@hardkas/localnet";
 // src/real-accounts.ts
 import fs from "fs";
 import path from "path";
+import { writeFileAtomicSync } from "@hardkas/core";
 import { HARDKAS_VERSION, ARTIFACT_SCHEMAS, ARTIFACT_VERSION } from "@hardkas/artifacts";
 function getDefaultRealAccountsPath(cwd = process.cwd()) {
   return path.join(cwd, ".hardkas", "accounts.real.json");
@@ -34,7 +35,7 @@ function createEmptyRealAccountStore() {
     networkId: "simnet",
     mode: "real",
     connectionMode: "node",
-    warning: "Development keys only. Do not use on mainnet. Private keys are stored in plaintext.",
+    warning: "HardKAS: Development account store. Encrypted storage is default. Unsafe plaintext storage is legacy.",
     accounts: []
   };
 }
@@ -45,7 +46,17 @@ function loadRealAccountStoreSync(options) {
   }
   try {
     const data = fs.readFileSync(filePath, "utf-8");
-    return JSON.parse(data);
+    const store = JSON.parse(data);
+    const plaintextAccounts = store.accounts.filter((a) => a.privateKey);
+    if (plaintextAccounts.length > 0) {
+      const names = plaintextAccounts.map((a) => a.name).join(", ");
+      console.warn(`
+  \u26A0\uFE0F  [SECURITY WARNING] Plaintext private keys detected in legacy account store for: ${names}`);
+      console.warn(`     Location: ${filePath}`);
+      console.warn(`     Recommendation: Re-import these accounts using encrypted keystores.
+`);
+    }
+    return store;
   } catch (e) {
     throw new Error(`Failed to load real account store at ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
   }
@@ -62,12 +73,11 @@ async function loadOrCreateRealAccountStore(options) {
 }
 async function saveRealAccountStore(store, options) {
   const filePath = options?.path || getDefaultRealAccountsPath(options?.cwd);
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
   try {
-    fs.writeFileSync(filePath, JSON.stringify(store, null, 2), "utf-8");
+    writeFileAtomicSync(filePath, JSON.stringify(store, null, 2), {
+      encoding: "utf-8",
+      mode: 384
+    });
   } catch (e) {
     throw new Error(`Failed to save real account store at ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
   }
@@ -253,6 +263,47 @@ function describeAccount(account) {
   return desc;
 }
 
+// src/evm-export.ts
+async function prepareEvmAccountExport(account, networkId, options = {}) {
+  if (networkId === "mainnet" || networkId.startsWith("testnet")) {
+    throw new Error(`EVM account export is NOT allowed on network "${networkId}" for security reasons.`);
+  }
+  if (networkId !== "simnet" && networkId !== "localnet") {
+    throw new Error(`EVM account export is only supported on local development networks (simnet, localnet).`);
+  }
+  if (account.kind !== "evm-private-key") {
+    throw new Error(`Account "${account.name}" is not an EVM/L2 account (kind: ${account.kind}). Only explicit EVM accounts can be exported.`);
+  }
+  if (!account.address || !account.address.startsWith("0x")) {
+    throw new Error(`Account "${account.name}" does not have a valid EVM address.`);
+  }
+  const result = {
+    address: account.address,
+    isSecret: false,
+    networkId
+  };
+  if (options.includeSecret) {
+    let privateKey;
+    if (account.kind === "evm-private-key") {
+      if (account.privateKeyEnv) {
+        privateKey = process.env[account.privateKeyEnv];
+        if (!privateKey) {
+          throw new Error(`Private key environment variable "${account.privateKeyEnv}" is not set.`);
+        }
+      } else {
+        privateKey = account.privateKey;
+      }
+    }
+    if (privateKey) {
+      result.privateKey = privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`;
+      result.isSecret = true;
+    } else {
+      throw new Error(`Private key for account "${account.name}" could not be retrieved.`);
+    }
+  }
+  return result;
+}
+
 // src/env.ts
 function getRequiredEnv(name) {
   const value = process.env[name];
@@ -445,7 +496,6 @@ async function signTxPlanArtifact(input) {
       version: "1.0.0-alpha",
       status: "signed",
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      signedId: `signed_${planArtifact.planId}_${Date.now().toString(36)}`,
       txId: result.txId || "",
       // Ensure txId is present
       sourcePlanId: planArtifact.planId,
@@ -459,7 +509,9 @@ async function signTxPlanArtifact(input) {
         payload: result.signedTransaction?.payload || ""
       }
     };
-    artifact.contentHash = calculateContentHash2(artifact);
+    const contentHash = calculateContentHash2(artifact);
+    artifact.signedId = `signed-${contentHash.slice(0, 16)}`;
+    artifact.contentHash = contentHash;
     return artifact;
   }
   if (account.kind === "external-wallet") {
@@ -471,6 +523,56 @@ async function signTxPlanArtifact(input) {
   throw new Error(`Unsupported account kind for signing: ${account.kind}`);
 }
 
+// src/kaspa-sdk-keygen.ts
+var KaspaSdkKeyGenerator = class {
+  networkId;
+  sdkLoader;
+  constructor(options) {
+    this.networkId = options?.networkId || "simnet";
+    const rawLoader = options?.sdkLoader || (async () => {
+      return await import("kaspa");
+    });
+    this.sdkLoader = async () => {
+      try {
+        return await rawLoader();
+      } catch (e) {
+        throw new Error(
+          "Kaspa SDK key generation dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter. Use 'hardkas accounts real import' to add accounts manually for now."
+        );
+      }
+    };
+  }
+  async generateAccount(options) {
+    const sdk = await this.sdkLoader();
+    const network = options?.networkId || this.networkId;
+    try {
+      if (typeof sdk.PrivateKey === "function") {
+        const privKey = new sdk.PrivateKey();
+        const pubKey = privKey.toPublicKey();
+        const address = pubKey.toAddress(network).toString();
+        const privateKeyStr = privKey.toString();
+        const publicKeyStr = pubKey.toString();
+        return {
+          address,
+          publicKey: publicKeyStr,
+          privateKey: privateKeyStr
+        };
+      }
+      throw new Error("Loaded Kaspa SDK does not expose expected PrivateKey constructor.");
+    } catch (e) {
+      throw new Error(`Failed to generate account using SDK: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+};
+
+// src/kaspa-wallet.ts
+async function createLocalKaspaWallet(options) {
+  const keygen = new KaspaSdkKeyGenerator({
+    networkId: options?.networkId || "simnet"
+  });
+  return await keygen.generateAccount();
+}
+
 // src/real-signer.ts
 var UnsupportedRealTxSigner = class {
   async sign() {
@@ -561,53 +663,12 @@ var UnsupportedKaspaKeyGenerator = class {
   }
 };
 
-// src/kaspa-sdk-keygen.ts
-var KaspaSdkKeyGenerator = class {
-  networkId;
-  sdkLoader;
-  constructor(options) {
-    this.networkId = options?.networkId || "simnet";
-    const rawLoader = options?.sdkLoader || (async () => {
-      return await import("kaspa");
-    });
-    this.sdkLoader = async () => {
-      try {
-        return await rawLoader();
-      } catch (e) {
-        throw new Error(
-          "Kaspa SDK key generation dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter. Use 'hardkas accounts real import' to add accounts manually for now."
-        );
-      }
-    };
-  }
-  async generateAccount(options) {
-    const sdk = await this.sdkLoader();
-    const network = options?.networkId || this.networkId;
-    try {
-      if (typeof sdk.PrivateKey === "function") {
-        const privKey = new sdk.PrivateKey();
-        const pubKey = privKey.toPublicKey();
-        const address = pubKey.toAddress(network).toString();
-        const privateKeyStr = privKey.toString();
-        const publicKeyStr = pubKey.toString();
-        return {
-          address,
-          publicKey: publicKeyStr,
-          privateKey: privateKeyStr
-        };
-      }
-      throw new Error("Loaded Kaspa SDK does not expose expected PrivateKey constructor.");
-    } catch (e) {
-      throw new Error(`Failed to generate account using SDK: ${e instanceof Error ? e.message : String(e)}`);
-    }
-  }
-};
-
 // src/keystore.ts
 import fs3 from "fs";
 import path3 from "path";
 import crypto from "crypto";
 import { argon2id } from "hash-wasm";
+import { writeFileAtomic } from "@hardkas/core";
 var KeystoreManager = class {
   /**
    * Keystore container format version. Separate from ARTIFACT_VERSION.
@@ -750,7 +811,10 @@ var KeystoreManager = class {
       if (!fs3.existsSync(dir)) {
         await fs3.promises.mkdir(dir, { recursive: true });
       }
-      await fs3.promises.writeFile(filePath, JSON.stringify(keystore, null, 2), "utf-8");
+      await writeFileAtomic(filePath, JSON.stringify(keystore, null, 2), {
+        encoding: "utf-8",
+        mode: 384
+      });
     } catch (e) {
       throw new Error(`Failed to save keystore at ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
     }
@@ -768,6 +832,7 @@ export {
   UnsupportedRealTxSigner,
   assertSigningNetworkAllowed,
   createEmptyRealAccountStore,
+  createLocalKaspaWallet,
   describeAccount,
   getDefaultRealAccountsPath,
   getKaspaSigningBackendStatus,
@@ -780,6 +845,7 @@ export {
   loadOrCreateRealAccountStore,
   loadRealAccountStore,
   loadRealAccountStoreSync,
+  prepareEvmAccountExport,
   removeRealDevAccount,
   resolveHardkasAccount,
   resolveHardkasAccountAddress,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/accounts",
-  "version": "0.2.2-alpha.1",
+  "version": "0.4.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,10 +17,10 @@
   ],
   "dependencies": {
     "hash-wasm": "^4.12.0",
-    "@hardkas/artifacts": "0.2.2-alpha.1",
-    "@hardkas/config": "0.2.2-alpha.1",
-    "@hardkas/core": "0.2.2-alpha.1",
-    "@hardkas/localnet": "0.2.2-alpha.1"
+    "@hardkas/artifacts": "0.4.0-alpha",
+    "@hardkas/core": "0.4.0-alpha",
+    "@hardkas/config": "0.4.0-alpha",
+    "@hardkas/localnet": "0.4.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",