verstak-docs/docs/superpowers/plans/2026-06-29-browser-receiver-pairing.md

# Browser Receiver Pairing Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a token-based pairing gate to the local browser capture receiver.

**Architecture:** Keep Browser Inbox as a plugin. Add a transport-level token option to `internal/core/browserreceiver`, preserve the open constructor for current development behavior, and document the extension header contract.

**Tech Stack:** Go desktop core package tests, browser extension protocol docs, Markdown docs.

## Global Constraints

- Do not move Browser Inbox queues or conversion workflows into desktop core.
- Preserve existing receiver behavior when no token is configured.
- Paired mode must not publish capture events for missing or wrong tokens.
- Use TDD: write the failing Go receiver test first, run it red, then implement.
- Commit and push each affected repository after meaningful changes.

---

### Task 1: Document The Pairing Contract

**Files:**
- Create: `/home/mirivlad/git/verstak2/verstak-docs/docs/superpowers/specs/2026-06-29-browser-receiver-pairing-design.md`
- Create: `/home/mirivlad/git/verstak2/verstak-docs/docs/superpowers/plans/2026-06-29-browser-receiver-pairing.md`

**Interfaces:**
- Produces documented `X-Verstak-Receiver-Token` pairing contract.

- [ ] **Step 1: Write spec and plan**

Write the design and this implementation plan.

- [ ] **Step 2: Verify docs**

Run:

```bash
cd /home/mirivlad/git/verstak2/verstak-docs
git diff --check
```

Expected: exits 0.

- [ ] **Step 3: Commit and push docs**

Run:

```bash
cd /home/mirivlad/git/verstak2/verstak-docs
git add docs/superpowers/specs/2026-06-29-browser-receiver-pairing-design.md docs/superpowers/plans/2026-06-29-browser-receiver-pairing.md
git commit -m "docs: plan browser receiver pairing"
git push
```

Expected: docs `main` is clean and pushed.

### Task 2: Desktop Receiver Token Gate

**Files:**
- Modify: `/home/mirivlad/git/verstak2/verstak-desktop/internal/core/browserreceiver/receiver_test.go`
- Modify: `/home/mirivlad/git/verstak2/verstak-desktop/internal/core/browserreceiver/receiver.go`

**Interfaces:**
- Produces:
  - `type Options struct { RequireToken bool; ReceiverToken string }`
  - `func NewWithOptions(bus *events.Bus, options Options, providers ...WorkspaceProvider) *Receiver`

- [ ] **Step 1: Write the failing tests**

Add tests proving missing/wrong token rejection and correct token acceptance.

- [ ] **Step 2: Run RED**

Run:

```bash
cd /home/mirivlad/git/verstak2/verstak-desktop
go test ./internal/core/browserreceiver
```

Expected: fails because `Options` / `NewWithOptions` do not exist.

- [ ] **Step 3: Implement token gate**

Add `Options`, `NewWithOptions`, header validation, and constant-time token
comparison. Keep `New` behavior unchanged.

- [ ] **Step 4: Run GREEN**

Run:

```bash
cd /home/mirivlad/git/verstak2/verstak-desktop
go test ./internal/core/browserreceiver
go test ./internal/core/...
```

Expected: both commands exit 0.

- [ ] **Step 5: Commit and push desktop**

Run:

```bash
cd /home/mirivlad/git/verstak2/verstak-desktop
git add internal/core/browserreceiver/receiver.go internal/core/browserreceiver/receiver_test.go
git commit -m "feat: require token for paired browser receiver"
git push
```

Expected: commit is pushed. Existing unrelated `frontend/wailsjs/go/models.ts`
remains unstaged.

### Task 3: Extension And Roadmap Docs

**Files:**
- Modify: `/home/mirivlad/git/verstak2/verstak-browser-extension/README.md`
- Modify: `/home/mirivlad/git/verstak2/verstak-docs/05_Official_Plugins.md`
- Modify: `/home/mirivlad/git/verstak2/verstak-docs/07_Full_Implementation_Roadmap.md`

**Interfaces:**
- Consumes verified receiver token gate.
- Produces docs matching implemented pairing behavior.

- [ ] **Step 1: Update extension README**

Change the receiver token header description from optional future work to:

```md
- `X-Verstak-Receiver-Token: <token>` required when the desktop receiver is in paired mode
```

- [ ] **Step 2: Verify and commit extension docs**

Run:

```bash
cd /home/mirivlad/git/verstak2/verstak-browser-extension
git diff --check
git add README.md
git commit -m "docs: describe receiver token pairing"
git push
```

Expected: extension `main` is clean and pushed.

- [ ] **Step 3: Update platform docs**

In `05_Official_Plugins.md`, describe that Browser Inbox receives captures
through the local receiver token pairing model. In
`07_Full_Implementation_Roadmap.md`, mark:

```md
- [x] define local receiver permission/pairing model;
```

- [ ] **Step 4: Verify and commit docs**

Run:

```bash
cd /home/mirivlad/git/verstak2/verstak-docs
git diff --check
rg -n "define local receiver permission/pairing model|X-Verstak-Receiver-Token" 05_Official_Plugins.md 07_Full_Implementation_Roadmap.md
git add 05_Official_Plugins.md 07_Full_Implementation_Roadmap.md
git commit -m "docs: mark browser receiver pairing complete"
git push
```

Expected: docs `main` is clean and pushed.