eteres 0.0.1-security → 6.7.1

package/src.ts/utils/rlp-encode.ts

@@ -0,0 +1,64 @@
+//See: https://github.com/ethereum/wiki/wiki/RLP
+
+import { getBytes } from "./data.js";
+
+import type { RlpStructuredData } from "./rlp.js";
+
+
+function arrayifyInteger(value: number): Array<number> {
+    const result: Array<number> = [];
+    while (value) {
+        result.unshift(value & 0xff);
+        value >>= 8;
+    }
+    return result;
+}
+
+function _encode(object: Array<any> | string): Array<number> {
+    if (Array.isArray(object)) {
+        let payload: Array<number> = [];
+        object.forEach(function(child) {
+            payload = payload.concat(_encode(child));
+        });
+
+        if (payload.length <= 55) {
+            payload.unshift(0xc0 + payload.length)
+            return payload;
+        }
+
+        const length = arrayifyInteger(payload.length);
+        length.unshift(0xf7 + length.length);
+
+        return length.concat(payload);
+
+    }
+
+    const data: Array<number> = Array.prototype.slice.call(getBytes(object, "object"));
+
+    if (data.length === 1 && data[0] <= 0x7f) {
+        return data;
+
+    } else if (data.length <= 55) {
+        data.unshift(0x80 + data.length);
+        return data;
+    }
+
+    const length = arrayifyInteger(data.length);
+    length.unshift(0xb7 + length.length);
+
+    return length.concat(data);
+}
+
+const nibbles = "0123456789abcdef";
+
+/**
+ *  Encodes %%object%% as an RLP-encoded [[DataHexString]].
+ */
+export function encodeRlp(object: RlpStructuredData): string {
+    let result = "0x";
+    for (const v of _encode(object)) {
+        result += nibbles[v >> 4];
+        result += nibbles[v & 0xf];
+    }
+    return result;
+}

package/src.ts/utils/rlp.ts

@@ -0,0 +1,15 @@
+/**
+ *  The [[link-rlp]] (RLP) encoding is used throughout Ethereum
+ *  to serialize nested structures of Arrays and data.
+ *
+ *  @_subsection api/utils:Recursive-Length Prefix  [about-rlp]
+ */
+
+export { decodeRlp } from "./rlp-decode.js";
+export { encodeRlp } from "./rlp-encode.js";
+
+/**
+ *  An RLP-encoded structure.
+ */
+export type RlpStructuredData = string | Array<RlpStructuredData>;
+

package/src.ts/utils/units.ts

@@ -0,0 +1,91 @@
+/**
+ *  Most interactions with Ethereum requires integer values, which use
+ *  the smallest magnitude unit.
+ *
+ *  For example, imagine dealing with dollars and cents. Since dollars
+ *  are divisible, non-integer values are possible, such as ``$10.77``.
+ *  By using the smallest indivisible unit (i.e. cents), the value can
+ *  be kept as the integer ``1077``.
+ *
+ *  When receiving decimal input from the user (as a decimal string),
+ *  the value should be converted to an integer and when showing a user
+ *  a value, the integer value should be converted to a decimal string.
+ *
+ *  This creates a clear distinction, between values to be used by code
+ *  (integers) and values used for display logic to users (decimals).
+ *
+ *  The native unit in Ethereum, //ether// is divisible to 18 decimal places,
+ *  where each individual unit is called a //wei//.
+ *
+ *  @_subsection api/utils:Unit Conversion  [about-units]
+ */
+import { assertArgument } from "./errors.js";
+import { FixedNumber } from "./fixednumber.js";
+import { getNumber } from "./maths.js";
+
+import type { BigNumberish, Numeric } from "../utils/index.js";
+
+
+const names = [
+    "wei",
+    "kwei",
+    "mwei",
+    "gwei",
+    "szabo",
+    "finney",
+    "ether",
+];
+
+/**
+ *  Converts %%value%% into a //decimal string//, assuming %%unit%% decimal
+ *  places. The %%unit%% may be the number of decimal places or the name of
+ *  a unit (e.g. ``"gwei"`` for 9 decimal places).
+ *
+ */
+export function formatUnits(value: BigNumberish, unit?: string | Numeric): string {
+    let decimals = 18;
+    if (typeof(unit) === "string") {
+        const index = names.indexOf(unit);
+        assertArgument(index >= 0, "invalid unit", "unit", unit);
+        decimals = 3 * index;
+    } else if (unit != null) {
+        decimals = getNumber(unit, "unit");
+    }
+
+    return FixedNumber.fromValue(value, decimals, { decimals, width: 512 }).toString();
+}
+
+/**
+ *  Converts the //decimal string// %%value%% to a BigInt, assuming
+ *  %%unit%% decimal places. The %%unit%% may the number of decimal places
+ *  or the name of a unit (e.g. ``"gwei"`` for 9 decimal places).
+ */
+export function parseUnits(value: string, unit?: string | Numeric): bigint {
+    assertArgument(typeof(value) === "string", "value must be a string", "value", value);
+
+    let decimals = 18;
+    if (typeof(unit) === "string") {
+        const index = names.indexOf(unit);
+        assertArgument(index >= 0, "invalid unit", "unit", unit);
+        decimals = 3 * index;
+    } else if (unit != null) {
+        decimals = getNumber(unit, "unit");
+    }
+
+    return FixedNumber.fromString(value, { decimals, width: 512 }).value;
+}
+
+/**
+ *  Converts %%value%% into a //decimal string// using 18 decimal places.
+ */
+export function formatEther(wei: BigNumberish): string {
+    return formatUnits(wei, 18);
+}
+
+/**
+ *  Converts the //decimal string// %%ether%% to a BigInt, using 18
+ *  decimal places.
+ */
+export function parseEther(ether: string): bigint {
+    return parseUnits(ether, 18);
+}

package/src.ts/utils/utf8.ts

@@ -0,0 +1,324 @@
+/**
+ *  Using strings in Ethereum (or any security-basd system) requires
+ *  additional care. These utilities attempt to mitigate some of the
+ *  safety issues as well as provide the ability to recover and analyse
+ *  strings.
+ *
+ *  @_subsection api/utils:Strings and UTF-8  [about-strings]
+ */
+import { getBytes } from "./data.js";
+import { assertArgument, assertNormalize } from "./errors.js";
+
+import type { BytesLike } from "./index.js";
+
+
+///////////////////////////////
+
+/**
+ *  The stanard normalization forms.
+ */
+export type UnicodeNormalizationForm = "NFC" | "NFD" | "NFKC" | "NFKD";
+
+/**
+ *  When using the UTF-8 error API the following errors can be intercepted
+ *  and processed as the %%reason%% passed to the [[Utf8ErrorFunc]].
+ *
+ *  **``"UNEXPECTED_CONTINUE"``** - a continuation byte was present where there
+ *  was nothing to continue.
+ *
+ *  **``"BAD_PREFIX"``** - an invalid (non-continuation) byte to start a
+ *  UTF-8 codepoint was found.
+ *
+ *  **``"OVERRUN"``** - the string is too short to process the expected
+ *  codepoint length.
+ *
+ *  **``"MISSING_CONTINUE"``** - a missing continuation byte was expected but
+ *  not found. The %%offset%% indicates the index the continuation byte
+ *  was expected at.
+ *
+ *  **``"OUT_OF_RANGE"``** - the computed code point is outside the range
+ *  for UTF-8. The %%badCodepoint%% indicates the computed codepoint, which was
+ *  outside the valid UTF-8 range.
+ *
+ *  **``"UTF16_SURROGATE"``** - the UTF-8 strings contained a UTF-16 surrogate
+ *  pair. The %%badCodepoint%% is the computed codepoint, which was inside the
+ *  UTF-16 surrogate range.
+ *
+ *  **``"OVERLONG"``** - the string is an overlong representation. The
+ *  %%badCodepoint%% indicates the computed codepoint, which has already
+ *  been bounds checked.
+ *
+ *
+ *  @returns string
+ */
+export type Utf8ErrorReason = "UNEXPECTED_CONTINUE" | "BAD_PREFIX" | "OVERRUN" |
+    "MISSING_CONTINUE" | "OUT_OF_RANGE" | "UTF16_SURROGATE" | "OVERLONG";
+
+
+/**
+ *  A callback that can be used with [[toUtf8String]] to analysis or
+ *  recovery from invalid UTF-8 data.
+ *
+ *  Parsing UTF-8 data is done through a simple Finite-State Machine (FSM)
+ *  which calls the ``Utf8ErrorFunc`` if a fault is detected.
+ *
+ *  The %%reason%% indicates where in the FSM execution the fault
+ *  occurred and the %%offset%% indicates where the input failed.
+ *
+ *  The %%bytes%% represents the raw UTF-8 data that was provided and
+ *  %%output%% is the current array of UTF-8 code-points, which may
+ *  be updated by the ``Utf8ErrorFunc``.
+ *
+ *  The value of the %%badCodepoint%% depends on the %%reason%%. See
+ *  [[Utf8ErrorReason]] for details.
+ *
+ *  The function should return the number of bytes that should be skipped
+ *  when control resumes to the FSM.
+ */
+export type Utf8ErrorFunc = (reason: Utf8ErrorReason, offset: number, bytes: Uint8Array, output: Array<number>, badCodepoint?: number) => number;
+
+
+function errorFunc(reason: Utf8ErrorReason, offset: number, bytes: Uint8Array, output: Array<number>, badCodepoint?: number): number {
+    assertArgument(false, `invalid codepoint at offset ${ offset }; ${ reason }`, "bytes", bytes);
+}
+
+function ignoreFunc(reason: Utf8ErrorReason, offset: number, bytes: Uint8Array, output: Array<number>, badCodepoint?: number): number {
+
+    // If there is an invalid prefix (including stray continuation), skip any additional continuation bytes
+    if (reason === "BAD_PREFIX" || reason === "UNEXPECTED_CONTINUE") {
+        let i = 0;
+        for (let o = offset + 1; o < bytes.length; o++) {
+            if (bytes[o] >> 6 !== 0x02) { break; }
+            i++;
+        }
+        return i;
+    }
+
+    // This byte runs us past the end of the string, so just jump to the end
+    // (but the first byte was read already read and therefore skipped)
+    if (reason === "OVERRUN") {
+        return bytes.length - offset - 1;
+    }
+
+    // Nothing to skip
+    return 0;
+}
+
+function replaceFunc(reason: Utf8ErrorReason, offset: number, bytes: Uint8Array, output: Array<number>, badCodepoint?: number): number {
+
+    // Overlong representations are otherwise "valid" code points; just non-deistingtished
+    if (reason === "OVERLONG") {
+        assertArgument(typeof(badCodepoint) === "number", "invalid bad code point for replacement", "badCodepoint", badCodepoint);
+        output.push(badCodepoint);
+        return 0;
+    }
+
+    // Put the replacement character into the output
+    output.push(0xfffd);
+
+    // Otherwise, process as if ignoring errors
+    return ignoreFunc(reason, offset, bytes, output, badCodepoint);
+}
+
+/**
+ *  A handful of popular, built-in UTF-8 error handling strategies.
+ *
+ *  **``"error"``** - throws on ANY illegal UTF-8 sequence or
+ *  non-canonical (overlong) codepoints (this is the default)
+ *
+ *  **``"ignore"``** - silently drops any illegal UTF-8 sequence
+ *  and accepts non-canonical (overlong) codepoints
+ *
+ *  **``"replace"``** - replace any illegal UTF-8 sequence with the
+ *  UTF-8 replacement character (i.e. ``"\\ufffd"``) and accepts
+ *  non-canonical (overlong) codepoints
+ *
+ *  @returns: Record<"error" | "ignore" | "replace", Utf8ErrorFunc>
+ */
+export const Utf8ErrorFuncs: Readonly<Record<"error" | "ignore" | "replace", Utf8ErrorFunc>> = Object.freeze({
+    error: errorFunc,
+    ignore: ignoreFunc,
+    replace: replaceFunc
+});
+
+// http://stackoverflow.com/questions/13356493/decode-utf-8-with-javascript#13691499
+function getUtf8CodePoints(_bytes: BytesLike, onError?: Utf8ErrorFunc): Array<number> {
+    if (onError == null) { onError = Utf8ErrorFuncs.error; }
+
+    const bytes = getBytes(_bytes, "bytes");
+
+    const result: Array<number> = [];
+    let i = 0;
+
+    // Invalid bytes are ignored
+    while(i < bytes.length) {
+
+        const c = bytes[i++];
+
+        // 0xxx xxxx
+        if (c >> 7 === 0) {
+            result.push(c);
+            continue;
+        }
+
+        // Multibyte; how many bytes left for this character?
+        let extraLength: null | number = null;
+        let overlongMask: null | number = null;
+
+        // 110x xxxx 10xx xxxx
+        if ((c & 0xe0) === 0xc0) {
+            extraLength = 1;
+            overlongMask = 0x7f;
+
+        // 1110 xxxx 10xx xxxx 10xx xxxx
+        } else if ((c & 0xf0) === 0xe0) {
+            extraLength = 2;
+            overlongMask = 0x7ff;
+
+        // 1111 0xxx 10xx xxxx 10xx xxxx 10xx xxxx
+        } else if ((c & 0xf8) === 0xf0) {
+            extraLength = 3;
+            overlongMask = 0xffff;
+
+        } else {
+            if ((c & 0xc0) === 0x80) {
+                i += onError("UNEXPECTED_CONTINUE", i - 1, bytes, result);
+            } else {
+                i += onError("BAD_PREFIX", i - 1, bytes, result);
+            }
+            continue;
+        }
+
+        // Do we have enough bytes in our data?
+        if (i - 1 + extraLength >= bytes.length) {
+            i += onError("OVERRUN", i - 1, bytes, result);
+            continue;
+        }
+
+        // Remove the length prefix from the char
+        let res: null | number = c & ((1 << (8 - extraLength - 1)) - 1);
+
+        for (let j = 0; j < extraLength; j++) {
+            let nextChar = bytes[i];
+
+            // Invalid continuation byte
+            if ((nextChar & 0xc0) != 0x80) {
+                i += onError("MISSING_CONTINUE", i, bytes, result);
+                res = null;
+                break;
+            };
+
+            res = (res << 6) | (nextChar & 0x3f);
+            i++;
+        }
+
+        // See above loop for invalid continuation byte
+        if (res === null) { continue; }
+
+        // Maximum code point
+        if (res > 0x10ffff) {
+            i += onError("OUT_OF_RANGE", i - 1 - extraLength, bytes, result, res);
+            continue;
+        }
+
+        // Reserved for UTF-16 surrogate halves
+        if (res >= 0xd800 && res <= 0xdfff) {
+            i += onError("UTF16_SURROGATE", i - 1 - extraLength, bytes, result, res);
+            continue;
+        }
+
+        // Check for overlong sequences (more bytes than needed)
+        if (res <= overlongMask) {
+            i += onError("OVERLONG", i - 1 - extraLength, bytes, result, res);
+            continue;
+        }
+
+        result.push(res);
+    }
+
+    return result;
+}
+
+// http://stackoverflow.com/questions/18729405/how-to-convert-utf8-string-to-byte-array
+
+/**
+ *  Returns the UTF-8 byte representation of %%str%%.
+ *
+ *  If %%form%% is specified, the string is normalized.
+ */
+export function toUtf8Bytes(str: string, form?: UnicodeNormalizationForm): Uint8Array {
+
+    if (form != null) {
+        assertNormalize(form);
+        str = str.normalize(form);
+    }
+
+    let result: Array<number> = [];
+    for (let i = 0; i < str.length; i++) {
+        const c = str.charCodeAt(i);
+
+        if (c < 0x80) {
+            result.push(c);
+
+        } else if (c < 0x800) {
+            result.push((c >> 6) | 0xc0);
+            result.push((c & 0x3f) | 0x80);
+
+        } else if ((c & 0xfc00) == 0xd800) {
+            i++;
+            const c2 = str.charCodeAt(i);
+
+            assertArgument(i < str.length && ((c2 & 0xfc00) === 0xdc00),
+                "invalid surrogate pair", "str", str);
+
+            // Surrogate Pair
+            const pair = 0x10000 + ((c & 0x03ff) << 10) + (c2 & 0x03ff);
+            result.push((pair >> 18) | 0xf0);
+            result.push(((pair >> 12) & 0x3f) | 0x80);
+            result.push(((pair >> 6) & 0x3f) | 0x80);
+            result.push((pair & 0x3f) | 0x80);
+
+        } else {
+            result.push((c >> 12) | 0xe0);
+            result.push(((c >> 6) & 0x3f) | 0x80);
+            result.push((c & 0x3f) | 0x80);
+        }
+    }
+
+    return new Uint8Array(result);
+};
+
+//export 
+function _toUtf8String(codePoints: Array<number>): string {
+    return codePoints.map((codePoint) => {
+        if (codePoint <= 0xffff) {
+            return String.fromCharCode(codePoint);
+        }
+        codePoint -= 0x10000;
+        return String.fromCharCode(
+            (((codePoint >> 10) & 0x3ff) + 0xd800),
+            ((codePoint & 0x3ff) + 0xdc00)
+        );
+    }).join("");
+}
+
+/**
+ *  Returns the string represented by the UTF-8 data %%bytes%%.
+ *
+ *  When %%onError%% function is specified, it is called on UTF-8
+ *  errors allowing recovery using the [[Utf8ErrorFunc]] API.
+ *  (default: [error](Utf8ErrorFuncs))
+ */
+export function toUtf8String(bytes: BytesLike, onError?: Utf8ErrorFunc): string {
+    return _toUtf8String(getUtf8CodePoints(bytes, onError));
+}
+
+/**
+ *  Returns the UTF-8 code-points for %%str%%.
+ *
+ *  If %%form%% is specified, the string is normalized.
+ */
+export function toUtf8CodePoints(str: string, form?: UnicodeNormalizationForm): Array<number> {
+    return getUtf8CodePoints(toUtf8Bytes(str, form));
+}
+

package/src.ts/utils/uuid.ts

@@ -0,0 +1,36 @@
+/**
+ *  Explain UUID and link to RFC here.
+ *
+ *  @_subsection: api/utils:UUID  [about-uuid]
+ */
+import { getBytes, hexlify } from "./data.js";
+
+import type { BytesLike } from "./index.js";
+
+/**
+ *  Returns the version 4 [[link-uuid]] for the %%randomBytes%%.
+ *
+ *  @see: https://www.ietf.org/rfc/rfc4122.txt (Section 4.4)
+ */
+export function uuidV4(randomBytes: BytesLike): string {
+    const bytes = getBytes(randomBytes, "randomBytes");
+
+    // Section: 4.1.3:
+    // - time_hi_and_version[12:16] = 0b0100
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+
+    // Section 4.4
+    // - clock_seq_hi_and_reserved[6] = 0b0
+    // - clock_seq_hi_and_reserved[7] = 0b1
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+    const value = hexlify(bytes);
+
+    return [
+       value.substring(2, 10),
+       value.substring(10, 14),
+       value.substring(14, 18),
+       value.substring(18, 22),
+       value.substring(22, 34),
+    ].join("-");
+}

package/src.ts/wallet/base-wallet.ts

@@ -0,0 +1,130 @@
+import { getAddress, resolveAddress } from "../address/index.js";
+import { hashMessage, TypedDataEncoder } from "../hash/index.js";
+import { AbstractSigner } from "../providers/index.js";
+import { computeAddress, Transaction } from "../transaction/index.js";
+import {
+    defineProperties, resolveProperties, assert, assertArgument
+} from "../utils/index.js";
+
+import type { SigningKey } from "../crypto/index.js";
+import type { TypedDataDomain, TypedDataField } from "../hash/index.js";
+import type { Provider, TransactionRequest } from "../providers/index.js";
+import type { TransactionLike } from "../transaction/index.js";
+
+
+/**
+ *  The **BaseWallet** is a stream-lined implementation of a
+ *  [[Signer]] that operates with a private key.
+ *
+ *  It is preferred to use the [[Wallet]] class, as it offers
+ *  additional functionality and simplifies loading a variety
+ *  of JSON formats, Mnemonic Phrases, etc.
+ *
+ *  This class may be of use for those attempting to implement
+ *  a minimal Signer.
+ */
+export class BaseWallet extends AbstractSigner {
+    /**
+     *  The wallet address.
+     */
+    readonly address!: string;
+
+    readonly #signingKey: SigningKey;
+
+    /**
+     *  Creates a new BaseWallet for %%privateKey%%, optionally
+     *  connected to %%provider%%.
+     *
+     *  If %%provider%% is not specified, only offline methods can
+     *  be used.
+     */
+    constructor(privateKey: SigningKey, provider?: null | Provider) {
+        super(provider);
+
+        assertArgument(privateKey && typeof(privateKey.sign) === "function", "invalid private key", "privateKey", "[ REDACTED ]");
+
+        this.#signingKey = privateKey;
+
+        const address = computeAddress(this.signingKey.publicKey);
+        defineProperties<BaseWallet>(this, { address });
+    }
+
+    // Store private values behind getters to reduce visibility
+    // in console.log
+
+    /**
+     *  The [[SigningKey]] used for signing payloads.
+     */
+    get signingKey(): SigningKey { return this.#signingKey; }
+
+    /**
+     *  The private key for this wallet.
+     */
+    get privateKey(): string { return this.signingKey.privateKey; }
+
+    async getAddress(): Promise<string> { return this.address; }
+
+    connect(provider: null | Provider): BaseWallet {
+        return new BaseWallet(this.#signingKey, provider);
+    }
+
+    async signTransaction(tx: TransactionRequest): Promise<string> {
+
+        // Replace any Addressable or ENS name with an address
+        const { to, from } = await resolveProperties({
+            to: (tx.to ? resolveAddress(tx.to, this.provider): undefined),
+            from: (tx.from ? resolveAddress(tx.from, this.provider): undefined)
+        });
+
+        if (to != null) { tx.to = to; }
+        if (from != null) { tx.from = from; }
+
+        if (tx.from != null) {
+            assertArgument(getAddress(<string>(tx.from)) === this.address,
+                "transaction from address mismatch", "tx.from", tx.from);
+            delete tx.from;
+        }
+
+        // Build the transaction
+        const btx = Transaction.from(<TransactionLike<string>>tx);
+        btx.signature = this.signingKey.sign(btx.unsignedHash);
+
+        return btx.serialized;
+    }
+
+    async signMessage(message: string | Uint8Array): Promise<string> {
+        return this.signMessageSync(message);
+    }
+
+    // @TODO: Add a secialized signTx and signTyped sync that enforces
+    // all parameters are known?
+    /**
+     *  Returns the signature for %%message%% signed with this wallet.
+     */
+    signMessageSync(message: string | Uint8Array): string {
+        return this.signingKey.sign(hashMessage(message)).serialized;
+    }
+
+    async signTypedData(domain: TypedDataDomain, types: Record<string, Array<TypedDataField>>, value: Record<string, any>): Promise<string> {
+
+        // Populate any ENS names
+        const populated = await TypedDataEncoder.resolveNames(domain, types, value, async (name: string) => {
+            // @TODO: this should use resolveName; addresses don't
+            //        need a provider
+
+            assert(this.provider != null, "cannot resolve ENS names without a provider", "UNSUPPORTED_OPERATION", {
+                operation: "resolveName",
+                info: { name }
+            });
+
+            const address = await this.provider.resolveName(name);
+            assert(address != null, "unconfigured ENS name", "UNCONFIGURED_NAME", {
+                value: name
+            });
+
+            return address;
+        });
+
+        return this.signingKey.sign(TypedDataEncoder.hash(populated.domain, types, populated.value)).serialized;
+    }
+}