A browser leaf app

In this tutorial you put a web page on the mesh. The page becomes a leaf: it has its own identity, kept in the browser, and reaches the mesh through one node that agrees to carry its mail, its mediator. You open the page twice as two different leaves and send an end-to-end encrypted message from one to the other. It takes about fifteen minutes.

You need meshnode (Install), Node.js 22 or newer with npm, a browser, two terminal windows, and the ports 7201 and 5173 free. You do not need meshctl.

What you are building

 http://127.0.0.1:5173        http://localhost:5173
   leaf A (one identity)        leaf B (another identity)
          \                        /
           \   wss/ws frames      /
            v                    v
        ws://127.0.0.1:7201  <- the anchor's relay face
              anchor (a meshnode of class anchor): admits each
              leaf, holds its mail until the leaf picks it up

A browser cannot listen for connections, so it cannot be a full node. A leaf keeps one socket to its mediator instead: it asks to be mediated, the mediator admits it, and messages for the leaf wait at the mediator until the leaf collects them. Only the leaf can read them: they are encrypted to a key that never leaves the browser.

1. Run an anchor node

A node of class anchor mediates leaves. Make one in a fresh directory, with its relay face on port 7201 serving as its own relay:

mkdir leaf-tutorial && cd leaf-tutorial
meshnode init anchor --class anchor --name anchor --face-port 7201 --relay ws://127.0.0.1:7201

Start it in your second terminal, in the same directory, and leave it running:

meshnode run anchor

Back in the first terminal, print the anchor’s public key. The page needs it:

meshnode whoami anchor | awk '/^pubkey/ {print $2}'

2. Make the page

The page is a plain Vite project: one HTML file, one JavaScript module.

mkdir leaf-app && cd leaf-app
npm init -y
npm pkg set type=module scripts.dev="vite --host 127.0.0.1"
npm install @fleetmesh/leaf@next vite@^8

--host 127.0.0.1 makes the dev server answer on 127.0.0.1 as well as localhost, which you need in step 4.

Create index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My first leaf</title>
  </head>
  <body>
    <h1>My first leaf</h1>
    <p>I am <code id="me">…</code></p>
    <p>Status: <strong id="status">idle</strong></p>

    <h2>Send a message</h2>
    <input id="to" size="80" placeholder="did:nostr:… of another leaf" />
    <input id="text" size="40" placeholder="hello" />
    <button id="send">Send</button>

    <h2>Inbox <button id="pickup">Check for messages</button></h2>
    <ul id="inbox"></ul>

    <script type="module" src="/main.js"></script>
  </body>
</html>

Create main.js, and put the anchor’s public key from step 1 in place of PASTE-THE-ANCHOR-PUBKEY-HERE:

import { LeafStore, event, startBrowserLeaf } from '@fleetmesh/leaf';

// Your anchor node: its public key and its relay face (step 1).
const MEDIATOR = {
  pubkey: 'PASTE-THE-ANCHOR-PUBKEY-HERE',
  endpoint: 'ws://127.0.0.1:7201',
};

const $ = (id) => document.getElementById(id);

// The leaf's identity is made once and kept in this origin's IndexedDB.
const store = await LeafStore.open();
const me = 'did:nostr:' + event.pubkeyOf((await store.identity()).nodeSk);
$('me').textContent = me;

// One call: connect to the anchor, ask it to mediate, and keep the session.
const hub = startBrowserLeaf({ mediator: MEDIATOR });
hub.on((e) => {
  if (e.t === 'status') $('status').textContent = e.status + (e.detail ? ` (${e.detail})` : '');
  if (e.t === 'delivered') {
    for (const delivery of e.deliveries) {
      for (const envelope of delivery.envelopes) show(envelope.message);
    }
  }
});

function show(message) {
  const li = document.createElement('li');
  li.textContent = `${message.from ?? 'someone'}: ${message.body?.content ?? JSON.stringify(message.body)}`;
  $('inbox').prepend(li);
}

$('send').onclick = async () => {
  await hub.sendForward($('to').value.trim(), {
    id: crypto.randomUUID(),
    type: 'https://didcomm.org/basicmessage/2.0/message',
    body: { content: $('text').value },
  });
  $('text').value = '';
};

$('pickup').onclick = () => hub.pickup();

That is the whole app. startBrowserLeaf does the work: it makes the leaf’s keys, opens the socket, publishes the leaf’s own descriptor, asks the anchor to mediate, and keeps the session. If you open the page in several tabs, they share one connection and one identity.

3. Open the page

Start the dev server in the first terminal:

npm run dev

Open http://127.0.0.1:5173. The page shows the leaf’s identity (did:nostr:…), and after a moment its status changes from connecting to connected. The anchor admitted it: its terminal shows mediation admission granted to did:nostr:….

If the status says the mediator has no live descriptor, check the anchor public key in main.js, and that the anchor is running.

4. Open it again, as a second leaf

Open http://localhost:5173 in another tab. It is the same page, but localhost and 127.0.0.1 are different origins to the browser, so this tab has its own storage and becomes a second leaf with its own identity. It connects to the same anchor.

5. Send a message

In the localhost tab, select and copy the did:nostr:… it shows. In the 127.0.0.1 tab, paste it into the first box, type a message in the second, and press Send.

The message is encrypted in the 127.0.0.1 tab to the localhost leaf’s key, wrapped in a DIDComm forward, and handed to the anchor, which holds it (forward message queued for recipient … in its terminal).

Switch to the localhost tab and press Check for messages. The message appears in its inbox, with the sender’s identity. (A leaf also checks by itself when its tab comes back into view.)

6. Clean up

Stop the dev server and the anchor with Ctrl-C. The leaves’ identities stay in each origin’s IndexedDB; clear the site data in the browser to forget them. Delete the leaf-tutorial directory when you are done.

What you did

  • Ran an anchor node that mediates leaves.

  • Built a web page that is a leaf, with startBrowserLeaf from @fleetmesh/leaf.

  • Sent an end-to-end encrypted message between two leaves, through a mediator that carried it but could not read it.

The same page works against any anchor: point MEDIATOR at a public node’s wss:// face and its key. @fleetmesh/leaf also does NIP-77 set reconciliation (hub.reconcile); its README covers the rest.