feat: Add @aptos-labs/aptos-keystore — Encrypted Private Key Storage Package

[gregnazario]

Description

New standalone package @aptos-labs/aptos-keystore (keystore/) that provides encrypted private key storage for Aptos, based on Ethereum's Web3 Secret Storage Definition. Extracted into its own package to keep @aptos-labs/ts-sdk lean — zero impact on existing SDK users.

Install:

npm install @aptos-labs/aptos-keystore
# For Argon2id (recommended):
npm install hash-wasm

Key features:

• Supports all Aptos private key types: Ed25519, Secp256k1, Secp256r1
• AES-256-GCM authenticated encryption (confidentiality + integrity, no separate MAC)
• Argon2id KDF by default when hash-wasm is installed, falls back to scrypt
• PBKDF2-HMAC-SHA256 also available
• Password or key-file encryption (string or Uint8Array)
• Portable JSON format for cross-SDK interop (TypeScript, Rust, Python, Go)

Package structure:

• Peer-depends on @aptos-labs/ts-sdk ^6.2.0
• Optional peer dep on hash-wasm ^4.12.0 (for Argon2id)
• Direct dep on @noble/hashes (scrypt, pbkdf2, sha256)
• Own build (tsup), tests (vitest), lint (biome)

Usage:

import { Ed25519PrivateKey } from "@aptos-labs/ts-sdk";
import { encryptKeystore, decryptKeystore } from "@aptos-labs/aptos-keystore";

const privateKey = Ed25519PrivateKey.generate();
const keystore = await encryptKeystore({ privateKey, password: "my-password" });
const recovered = await decryptKeystore({ keystore, password: "my-password" });

Keystore JSON format:

{
  "version": 1,
  "id": "a7b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "key_type": "ed25519",
  "crypto": {
    "cipher": "aes-256-gcm",
    "cipherparams": { "iv": "...", "tag": "..." },
    "ciphertext": "...",
    "kdf": "argon2id",
    "kdfparams": { "iterations": 3, "parallelism": 4, "memorySize": 65536, "dklen": 32, "salt": "..." }
  }
}

Main SDK changes: Removed the previously-added keystore code from src/core/crypto/ and its hash-wasm peer dependency. No new exports or dependencies in @aptos-labs/ts-sdk.

Test Plan

25 unit tests in keystore/tests/keystore.test.ts:

• Default KDF selection (argon2id when hash-wasm present)
• All three KDFs × all three key types
• AES-256-GCM auth: wrong password, tampered ciphertext, tampered tag
• Key-file (Uint8Array) password support
• JSON round-trip serialization
• Signature verification after decrypt

cd keystore && pnpm install && pnpm test

Related Links

• Closes #3583
• Based on Ethereum Web3 Secret Storage Definition

Checklist

• Have you ran pnpm fmt?
• Have you updated the CHANGELOG.md?

  

[gregnazario]

Fix to 128mb, 1 parallelism, 2 iterations

[Copilot]

Pull request overview

Adds an Aptos keystore (encrypted private key JSON) feature to the TypeScript SDK, enabling password/key-file based encryption and decryption of Ed25519/Secp256k1/Secp256r1 private keys with modern KDF + AES-GCM.

Changes:

• Introduces encryptKeystore / decryptKeystore APIs and keystore-related types (AES-256-GCM + argon2id/scrypt/pbkdf2).
• Exposes the new keystore module via the core crypto barrel export.
• Adds unit tests and updates metadata/docs (optional hash-wasm peer dep, changelog, lockfile).

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/core/crypto/keystore.ts	New keystore format/types plus encrypt/decrypt implementation (KDF selection, AES-GCM).
src/core/crypto/index.ts	Re-exports the new keystore module from the crypto barrel.
tests/unit/keystore.test.ts	Adds unit tests for keystore encryption/decryption across key types and KDFs.
package.json	Declares hash-wasm as an optional peer dependency for argon2id support.
pnpm-lock.yaml	Adds lock entries for hash-wasm.
CHANGELOG.md	Notes the new keystore feature in Unreleased.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

tryLoadArgon2id() swallows all dynamic import errors and returns null, which can mask real runtime failures (e.g., WASM initialization errors) and later produce a misleading "Install hash-wasm" error from loadArgon2id(). Consider only treating module-not-found as "not available" and rethrowing (or attaching) other errors so callers can diagnose environment issues accurately.

Suggested change

	} catch {
	return null;
	} catch (error) {
	// Only treat "module not found" as optional; rethrow other errors so they are not masked.
	const err = error as unknown;
	if (err && typeof err === "object") {
	const anyErr = err as { code?: unknown; message?: unknown };
	const code = typeof anyErr.code === "string" ? anyErr.code : undefined;
	const message = typeof anyErr.message === "string" ? anyErr.message : undefined;
	// Node-style dynamic import missing-module error.
	if (code === "ERR_MODULE_NOT_FOUND") {
	return null;
	}
	// Fallback: message-based detection for environments that don't set `code`.
	if (message && /Cannot find (module|package) 'hash-wasm'/.test(message)) {
	return null;
	}
	}
	// For any other error, rethrow so callers can diagnose the real issue.
	throw error;

[Copilot]

deriveKey() trusts kdfparams.dklen from the keystore JSON. Because WebCrypto accepts 16/24/32-byte AES keys, a keystore claiming cipher: "aes-256-gcm" could be decrypted with a shorter derived key if dklen is tampered. Validate that kdfparams.dklen equals 32 (and optionally enforce expected salt length) before deriving/importing the AES key.

[Copilot]

For kdf: "pbkdf2", the keystore includes a prf field but deriveKey() ignores it. Please validate prf === "hmac-sha256" and throw an "unsupported PRF" error otherwise; without this, unsupported keystores fail as a generic "Invalid password" (or could be misinterpreted in other tooling).

[Copilot]

key_type (and id/address) are not authenticated: an attacker can modify keystore.key_type without affecting AES-GCM authentication, causing decryptKeystore() to return a different key class for the same decrypted bytes. Consider binding critical metadata via AES-GCM additionalData (AAD) or including the key type inside the encrypted payload and verifying it after decryption.

Suggested change

	return createPrivateKey(plaintext, keystore.key_type);
	// Validate that the decrypted key bytes are consistent with the claimed key_type.
	// This prevents an attacker from tampering with `keystore.key_type` without
	// invalidating the AES-GCM authentication tag.
	const claimedType = keystore.key_type as PrivateKeyVariants["type"];
	// Helper to try constructing a key of a given type; returns undefined on failure.
	const tryCreateKey = (type: PrivateKeyVariants["type"]): KeystorePrivateKey | undefined => {
	try {
	switch (type) {
	case "ed25519":
	return new Ed25519PrivateKey(plaintext);
	case "secp256k1":
	return new Secp256k1PrivateKey(plaintext);
	case "secp256r1":
	return new Secp256r1PrivateKey(plaintext);
	default:
	return undefined;
	}
	} catch {
	return undefined;
	}
	};
	const claimedKey = tryCreateKey(claimedType);
	if (!claimedKey) {
	throw new Error("Keystore integrity error: decrypted key bytes are incompatible with key_type");
	}
	return claimedKey;

[Copilot]

This test assumes hash-wasm is installed in the test environment; if it isn't, the default KDF will be scrypt and the assertion will fail. To keep unit tests deterministic across environments, either (a) explicitly set options.kdf: "argon2id" for this test and separately mock the default-selection behavior, or (b) conditionally skip when hash-wasm cannot be imported.