@hardkas/accounts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,340 @@
+import { HardkasConfig } from '@hardkas/config';
+import { TxPlanArtifact, SignedTxArtifact, HardkasArtifactBase } from '@hardkas/artifacts';
+import { NetworkId } from '@hardkas/core';
+
+type HardkasAccountKind = "simulated" | "kaspa-private-key" | "external-wallet" | "evm-private-key";
+interface KeystorePayload {
+    address: string;
+    privateKey: string;
+    publicKey?: string;
+    network: string;
+}
+interface KeystoreKdfParams {
+    algorithm: "argon2id" | "scrypt";
+    memory: number;
+    iterations: number;
+    parallelism: number;
+    salt: string;
+}
+interface KeystoreCipherParams {
+    algorithm: "aes-256-gcm";
+    nonce: string;
+    tag: string;
+}
+/**
+ * Encrypted keystore envelope format.
+ * version/type here refer to the keystore container format, NOT artifact schema version.
+ * This is intentionally separate from ARTIFACT_VERSION.
+ */
+interface EncryptedKeystoreV2 {
+    version: "2.0.0";
+    type: "hardkas.encryptedKeystore.v2";
+    kdf: KeystoreKdfParams;
+    cipher: KeystoreCipherParams;
+    encryptedPayload: string;
+    createdAt: string;
+    metadata: {
+        label: string;
+        network: string;
+        [key: string]: any;
+    };
+}
+interface KeystoreUnlockResult {
+    success: boolean;
+    payload?: KeystorePayload;
+    error?: string;
+}
+interface HardkasBaseAccount {
+    name: string;
+    kind: HardkasAccountKind;
+    address?: string;
+}
+interface HardkasSimulatedAccount extends HardkasBaseAccount {
+    kind: "simulated";
+    address: string;
+}
+interface HardkasKaspaPrivateKeyAccount extends HardkasBaseAccount {
+    kind: "kaspa-private-key";
+    privateKeyEnv?: string | undefined;
+    address?: string;
+}
+interface HardkasExternalWalletAccount extends HardkasBaseAccount {
+    kind: "external-wallet";
+    walletId?: string;
+    address?: string;
+}
+interface HardkasEvmPrivateKeyAccount extends HardkasBaseAccount {
+    kind: "evm-private-key";
+    privateKeyEnv?: string | undefined;
+    address?: string;
+}
+type HardkasAccount = HardkasSimulatedAccount | HardkasKaspaPrivateKeyAccount | HardkasExternalWalletAccount | HardkasEvmPrivateKeyAccount;
+type HardkasSignerKind = "simulated" | "kaspa-private-key" | "external-wallet" | "unsupported";
+interface SignTxPlanInput {
+    planArtifact: any;
+    accountName: string;
+}
+interface SignTxPlanResult {
+    signatureKind: HardkasSignerKind;
+    signerAddress: string;
+    txId?: string;
+    signedTransaction: {
+        format: "hex" | "simulated" | "unknown";
+        payload: string;
+    };
+    signature?: {
+        value: string;
+    };
+}
+interface HardkasTxPlanSigner {
+    kind: HardkasSignerKind;
+    signTxPlan(input: SignTxPlanInput): Promise<SignTxPlanResult>;
+}
+interface HardkasSigner<TTx = unknown, TSignedTx = unknown> {
+    account: HardkasAccount;
+    signTransaction(tx: TTx): Promise<TSignedTx>;
+}
+
+declare class SimulatedSigner implements HardkasSigner {
+    readonly account: HardkasSimulatedAccount;
+    constructor(account: HardkasSimulatedAccount);
+    signTransaction(tx: unknown): Promise<unknown>;
+}
+
+interface ResolveAccountOptions {
+    nameOrAddress: string;
+    config?: HardkasConfig | undefined;
+}
+declare function resolveHardkasAccount(options: ResolveAccountOptions): HardkasAccount;
+declare function listHardkasAccounts(config?: HardkasConfig): HardkasAccount[];
+declare function resolveHardkasAccountAddress(accountOrAddress: string, config?: HardkasConfig): string;
+declare function describeAccount(account: HardkasAccount): Record<string, unknown>;
+
+declare function getRequiredEnv(name: string): string;
+
+declare function redactSecret(value: string): string;
+
+/**
+ * Simulated signer for simnet development.
+ * Produces deterministic signatures without real private keys.
+ */
+declare class SimulatedTxPlanSigner implements HardkasTxPlanSigner {
+    kind: HardkasSignerKind;
+    signTxPlan(input: SignTxPlanInput): Promise<SignTxPlanResult>;
+}
+/**
+ * Placeholder for real Kaspa signing.
+ */
+declare class UnsupportedRealKaspaSigner implements HardkasTxPlanSigner {
+    kind: HardkasSignerKind;
+    signTxPlan(_input: SignTxPlanInput): Promise<SignTxPlanResult>;
+}
+/**
+ * Main entry point for signing transaction plan artifacts.
+ */
+declare function signTxPlanArtifact(input: {
+    planArtifact: TxPlanArtifact;
+    account: HardkasAccount;
+    config?: HardkasConfig;
+    allowMainnet?: boolean;
+}): Promise<SignedTxArtifact>;
+
+interface KaspaSigningBackendStatus {
+    available: boolean;
+    name: string;
+    version?: string;
+    error?: string;
+}
+/**
+ * Loads the official Kaspa WASM SDK dynamically.
+ * This ensures the toolkit remains usable even if the SDK is not installed.
+ */
+declare function loadKaspaWasm(): Promise<any>;
+/**
+ * Checks if the Kaspa WASM SDK is available without throwing.
+ */
+declare function getKaspaSigningBackendStatus(): Promise<KaspaSigningBackendStatus>;
+
+/**
+ * Real Kaspa signer using the official WASM SDK.
+ * Only works if the 'kaspa' package is installed.
+ */
+declare class KaspaWasmPrivateKeySigner implements HardkasTxPlanSigner {
+    private options;
+    kind: HardkasSignerKind;
+    constructor(options: {
+        account: HardkasKaspaPrivateKeyAccount;
+        allowMainnet?: boolean | undefined;
+    });
+    signTxPlan(input: SignTxPlanInput): Promise<SignTxPlanResult>;
+}
+/**
+ * Security guard for network types.
+ */
+declare function assertSigningNetworkAllowed(input: {
+    network: NetworkId;
+    mode: string;
+    allowMainnet?: boolean | undefined;
+}): void;
+
+interface RealAccountStore extends HardkasArtifactBase {
+    readonly schema: "hardkas.realAccountStore.v1";
+    readonly networkId: NetworkId;
+    readonly mode: "real";
+    readonly connectionMode?: "node" | "rpc";
+    readonly warning: string;
+    readonly accounts: readonly RealDevAccount[];
+}
+interface RealDevAccount {
+    readonly name: string;
+    readonly address: string;
+    readonly publicKey?: string;
+    readonly privateKey?: string;
+    readonly createdAt: string;
+}
+declare function getDefaultRealAccountsPath(cwd?: string): string;
+declare function createEmptyRealAccountStore(): RealAccountStore;
+declare function loadRealAccountStoreSync(options?: {
+    readonly cwd?: string;
+    readonly path?: string;
+}): RealAccountStore | null;
+declare function loadRealAccountStore(options?: {
+    readonly cwd?: string;
+    readonly path?: string;
+}): Promise<RealAccountStore | null>;
+declare function loadOrCreateRealAccountStore(options?: {
+    readonly cwd?: string;
+    readonly path?: string;
+}): Promise<RealAccountStore>;
+declare function saveRealAccountStore(store: RealAccountStore, options?: {
+    readonly cwd?: string;
+    readonly path?: string;
+}): Promise<void>;
+declare function validateAccountName(name: string): void;
+declare function validateAddressPrefix(address: string): void;
+declare function importRealDevAccount(store: RealAccountStore, account: {
+    readonly name: string;
+    readonly address: string;
+    readonly publicKey?: string;
+    readonly privateKey?: string;
+}): RealAccountStore;
+declare function removeRealDevAccount(store: RealAccountStore, name: string): RealAccountStore;
+declare function getRealDevAccount(store: RealAccountStore, name: string): RealDevAccount | null;
+declare function listRealDevAccounts(store: RealAccountStore): readonly RealDevAccount[];
+/**
+ * Resolves a name (alias) or a direct Kaspa address from the real store.
+ */
+declare function resolveRealAccountOrAddress(store: RealAccountStore | null, nameOrAddress: string): {
+    address: string;
+    name?: string;
+};
+
+interface RealTxSigningInput {
+    readonly plan: TxPlanArtifact;
+    readonly account: RealDevAccount;
+}
+interface RealTxSigningResult {
+    readonly signedTransaction: {
+        readonly format: "kaspa-sdk" | "hex" | "json" | "simulated" | "unknown";
+        readonly payload: string;
+    };
+    readonly txId?: string;
+}
+interface RealTxSigner {
+    sign(input: RealTxSigningInput): Promise<RealTxSigningResult>;
+}
+declare class UnsupportedRealTxSigner implements RealTxSigner {
+    sign(): Promise<RealTxSigningResult>;
+}
+
+interface KaspaSdkRealTxSignerOptions {
+    readonly sdkLoader?: () => Promise<any>;
+}
+declare class KaspaSdkRealTxSigner implements RealTxSigner {
+    private readonly sdkLoader;
+    constructor(options?: KaspaSdkRealTxSignerOptions);
+    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>;
+}
+/**
+ * Adapter for Kaspa SDK key generation.
+ * Uses dynamic imports to avoid breaking if the SDK is not installed.
+ */
+declare class KaspaSdkKeyGenerator implements KaspaKeyGenerator {
+    private readonly networkId;
+    private readonly sdkLoader;
+    constructor(options?: KaspaSdkKeyGeneratorOptions);
+    generateAccount(options?: {
+        readonly networkId?: "simnet" | "testnet-10" | "mainnet";
+    }): Promise<GeneratedKaspaDevAccount>;
+}
+
+/**
+ * HardKAS Keystore V2 Implementation
+ *
+ * Uses Argon2id for KDF and AES-256-GCM for encryption.
+ * Designed for local developer workflows.
+ */
+declare class KeystoreManager {
+    /**
+     * Keystore container format version. Separate from ARTIFACT_VERSION.
+     * This versions the encrypted keystore envelope, not HardKAS artifacts.
+     */
+    private static readonly KEYSTORE_FORMAT_VERSION;
+    private static readonly KEYSTORE_FORMAT_TYPE;
+    /**
+     * Creates an encrypted keystore from a payload and password.
+     */
+    static createEncryptedKeystore(payload: KeystorePayload, password: string, options: {
+        label: string;
+        network: string;
+        iterations?: number;
+        memory?: number;
+        parallelism?: number;
+    }): Promise<EncryptedKeystoreV2>;
+    /**
+     * Decrypts an encrypted keystore using a password.
+     */
+    static decryptEncryptedKeystore(keystore: EncryptedKeystoreV2, password: string): Promise<KeystoreUnlockResult>;
+    /**
+     * Verifies if the password is correct for the keystore.
+     */
+    static verifyKeystorePassword(keystore: EncryptedKeystoreV2, password: string): Promise<boolean>;
+    /**
+     * Changes the password of an encrypted keystore.
+     */
+    static changeKeystorePassword(keystore: EncryptedKeystoreV2, oldPassword: string, newPassword: string): Promise<EncryptedKeystoreV2>;
+    /**
+     * Loads an encrypted keystore from the filesystem.
+     */
+    static loadEncryptedKeystore(filePath: string): Promise<EncryptedKeystoreV2>;
+    /**
+     * Saves an encrypted keystore to the filesystem.
+     */
+    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, redactSecret, removeRealDevAccount, resolveHardkasAccount, resolveHardkasAccountAddress, resolveRealAccountOrAddress, saveRealAccountStore, signTxPlanArtifact, validateAccountName, validateAddressPrefix };

package/dist/index.js

@@ -0,0 +1,801 @@
+// src/simulated.ts
+var SimulatedSigner = class {
+  constructor(account) {
+    this.account = account;
+  }
+  account;
+  async signTransaction(tx) {
+    return {
+      tx,
+      signature: "simulated",
+      account: this.account.name
+    };
+  }
+};
+
+// src/resolve.ts
+import fs2 from "fs";
+import path2 from "path";
+import { createDeterministicAccounts } from "@hardkas/localnet";
+
+// src/real-accounts.ts
+import fs from "fs";
+import path from "path";
+import { HARDKAS_VERSION, ARTIFACT_SCHEMAS, ARTIFACT_VERSION } from "@hardkas/artifacts";
+function getDefaultRealAccountsPath(cwd = process.cwd()) {
+  return path.join(cwd, ".hardkas", "accounts.real.json");
+}
+function createEmptyRealAccountStore() {
+  return {
+    schema: ARTIFACT_SCHEMAS.REAL_ACCOUNT_STORE,
+    hardkasVersion: HARDKAS_VERSION,
+    version: ARTIFACT_VERSION,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    networkId: "simnet",
+    mode: "real",
+    connectionMode: "node",
+    warning: "Development keys only. Do not use on mainnet. Private keys are stored in plaintext.",
+    accounts: []
+  };
+}
+function loadRealAccountStoreSync(options) {
+  const filePath = options?.path || getDefaultRealAccountsPath(options?.cwd);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const data = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(data);
+  } catch (e) {
+    throw new Error(`Failed to load real account store at ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+async function loadRealAccountStore(options) {
+  return loadRealAccountStoreSync(options);
+}
+async function loadOrCreateRealAccountStore(options) {
+  const store = await loadRealAccountStore(options);
+  if (store) return store;
+  const newStore = createEmptyRealAccountStore();
+  await saveRealAccountStore(newStore, options);
+  return newStore;
+}
+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");
+  } catch (e) {
+    throw new Error(`Failed to save real account store at ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+function validateAccountName(name) {
+  if (!name) {
+    throw new Error("Account name is required.");
+  }
+  const nameRegex = /^[a-zA-Z0-9_-]+$/;
+  if (!nameRegex.test(name)) {
+    throw new Error(`Invalid account name '${name}'. Only letters, numbers, dashes and underscores are allowed.`);
+  }
+}
+function validateAddressPrefix(address) {
+  if (!address) {
+    throw new Error("Address is required.");
+  }
+  const validPrefixes = ["kaspa:", "kaspatest:", "kaspasim:"];
+  const hasValidPrefix = validPrefixes.some((prefix) => address.startsWith(prefix));
+  if (!hasValidPrefix) {
+    throw new Error(`Invalid address '${address}'. Must start with one of: ${validPrefixes.join(", ")}`);
+  }
+}
+function importRealDevAccount(store, account) {
+  validateAccountName(account.name);
+  validateAddressPrefix(account.address);
+  if (store.accounts.some((a) => a.name.toLowerCase() === account.name.toLowerCase())) {
+    throw new Error(`Account with name '${account.name}' already exists.`);
+  }
+  const newAccount = {
+    ...account,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    ...store,
+    accounts: [...store.accounts, newAccount]
+  };
+}
+function removeRealDevAccount(store, name) {
+  const index = store.accounts.findIndex((a) => a.name.toLowerCase() === name.toLowerCase());
+  if (index === -1) {
+    throw new Error(`Account with name '${name}' not found.`);
+  }
+  const newAccounts = [...store.accounts];
+  newAccounts.splice(index, 1);
+  return {
+    ...store,
+    accounts: newAccounts
+  };
+}
+function getRealDevAccount(store, name) {
+  return store.accounts.find((a) => a.name.toLowerCase() === name.toLowerCase()) || null;
+}
+function listRealDevAccounts(store) {
+  return store.accounts;
+}
+function resolveRealAccountOrAddress(store, nameOrAddress) {
+  const account = store ? getRealDevAccount(store, nameOrAddress) : null;
+  if (account) {
+    return { address: account.address, name: account.name };
+  }
+  if (nameOrAddress.startsWith("kaspa:") || nameOrAddress.startsWith("kaspatest:") || nameOrAddress.startsWith("kaspasim:")) {
+    return { address: nameOrAddress };
+  }
+  throw new Error(`'${nameOrAddress}' is not a registered real account name and is not a valid Kaspa address.`);
+}
+
+// src/resolve.ts
+function resolveHardkasAccount(options) {
+  const { nameOrAddress, config } = options;
+  if (nameOrAddress.startsWith("kaspa:") || nameOrAddress.startsWith("kaspatest:") || nameOrAddress.startsWith("kaspasim:")) {
+    return {
+      name: nameOrAddress,
+      kind: "external-wallet",
+      address: nameOrAddress
+    };
+  }
+  if (config?.accounts && config.accounts[nameOrAddress]) {
+    const accConfig = config.accounts[nameOrAddress];
+    return {
+      name: nameOrAddress,
+      ...accConfig
+    };
+  }
+  const realStore = loadRealAccountStoreSync();
+  const realAcc = realStore ? getRealDevAccount(realStore, nameOrAddress) : null;
+  if (realAcc) {
+    return {
+      name: realAcc.name,
+      kind: "kaspa-private-key",
+      // Assuming Kaspa for now, could be extensible
+      address: realAcc.address
+    };
+  }
+  const detAccounts = createDeterministicAccounts();
+  const det = detAccounts.find((a) => a.name === nameOrAddress);
+  if (det) {
+    return {
+      name: det.name,
+      kind: "simulated",
+      address: det.address
+    };
+  }
+  const available = listHardkasAccounts(config).map((a) => a.name).join(", ");
+  throw new Error(`Unknown HardKAS account '${nameOrAddress}'. Available accounts: ${available}`);
+}
+function listHardkasAccounts(config) {
+  const accounts = /* @__PURE__ */ new Map();
+  const detAccounts = createDeterministicAccounts();
+  for (const det of detAccounts) {
+    accounts.set(det.name, {
+      name: det.name,
+      kind: "simulated",
+      address: det.address
+    });
+  }
+  const realStore = loadRealAccountStoreSync();
+  if (realStore) {
+    for (const realAcc of listRealDevAccounts(realStore)) {
+      accounts.set(realAcc.name, {
+        name: realAcc.name,
+        kind: "kaspa-private-key",
+        address: realAcc.address
+      });
+    }
+  }
+  const keystoreDir = path2.join(process.cwd(), ".hardkas", "keystore");
+  if (fs2.existsSync(keystoreDir)) {
+    const files = fs2.readdirSync(keystoreDir);
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        try {
+          const name = path2.basename(file, ".json");
+          const data = fs2.readFileSync(path2.join(keystoreDir, file), "utf-8");
+          const keystore = JSON.parse(data);
+          if (keystore.type === "hardkas.encryptedKeystore.v2") {
+            accounts.set(name, {
+              name,
+              kind: "kaspa-private-key",
+              address: keystore.payload?.address || keystore.metadata?.address
+              // Payloads are encrypted, but address might be in metadata
+            });
+          }
+        } catch (e) {
+        }
+      }
+    }
+  }
+  if (config?.accounts) {
+    for (const [name, accConfig] of Object.entries(config.accounts)) {
+      accounts.set(name, {
+        name,
+        ...accConfig
+      });
+    }
+  }
+  return Array.from(accounts.values());
+}
+function resolveHardkasAccountAddress(accountOrAddress, config) {
+  if (accountOrAddress.startsWith("kaspa:") || accountOrAddress.startsWith("kaspatest:") || accountOrAddress.startsWith("kaspasim:")) {
+    return accountOrAddress;
+  }
+  const account = resolveHardkasAccount({ nameOrAddress: accountOrAddress, config });
+  if (!account.address) {
+    throw new Error(`Account '${account.name}' does not have a resolved address yet.`);
+  }
+  return account.address;
+}
+function describeAccount(account) {
+  const desc = {
+    name: account.name,
+    kind: account.kind
+  };
+  if (account.address) {
+    desc.address = account.address;
+  }
+  if (account.kind === "kaspa-private-key" || account.kind === "evm-private-key") {
+    desc.privateKeyEnv = account.privateKeyEnv;
+  }
+  if (account.kind === "external-wallet" && account.walletId) {
+    desc.walletId = account.walletId;
+  }
+  return desc;
+}
+
+// src/env.ts
+function getRequiredEnv(name) {
+  const value = process.env[name];
+  if (!value || value.trim() === "") {
+    throw new Error(`Missing required environment variable '${name}'.`);
+  }
+  return value;
+}
+
+// src/redact.ts
+function redactSecret(value) {
+  if (!value) return "";
+  if (value.length <= 10) {
+    return "***";
+  }
+  return `${value.slice(0, 6)}...${value.slice(-4)}`;
+}
+
+// src/signer.ts
+import {
+  createSimulatedSignedTxArtifact,
+  calculateContentHash as calculateContentHash2,
+  HARDKAS_VERSION as HARDKAS_VERSION2
+} from "@hardkas/artifacts";
+
+// src/signer-backend.ts
+async function loadKaspaWasm() {
+  try {
+    const sdk = await import("kaspa");
+    return sdk;
+  } catch (error) {
+    throw new Error(
+      "Kaspa WASM signing backend is not available. Please install the official 'kaspa' package: pnpm add kaspa"
+    );
+  }
+}
+async function getKaspaSigningBackendStatus() {
+  try {
+    const sdk = await loadKaspaWasm();
+    return {
+      available: true,
+      name: "Kaspa WASM SDK",
+      version: sdk.version || "unknown"
+    };
+  } catch (error) {
+    return {
+      available: false,
+      name: "None",
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/kaspa-wasm-signer.ts
+import {
+  calculateContentHash
+} from "@hardkas/artifacts";
+var KaspaWasmPrivateKeySigner = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  kind = "kaspa-private-key";
+  async signTxPlan(input) {
+    const plan = input.planArtifact;
+    const account = this.options.account;
+    const sdk = await loadKaspaWasm();
+    assertSigningNetworkAllowed({
+      network: plan.networkId,
+      mode: plan.mode,
+      allowMainnet: this.options.allowMainnet
+    });
+    const pkValue = account.privateKeyEnv ? process.env[account.privateKeyEnv] : void 0;
+    if (!pkValue) {
+      throw new Error(`Missing required private key for account '${account.name}'.`);
+    }
+    try {
+      const privateKey = new sdk.PrivateKey(pkValue);
+      const utxos = plan.inputs.map((u) => {
+        if (!u.outpoint.transactionId || u.outpoint.index === void 0) {
+          throw new Error(`UTXO is missing transactionId or index. Re-run tx plan.`);
+        }
+        const spk = u.scriptPublicKey || "mock-script";
+        return new sdk.UtxoEntry(
+          BigInt(u.amountSompi),
+          spk,
+          u.outpoint.transactionId,
+          u.outpoint.index,
+          plan.from.address
+        );
+      });
+      const outputs = plan.outputs.map((o) => {
+        if (!o.address) throw new Error("Output is missing address.");
+        return new sdk.PaymentOutput(
+          new sdk.Address(o.address),
+          BigInt(o.amountSompi)
+        );
+      });
+      const changeAddress = plan.change?.address ? new sdk.Address(plan.change.address) : void 0;
+      const priorityFee = BigInt(plan.estimatedFeeSompi);
+      const unsignedTx = sdk.createTransaction(
+        utxos,
+        outputs,
+        changeAddress,
+        priorityFee
+      );
+      const signedTx = sdk.signTransaction(unsignedTx, [privateKey], true);
+      const rawTx = signedTx.serialize ? signedTx.serialize() : JSON.stringify(signedTx.toRpcTransaction());
+      return {
+        signatureKind: "kaspa-private-key",
+        signerAddress: account.address || privateKey.toAddress(plan.networkId).toString(),
+        signedTransaction: {
+          format: "hex",
+          payload: rawTx
+        },
+        txId: signedTx.id,
+        signature: {
+          // We use the txid as the signature identifier in the artifact
+          value: signedTx.id || calculateContentHash(plan)
+        }
+      };
+    } catch (error) {
+      throw new Error(`Kaspa WASM signing failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+};
+function assertSigningNetworkAllowed(input) {
+  const isMainnet = input.network === "mainnet";
+  if (isMainnet && !input.allowMainnet) {
+    throw new Error(
+      "Mainnet signing is disabled by default. Use --allow-mainnet-signing only if you understand the risks."
+    );
+  }
+}
+
+// src/signer.ts
+var SimulatedTxPlanSigner = class {
+  kind = "simulated";
+  async signTxPlan(input) {
+    const plan = input.planArtifact;
+    return {
+      signatureKind: "simulated",
+      signerAddress: plan.from.address,
+      signedTransaction: {
+        format: "simulated",
+        payload: `simulated-signed-tx:${plan.planId}`
+      }
+    };
+  }
+};
+var UnsupportedRealKaspaSigner = class {
+  kind = "unsupported";
+  async signTxPlan(_input) {
+    throw new Error(
+      "Real Kaspa signing requires an official Kaspa transaction signing library. No supported signer backend is configured."
+    );
+  }
+};
+async function signTxPlanArtifact(input) {
+  const { planArtifact, account } = input;
+  if (planArtifact.schema === "hardkas.txPlan") {
+  } else if (planArtifact.status !== "built" && planArtifact.status !== "unsigned") {
+    throw new Error(`Cannot sign artifact with status: ${planArtifact.status}`);
+  }
+  if (planArtifact.mode === "simulated") {
+    if (account.kind !== "simulated") {
+      throw new Error(`Simulated plans must be signed with simulated accounts (account '${account.name}' is '${account.kind}').`);
+    }
+  } else {
+    if (account.kind === "simulated") {
+      throw new Error(`Real Kaspa transaction plans (mode: ${planArtifact.mode}) cannot be signed with simulated accounts.`);
+    }
+  }
+  if (planArtifact.networkId === "mainnet" && !input.allowMainnet) {
+    throw new Error("Mainnet signing is disabled by default. Use --allow-mainnet-signing only if you understand the risks.");
+  }
+  if (account.kind === "simulated") {
+    return createSimulatedSignedTxArtifact(
+      planArtifact,
+      `simulated-signed-tx:${planArtifact.planId}`
+    );
+  }
+  if (account.kind === "kaspa-private-key") {
+    const status = await getKaspaSigningBackendStatus();
+    if (!status.available) {
+      throw new Error(`Real Kaspa signing is not available: ${status.error || "Unknown error"}. Ensure 'kaspa' package is installed.`);
+    }
+    const signer = new KaspaWasmPrivateKeySigner({
+      account,
+      allowMainnet: input.allowMainnet
+    });
+    const result = await signer.signTxPlan({
+      planArtifact,
+      accountName: account.name
+    });
+    const artifact = {
+      schema: "hardkas.signedTx",
+      hardkasVersion: HARDKAS_VERSION2,
+      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,
+      networkId: planArtifact.networkId,
+      mode: planArtifact.mode,
+      from: { address: planArtifact.from.address },
+      to: { address: planArtifact.to.address },
+      amountSompi: planArtifact.amountSompi,
+      signedTransaction: {
+        format: result.signedTransaction?.format === "hex" ? "hex" : "unknown",
+        payload: result.signedTransaction?.payload || ""
+      }
+    };
+    artifact.contentHash = calculateContentHash2(artifact);
+    return artifact;
+  }
+  if (account.kind === "external-wallet") {
+    throw new Error("External wallet signing is not implemented yet.");
+  }
+  if (account.kind === "evm-private-key") {
+    throw new Error("EVM accounts are reserved for future Igra support and cannot sign Kaspa L1 transactions.");
+  }
+  throw new Error(`Unsupported account kind for signing: ${account.kind}`);
+}
+
+// src/real-signer.ts
+var UnsupportedRealTxSigner = class {
+  async sign() {
+    throw new Error(
+      "Real transaction signing is not configured yet. Install/configure a supported Kaspa SDK signer adapter."
+    );
+  }
+};
+
+// src/kaspa-sdk-real-signer.ts
+var KaspaSdkRealTxSigner = class {
+  sdkLoader;
+  constructor(options) {
+    this.sdkLoader = options?.sdkLoader || loadKaspaWasm;
+  }
+  async sign(input) {
+    const { plan, account } = input;
+    let sdk;
+    try {
+      sdk = await this.sdkLoader();
+    } catch (e) {
+      throw new Error("Kaspa SDK real transaction signer dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter.");
+    }
+    if (!sdk) {
+      throw new Error("Kaspa SDK real transaction signer dependency is not installed. Install/configure the supported Kaspa WASM SDK adapter.");
+    }
+    if (!account.privateKey) {
+      throw new Error("Account has no private key available for signing.");
+    }
+    if (plan.from.address !== account.address) {
+      throw new Error(`Address mismatch: Plan requires ${plan.from.address}, but account has ${account.address}.`);
+    }
+    try {
+      const privateKey = new sdk.PrivateKey(account.privateKey);
+      const utxos = plan.inputs.map((u) => {
+        if (!u.scriptPublicKey) {
+          throw new Error(`UTXO ${u.outpoint.transactionId}:${u.outpoint.index} is missing scriptPublicKey required for signing.`);
+        }
+        const spk = u.scriptPublicKey;
+        return new sdk.UtxoEntry(
+          BigInt(u.amountSompi),
+          spk,
+          u.outpoint.transactionId,
+          u.outpoint.index,
+          plan.from.address
+        );
+      });
+      const outputs = [
+        new sdk.PaymentOutput(
+          new sdk.Address(plan.to.address),
+          BigInt(plan.amountSompi)
+        )
+      ];
+      const changeAddress = plan.change ? new sdk.Address(plan.change.address) : void 0;
+      const priorityFee = BigInt(plan.estimatedFeeSompi);
+      const unsignedTx = sdk.createTransaction(
+        utxos,
+        outputs,
+        changeAddress,
+        priorityFee
+      );
+      const signedTx = sdk.signTransaction(unsignedTx, [privateKey], true);
+      const payload = signedTx.serialize ? signedTx.serialize() : JSON.stringify(signedTx.toRpcTransaction());
+      const txId = signedTx.id;
+      return {
+        signedTransaction: {
+          format: "kaspa-sdk",
+          payload
+        },
+        txId
+      };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (msg.includes("is not a constructor") || msg.includes("is not a function")) {
+        throw new Error(`Kaspa SDK signer adapter could not find required transaction signing primitives: ${msg}`);
+      }
+      throw new Error(`Real transaction signing failed in Kaspa SDK: ${msg}`);
+    }
+  }
+};
+
+// src/real-keygen.ts
+var UnsupportedKaspaKeyGenerator = class {
+  async generateAccount() {
+    throw new Error(
+      "Real Kaspa key generation is not configured. Install/configure a supported Kaspa SDK adapter."
+    );
+  }
+};
+
+// 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";
+var KeystoreManager = class {
+  /**
+   * Keystore container format version. Separate from ARTIFACT_VERSION.
+   * This versions the encrypted keystore envelope, not HardKAS artifacts.
+   */
+  static KEYSTORE_FORMAT_VERSION = "2.0.0";
+  static KEYSTORE_FORMAT_TYPE = "hardkas.encryptedKeystore.v2";
+  /**
+   * Creates an encrypted keystore from a payload and password.
+   */
+  static async createEncryptedKeystore(payload, password, options) {
+    if (!password) throw new Error("Password cannot be empty.");
+    if (password.length < 8) throw new Error("Password must be at least 8 characters long.");
+    const salt = crypto.randomBytes(16);
+    const nonce = crypto.randomBytes(12);
+    const iterations = options.iterations || 3;
+    const memory = options.memory || 65536;
+    const parallelism = options.parallelism || 1;
+    const derivedKeyHex = await argon2id({
+      password,
+      salt,
+      parallelism,
+      iterations,
+      memorySize: memory,
+      hashLength: 32,
+      // 256 bits for AES-256
+      outputType: "hex"
+    });
+    const derivedKey = Buffer.from(derivedKeyHex, "hex");
+    const cipher = crypto.createCipheriv("aes-256-gcm", derivedKey, nonce);
+    const encryptedPayload = Buffer.concat([
+      cipher.update(JSON.stringify(payload), "utf8"),
+      cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    derivedKey.fill(0);
+    return {
+      version: this.KEYSTORE_FORMAT_VERSION,
+      type: this.KEYSTORE_FORMAT_TYPE,
+      kdf: {
+        algorithm: "argon2id",
+        memory,
+        iterations,
+        parallelism,
+        salt: salt.toString("base64")
+      },
+      cipher: {
+        algorithm: "aes-256-gcm",
+        nonce: nonce.toString("base64"),
+        tag: tag.toString("base64")
+      },
+      encryptedPayload: encryptedPayload.toString("base64"),
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      metadata: {
+        label: options.label,
+        network: options.network,
+        address: payload.address
+      }
+    };
+  }
+  /**
+   * Decrypts an encrypted keystore using a password.
+   */
+  static async decryptEncryptedKeystore(keystore, password) {
+    if (keystore.version !== this.KEYSTORE_FORMAT_VERSION) {
+      return { success: false, error: `Unsupported keystore version: ${keystore.version}` };
+    }
+    try {
+      const salt = Buffer.from(keystore.kdf.salt, "base64");
+      const nonce = Buffer.from(keystore.cipher.nonce, "base64");
+      const tag = Buffer.from(keystore.cipher.tag, "base64");
+      const encryptedData = Buffer.from(keystore.encryptedPayload, "base64");
+      const derivedKeyHex = await argon2id({
+        password,
+        salt,
+        parallelism: keystore.kdf.parallelism,
+        iterations: keystore.kdf.iterations,
+        memorySize: keystore.kdf.memory,
+        hashLength: 32,
+        outputType: "hex"
+      });
+      const derivedKey = Buffer.from(derivedKeyHex, "hex");
+      const decipher = crypto.createDecipheriv("aes-256-gcm", derivedKey, nonce);
+      decipher.setAuthTag(tag);
+      const decrypted = Buffer.concat([
+        decipher.update(encryptedData),
+        decipher.final()
+      ]);
+      derivedKey.fill(0);
+      const payload = JSON.parse(decrypted.toString("utf8"));
+      return { success: true, payload };
+    } catch (e) {
+      return { success: false, error: "Invalid password or corrupted keystore." };
+    }
+  }
+  /**
+   * Verifies if the password is correct for the keystore.
+   */
+  static async verifyKeystorePassword(keystore, password) {
+    const result = await this.decryptEncryptedKeystore(keystore, password);
+    return result.success;
+  }
+  /**
+   * Changes the password of an encrypted keystore.
+   */
+  static async changeKeystorePassword(keystore, oldPassword, newPassword) {
+    const unlock = await this.decryptEncryptedKeystore(keystore, oldPassword);
+    if (!unlock.success || !unlock.payload) {
+      throw new Error("Invalid current password.");
+    }
+    return this.createEncryptedKeystore(unlock.payload, newPassword, {
+      label: keystore.metadata.label,
+      network: keystore.metadata.network,
+      iterations: keystore.kdf.iterations,
+      memory: keystore.kdf.memory,
+      parallelism: keystore.kdf.parallelism
+    });
+  }
+  /**
+   * Loads an encrypted keystore from the filesystem.
+   */
+  static async loadEncryptedKeystore(filePath) {
+    try {
+      const data = await fs3.promises.readFile(filePath, "utf-8");
+      const keystore = JSON.parse(data);
+      if (keystore.type !== this.KEYSTORE_FORMAT_TYPE) {
+        throw new Error(`Invalid keystore type: ${keystore.type}`);
+      }
+      return keystore;
+    } catch (e) {
+      throw new Error(`Failed to load keystore at ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  /**
+   * Saves an encrypted keystore to the filesystem.
+   */
+  static async saveEncryptedKeystore(filePath, keystore) {
+    try {
+      const dir = path3.dirname(filePath);
+      if (!fs3.existsSync(dir)) {
+        await fs3.promises.mkdir(dir, { recursive: true });
+      }
+      await fs3.promises.writeFile(filePath, JSON.stringify(keystore, null, 2), "utf-8");
+    } catch (e) {
+      throw new Error(`Failed to save keystore at ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+};
+export {
+  KaspaSdkKeyGenerator,
+  KaspaSdkRealTxSigner,
+  KaspaWasmPrivateKeySigner,
+  KeystoreManager,
+  SimulatedSigner,
+  SimulatedTxPlanSigner,
+  UnsupportedKaspaKeyGenerator,
+  UnsupportedRealKaspaSigner,
+  UnsupportedRealTxSigner,
+  assertSigningNetworkAllowed,
+  createEmptyRealAccountStore,
+  describeAccount,
+  getDefaultRealAccountsPath,
+  getKaspaSigningBackendStatus,
+  getRealDevAccount,
+  getRequiredEnv,
+  importRealDevAccount,
+  listHardkasAccounts,
+  listRealDevAccounts,
+  loadKaspaWasm,
+  loadOrCreateRealAccountStore,
+  loadRealAccountStore,
+  loadRealAccountStoreSync,
+  redactSecret,
+  removeRealDevAccount,
+  resolveHardkasAccount,
+  resolveHardkasAccountAddress,
+  resolveRealAccountOrAddress,
+  saveRealAccountStore,
+  signTxPlanArtifact,
+  validateAccountName,
+  validateAddressPrefix
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hardkas/accounts",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "hash-wasm": "^4.12.0",
+    "@hardkas/config": "0.1.0",
+    "@hardkas/localnet": "0.1.0",
+    "@hardkas/artifacts": "0.1.0",
+    "@hardkas/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "author": "Javier Rodriguez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jrodrg92/Hardkas.git",
+    "directory": "packages/accounts"
+  },
+  "bugs": {
+    "url": "https://github.com/jrodrg92/Hardkas/issues"
+  },
+  "homepage": "https://github.com/jrodrg92/Hardkas/tree/main/packages/accounts#readme",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external kaspa",
+    "dev": "tsup src/index.ts --format esm --watch --dts --external kaspa",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}