feat(argon2): vendor hash-wasm v4.12.0 as @bitgo/argon2

.github/workflows/ci.yml

@@ -353,6 +353,17 @@ jobs:
 
           echo "✅ Docker image tests passed"
 
+  verify-vendor-integrity:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Verify argon2 vendor integrity
+        run: modules/argon2/scripts/verify-vendor.sh
+
   verify-npm-packages:
     runs-on: ubuntu-latest
 

modules/argon2/.mocharc.yml

@@ -0,0 +1,8 @@
+require: 'tsx'
+timeout: '60000'
+reporter: 'min'
+reporter-option:
+  - 'cdn=true'
+  - 'json=false'
+exit: true
+spec: ['test/**/*.ts']

modules/argon2/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+## 1.0.0
+
+- Initial release. Vendored argon2 from hash-wasm v4.12.0 (MIT license).
+- Provides argon2id, argon2i, argon2d, and argon2Verify functions.
+- WASM binaries (~6.6KB argon2 + ~7.4KB blake2b) embedded as base64 in the JS bundle.

modules/argon2/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2020 Dani Biro
+
+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.
+
+Vendored from hash-wasm v4.12.0 (https://github.com/Daninet/hash-wasm)

modules/argon2/PROVENANCE.md

@@ -0,0 +1,25 @@
+# Provenance
+
+Vendored from [hash-wasm](https://github.com/Daninet/hash-wasm) v4.12.0.
+
+- **npm**: `hash-wasm@4.12.0`
+- **git**: `github.com/Daninet/hash-wasm` commit `373b796205ab55fb4a657374dad6ea589bf75815`
+- **file**: `dist/argon2.umd.min.js` from the npm tarball
+
+## SHA256
+
+```
+dcec617a2e1b700fa132d1583a186cb70611113395e869f2dd6cc82b415d3094  argon2.umd.min.js
+```
+
+## Verification
+
+```bash
+./scripts/verify-vendor.sh
+```
+
+Compares the local file against the npm tarball. To verify against the pinned hash:
+
+```bash
+echo "dcec617a2e1b700fa132d1583a186cb70611113395e869f2dd6cc82b415d3094  argon2.umd.min.js" | shasum -a 256 -c
+```

modules/argon2/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @bitgo/argon2 - Vendored from hash-wasm v4.12.0
+ * https://github.com/Daninet/hash-wasm
+ * MIT License - Copyright (c) 2020 Dani Biro
+ */
+
+export type ITypedArray = Uint8Array | Uint16Array | Uint32Array;
+export type IDataType = string | ITypedArray;
+
+export interface IArgon2Options {
+  /** Password (or message) to be hashed */
+  password: IDataType;
+  /** Salt (usually containing random bytes) */
+  salt: IDataType;
+  /** Secret for keyed hashing */
+  secret?: IDataType;
+  /** Number of iterations to perform */
+  iterations: number;
+  /** Degree of parallelism */
+  parallelism: number;
+  /** Amount of memory to be used in kibibytes (1024 bytes) */
+  memorySize: number;
+  /** Output size in bytes */
+  hashLength: number;
+  /** Desired output type. Defaults to 'hex' */
+  outputType?: 'hex' | 'binary' | 'encoded';
+}
+
+interface IArgon2OptionsBinary {
+  outputType: 'binary';
+}
+
+type Argon2ReturnType<T> = T extends IArgon2OptionsBinary ? Uint8Array : string;
+
+/** Calculates hash using the argon2i password-hashing function */
+export function argon2i<T extends IArgon2Options>(options: T): Promise<Argon2ReturnType<T>>;
+
+/** Calculates hash using the argon2id password-hashing function */
+export function argon2id<T extends IArgon2Options>(options: T): Promise<Argon2ReturnType<T>>;
+
+/** Calculates hash using the argon2d password-hashing function */
+export function argon2d<T extends IArgon2Options>(options: T): Promise<Argon2ReturnType<T>>;
+
+export interface Argon2VerifyOptions {
+  /** Password to be verified */
+  password: IDataType;
+  /** Secret used on hash creation */
+  secret?: IDataType;
+  /** A previously generated argon2 hash in the 'encoded' output format */
+  hash: string;
+}
+
+/** Verifies password using the argon2 password-hashing function */
+export function argon2Verify(options: Argon2VerifyOptions): Promise<boolean>;

modules/argon2/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@bitgo/argon2",
+  "version": "1.0.0",
+  "description": "Vendored argon2 (hash-wasm v4.12.0) for BitGo SDK",
+  "main": "argon2.umd.min.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "mocha test/**/*.ts",
+    "verify": "./scripts/verify-vendor.sh"
+  },
+  "files": [
+    "argon2.umd.min.js",
+    "index.d.ts",
+    "LICENSE",
+    "PROVENANCE.md"
+  ],
+  "author": "BitGo SDK Team <sdkteam@bitgo.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BitGo/BitGoJS.git",
+    "directory": "modules/argon2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

modules/argon2/scripts/verify-vendor.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Verify (or re-vendor) argon2.umd.min.js from hash-wasm on npm.
+#
+# Usage:
+#   ./scripts/verify-vendor.sh           # verify current file matches upstream + pinned hash
+#   ./scripts/verify-vendor.sh 4.13.0    # re-vendor from a specific version
+#
+set -euo pipefail
+
+VERSION="${1:-4.12.0}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+MODULE_DIR="$(dirname "$SCRIPT_DIR")"
+TARGET="$MODULE_DIR/argon2.umd.min.js"
+
+# Pinned SHA256 from PROVENANCE.md -- update when re-vendoring
+PINNED_SHA="dcec617a2e1b700fa132d1583a186cb70611113395e869f2dd6cc82b415d3094"
+
+# Step 1: Verify local file against pinned hash
+if [ -f "$TARGET" ] && [ -z "${1:-}" ]; then
+  LOCAL_SHA=$(shasum -a 256 "$TARGET" | awk '{print $1}')
+  echo "Local    SHA256: $LOCAL_SHA"
+  echo "Pinned   SHA256: $PINNED_SHA"
+
+  if [ "$LOCAL_SHA" != "$PINNED_SHA" ]; then
+    echo "FAIL: local file does not match pinned hash in PROVENANCE.md" >&2
+    exit 1
+  fi
+  echo "PASS: local file matches pinned hash"
+fi
+
+# Step 2: Verify against npm tarball
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+echo "Downloading hash-wasm@${VERSION} from npm..."
+curl -sL "https://registry.npmjs.org/hash-wasm/-/hash-wasm-${VERSION}.tgz" | tar xz -C "$TMPDIR"
+
+UPSTREAM="$TMPDIR/package/dist/argon2.umd.min.js"
+if [ ! -f "$UPSTREAM" ]; then
+  echo "ERROR: argon2.umd.min.js not found in hash-wasm@${VERSION}" >&2
+  exit 1
+fi
+
+UPSTREAM_SHA=$(shasum -a 256 "$UPSTREAM" | awk '{print $1}')
+echo "Upstream SHA256: $UPSTREAM_SHA"
+
+if [ -f "$TARGET" ]; then
+  LOCAL_SHA=$(shasum -a 256 "$TARGET" | awk '{print $1}')
+
+  if [ "$UPSTREAM_SHA" = "$LOCAL_SHA" ]; then
+    echo "PASS: vendored file is identical to hash-wasm@${VERSION}"
+    exit 0
+  else
+    echo "MISMATCH: vendored file differs from hash-wasm@${VERSION}"
+    if [ -z "${1:-}" ]; then
+      exit 1
+    fi
+  fi
+fi
+
+if [ -n "${1:-}" ]; then
+  echo "Copying hash-wasm@${VERSION} argon2.umd.min.js into $MODULE_DIR..."
+  cp "$UPSTREAM" "$TARGET"
+  echo "New SHA256: $UPSTREAM_SHA"
+  echo "Done. Update PINNED_SHA in this script and PROVENANCE.md."
+fi