170 lines
5.1 KiB
Markdown
170 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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](https://github.com/mirivlad/verstak-browser-extension/releases).
|
|
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 and publish it, together with `updates.json`, as the
|
|
current GitHub Release:
|
|
|
|
```bash
|
|
VERSTAK_BROWSER_ENV=/path/to/.env npm run publish:firefox
|
|
```
|
|
|
|
The first invocation publishes tag `v2.0.3` and bootstraps the
|
|
`releases/latest/download/updates.json` endpoint. Re-running the command
|
|
replaces those two release assets for the same tag.
|
|
|
|
To sign and prepare release files locally without changing GitHub:
|
|
|
|
```bash
|
|
VERSTAK_BROWSER_ENV=/home/mirivlad/git/verstak/.env npm run release:firefox
|
|
```
|
|
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{ "status": "accepted", "captureId": "uuid-or-generated-id" }
|
|
```
|
|
|
|
## License
|
|
|
|
Copyright © 2026 Verstak contributors. Licensed under
|
|
[GNU AGPLv3 or later](LICENSE).
|