@lavamoat/across

Across ↔

Allowing Communication Relationship Of Scripts Securely

Across standard allows different scripts within the same web application to communicate with each other by passing messages between one another securely.

• Test Across for yourself with this live demo!
• Learn more about the motivation behind Across
• Across is still experimental ⚠️ - your help is highly appreciated!

This capability obviously already exists (by reading/writing from/to window), however the edge Across brings is its core added values:

Core Values

Across makes sure that a message passed on from script A to script B

• really did come from the sender script and not any other entity.
• was not tampered by any other entity.
• was not read by any other entity.

Install

The latest across production version is included in the official repo and also in upkg cdn, so in order to install across in the website, simply place it wherever and serve it to the website as-is:

<script src="https://unpkg.com/@lavamoat/across/across.prod.js"></script>
<script>
    // apply Across by running:
    ACROSS();
</script>

Make sure this runs first - any javascript that runs before Across can easily break it from securely working!

ACROSS API can also be required as part of a bundle instead of a script tag:

yarn add @lavamoat/across

const across = require('@lavamoat/across');
across(); // remember to call Across in order for it to apply

Usage

Once you register your onmessage callback by calling the document.onmessage() API by Across, you'll get a postMessage function that can be used to send messages to other scripts within the web app:

receive message example

<script src="https://x.com/script-a.js">
  (function(){
    const postMessage = document.onmessage((src, msg) => {
        if (src !== 'htts://y.com/script-b.js') {
          console.log('message is not really from "script-b.js"');
          return;
        }
        console.log('got a message from "' + src + '" : ', msg);
    });
  }())
</script>

send message example

<script src="https://y.com/script-b.js">
  (function(){
    const postMessage = document.onmessage((src, msg) => {
      // do nothing    
    });
    setTimeout(() => {
        postMessage('https://x.com/script-a.js', 'hi A, this is B!');
    }, 30);
  }())
</script>

Due to security limitations, registering a script to send and receive messages from other scripts can only be done before DOM is loaded (that's when document.currentScript API is still relevant).

Contribute

This project is an important POC aspiring to standardize how scripts can securely communicate with each other, however it is not yet production ready:

Support

Currently across is written to support chromium based browsers only, it was never tested on anything else.

Performance

Achieving an hermetic solution costs in performance. Injecting this script into some major websites went smoothly while with some others it caused them some performance issues.

Security

Although this project takes the hermetic concept very seriously and massively tests for potential flaws, across might potentially still have flaws which might enable attackers to bypass its hooks.

Bottom line - across might have security vulnerabilities!

Tests

In order to assure security, there are many tests that verify that across is fully hermetic as promised - everything that across supports is fully tested.

The tests mainly try to bypass across in any possible way.

If you found a vulnerability in across, open a PR with a test that demonstrates it.

Help

Help with promoting any of the topics above is very much appreciated in order for this project to become production ready and reshape how browser scripts can communicate with one another!

Supporters

Funded by Consensys 💙

Maintained and developed by MetaMask 🦊

Invented and developed by Gal Weizman 👋🏻

Runs on Snow ❄️