Verstak Browser Extension

Verstak Browser Extension captures pages, selected text, links, and selected files and sends them to a local Verstak browser inbox receiver.

The extension does not know Notes, Files, Activity, or Journal internals. It only sends capture events through the public local receiver protocol. If the receiver is offline, captures stay in the extension pending queue.

Alpha software. Use with a matching Verstak Desktop alpha release.

Build

npm ci
npm test
npm run build

Build output:

• dist/chromium
• dist/firefox

Load dist/chromium as an unpacked extension in Chromium-based browsers, or load dist/firefox temporarily in Firefox during development.

Passive domain activity

Passive tracking is off by default. On first use the extension explains what it records; the user must explicitly enable it in extension settings.

When enabled, it observes only the focused browser's active tab and sends bounded aggregate intervals as a canonical domain name plus duration. It never sends URL paths, page titles, page text, selected text, keystrokes, navigation history or inactive-tab time. The settings screen has an exclusion list for domains such as youtube.com or x.com.

Manual “Send page”, selection, link and file actions are separate. They create Browser Inbox captures; they do not create a workspace or a journal entry.

Firefox download and updates

The signed XPI is published on the GitHub Releases page. Download the Firefox asset named verstak-firefox-<version>.xpi from the latest release and open it in Firefox to install it.

After the first public release, installed copies check GitHub Releases for updates through the release's updates.json asset. During the alpha phase each published release is the current update channel.

Firefox release publishing

Firefox signing uses web-ext and AMO credentials from an env file. The script requires WEB_EXT_API_PROXY; AMO upload and approval polling run through that proxy.

Create the signed XPI locally, without publishing it:

VERSTAK_BROWSER_ENV=/path/to/.env npm run release:firefox

Publish the signed XPI and updates.json as the current GitHub Release:

VERSTAK_BROWSER_ENV=/path/to/.env npm run publish:github

The publisher reads the version from package.json and requires an authenticated GitHub CLI plus a clean local main equal to origin/main. It creates and pushes the version tag if needed, then creates or updates the GitHub Release. Re-running it for the same tag replaces the XPI and updates.json assets. npm run publish:firefox remains as a compatible alias for the same Firefox publishing flow.

For an explicit version check, pass the current tag after --:

VERSTAK_BROWSER_ENV=/path/to/.env npm run publish:github -- v2.0.3

Release output:

• release/firefox/verstak-firefox-<version>.xpi
• release/firefox/updates.json

The XPI is signed as an unlisted/self-distributed Firefox extension; GitHub Releases distribute that signed file. Build and release artifacts are local outputs and are not committed.

Reproducible local package

npm run release:package -- v0.1.0-alpha.1

This runs the tests and build, then writes unsigned Chromium and Firefox source packages to release/ with a SHA256SUMS file. Use release:firefox above when an AMO-signed XPI is required.

Manual Check

1. Start Verstak desktop with the verstak.browser-inbox plugin installed.
2. Open the Browser Inbox workspace item so it subscribes to capture events.
3. Install/load dist/firefox or the signed XPI in Firefox.
4. Use the popup Send Page or Send File actions, or use page context menu actions for selection/link captures.

Local Receiver Protocol

Default endpoint:

POST http://127.0.0.1:47731/api/browser-inbox/v1/captures

Headers:

• Content-Type: application/json
• X-Verstak-Receiver-Token: <token> required when the desktop receiver is in paired mode

Pairing

1. In Verstak Desktop, open the Browser Inbox settings panel.
2. Copy the Receiver URL and Pairing Token.
3. Paste both values into the extension popup settings and select Save.

Rotating the token in Desktop invalidates the value stored by the extension.

Language

The popup settings provide a persisted System / English / Russian language selector. System follows the browser UI language: Russian browser locales use Russian, and all other locales use English.

The extension and desktop application store their language choices independently. Changing one does not change the other.

Payload:

{
  "schemaVersion": 1,
  "captureId": "uuid-or-generated-id",
  "capturedAt": "2026-06-27T00:00:00.000Z",
  "source": "verstak-browser-extension",
  "kind": "page",
  "page": {
    "url": "https://example.com/article",
    "title": "Example Article",
    "domain": "example.com"
  },
  "browser": {
    "name": ""
  }
}

Supported kind values:

• page
• selection, with selection.text
• link, with link.url and optional link.text
• file, with file.name and either file.dataBase64 for selected files up to 8 MB or file.text for text-compatible captures

Expected success response:

{ "status": "accepted", "captureId": "uuid-or-generated-id" }

License

Copyright © 2026 Verstak contributors. Licensed under GNU AGPLv3 or later.