near-kit 0.0.0 → 0.2.0

package/dist/utils/key.js

@@ -0,0 +1,270 @@
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { base58, base64 } from "@scure/base";
+import { HDKey } from "@scure/bip32";
+import * as bip39 from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { ED25519_KEY_PREFIX, SECP256K1_KEY_PREFIX } from "../core/constants.js";
+import { KeyType, } from "../core/types.js";
+import { InvalidKeyError } from "../errors/index.js";
+import { serializeNep413Message } from "./nep413.js";
+/**
+ * Ed25519 key pair implementation.
+ *
+ * @remarks
+ * Implements the {@link KeyPair} interface used throughout the library and
+ * provides NEP-413 message signing via {@link Ed25519KeyPair.signNep413Message}.
+ */
+export class Ed25519KeyPair {
+    constructor(secretKey) {
+        // secretKey is 64 bytes: [32 bytes private key][32 bytes public key]
+        this.privateKey = secretKey.slice(0, 32);
+        const publicKeyData = secretKey.slice(32);
+        this.publicKey = {
+            keyType: KeyType.ED25519,
+            data: publicKeyData,
+            toString: () => ED25519_KEY_PREFIX + base58.encode(publicKeyData),
+        };
+        this.secretKey = ED25519_KEY_PREFIX + base58.encode(secretKey);
+    }
+    sign(message) {
+        const signature = ed25519.sign(message, this.privateKey);
+        return {
+            keyType: KeyType.ED25519,
+            data: signature,
+        };
+    }
+    /**
+     * Sign a message according to NEP-413 specification
+     *
+     * NEP-413 enables off-chain message signing for authentication and ownership verification.
+     * The message is signed with a full-access key but does not require gas or blockchain state.
+     *
+     * @param accountId - The NEAR account ID that owns this key
+     * @param params - Message signing parameters (message, recipient, nonce)
+     * @returns Signed message with account ID, public key, and base64-encoded signature
+     *
+     * @see https://github.com/near/NEPs/blob/master/neps/nep-0413.md
+     *
+     * @example
+     * ```typescript
+     * const nonce = crypto.getRandomValues(new Uint8Array(32))
+     * const signedMessage = keyPair.signNep413Message("alice.near", {
+     *   message: "Login to MyApp",
+     *   recipient: "myapp.near",
+     *   nonce,
+     * })
+     * console.log(signedMessage.signature) // Base64-encoded signature
+     * ```
+     */
+    signNep413Message(accountId, params) {
+        // Serialize and hash the message according to NEP-413
+        const hash = serializeNep413Message(params);
+        // Sign the hash
+        const signature = ed25519.sign(hash, this.privateKey);
+        // Return signed message with base64-encoded signature
+        return {
+            accountId,
+            publicKey: this.publicKey.toString(),
+            signature: base64.encode(signature),
+        };
+    }
+    static fromRandom() {
+        const privateKey = ed25519.utils.randomSecretKey();
+        const publicKey = ed25519.getPublicKey(privateKey);
+        // Combine into 64-byte format for compatibility
+        const secretKey = new Uint8Array(64);
+        secretKey.set(privateKey, 0);
+        secretKey.set(publicKey, 32);
+        return new Ed25519KeyPair(secretKey);
+    }
+    static fromString(keyString) {
+        const key = keyString.replace(ED25519_KEY_PREFIX, "");
+        const decoded = base58.decode(key);
+        return new Ed25519KeyPair(decoded);
+    }
+}
+/**
+ * Secp256k1 key pair implementation.
+ *
+ * NEAR expects secp256k1 public keys to be 64 bytes (uncompressed without 0x04 header).
+ * The secp256k1 library returns 65-byte uncompressed keys (with 0x04 header), so we
+ * manually remove/add that byte as needed.
+ *
+ * Signatures are 65 bytes: 64-byte signature + 1-byte recovery ID.
+ */
+export class Secp256k1KeyPair {
+    constructor(secretKey) {
+        // secretKey is 96 bytes: [32 bytes private key][64 bytes public key]
+        this.privateKey = secretKey.slice(0, 32);
+        const publicKeyData = secretKey.slice(32); // 64 bytes without 0x04 header
+        this.publicKey = {
+            keyType: KeyType.SECP256K1,
+            data: publicKeyData,
+            toString: () => SECP256K1_KEY_PREFIX + base58.encode(publicKeyData),
+        };
+        this.secretKey = SECP256K1_KEY_PREFIX + base58.encode(secretKey);
+    }
+    sign(message) {
+        // Sign with format: 'recovered' to get 65 bytes (recovery ID + signature)
+        // This is what NEAR expects: [recovery][r][s]
+        const signatureBytes = secp256k1.sign(message, this.privateKey, {
+            format: "recovered",
+        });
+        return {
+            keyType: KeyType.SECP256K1,
+            data: signatureBytes, // 65 bytes
+        };
+    }
+    /**
+     * Sign a message according to NEP-413 specification
+     *
+     * NEP-413 enables off-chain message signing for authentication and ownership verification.
+     * The message is signed with a full-access key but does not require gas or blockchain state.
+     *
+     * @param accountId - The NEAR account ID that owns this key
+     * @param params - Message signing parameters (message, recipient, nonce)
+     * @returns Signed message with account ID, public key, and base64-encoded signature
+     *
+     * @see https://github.com/near/NEPs/blob/master/neps/nep-0413.md
+     *
+     * @example
+     * ```typescript
+     * const nonce = crypto.getRandomValues(new Uint8Array(32))
+     * const signedMessage = keyPair.signNep413Message("alice.near", {
+     *   message: "Login to MyApp",
+     *   recipient: "myapp.near",
+     *   nonce,
+     * })
+     * console.log(signedMessage.signature) // Base64-encoded signature
+     * ```
+     */
+    signNep413Message(accountId, params) {
+        // Serialize and hash the message according to NEP-413
+        const hash = serializeNep413Message(params);
+        // Sign the hash with format: 'recovered' for secp256k1
+        const signature = secp256k1.sign(hash, this.privateKey, {
+            format: "recovered",
+        });
+        // Return signed message with base64-encoded signature
+        return {
+            accountId,
+            publicKey: this.publicKey.toString(),
+            signature: base64.encode(signature),
+        };
+    }
+    static fromRandom() {
+        // Generate random 32-byte private key
+        const privateKey = new Uint8Array(32);
+        crypto.getRandomValues(privateKey);
+        // Get uncompressed public key (65 bytes with 0x04 header)
+        const publicKeyFull = secp256k1.getPublicKey(privateKey, false);
+        // Remove 0x04 header to get 64 bytes for NEAR
+        const publicKey = publicKeyFull.slice(1);
+        // Combine into 96-byte format: 32 bytes private + 64 bytes public
+        const secretKey = new Uint8Array(96);
+        secretKey.set(privateKey, 0);
+        secretKey.set(publicKey, 32);
+        return new Secp256k1KeyPair(secretKey);
+    }
+    static fromString(keyString) {
+        const key = keyString.replace(SECP256K1_KEY_PREFIX, "");
+        const decoded = base58.decode(key);
+        return new Secp256k1KeyPair(decoded);
+    }
+}
+/**
+ * Generate a new random Ed25519 key pair.
+ * @returns A new {@link KeyPair} instance.
+ */
+export function generateKey() {
+    return Ed25519KeyPair.fromRandom();
+}
+/**
+ * Parse a key string to a {@link KeyPair}.
+ *
+ * @param keyString - Key string (e.g. `"ed25519:..."` or `"secp256k1:..."`).
+ * @returns A concrete {@link Ed25519KeyPair} or {@link Secp256k1KeyPair}.
+ */
+export function parseKey(keyString) {
+    if (keyString.startsWith(ED25519_KEY_PREFIX)) {
+        return Ed25519KeyPair.fromString(keyString);
+    }
+    if (keyString.startsWith(SECP256K1_KEY_PREFIX)) {
+        return Secp256k1KeyPair.fromString(keyString);
+    }
+    throw new InvalidKeyError(`Unsupported key type: ${keyString}`);
+}
+/**
+ * Parse a public key string to a {@link PublicKey} object.
+ *
+ * @param publicKeyString - Public key string (e.g. `"ed25519:..."` or `"secp256k1:..."`).
+ * @returns {@link PublicKey} instance.
+ */
+export function parsePublicKey(publicKeyString) {
+    if (publicKeyString.startsWith(ED25519_KEY_PREFIX)) {
+        const key = publicKeyString.replace(ED25519_KEY_PREFIX, "");
+        const decoded = base58.decode(key);
+        return {
+            keyType: KeyType.ED25519,
+            data: decoded,
+            toString: () => publicKeyString,
+        };
+    }
+    if (publicKeyString.startsWith(SECP256K1_KEY_PREFIX)) {
+        const key = publicKeyString.replace(SECP256K1_KEY_PREFIX, "");
+        const decoded = base58.decode(key);
+        return {
+            keyType: KeyType.SECP256K1,
+            data: decoded,
+            toString: () => publicKeyString,
+        };
+    }
+    throw new InvalidKeyError(`Unsupported public key type: ${publicKeyString}`);
+}
+/**
+ * Generate a BIP39 seed phrase (12 words by default)
+ * Uses proper BIP39 implementation with cryptographically secure randomness
+ * @param wordCount - Number of words (12, 15, 18, 21, or 24). Defaults to 12
+ * @returns A BIP39 seed phrase string
+ */
+export function generateSeedPhrase(wordCount = 12) {
+    // Map word count to entropy bits (as per BIP39 spec)
+    const entropyBits = wordCount * 11 - wordCount / 3;
+    const entropyBytes = entropyBits / 8;
+    // Generate cryptographically secure random entropy
+    const entropy = new Uint8Array(entropyBytes);
+    crypto.getRandomValues(entropy);
+    // Generate mnemonic from entropy
+    return bip39.entropyToMnemonic(entropy, wordlist);
+}
+/**
+ * Parse a BIP39 seed phrase to derive a key pair using proper BIP32/SLIP10 derivation
+ * @param phrase - BIP39 seed phrase (12-24 words)
+ * @param path - BIP32 derivation path (defaults to "m/44'/397'/0'" for NEAR)
+ * @returns KeyPair instance
+ */
+export function parseSeedPhrase(phrase, path = "m/44'/397'/0'") {
+    // Validate the mnemonic
+    if (!bip39.validateMnemonic(phrase, wordlist)) {
+        throw new InvalidKeyError("Invalid BIP39 seed phrase");
+    }
+    // Convert mnemonic to seed (64 bytes)
+    const seed = bip39.mnemonicToSeedSync(phrase);
+    // Derive HD key using BIP32 with ed25519 (SLIP10)
+    // Note: HDKey from @scure/bip32 supports ed25519 via SLIP10
+    const hdkey = HDKey.fromMasterSeed(seed);
+    const derived = hdkey.derive(path);
+    if (!derived.privateKey) {
+        throw new InvalidKeyError("Failed to derive private key from seed phrase");
+    }
+    // Get the ed25519 public key from private key
+    const privateKey = derived.privateKey;
+    const publicKey = ed25519.getPublicKey(privateKey);
+    // Combine into 64-byte format for compatibility
+    const secretKey = new Uint8Array(64);
+    secretKey.set(privateKey, 0);
+    secretKey.set(publicKey, 32);
+    return new Ed25519KeyPair(secretKey);
+}
+//# sourceMappingURL=key.js.map

package/dist/utils/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../src/utils/key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACpC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EAEL,OAAO,GAKR,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAKzB,YAAY,SAAqB;QAC/B,qEAAqE;QACrE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QACxC,MAAM,aAAa,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAEzC,IAAI,CAAC,SAAS,GAAG;YACf,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,GAAG,EAAE,CAAC,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;SAClE,CAAA;QAED,IAAI,CAAC,SAAS,GAAG,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IAChE,CAAC;IAED,IAAI,CAAC,OAAmB;QACtB,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;QACxD,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,SAAS;SAChB,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,CACf,SAAiB,EACjB,MAAyB;QAEzB,sDAAsD;QACtD,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAA;QAE3C,gBAAgB;QAChB,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;QAErD,sDAAsD;QACtD,OAAO;YACL,SAAS;YACT,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE;YACpC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;SACpC,CAAA;IACH,CAAC;IAED,MAAM,CAAC,UAAU;QACf,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAA;QAClD,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAA;QAElD,gDAAgD;QAChD,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;QACpC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAA;QAC5B,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;QAE5B,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAA;IACtC,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,SAAiB;QACjC,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAA;QACrD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAClC,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,CAAA;IACpC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IAK3B,YAAY,SAAqB;QAC/B,qEAAqE;QACrE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QACxC,MAAM,aAAa,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA,CAAC,+BAA+B;QAEzE,IAAI,CAAC,SAAS,GAAG;YACf,OAAO,EAAE,OAAO,CAAC,SAAS;YAC1B,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,GAAG,EAAE,CAAC,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;SACpE,CAAA;QAED,IAAI,CAAC,SAAS,GAAG,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IAClE,CAAC;IAED,IAAI,CAAC,OAAmB;QACtB,0EAA0E;QAC1E,8CAA8C;QAC9C,MAAM,cAAc,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE;YAC9D,MAAM,EAAE,WAAW;SACpB,CAAC,CAAA;QAEF,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,SAAS;YAC1B,IAAI,EAAE,cAAc,EAAE,WAAW;SAClC,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,CACf,SAAiB,EACjB,MAAyB;QAEzB,sDAAsD;QACtD,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAA;QAE3C,uDAAuD;QACvD,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE;YACtD,MAAM,EAAE,WAAW;SACpB,CAAC,CAAA;QAEF,sDAAsD;QACtD,OAAO;YACL,SAAS;YACT,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE;YACpC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;SACpC,CAAA;IACH,CAAC;IAED,MAAM,CAAC,UAAU;QACf,sCAAsC;QACtC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;QACrC,MAAM,CAAC,eAAe,CAAC,UAAU,CAAC,CAAA;QAElC,0DAA0D;QAC1D,MAAM,aAAa,GAAG,SAAS,CAAC,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;QAE/D,8CAA8C;QAC9C,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAExC,kEAAkE;QAClE,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;QACpC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAA;QAC5B,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;QAE5B,OAAO,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAA;IACxC,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,SAAiB;QACjC,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAA;QACvD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAClC,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACtC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,cAAc,CAAC,UAAU,EAAE,CAAA;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,SAAiB;IACxC,IAAI,SAAS,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC7C,OAAO,cAAc,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC7C,CAAC;IAED,IAAI,SAAS,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC/C,OAAO,gBAAgB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC/C,CAAC;IAED,MAAM,IAAI,eAAe,CAAC,yBAAyB,SAAS,EAAE,CAAC,CAAA;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,eAAuB;IACpD,IAAI,eAAe,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACnD,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAA;QAC3D,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAClC,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,GAAG,EAAE,CAAC,eAAe;SAChC,CAAA;IACH,CAAC;IAED,IAAI,eAAe,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACrD,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAA;QAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAClC,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,SAAS;YAC1B,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,GAAG,EAAE,CAAC,eAAe;SAChC,CAAA;IACH,CAAC;IAED,MAAM,IAAI,eAAe,CAAC,gCAAgC,eAAe,EAAE,CAAC,CAAA;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAAoC,EAAE;IAEtC,qDAAqD;IACrD,MAAM,WAAW,GAAG,SAAS,GAAG,EAAE,GAAG,SAAS,GAAG,CAAC,CAAA;IAClD,MAAM,YAAY,GAAG,WAAW,GAAG,CAAC,CAAA;IAEpC,mDAAmD;IACnD,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAA;IAC5C,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAA;IAE/B,iCAAiC;IACjC,OAAO,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,OAAe,eAAe;IAE9B,wBAAwB;IACxB,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,eAAe,CAAC,2BAA2B,CAAC,CAAA;IACxD,CAAC;IAED,sCAAsC;IACtC,MAAM,IAAI,GAAG,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;IAE7C,kDAAkD;IAClD,4DAA4D;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAElC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,eAAe,CAAC,+CAA+C,CAAC,CAAA;IAC5E,CAAC;IAED,8CAA8C;IAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAA;IACrC,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAA;IAElD,gDAAgD;IAChD,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IACpC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAA;IAC5B,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;IAE5B,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAA;AACtC,CAAC"}

package/dist/utils/nep413.d.ts

@@ -0,0 +1,97 @@
+/**
+ * NEP-413: Message signing utilities
+ *
+ * NEP-413 enables off-chain message signing for authentication and ownership verification
+ * without gas fees or blockchain transactions.
+ *
+ * @see https://github.com/near/NEPs/blob/master/neps/nep-0413.md
+ */
+import type { SignedMessage, SignMessageParams } from "../core/types.js";
+/**
+ * NEP-413 tag prefix: 2^31 + 413 = 2147484061
+ *
+ * This prefix ensures that signed messages cannot be confused with valid transactions.
+ * The tag makes the message too long to be a valid signer account ID.
+ */
+export declare const NEP413_TAG = 2147484061;
+/**
+ * NEP-413 message payload schema
+ *
+ * Fields are serialized in this order:
+ * 1. message: string - The message to sign
+ * 2. nonce: [u8; 32] - 32-byte nonce for replay protection
+ * 3. recipient: string - Recipient identifier (e.g., "alice.near" or "myapp.com")
+ * 4. callbackUrl: Option<string> - Optional callback URL for web wallets
+ */
+export declare const Nep413PayloadSchema: import("@zorsh/zorsh").Schema<{
+    message: string;
+    nonce: number[];
+    recipient: string;
+    callbackUrl: string | null;
+}, string>;
+/**
+ * Serialize NEP-413 message parameters for signing
+ *
+ * Serialization steps:
+ * 1. Serialize the tag (2147484061) as u32
+ * 2. Serialize the payload (message, nonce, recipient, callbackUrl)
+ * 3. Concatenate: tag_bytes + payload_bytes
+ * 4. Hash with SHA256
+ *
+ * @param params - Message signing parameters
+ * @returns Serialized and hashed message ready for signing
+ *
+ * @example
+ * ```typescript
+ * const nonce = crypto.getRandomValues(new Uint8Array(32))
+ * const hash = serializeNep413Message({
+ *   message: "Login to MyApp",
+ *   recipient: "myapp.near",
+ *   nonce,
+ * })
+ * const signature = keyPair.sign(hash)
+ * ```
+ */
+export declare function serializeNep413Message(params: SignMessageParams): Uint8Array;
+/**
+ * Verify a NEP-413 signed message
+ *
+ * Verification steps:
+ * 1. Reconstruct the payload from parameters
+ * 2. Serialize and hash (tag + payload)
+ * 3. Verify the signature against the hash using the public key
+ *
+ * @param signedMessage - The signed message to verify
+ * @param params - Original message parameters (must match what was signed)
+ * @returns true if signature is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = verifyNep413Signature(signedMessage, {
+ *   message: "Login to MyApp",
+ *   recipient: "myapp.near",
+ *   nonce,
+ * })
+ * if (isValid) {
+ *   console.log("Signature verified!")
+ * }
+ * ```
+ */
+export declare function verifyNep413Signature(signedMessage: SignedMessage, params: SignMessageParams): boolean;
+/**
+ * Generate a random nonce for NEP-413 message signing
+ *
+ * @returns 32-byte random nonce
+ *
+ * @example
+ * ```typescript
+ * const nonce = generateNep413Nonce()
+ * const signedMessage = await near.signMessage({
+ *   message: "Login to MyApp",
+ *   recipient: "myapp.near",
+ *   nonce,
+ * })
+ * ```
+ */
+export declare function generateNep413Nonce(): Uint8Array;
+//# sourceMappingURL=nep413.d.ts.map

package/dist/utils/nep413.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nep413.d.ts","sourceRoot":"","sources":["../../src/utils/nep413.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGxE;;;;;GAKG;AACH,eAAO,MAAM,UAAU,aAAa,CAAA;AAEpC;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;;;;UAK9B,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,UAAU,CAuB5E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAiCT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CAEhD"}

package/dist/utils/nep413.js

@@ -0,0 +1,154 @@
+/**
+ * NEP-413: Message signing utilities
+ *
+ * NEP-413 enables off-chain message signing for authentication and ownership verification
+ * without gas fees or blockchain transactions.
+ *
+ * @see https://github.com/near/NEPs/blob/master/neps/nep-0413.md
+ */
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { base58, base64 } from "@scure/base";
+import { b } from "@zorsh/zorsh";
+import { parsePublicKey } from "./key.js";
+/**
+ * NEP-413 tag prefix: 2^31 + 413 = 2147484061
+ *
+ * This prefix ensures that signed messages cannot be confused with valid transactions.
+ * The tag makes the message too long to be a valid signer account ID.
+ */
+export const NEP413_TAG = 2147484061;
+/**
+ * NEP-413 message payload schema
+ *
+ * Fields are serialized in this order:
+ * 1. message: string - The message to sign
+ * 2. nonce: [u8; 32] - 32-byte nonce for replay protection
+ * 3. recipient: string - Recipient identifier (e.g., "alice.near" or "myapp.com")
+ * 4. callbackUrl: Option<string> - Optional callback URL for web wallets
+ */
+export const Nep413PayloadSchema = b.struct({
+    message: b.string(),
+    nonce: b.array(b.u8(), 32),
+    recipient: b.string(),
+    callbackUrl: b.option(b.string()),
+});
+/**
+ * Serialize NEP-413 message parameters for signing
+ *
+ * Serialization steps:
+ * 1. Serialize the tag (2147484061) as u32
+ * 2. Serialize the payload (message, nonce, recipient, callbackUrl)
+ * 3. Concatenate: tag_bytes + payload_bytes
+ * 4. Hash with SHA256
+ *
+ * @param params - Message signing parameters
+ * @returns Serialized and hashed message ready for signing
+ *
+ * @example
+ * ```typescript
+ * const nonce = crypto.getRandomValues(new Uint8Array(32))
+ * const hash = serializeNep413Message({
+ *   message: "Login to MyApp",
+ *   recipient: "myapp.near",
+ *   nonce,
+ * })
+ * const signature = keyPair.sign(hash)
+ * ```
+ */
+export function serializeNep413Message(params) {
+    if (params.nonce.length !== 32) {
+        throw new Error("Nonce must be exactly 32 bytes");
+    }
+    // Serialize tag as u32
+    const tagBytes = b.u32().serialize(NEP413_TAG);
+    // Serialize payload
+    const payloadBytes = Nep413PayloadSchema.serialize({
+        message: params.message,
+        nonce: Array.from(params.nonce),
+        recipient: params.recipient,
+        callbackUrl: null, // Optional, not typically used in direct signing
+    });
+    // Concatenate tag + payload
+    const combined = new Uint8Array(tagBytes.length + payloadBytes.length);
+    combined.set(tagBytes, 0);
+    combined.set(payloadBytes, tagBytes.length);
+    // Hash the combined bytes
+    return sha256(combined);
+}
+/**
+ * Verify a NEP-413 signed message
+ *
+ * Verification steps:
+ * 1. Reconstruct the payload from parameters
+ * 2. Serialize and hash (tag + payload)
+ * 3. Verify the signature against the hash using the public key
+ *
+ * @param signedMessage - The signed message to verify
+ * @param params - Original message parameters (must match what was signed)
+ * @returns true if signature is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = verifyNep413Signature(signedMessage, {
+ *   message: "Login to MyApp",
+ *   recipient: "myapp.near",
+ *   nonce,
+ * })
+ * if (isValid) {
+ *   console.log("Signature verified!")
+ * }
+ * ```
+ */
+export function verifyNep413Signature(signedMessage, params) {
+    try {
+        // Parse the public key
+        const publicKey = parsePublicKey(signedMessage.publicKey);
+        // Only Ed25519 is currently supported
+        if (publicKey.keyType !== 0) {
+            throw new Error("Only Ed25519 keys are supported for NEP-413");
+        }
+        // Reconstruct the hashed payload
+        const hash = serializeNep413Message(params);
+        // Decode the signature
+        // Try base64 first (most common), fallback to base58
+        let signatureBytes;
+        try {
+            signatureBytes = base64.decode(signedMessage.signature);
+        }
+        catch {
+            try {
+                // Remove ed25519: prefix if present
+                const sig = signedMessage.signature.replace("ed25519:", "");
+                signatureBytes = base58.decode(sig);
+            }
+            catch {
+                return false;
+            }
+        }
+        // Verify the signature
+        return ed25519.verify(signatureBytes, hash, publicKey.data);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate a random nonce for NEP-413 message signing
+ *
+ * @returns 32-byte random nonce
+ *
+ * @example
+ * ```typescript
+ * const nonce = generateNep413Nonce()
+ * const signedMessage = await near.signMessage({
+ *   message: "Login to MyApp",
+ *   recipient: "myapp.near",
+ *   nonce,
+ * })
+ * ```
+ */
+export function generateNep413Nonce() {
+    return crypto.getRandomValues(new Uint8Array(32));
+}
+//# sourceMappingURL=nep413.js.map

package/dist/utils/nep413.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nep413.js","sourceRoot":"","sources":["../../src/utils/nep413.ts"],"names":[],"mappings":"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"}

package/dist/utils/validation.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Zod validation schemas and helpers for NEAR types.
+ *
+ * @remarks
+ * These schemas power runtime validation for account IDs, public/private keys,
+ * amounts, and gas while keeping the developer-facing API ergonomic via
+ * helpers like {@link validateAccountId} and {@link normalizeAmount}.
+ */
+import { z } from "zod";
+/**
+ * Schema for validating NEAR account IDs.
+ *
+ * Rules:
+ * - Length: 2-64 characters
+ * - Characters: lowercase alphanumeric, hyphens, underscores, and dots
+ * - Pattern: subdomain-like structure (e.g., alice.near, contract.mainnet)
+ */
+export declare const AccountIdSchema: z.ZodString;
+export type AccountId = z.infer<typeof AccountIdSchema>;
+/**
+ * Schema for validating NEAR public keys.
+ *
+ * Supports:
+ * - Ed25519: "ed25519:..." (base58 encoded)
+ * - Secp256k1: "secp256k1:..." (base58 encoded)
+ */
+export declare const PublicKeySchema: z.ZodString;
+export type PublicKeyString = z.infer<typeof PublicKeySchema>;
+/**
+ * Type-safe private key string using template literal types.
+ *
+ * Provides compile-time type safety for private keys.
+ * Supports both ed25519 and secp256k1 keys.
+ *
+ * @example
+ * ```typescript
+ * const key: PrivateKey = 'ed25519:...'     // ✅ Valid
+ * const key: PrivateKey = 'secp256k1:...'   // ✅ Valid
+ * const key: PrivateKey = 'alice.near'      // ❌ Type error at compile time
+ *
+ * // Function signature ensures type safety
+ * function signWith(key: PrivateKey) { ... }
+ * signWith('ed25519:abc')      // ✅ Valid
+ * signWith('secp256k1:abc')    // ✅ Valid
+ * signWith('alice.near')       // ❌ Type error
+ * ```
+ */
+export type PrivateKey = `ed25519:${string}` | `secp256k1:${string}`;
+/**
+ * Schema for validating NEAR private keys.
+ *
+ * Supports:
+ * - Ed25519: "ed25519:..." (base58 encoded, 64 bytes)
+ * - Secp256k1: "secp256k1:..." (base58 encoded, 96 bytes)
+ */
+export declare const PrivateKeySchema: z.ZodString;
+export type PrivateKeyString = z.infer<typeof PrivateKeySchema>;
+/**
+ * Schema for NEAR amounts with explicit units.
+ *
+ * Accepts:
+ * - String with unit: "10 NEAR", "1000000 yocto"
+ * - Created via Amount.NEAR(10) or Amount.yocto(1000000n)
+ * - Raw bigint: 1000000n (treated as yoctoNEAR)
+ *
+ * Rejects bare numbers to prevent unit confusion.
+ * Normalizes to yoctoNEAR string.
+ */
+export declare const AmountSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodBigInt]>, z.ZodTransform<string, string | bigint>>;
+export type Amount = z.input<typeof AmountSchema>;
+/**
+ * Schema for gas amounts.
+ *
+ * Accepts:
+ * - String with unit: "30 Tgas", Gas.Tgas(30)
+ * - Raw gas number strings for advanced use
+ *
+ * Normalizes to raw gas string.
+ */
+export declare const GasSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export type Gas = z.input<typeof GasSchema>;
+/**
+ * Validate account ID (throws on invalid).
+ */
+export declare function validateAccountId(accountId: string): string;
+/**
+ * Check if account ID is valid (boolean).
+ */
+export declare function isValidAccountId(accountId: string): boolean;
+/**
+ * Validate public key (throws on invalid).
+ */
+export declare function validatePublicKey(key: string): string;
+/**
+ * Check if public key is valid (boolean).
+ */
+export declare function isValidPublicKey(key: string): boolean;
+/**
+ * Validate private key (throws on invalid).
+ */
+export declare function validatePrivateKey(key: string): string;
+/**
+ * Check if private key is valid (boolean).
+ */
+export declare function isPrivateKey(key: string): boolean;
+/**
+ * Normalize amount to yoctoNEAR string.
+ */
+export declare function normalizeAmount(amount: Amount): string;
+/**
+ * Normalize gas to gas string.
+ */
+export declare function normalizeGas(gas: Gas): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAyBvB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,aAazB,CAAA;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAIvD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,aAaoB,CAAA;AAEhD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAI7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,MAAM,EAAE,GAAG,aAAa,MAAM,EAAE,CAAA;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,aAaoB,CAAA;AAEjD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAI/D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,qGAIrB,CAAA;AAEJ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAIjD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,wDAEpB,CAAA;AAEF,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAI3C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAE7C"}