@anywalletkit/wallet-near 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -401,6 +401,13 @@ declare function actionKey(a: NearAction): NearActionKey;
 declare function isPlainObject(v: unknown): v is Record<string, unknown>;
 /** Function-call args as bytes: raw bytes pass through; plain objects / strings become UTF-8 JSON / UTF-8. Anything else throws. */
 declare function argsBytes(args: Uint8Array | Record<string, unknown> | string): Uint8Array;
+/**
+ * The borsh tag of an access-key permission (0 FunctionCall, 1 FullAccess), read from a permission of
+ * exactly one known variant: `{ fullAccess: {} }` or `{ functionCall: { receiverId, methodNames, allowance? } }`.
+ * Anything else throws, so an empty, misspelled, unknown or doubled variant is never encoded as
+ * FullAccess. The encoder, `assertWellFormed` and the description all read this one tag (scan 2026-10-30 F9).
+ */
+declare function accessKeyPermissionTag(permission: unknown): 0 | 1;
 declare function writeAction(w: BorshWriter, a: NearAction): void;
 declare function readAction(r: BorshReader): NearAction;
 /** Borsh bytes of an unsigned transaction. */
@@ -624,7 +631,8 @@ declare function parseSignature(signature: string): Uint8Array;
 /**
  * An object transaction has exactly the shape the encoder writes, before it is built or signed (also
  * `signBuilt`): every action one known key; a function call's `methodName` a string of the method
- * grammar, `args` bytes, a string or a plain object, `gas` / `deposit` bigints; every account id and
+ * grammar, `args` bytes, a string or a plain object, `gas` / `deposit` bigints; an AddKey permission
+ * exactly one known variant (scan 2026-10-30 F9); every account id and
  * method name well formed. What the policies read is then what gets encoded (scan 2026-10-27 F6, F28).
  */
 declare function assertWellFormed(tx: Pick<NearBuiltTransaction, 'receiverId' | 'actions'>): void;
@@ -648,8 +656,8 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     readonly needsNetwork = true;
     /** Derivation path, or `external` for an external signer. */
     readonly path: string;
-    /** The signer that holds the key. */
-    readonly signer: Signer;
+    /** What holds the key: `seed`, `key` (one imported key) or `external`. */
+    readonly signerKind: Signer['kind'];
     private _disposed;
     private _readOnly;
     constructor(signer: Signer, publicKey: Uint8Array, path: string, config?: NearConfig, accountId?: string);
@@ -719,4 +727,4 @@ declare class WalletManagerNear extends WalletManager<WalletAccountNear, NearCon
     getFeeRates(): Promise<FeeRates>;
 }
 
-export { ACTION_TAG, BorshReader, BorshWriter, BroadcastUnknownError, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, MessageIsTransactionError, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, type RawAccessKeyView, type RawAccountView, type RawFinalOutcome, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, actionKey, argsBytes, assertWellFormed, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isPlainObject, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };
+export { ACTION_TAG, BorshReader, BorshWriter, BroadcastUnknownError, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, MessageIsTransactionError, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, type RawAccessKeyView, type RawAccountView, type RawFinalOutcome, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, accessKeyPermissionTag, actionKey, argsBytes, assertWellFormed, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isPlainObject, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };

package/dist/index.d.ts

@@ -401,6 +401,13 @@ declare function actionKey(a: NearAction): NearActionKey;
 declare function isPlainObject(v: unknown): v is Record<string, unknown>;
 /** Function-call args as bytes: raw bytes pass through; plain objects / strings become UTF-8 JSON / UTF-8. Anything else throws. */
 declare function argsBytes(args: Uint8Array | Record<string, unknown> | string): Uint8Array;
+/**
+ * The borsh tag of an access-key permission (0 FunctionCall, 1 FullAccess), read from a permission of
+ * exactly one known variant: `{ fullAccess: {} }` or `{ functionCall: { receiverId, methodNames, allowance? } }`.
+ * Anything else throws, so an empty, misspelled, unknown or doubled variant is never encoded as
+ * FullAccess. The encoder, `assertWellFormed` and the description all read this one tag (scan 2026-10-30 F9).
+ */
+declare function accessKeyPermissionTag(permission: unknown): 0 | 1;
 declare function writeAction(w: BorshWriter, a: NearAction): void;
 declare function readAction(r: BorshReader): NearAction;
 /** Borsh bytes of an unsigned transaction. */
@@ -624,7 +631,8 @@ declare function parseSignature(signature: string): Uint8Array;
 /**
  * An object transaction has exactly the shape the encoder writes, before it is built or signed (also
  * `signBuilt`): every action one known key; a function call's `methodName` a string of the method
- * grammar, `args` bytes, a string or a plain object, `gas` / `deposit` bigints; every account id and
+ * grammar, `args` bytes, a string or a plain object, `gas` / `deposit` bigints; an AddKey permission
+ * exactly one known variant (scan 2026-10-30 F9); every account id and
  * method name well formed. What the policies read is then what gets encoded (scan 2026-10-27 F6, F28).
  */
 declare function assertWellFormed(tx: Pick<NearBuiltTransaction, 'receiverId' | 'actions'>): void;
@@ -648,8 +656,8 @@ declare class WalletAccountNear extends WalletAccountReadOnlyNear implements IWa
     readonly needsNetwork = true;
     /** Derivation path, or `external` for an external signer. */
     readonly path: string;
-    /** The signer that holds the key. */
-    readonly signer: Signer;
+    /** What holds the key: `seed`, `key` (one imported key) or `external`. */
+    readonly signerKind: Signer['kind'];
     private _disposed;
     private _readOnly;
     constructor(signer: Signer, publicKey: Uint8Array, path: string, config?: NearConfig, accountId?: string);
@@ -719,4 +727,4 @@ declare class WalletManagerNear extends WalletManager<WalletAccountNear, NearCon
     getFeeRates(): Promise<FeeRates>;
 }
 
-export { ACTION_TAG, BorshReader, BorshWriter, BroadcastUnknownError, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, MessageIsTransactionError, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, type RawAccessKeyView, type RawAccountView, type RawFinalOutcome, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, actionKey, argsBytes, assertWellFormed, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isPlainObject, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };
+export { ACTION_TAG, BorshReader, BorshWriter, BroadcastUnknownError, CAIP2, DANGEROUS_ACTIONS, type DescribeContext, FT_TRANSFER_GAS, IMPLICIT_ACCOUNT_MIN_DEPOSIT, MAX_GAS, MessageIsTransactionError, NEAR_BASE_PATH, NEP413_PREFIX, type NearAccessKey, type NearAccountView, type NearAction, type NearAddKeyAction, type NearBuiltTransaction, type NearConfig, type NearCreateAccountAction, type NearDelegateAction, type NearDeleteAccountAction, type NearDeleteKeyAction, type NearDeployContractAction, type NearDeployGlobalContractAction, type NearFeeEstimate, type NearFetch, type NearFunctionCallAction, type NearProvider, type NearPublicKey, type NearQuote, type NearReceipt, NearRpc, NearRpcError, type NearSignature, type NearSignedDelegateAction, type NearSignedTransaction, type NearSimulation, type NearStakeAction, type NearTransaction, type NearTransferAction, type NearTransferOptions, type NearTransferResult, type NearTxDescription, type NearTxKind, type NearTxWarning, type NearTxWarningCode, type NearUseGlobalContractAction, type Nep413Payload, type Nep413Signed, ONE_YOCTO, type RawAccessKeyView, type RawAccountView, type RawFinalOutcome, STORAGE_DEPOSIT_GAS, STORAGE_PRICE_PER_BYTE, SimulationError, TGAS, type UnsafeTransactionCode, UnsafeTransactionError, WalletAccountNear, WalletAccountReadOnlyNear, WalletManagerNear, YOCTO, accessKeyPermissionTag, actionKey, argsBytes, assertWellFormed, base58ToBytes, bytesToBase58, createClient, decodeAnyTransaction, decodeSignedTransaction, decodeTransaction, WalletManagerNear as default, describeTransaction, ed25519Key, encodeSignedTransaction, encodeTransaction, failureOf, fromBase64, implicitAccountId, isDangerous, isImplicitAccountId, isPlainObject, isValidAccountId, nep413Bytes, nep413Hash, outcomeFailed, parsePublicKey, parseSignature, publicKeyOfImplicit, publicKeyToString, readAction, readPublicKey, readSignature, receiptOf, toBase64, writeAction, writePublicKey, writeSignature };

package/dist/index.js

@@ -239,17 +239,34 @@ function argsBytes(args) {
   if (!isPlainObject(args)) throw new TypeError("function-call args must be bytes, a string or a plain object");
   return utf8.encode(JSON.stringify(args));
 }
+var FUNCTION_CALL_PERMISSION_KEYS = /* @__PURE__ */ new Set(["allowance", "receiverId", "methodNames"]);
+function accessKeyPermissionTag(permission) {
+  const keys = isPlainObject(permission) ? Object.keys(permission) : [];
+  if (keys.length !== 1) throw new TypeError(`an access-key permission must have exactly one variant, fullAccess or functionCall (has: ${keys.join(", ") || "none"})`);
+  const variant = permission[keys[0]];
+  if (keys[0] === "fullAccess") {
+    if (!isPlainObject(variant)) throw new TypeError("fullAccess must be a plain object");
+    return 1;
+  }
+  if (keys[0] === "functionCall") {
+    if (!isPlainObject(variant) || Object.keys(variant).some((k) => !FUNCTION_CALL_PERMISSION_KEYS.has(k))) throw new TypeError("functionCall must be a plain { receiverId, methodNames, allowance? } object");
+    if (typeof variant.receiverId !== "string") throw new TypeError("functionCall.receiverId must be a string");
+    if (!Array.isArray(variant.methodNames) || !variant.methodNames.every((m) => typeof m === "string")) throw new TypeError("functionCall.methodNames must be an array of strings");
+    if (variant.allowance !== void 0 && typeof variant.allowance !== "bigint") throw new TypeError("functionCall.allowance must be a bigint or absent");
+    return 0;
+  }
+  throw new TypeError(`unknown access-key permission ${JSON.stringify(keys[0])}`);
+}
 function writeAccessKey(w, k) {
   w.u64(k.nonce);
-  if ("functionCall" in k.permission) {
+  const tag = accessKeyPermissionTag(k.permission);
+  w.u8(tag);
+  if (tag === 0) {
     const p = k.permission.functionCall;
-    w.u8(0);
     w.option(p.allowance, (a) => w.u128(a));
     w.string(p.receiverId);
     w.u32(p.methodNames.length);
     for (const m of p.methodNames) w.string(m);
-  } else {
-    w.u8(1);
   }
 }
 function readAccessKey(r) {
@@ -489,8 +506,15 @@ function describeTransaction(tx, ctx = {}) {
     if (DANGEROUS_ACTIONS.has(key)) {
       dangerous ??= KIND_OF_DANGEROUS[key];
       warnings.push({ code: "dangerous-action", message: `${key} changes the account, its keys or its code.` });
-      if (key === "addKey" && "fullAccess" in a.addKey.accessKey.permission) {
-        warnings.push({ code: "full-access-key", message: "Adds a FULL ACCESS key: whoever holds it owns the account." });
+      if (key === "addKey") {
+        let tag;
+        try {
+          tag = accessKeyPermissionTag(a.addKey?.accessKey?.permission);
+        } catch {
+          tag = void 0;
+        }
+        if (tag === 1) warnings.push({ code: "full-access-key", message: "Adds a FULL ACCESS key: whoever holds it owns the account." });
+        else if (tag === void 0) warnings.push({ code: "dangerous-action", message: "Malformed access-key permission: neither fullAccess nor functionCall. The wallet refuses to sign it." });
       }
       continue;
     }
@@ -888,6 +912,15 @@ function assertShape(actions, depth = 0) {
       if (!(f.args instanceof Uint8Array) && typeof f.args !== "string" && !isPlainObject(f.args)) throw new UnsafeTransactionError("malformed-action", "Function-call args must be bytes, a string or a plain object.");
       if (f.gas !== void 0 && typeof f.gas !== "bigint" || f.deposit !== void 0 && typeof f.deposit !== "bigint") throw new UnsafeTransactionError("malformed-action", "Function-call gas and deposit must be bigints.");
     }
+    if ("addKey" in a) {
+      const k = a.addKey;
+      if (!isPlainObject(k) || !isPlainObject(k.accessKey)) throw new UnsafeTransactionError("malformed-action", "addKey must carry an accessKey object.");
+      try {
+        accessKeyPermissionTag(k.accessKey.permission);
+      } catch (e) {
+        throw new UnsafeTransactionError("malformed-action", `AddKey: ${e.message}.`);
+      }
+    }
     if ("signedDelegate" in a && depth === 0) assertShape(a.signedDelegate.delegateAction.actions, depth + 1);
   }
 }
@@ -950,13 +983,20 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
   needsNetwork = true;
   /** Derivation path, or `external` for an external signer. */
   path;
-  /** The signer that holds the key. */
-  signer;
+  /**
+   * The signer that holds the key, in a private field: not a property of the account, so no code
+   * the account is handed to (a protocol module, a logger) can reach it and sign around the
+   * account's checks (audit 2026-10-29 A1).
+   */
+  #signer;
+  /** What holds the key: `seed`, `key` (one imported key) or `external`. */
+  signerKind;
   _disposed = false;
   _readOnly;
   constructor(signer, publicKey, path, config = {}, accountId) {
     super(accountId ?? implicitAccountId(publicKey), config, ed25519Key(publicKey));
-    this.signer = requireCurve(signer, "ed25519");
+    this.#signer = requireCurve(signer, "ed25519");
+    this.signerKind = this.#signer.kind;
     this.path = path;
   }
   /** Wrap a raw derived key (takes ownership; zeroized on dispose). */
@@ -970,14 +1010,14 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
   }
   /** The same key bound to a named account (`alice.near`) that lists it as a full-access key. */
   withAccountId(accountId) {
-    return new _WalletAccountNear(this.signer, this.publicKey.data, this.path, this._config, accountId);
+    return new _WalletAccountNear(this.#signer, this.publicKey.data, this.path, this._config, accountId);
   }
   key() {
     if (this._disposed) throw new SignerError("This account has been disposed.");
   }
   async #signBytes(bytes, context) {
     this.key();
-    return this.signer.sign(bytes, { scheme: "ed25519", context });
+    return this.#signer.sign(bytes, { scheme: "ed25519", context });
   }
   /**
    * Raw ed25519 signature over the message bytes, as NEAR tooling prints it: "ed25519:<base58>".
@@ -1064,7 +1104,7 @@ var WalletAccountNear = class _WalletAccountNear extends WalletAccountReadOnlyNe
   /** Dispose the signer (zeroizes a local key). Idempotent. */
   dispose() {
     this._disposed = true;
-    this.signer.dispose();
+    this.#signer.dispose();
   }
 };
 function decodeSigned(b64) {
@@ -1152,6 +1192,7 @@ export {
   WalletAccountReadOnlyNear,
   WalletManagerNear,
   YOCTO,
+  accessKeyPermissionTag,
   actionKey,
   argsBytes,
   assertWellFormed,