argon2-extension-mv3

A secure, WebAssembly-based Argon2id implementation specifically designed for Chrome Extensions (Manifest V3).

🧐 The Problem

Most existing WebAssembly ports of Argon2 (such as argon2-browser or hash-wasm) rely on dynamic code generation (eval() or new Function()) within their JavaScript "glue code" to instantiate the WASM module.

This is strictly prohibited in Chrome Extensions under Manifest V3 due to the Content Security Policy (CSP), which disallows 'unsafe-eval'. Attempting to use standard libraries results in:

EvalError: Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive...

💡 The Solution

This package provides a custom compilation of the reference C implementation (phc-winner-argon2) using Emscripten with specific flags to ensure full MV3 compliance:

• DYNAMIC_EXECUTION=0: Removes all reliance on eval() and dynamic code generation.
• EMBIND_AOT=1: Generates bindings Ahead-Of-Time during compilation.
• Type Safety: Includes TypeScript definitions out of the box.

🚀 Installation

npm install argon2-extension-mv3

🛠 Configuration (Vite)

Since this is a WASM library, the .wasm binary file must be served alongside your JavaScript bundle. For a Chrome Extension built with Vite, you need to copy the WASM file from node_modules to your output directory.

1. Install vite-plugin-static-copy:

npm install -D vite-plugin-static-copy

2. Update vite.config.ts:

import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          // Copy the WASM binary from the package to the root of your build
          src: 'node_modules/argon2-extension-mv3/dist/argon2_wasm.wasm',
          dest: '.' 
        }
      ]
    })
  ]
});

💻 Usage

Here is a complete example of how to use it in a TypeScript service.

import createArgon2Module from 'argon2-extension-mv3';

export class CryptoService {
    
    async hashPassword(password: string, salt: string): Promise<string> {
        // 1. Initialize the module
        const argon2 = await createArgon2Module({
            // Important: Tell the module where to find the .wasm file
            // usage in Chrome Extension:
            locateFile: (path: string) => {
                if (typeof chrome !== "undefined" && chrome.runtime) {
                    return chrome.runtime.getURL('argon2_wasm.wasm');
                }
                return path;
            }
        });

        // 2. Generate Hash
        // The salt must be a hex string for this implementation
        const hashHex = argon2.generateArgon2idHash(password, salt);
        
        return hashHex;
    }
}

🏗 Building from Source

If you want to compile the WASM binary yourself, you will need the Emscripten SDK installed and active in your terminal.

1. Clone the repository:

   git clone [https://github.com/ArturCharylo/argon2-extension-mv3.git](https://github.com/ArturCharylo/argon2-extension-mv3.git)
   cd argon2-extension-mv3

2. Install dependencies:

   npm install

3. Build:

   npm run build

   This command will:

   • Compile the C++ source code to WASM using emcc.
   • Compile the TypeScript wrapper.
   • Output files to the dist/ folder.

🤝 Contributing

Contributions are welcome! If you find a bug or want to add a feature, please open an issue or submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

🙏 Acknowledgments

• Based on the reference C implementation: P-H-C/phc-winner-argon2