# Spec: Settings Tailscale Access Panel

> **Purpose:** Builder-facing BrainDrive product/engineering spec for adding a Tailscale access panel to Settings.
> **Generated from:** Product request on 2026-07-07, current BrainDrive settings/browser-access implementation review, and current Tailscale docs review.
> **Primary product surface:** Local-mode Settings modal, proposed `Tailscale Access` tab.
> **Recommendation:** V1 should support three owner-selected access intents: own trusted devices, someone else's device, and a public link. Own trusted devices should remain the safest default; the latter two require explicit warning-checkbox consent before the flow can continue.

## Overview

### What We're Building

Add a local-mode Settings panel that helps a BrainDrive owner connect their local BrainDrive to Tailscale so they can open BrainDrive from another trusted device outside the local machine, such as a phone, tablet, laptop, or desktop away from home.

The panel must be beginner-first. It should not assume the owner knows what a tailnet, MagicDNS, Serve, Funnel, CLI, port, or reverse proxy is. The panel should guide the owner through:

1. Understanding what Tailscale access means.
2. Installing/signing into Tailscale if needed.
3. Verifying that this BrainDrive computer is connected to a Tailscale network.
4. Enabling a BrainDrive remote access endpoint.
5. Copying or opening a working access address.
6. Testing from a second device.
7. Turning access off clearly.

The V1 product target is "BrainDrive from the place I choose, with BrainDrive making the risk clear before access is widened." The safest default is the owner's own trusted devices. Access from someone else's device and public-link access are supported only after explicit warning-checkbox consent.

### Why It Matters

BrainDrive is user-owned and can run locally. Local ownership is valuable, but it creates a usability gap: the owner often wants to reach their BrainDrive from another device without moving to hosted BrainDrive or learning networking. Current Browser Access supports this computer and private-network/LAN access in the desktop app, but it does not provide a guided remote-from-anywhere path for non-technical owners.

Tailscale can solve this by creating a private network across the owner's trusted devices. The product challenge is not merely invoking Tailscale; it is making the setup safe, explainable, reversible, and usable by someone who has never used Tailscale before.

### External Context Checked

- Tailscale quickstart: creating a tailnet, installing the client, adding devices, and MagicDNS recommendation: <https://tailscale.com/docs/how-to/quickstart>
- Tailscale MagicDNS: device names and tailnet DNS names: <https://tailscale.com/docs/features/magicdns>
- Tailscale Serve: tailnet-only sharing of local services: <https://tailscale.com/docs/features/tailscale-serve>
- Tailscale Serve CLI reference: <https://tailscale.com/docs/reference/tailscale-cli/serve>
- Tailscale Funnel: public internet routing to local services and beta status: <https://tailscale.com/docs/features/tailscale-funnel>
- Tailscale auth keys and OAuth clients for future automation evaluation: <https://tailscale.com/docs/features/access-control/auth-keys>, <https://tailscale.com/docs/features/oauth-clients>

### Target Audience And Stakeholders

| Audience | Role / Need |
|---|---|
| Local BrainDrive owner, non-technical | Wants to reach BrainDrive from another personal device without learning networking vocabulary or weakening security accidentally. |
| Local BrainDrive owner, technical | Wants status, addresses, diagnostics, and a clean on/off control without hiding the real network behavior. |
| Builder / implementation owner | Maintains Settings UI, Tauri desktop integration, Browser Access bridge interaction, gateway trust boundaries, Tailscale detection, and tests. |
| QA / harness audience | Verifies beginner setup flows, local-only/desktop-only visibility, error handling, off-switch behavior, and no auth/secrets regressions. |
| Operator / maintainer | Diagnoses Tailscale setup failures through safe local status and logs without collecting Tailscale credentials or BrainDrive secrets. |

### Success Definition

The Tailscale Access panel is successful when a local desktop owner can:

1. Open Settings and understand whether Tailscale Access is off, ready, needs setup, running, or needs attention.
2. Start from no Tailscale knowledge and complete a guided setup that tells them what to install, where to sign in, and how to add a second device.
3. Enable a private Tailscale address for BrainDrive without manually choosing bind addresses, firewall rules, or reverse proxy commands.
4. Use a copied or opened Tailscale address from another trusted device and reach the normal BrainDrive login/app experience.
5. Turn off Tailscale Access and verify the address no longer works through the managed endpoint.
6. Understand the difference between access from their own trusted devices, access from someone else's device, and a public link anyone can open.

The work is not successful if:

1. The owner has to understand CLI syntax, MagicDNS, tailnets, Serve, Funnel, ports, or firewall rules to complete the default flow.
2. BrainDrive is exposed to someone else's device or the public internet without an explicit warning checkbox.
3. Tailscale credentials, OAuth client secrets, auth keys, BrainDrive owner API keys, or BrainDrive auth secrets are stored in memory, returned to the client, or logged.
4. Managed-hosted mode shows local Tailscale controls.
5. Enabling Tailscale Access bypasses BrainDrive authentication, authorization, CSRF/CORS expectations, or local account setup requirements.
6. Turning the feature off leaves a stale BrainDrive endpoint advertised through Tailscale without a clear warning and remediation.

### Definition Of Done (V1)

When V1 is done-done, it can:

1. Render a local-mode desktop-only Settings tab for Tailscale Access.
2. Detect and display Tailscale readiness states: not installed, installed but signed out, connected, Serve unavailable/unsupported, endpoint running, endpoint stopped, and endpoint failed.
3. Provide beginner-safe setup guidance for installing Tailscale, signing in, adding another device, and retrying detection.
4. Enable the selected access mode using the existing BrainDrive desktop Browser Access bridge or an equivalent local bridge that preserves current auth/rate-limit/security behavior.
5. Require explicit warning-checkbox consent before enabling `Someone else's device` or `A public link anyone can open`.
6. Display one or more owner-usable addresses, preferring a stable MagicDNS/HTTPS address when available.
7. Provide `Copy`, `Open`, `Test again`, `Restart`, and `Turn off` controls with clear state changes.
8. Verify that the owner has created the local BrainDrive account before enabling remote access.
9. Include automated unit/integration coverage for state mapping, API contracts, warning consent, and UI states; include manual cross-device verification evidence for at least one supported OS.

Explicitly not required for V1:

- Fully automated Tailscale account creation. Recommendation: use Tailscale's normal sign-up/login flow rather than handling identity-provider credentials inside BrainDrive.
- Tailscale OAuth/client-secret automation. Recommendation: defer until there is a concrete need to manage tailnet API resources; V1 should avoid collecting long-lived Tailscale admin credentials.
- Multi-user sharing policy management and ACL editing. Recommendation: link to Tailscale admin docs; do not edit tailnet policy in BrainDrive V1.
- Mobile app deep integration. Recommendation: V1 only guides the owner to install/sign into Tailscale on the second device and test the URL.
- Docker/headless/server automation. Recommendation: specify separately because desktop Tauri assumptions and service permissions differ.

## Product Behavior

### User / System Experience

The owner opens Settings in the BrainDrive desktop app and sees a new local-only tab labeled `Tailscale Access`. The tab is shown only when BrainDrive is running locally in the desktop shell. It is hidden in managed mode and unavailable in a normal browser-only client if desktop commands cannot run.

The panel should be structured around one primary question: "Can I open this BrainDrive from my trusted devices?"

The owner should see:

1. A status card with the current connection state.
2. A short explanation of private Tailscale access in plain language.
3. A guided setup checklist with only the next relevant action visible or emphasized.
4. A safe enable/disable control.
5. The active address once available.
6. A test checklist for using a phone/tablet/other computer.
7. Troubleshooting messages that map technical failures to owner actions.

The panel should avoid making the owner choose low-level network settings in the default path. Advanced diagnostics can show details such as detected Tailscale version, hostname, tailnet DNS name, selected local bridge port, and raw command status, but those details should not be required to complete setup.

### Recommended V1 Access Model

V1 should support three owner-selected access modes:

1. **My own phone, tablet, or laptop**
   - Safest default.
   - Uses private Tailscale access for devices signed into the owner's tailnet.
   - No extra risk checkbox is required beyond normal enable consent.

2. **Someone else's device**
   - Supported only after a warning checkbox.
   - Intended for temporary access where the owner understands the other device may be less trusted.
   - The UI must warn the owner to use a device they trust, avoid saving credentials, sign out when finished, and turn off the access mode after use.

3. **A public link anyone can open**
   - Supported only after a stronger warning checkbox.
   - This is materially different from private Tailscale access because anyone with the link can reach the BrainDrive login surface while the link is active.
   - The UI must show a persistent public-access state, require BrainDrive authentication, and keep the off switch visible.

Private trusted-device access should work like this:

1. BrainDrive starts or reuses a local Browser Access bridge bound to localhost.
2. Tailscale Serve or an equivalent Tailscale-supported local service proxy exposes that local bridge to the owner's tailnet.
3. Other devices signed into the same tailnet can open BrainDrive through the Tailscale address.
4. Devices not in the tailnet cannot reach the endpoint.
5. BrainDrive login/auth still applies after the network connection succeeds.

Someone-else/public-link access must preserve the same BrainDrive auth requirement, but the access mode must be visibly different from the safest default.

### Beginner Setup Interview / Wizard Shape

This is the product interview/setup flow that should shape the panel. It is written as the user's experience, not as an AI chat interview requirement.

1. **Need framing**
   - Ask/show: "Where do you want to use BrainDrive?"
   - Recommended choices:
     - `My own phone, tablet, or laptop`
     - `Someone else's device`
     - `A public link anyone can open`
   - V1 supports all three choices.
   - `My own phone, tablet, or laptop` continues without an extra risk checkbox.
   - If `Someone else's device` is selected, require a checkbox before continuing:
     - `I understand this device may not be fully under my control. I will only use a device I trust, avoid saving my BrainDrive sign-in, sign out when finished, and turn off this access when I am done.`
   - If `A public link anyone can open` is selected, require a stronger checkbox before continuing:
     - `I understand anyone with this link can reach my BrainDrive sign-in while the link is on. BrainDrive sign-in is still required, but this exposes my BrainDrive login surface to the public internet. I will turn it off when I am done.`

2. **Tailscale familiarity**
   - Ask/show: "Do you already use Tailscale?"
   - Choices:
     - `No, help me set it up`
     - `Yes, I already have it`
   - If no, show install/sign-in steps and explain Tailscale as "a private network for your own trusted devices."
   - If yes, skip to detection and verification.

3. **Install and sign in**
   - Detect whether Tailscale is installed on the BrainDrive computer.
   - If missing, show OS-specific install action and a `Check again` button.
   - If installed but signed out, show `Open Tailscale` / `Sign in to Tailscale` action and a `Check again` button.
   - Do not ask for Tailscale passwords, auth keys, OAuth client secrets, or admin tokens.

4. **Add the second device**
   - Explain that each device must be signed into Tailscale.
   - Provide a short checklist:
     - Install Tailscale on the second device.
     - Sign in with the same Tailscale account.
     - Return here and continue.
   - Include a Tailscale download/admin link as help, not as a hidden prerequisite.

5. **Enable BrainDrive access**
   - Show a single primary action: `Enable Tailscale Access`.
   - On click, BrainDrive verifies local account setup, starts the bridge, configures the Tailscale endpoint, and returns an address.
   - The owner should not need to pick a port or command.

6. **Test**
   - Show: "On your other device, open this address while Tailscale is connected."
   - Provide copy/open actions.
   - Provide a manual confirmation checkbox or button: `I reached BrainDrive from another device`.
   - Store only a harmless local `last_successfully_tested_at` timestamp if persistence is needed.

7. **Manage**
   - Show the endpoint state and address.
   - Provide `Copy`, `Open`, `Restart`, and `Turn off`.
   - If off, explain that existing browsers may need refresh and that the address should stop working shortly.

8. **Higher-risk access confirmation**
   - If the owner selected `Someone else's device`, keep a visible reminder that this mode is for temporary use on a trusted borrowed device.
   - If the owner selected `A public link anyone can open`, keep a visible public-access badge and warning while the link is active.
   - Both modes must keep `Turn off` visible near the active address.

### Primary Flows

1. **First-time owner with no Tailscale installed**
   - Owner opens Settings.
   - Owner selects `Tailscale Access`.
   - Panel detects Tailscale is not installed or not callable.
   - Panel explains Tailscale in one sentence and offers OS-specific install/open docs action.
   - Owner installs Tailscale and signs in through Tailscale.
   - Owner clicks `Check again`.
   - Panel detects Tailscale is connected and moves to enable flow.

2. **Owner already has Tailscale**
   - Owner opens the panel.
   - Panel detects Tailscale connected state, device name, and available service capability.
   - Panel shows `Ready to enable`.
   - Owner clicks `Enable Tailscale Access`.
   - BrainDrive starts/reuses local bridge, configures private tailnet endpoint, and shows the address.

3. **Remote device test**
   - Owner copies the Tailscale address.
   - Owner opens the address on another device signed into the same tailnet.
   - BrainDrive login/app loads.
   - Owner marks the test complete in the panel or simply sees status remain running after `Test again`.

4. **Use someone else's device**
   - Owner chooses `Someone else's device` in need framing.
   - Panel shows the borrowed-device warning and disables continue until the owner checks the acknowledgement box.
   - BrainDrive enables the selected access path only after acknowledgement.
   - Running state keeps a temporary-use warning visible near the address.
   - Panel emphasizes signing out and turning access off when done.

5. **Create a public link**
   - Owner chooses `A public link anyone can open` in need framing.
   - Panel shows the public-link warning and disables continue until the owner checks the acknowledgement box.
   - BrainDrive enables the public access path only after acknowledgement.
   - Running state shows a persistent public-access badge and keeps `Turn off` visible near the address.
   - BrainDrive authentication remains required when the public link is opened.

6. **Turn off access**
   - Owner clicks `Turn off`.
   - BrainDrive disables the Tailscale endpoint and stops or detaches the bridge if it was started only for Tailscale.
   - Panel updates to `Off`.
   - The previously displayed address is removed or marked inactive.

7. **Recover from endpoint failure**
   - Tailscale endpoint setup fails because Serve is unavailable, HTTPS is not enabled, user consent is required, or Tailscale is not connected.
   - Panel shows one clear next action.
   - No partial "enabled" state is shown.
   - Owner can retry after fixing the Tailscale issue.

### Secondary Flows

- If the local BrainDrive account is not created, enabling is blocked with a message to create the local account first.
- If Tailscale is installed but the CLI is not on PATH, the panel should try platform-appropriate detection paths or show "Tailscale is installed but BrainDrive cannot find it" with manual remediation.
- If MagicDNS is disabled or a stable DNS name cannot be found, the panel may show a tailnet IP-based fallback only if it remains private to the tailnet and the UX explains that the address may be less friendly.
- If the local bridge port is unavailable, BrainDrive should select from the existing Browser Access fallback range or report the conflict in plain language.
- If the owner is offline, the panel should distinguish "no internet/Tailscale disconnected" from "BrainDrive endpoint failed."
- If another device is not signed into Tailscale, the endpoint may work locally but fail remotely; the panel should guide the owner to install/sign into Tailscale on that device.
- If `Someone else's device` is selected, the enable action must remain disabled until the borrowed-device warning checkbox is checked.
- If `A public link anyone can open` is selected, the enable action must remain disabled until the public-link warning checkbox is checked.
- If the Tailscale Serve command requires web consent, the panel should open the consent URL or display it with copy/open controls.
- If the owner changes their Tailscale machine name, the displayed address should refresh.
- If Tailscale is uninstalled after setup, the panel should show `Needs setup` and offer cleanup/turn-off.
- If BrainDrive restarts, the endpoint should reconcile to the saved desired state or show a clear "not running; restart access" state.

### UX / Trust Bar

- The owner must understand that Tailscale Access lets trusted Tailscale devices reach this local BrainDrive.
- The owner must understand that each device must be signed into Tailscale.
- The owner must understand when they are using their own trusted devices, someone else's device, or a public link.
- The UI must avoid jargon in primary copy. Acceptable primary words: `trusted devices`, `this computer`, `another device`, `private Tailscale network`, `address`.
- Jargon such as `tailnet`, `MagicDNS`, `Serve`, `Funnel`, `ACL`, `CLI`, and `port` belongs in expandable details or advanced diagnostics.
- The panel must always provide a clear off switch.
- The panel must never imply Tailscale replaces BrainDrive login.
- Any action that increases exposure beyond the owner's own trusted devices must require explicit owner action and warning-checkbox consent.
- Errors must be actionable: state what happened, what the owner can do, and whether BrainDrive is currently reachable remotely.

## User Stories

### US-1: Understand The Safe Default - **Open**

As a local BrainDrive owner, I want Settings to explain Tailscale Access in plain language so I know whether it solves my "use BrainDrive elsewhere" problem.

**Source:** Product request, 2026-07-07.

**Acceptance Criteria:**

```gherkin
Given BrainDrive is running in local desktop mode
When the owner opens Settings
Then a Tailscale Access tab is available
And the panel asks whether they want access from their own device, someone else's device, or a public link
And the panel identifies own trusted devices as the safest default
And the panel requires warning-checkbox consent for someone else's device or a public link
```

```gherkin
Given BrainDrive is running in managed mode
When the owner opens Settings
Then the Tailscale Access tab is not shown
```

**Recommendation:** Confirm this as V1. The product should support all three intents while making the risk difference explicit before setup continues.

### US-2: Guided Setup For A New Tailscale User - **Open**

As a local BrainDrive owner who has never used Tailscale, I want step-by-step setup inside Settings so I can connect without searching docs or learning networking.

**Acceptance Criteria:**

```gherkin
Given Tailscale is not detected on the BrainDrive computer
When the owner opens Tailscale Access
Then the panel shows an install/sign-in checklist
And the panel provides an OS-appropriate install or download action
And the primary action is Check again, not Enable
```

```gherkin
Given Tailscale is installed but signed out
When the owner opens Tailscale Access
Then the panel asks the owner to sign into Tailscale
And BrainDrive does not ask for Tailscale credentials directly
```

```gherkin
Given Tailscale is connected
When the owner clicks Check again
Then the panel moves to Ready to enable
```

**Recommendation:** Confirm for V1. This is the main product differentiator versus simply documenting a command.

### US-3: Enable Private Tailscale Access - **Open**

As a local BrainDrive owner, I want one button to enable BrainDrive through Tailscale so I can open it from my other trusted devices.

**Acceptance Criteria:**

```gherkin
Given Tailscale is connected
And the local BrainDrive account is initialized
When the owner clicks Enable Tailscale Access
Then BrainDrive starts or reuses a local access bridge
And configures a private tailnet-only endpoint
And displays at least one usable Tailscale address
And the address requires normal BrainDrive authentication when opened
```

```gherkin
Given the local BrainDrive account is not initialized
When the owner clicks Enable Tailscale Access
Then the action is blocked
And the panel tells the owner to create the local BrainDrive account first
And no Tailscale endpoint is configured
```

**Recommendation:** Confirm for V1. Prefer Tailscale Serve/private endpoint over binding BrainDrive directly to all network interfaces.

### US-4: Copy And Test From Another Device - **Open**

As a BrainDrive owner, I want the panel to help me test from my phone or another computer so I know setup worked.

**Acceptance Criteria:**

```gherkin
Given Tailscale Access is running
When the panel shows the access address
Then it provides Copy and Open controls
And it shows a short checklist for opening the address on another device signed into Tailscale
```

```gherkin
Given the owner cannot reach BrainDrive from the second device
When they open troubleshooting
Then the panel suggests checking that Tailscale is installed, signed in, and connected on the second device
And it does not tell the owner to modify router port forwarding
```

**Recommendation:** Confirm for V1. The test flow is necessary for non-technical confidence.

### US-5: Turn Off Tailscale Access - **Open**

As a local BrainDrive owner, I want a clear off switch so I can stop remote access when I do not need it.

**Acceptance Criteria:**

```gherkin
Given Tailscale Access is running
When the owner clicks Turn off and confirms if needed
Then BrainDrive disables the Tailscale endpoint
And the panel shows Off
And stale active addresses are removed or marked inactive
```

```gherkin
Given disabling the endpoint fails
When the panel reports the error
Then it tells the owner whether the endpoint may still be reachable
And it provides a retry or manual cleanup path
```

**Recommendation:** Confirm for V1. A trustworthy off switch is mandatory because this feature changes network reachability.

### US-6: Restart Or Repair Access - **Open**

As a local BrainDrive owner, I want BrainDrive to tell me what to do when Tailscale Access stops working.

**Acceptance Criteria:**

```gherkin
Given Tailscale Access was previously enabled
When BrainDrive starts
Then the panel reconciles the saved desired state with actual Tailscale endpoint state
And shows Running, Off, Needs setup, or Needs attention
```

```gherkin
Given Tailscale is disconnected
When the owner views the panel
Then the panel says Tailscale is disconnected
And offers Check again after reconnecting
And does not claim BrainDrive is reachable remotely
```

**Recommendation:** Confirm for V1. Without reconciliation, restarts will create confusing stale states.

### US-7: Borrowed Device Warning - **Open**

As a BrainDrive owner, I want a clear warning before using BrainDrive from someone else's device so I do not accidentally leave my local AI system reachable or signed in on a device I do not fully control.

**Acceptance Criteria:**

```gherkin
Given the owner chooses Someone else's device
When the setup flow reaches risk acknowledgement
Then the panel explains that the device may not be fully under the owner's control
And the Continue or Enable action is disabled until the owner checks the warning acknowledgement
```

```gherkin
Given the owner checked the borrowed-device warning acknowledgement
When the borrowed-device access mode is running
Then the panel keeps a temporary-use warning visible
And the panel keeps Turn off visible near the active address
And BrainDrive authentication is still required when the address is opened
```

**Recommendation:** Confirm for V1. This supports the requested use case while making the risk concrete for non-technical owners.

### US-8: Public Internet Link Warning - **Open**

As a BrainDrive owner, I may want a link that anyone can open, but I need BrainDrive to warn me before exposing my local AI system publicly.

**Acceptance Criteria:**

```gherkin
Given the owner chooses a public link or asks for public access
When V1 is installed
Then the panel explains that anyone with the link can reach the BrainDrive sign-in surface while the link is on
And the Continue or Enable action is disabled until the owner checks the public-link warning acknowledgement
And BrainDrive authentication is still required when the public link is opened
```

```gherkin
Given public-link access is running
When the owner views the Tailscale Access panel
Then the panel shows a persistent public-access badge
And Turn off is visible near the active address
And the panel does not present public access as the safest default
```

**Recommendation:** Confirm for V1 only with explicit warning-checkbox consent, persistent public state, BrainDrive auth enforcement, and a visible off switch.

### US-9: Advanced Diagnostics - **Open**

As a technical owner or maintainer, I want enough diagnostics to troubleshoot without exposing secrets.

**Acceptance Criteria:**

```gherkin
Given the owner opens advanced details
When Tailscale Access has status data
Then the panel may show Tailscale version, device name, tailnet DNS suffix, endpoint state, local bridge port, and last non-secret error
And it must not show auth keys, OAuth secrets, BrainDrive tokens, or raw credential-bearing commands
```

**Recommendation:** Include minimal diagnostics in V1 behind an expandable details control.

## Requirements

### Functional Requirements

- [ ] Add a `Tailscale Access` Settings tab for local desktop mode only.
- [ ] Hide the tab in managed mode.
- [ ] Hide or disable the tab with a clear message when not running inside the desktop/Tauri shell.
- [ ] Detect whether Tailscale is available on the host.
- [ ] Detect whether the host is signed into and connected to Tailscale.
- [ ] Detect or derive a friendly device address, preferring MagicDNS/HTTPS when available.
- [ ] Start or reuse the BrainDrive local Browser Access bridge without exposing the gateway directly.
- [ ] Configure the endpoint that matches the selected access mode: own trusted device, someone else's device, or public link.
- [ ] Require borrowed-device warning acknowledgement before configuring `Someone else's device`.
- [ ] Require public-link warning acknowledgement before configuring `A public link anyone can open`.
- [ ] Return structured status to the UI: desired enabled state, actual running state, Tailscale readiness, endpoint URL(s), local bridge status, last error, and safe diagnostics.
- [ ] Provide beginner setup guidance for installing/signing into Tailscale and adding another device.
- [ ] Provide copy/open/test controls for the active address.
- [ ] Provide restart/reconcile and turn-off controls.
- [ ] Persist only safe local settings needed to reconcile desired state after restart.
- [ ] Preserve existing Browser Access behavior for this-computer and private-network/LAN access unless the user explicitly changes those settings.
- [ ] Never require a BrainDrive-owned Tailscale account, API key, or provider key.

### AI / Model / Tool Behavior

- [ ] No model behavior is required for V1.
- [ ] If future AI help text is added, it must not invent Tailscale state; it must use status returned by local system checks.
- [ ] If future agent tools can manage Tailscale Access, they must require explicit owner approval before enabling, disabling, or changing network exposure.

### Data, Memory, And Artifact Contracts

| Data / Artifact | Source | Owner | Read/Write Rules | Retention / Migration |
|---|---|---|---|---|
| Tailscale Access settings | Desktop app local config | Local BrainDrive runtime | Store desired enabled state, selected mode, last known safe URL, and timestamps only. No Tailscale credentials. | Local machine config; not owner memory; migration behavior TBD. |
| Tailscale status | Local Tailscale client/CLI/system service | Tailscale owner account | Read status only. Do not persist raw status dumps if they include unnecessary machine/user metadata. | Runtime only except sanitized last status fields. |
| BrainDrive bridge status | Desktop Browser Access bridge | BrainDrive runtime | Read/write through desktop commands. Preserve transport secret handling. | Existing Browser Access config remains separate unless build plan intentionally unifies. |
| Endpoint URL | Tailscale Serve/status or derived MagicDNS/IP | Local runtime | Display/copy to owner. Persist last known URL only if useful for stale-state messaging. | Safe to persist locally; avoid writing to memory by default. |
| Last successful test timestamp | Owner action | Local runtime | Optional write when owner confirms remote test. | Local config only; not required for migration. |
| Logs | Desktop/runtime logs | BrainDrive runtime | Log status transitions and sanitized errors. Never log credentials, session tokens, auth keys, or OAuth secrets. | Existing log retention policy. |

### BrainDrive Page Context And Write Placement

N/A. This is a Settings/system feature, not a BrainDrive page, built-in journaling feature, to-do item, or owner-memory workflow.

### Interface / UX Requirements

- [ ] Use existing Settings modal visual patterns, dark-mode design tokens, 8px-or-less radius conventions, and lucide icons.
- [ ] Keep the first screen state-driven: the panel should show the current status and next action, not a documentation wall.
- [ ] Use plain-language labels:
  - `Off`
  - `Needs setup`
  - `Ready to enable`
  - `Running`
  - `Needs attention`
- [ ] Use "trusted devices" copy before introducing "tailnet."
- [ ] Show only one primary action for the current state.
- [ ] Make `Turn off` visible whenever access is running or partially configured.
- [ ] Include a concise "What this does" disclosure:
  - "Devices signed into your Tailscale network can reach this BrainDrive address."
  - "BrainDrive sign-in is still required."
  - "Public links require an extra warning step."
- [ ] Include advanced details behind disclosure, not in the default path.
- [ ] Avoid requiring the owner to edit ports, firewall rules, terminal commands, or router settings in the default path.
- [ ] Visually separate public-link access from private trusted-device access and require a stronger warning style.
- [ ] Require checkbox acknowledgement before continuing from `Someone else's device`.
- [ ] Require checkbox acknowledgement before continuing from `A public link anyone can open`.
- [ ] All actionable controls must have loading, success, error, disabled, and retry states.
- [ ] Address rows must support copy and external open, matching current Browser Access patterns.
- [ ] Text must fit in the existing Settings modal at desktop and narrow widths.

### Observability / Evidence Requirements

- [ ] Status endpoint/command result includes sanitized state fields sufficient for UI and tests.
- [ ] Runtime logs record enable, disable, restart, and reconciliation attempts without secrets.
- [ ] Errors preserve enough detail for support: missing Tailscale, signed out, disconnected, Serve unavailable, consent required, port unavailable, bridge failed, endpoint cleanup failed.
- [ ] Manual verification evidence for V1 must include screenshots or a short recording of:
  - first-run setup state,
  - running state with URL,
  - remote-device access,
  - disabled state.

## Scope

### Work Type

- [x] **V1** - First usable version with clear acceptance criteria.
- [x] **Interface / shell** - Settings UI and desktop runtime commands.
- [x] **BrainDrive core/foundation** - Local access/auth/network boundary.
- [x] **Testing / harness** - UI state tests, desktop command tests where available, manual cross-device verification.
- [x] **Production** - Public-link access is in V1 only with explicit warning consent, visible state, auth enforcement, and shutdown controls.

### Implementation Location / Ownership

- [x] **Interface / shell** - `builds/typescript/client_web/src/components/settings/SettingsModal.tsx` or extracted Settings panel components.
- [x] **Client API integration** - `builds/typescript/client_web/src/api/`.
- [x] **Desktop shell** - `builds/typescript/src-tauri/`.
- [x] **Desktop bridge** - Existing `builds/typescript/desktop/bridge.ts` behavior as needed.
- [x] **Gateway/auth boundary** - Existing gateway auth/rate-limit/CORS behavior must continue to apply.
- [x] **Documentation/specification** - This spec and downstream test/build plans.

### Included

- New Settings panel for Tailscale Access.
- Beginner-oriented install/sign-in/add-device guidance.
- Local Tailscale detection and safe status reporting.
- Private tailnet-only endpoint enable/disable/restart/reconcile.
- Borrowed-device access mode with warning-checkbox acknowledgement.
- Public-link access mode with stronger warning-checkbox acknowledgement and persistent public-access state.
- Address display/copy/open/test guidance.
- Safe diagnostics.
- Focused tests and manual cross-device verification.

### Explicitly Excluded

- Public access without explicit warning-checkbox consent -> Out of scope.
- Router port forwarding, UPnP, raw public IP exposure, or non-Tailscale tunneling -> Out of scope.
- BrainDrive-managed Tailscale identity, OAuth client creation, auth key generation, or ACL editing -> Future automation only if justified.
- Managed-hosted BrainDrive remote access controls -> Separate hosted product surface.
- Replacing existing Browser Access LAN behavior -> Out of scope unless build plan explicitly unifies internals without UX regression.
- Removing Ollama/BYOK/provider/settings flows -> Out of scope.
- Tailscale SSH, subnet routing, exit nodes, Kubernetes operator, app connectors, Taildrop -> Out of scope.
- Mobile-native BrainDrive changes -> Out of scope for this Settings panel.

### Future Versions / Deepenings

- Public-link refinements such as time-limited links, one-click expiry timers, stronger account/session controls, and richer audit history.
- Headless/Docker/server setup path using auth keys or OAuth after a separate secrets/security design.
- Tailnet ACL helper or policy checker for owners who use advanced Tailscale policies.
- QR code for opening the private URL on mobile.
- In-app remote-device heartbeat/test endpoint that confirms a second device reached BrainDrive.
- Installer-time prompt: "Do you want to make this local BrainDrive reachable from your trusted Tailscale devices?"
- Support bundle export with sanitized Tailscale Access diagnostics.

## Invariants And Edge Cases

### Properties That Must Always Hold

- [ ] Tailscale Access is opt-in and off by default.
- [ ] Enabling Tailscale Access never disables BrainDrive authentication.
- [ ] Managed mode never exposes local Tailscale controls.
- [ ] The default path never creates public internet access without the public-link warning checkbox.
- [ ] `Someone else's device` access cannot be enabled until the borrowed-device warning checkbox is checked.
- [ ] `A public link anyone can open` access cannot be enabled until the public-link warning checkbox is checked.
- [ ] The UI never asks for or stores Tailscale account passwords.
- [ ] The UI never asks for or stores Tailscale auth keys/OAuth secrets in V1.
- [ ] BrainDrive-owned provider keys are never introduced into client config.
- [ ] Turning off access attempts to remove the endpoint and clearly reports if cleanup may be incomplete.
- [ ] Runtime state shown to the owner must distinguish desired state from actual reachability.
- [ ] Logs and client responses must not include session tokens, internal transport tokens, Tailscale credentials, or owner API keys.

### Edge Cases To Test

- [ ] Tailscale not installed.
- [ ] Tailscale installed but CLI unavailable to BrainDrive.
- [ ] Tailscale installed but signed out.
- [ ] Tailscale signed in but disconnected/offline.
- [ ] MagicDNS disabled or unavailable.
- [ ] Serve unavailable due to Tailscale version, OS support, HTTPS setting, consent requirement, or policy.
- [ ] Tailscale command returns a consent URL.
- [ ] Local BrainDrive account not initialized.
- [ ] Local bridge port unavailable; fallback range exhausted.
- [ ] Browser Access already enabled for LAN; Tailscale enabling must not silently weaken or alter it.
- [ ] Tailscale endpoint configured externally before BrainDrive tries to manage it.
- [ ] Endpoint enable succeeds but status read fails.
- [ ] Endpoint disable fails.
- [ ] BrainDrive restarts while Tailscale is running.
- [ ] Tailscale machine name changes.
- [ ] Second device is on the same tailnet but cannot resolve DNS.
- [ ] Second device is not on the tailnet.
- [ ] Borrowed-device warning checkbox is not checked.
- [ ] Public-link warning checkbox is not checked.
- [ ] Owner tries to use the URL after turning access off.
- [ ] Windows/macOS/Linux differences in Tailscale install path and CLI behavior.
- [ ] UI narrow-width wrapping for long MagicDNS names.

### Failure Modes

| Scenario | Expected Behavior |
|---|---|
| Tailscale is missing | Show `Needs setup`, explain install/sign-in, provide install link/action, disable enable button. |
| Tailscale is signed out | Show `Sign in to Tailscale`, open Tailscale/login flow if possible, provide `Check again`. |
| Tailscale is disconnected | Show disconnected state; do not claim remote reachability. |
| Serve setup requires consent | Show a consent-required state with open/copy action for the Tailscale consent URL. |
| Serve/private endpoint cannot be configured | Show one clear error and keep desired enabled state false unless the endpoint is known running. |
| Local account missing | Block enabling and route the owner to account setup. |
| Bridge fails | Show BrainDrive local bridge failure; do not blame Tailscale. |
| URL cannot be resolved | Show fallback address only if safe; otherwise show troubleshooting. |
| Disable cleanup fails | Show that access may still be reachable and provide retry/manual cleanup guidance. |
| Borrowed-device access requested without acknowledgement | Keep enable disabled and show the borrowed-device warning checkbox. |
| Public access requested without acknowledgement | Keep enable disabled and show the public-link warning checkbox. |
| System is unsure | Show `Needs attention` and ask the owner to retry/check Tailscale, rather than showing `Running`. |

## Technical Context

### Existing System Context

- **Current Settings modal:** `builds/typescript/client_web/src/components/settings/SettingsModal.tsx` defines tabs and local/managed/desktop visibility.
- **Current Browser Access tab:** local-only, desktop-only, uses Tauri commands from `builds/typescript/client_web/src/api/desktop-browser-access.ts`.
- **Current Browser Access behavior:** supports `thisComputer` and `privateNetwork` scopes, starts a desktop bridge, displays local/private network URLs, and gives firewall guidance.
- **Current desktop bridge:** `builds/typescript/desktop/bridge.ts` marks browser-access requests with internal transport headers.
- **Current gateway boundary:** gateway recognizes Browser Access requests through internal transport headers for client IP/rate-limit behavior; BrainDrive auth remains gateway-controlled.
- **Current Tauri code:** `builds/typescript/src-tauri/src/main.rs` manages Browser Access config, process startup, port selection, URLs, firewall hints, and desktop commands.
- **Known gap:** there is no Tailscale-specific settings panel, Tailscale readiness detection, MagicDNS/private endpoint display, or guided second-device setup.

### Integration Points

- Settings tab list and panel rendering.
- Tauri command API for local system checks and endpoint management.
- Existing Browser Access bridge startup and status, or a dedicated bridge wrapper that preserves the same security properties.
- Local config storage under desktop app config root.
- Gateway auth/rate-limit/CORS behavior.
- Tailscale local client/CLI/status APIs available on host OS.
- External Tailscale docs/download/admin URLs opened through trusted external URL handling.
- Settings tests in `builds/typescript/client_web/src/components/settings/SettingsModal.test.tsx`.

### Hard Constraints

- Tailscale Access is local desktop only for V1.
- No public internet exposure without explicit warning-checkbox consent.
- No BrainDrive-owned Tailscale credentials.
- No Tailscale auth keys/OAuth secrets in V1.
- No change may bypass local BrainDrive account initialization or auth.
- Existing Browser Access behavior must not regress.
- Long-running or elevated OS commands must be avoided unless explicitly required and consented.
- Tailscale CLI behavior must be checked against current docs during build planning because Tailscale Serve/Funnel CLI semantics have changed in recent client versions.

### Build Workflow Inputs

These are implementation inputs for a downstream build plan, not final architecture decisions:

- Prefer adding a dedicated `desktop-tailscale-access` client API module rather than overloading `desktop-browser-access.ts`.
- Consider extracting current Browser Access panel into its own component before adding another large Settings section if needed to keep `SettingsModal.tsx` maintainable.
- Evaluate Tailscale status via `tailscale status --json` or platform-supported equivalent.
- Evaluate endpoint setup via Tailscale Serve, preferring current documented commands and JSON status/config reads.
- Use existing `openExternalUrl` helper for Tailscale docs/admin/consent links.
- Keep Tailscale desired state in desktop local config, not owner memory.
- If endpoint cleanup cannot be guaranteed through the CLI, design a manual cleanup fallback before implementation starts.

## Test Strategy

### Test Levels Required

- [x] **Unit** - State mapping, validation, URL formatting, safe diagnostics filtering.
- [x] **Integration** - Tauri command wrappers, mocked Tailscale command outputs, Browser Access bridge interaction.
- [x] **E2E / workflow** - Settings panel flows with mocked desktop APIs; manual real-device verification.
- [x] **Regression** - Existing Settings tabs, Browser Access, auth/login, local/managed visibility.
- [x] **Human review** - Beginner UX copy, consent clarity, public/private distinction.
- [x] **Cross-platform/responsive** - At minimum one real OS for V1 manual verification; mocked paths for Windows/macOS/Linux command differences.
- [ ] **Harness / AI judge** - Not required for V1 unless a UX harness exists for Settings panels.

### Verification Approach

- **Agent self-verification:** Read touched files and callers; run focused unit tests; run typecheck/build where practical.
- **Automated verification:**
  - `cd builds/typescript && npm run web:typecheck`
  - `cd builds/typescript && npm run web:test -- SettingsModal`
  - Tauri/Rust focused tests if Tailscale command parsing is implemented in Rust.
  - Existing Browser Access tests must still pass.
- **Manual verification:**
  - With Tailscale not installed or mocked missing.
  - With Tailscale signed out or mocked signed out.
  - With Tailscale connected and endpoint enabled.
  - From a second Tailscale-connected device opening the shown address.
  - Borrowed-device flow cannot continue until the warning checkbox is checked.
  - Public-link flow cannot continue until the warning checkbox is checked.
  - Disable endpoint and verify the address stops working.
- **Security verification:**
  - Inspect logs/client responses for secrets.
  - Confirm public-link access is not enabled by default.
  - Confirm public-link access requires explicit checkbox acknowledgement.
  - Confirm BrainDrive login remains required from remote device.

### Acceptance Evidence

- [ ] Screenshot of `Needs setup` state.
- [ ] Screenshot of `Ready to enable` state.
- [ ] Screenshot of `Running` state with a safe/redacted Tailscale address.
- [ ] Screenshot or recording from a second trusted device reaching BrainDrive login/app.
- [ ] Screenshot of borrowed-device warning checkbox gating continue/enable.
- [ ] Screenshot of public-link warning checkbox gating continue/enable.
- [ ] Screenshot of public-link running state with a persistent public-access badge.
- [ ] Screenshot of `Off` state after disabling.
- [ ] Test output for focused Settings and Tailscale state tests.
- [ ] Typecheck/build output.
- [ ] Short security note confirming no credentials were logged or persisted.

### Baseline / Regression Impact

- **Always-run checks affected:** web typecheck, Settings tests, desktop preflight if Tauri commands change.
- **Existing user flows that must keep working:** AI Model, Model Providers, Your Profile, Your Agent, Browser Access, Backup, Migrate, Account in managed mode.
- **Global properties affected:** local network exposure, auth trust boundary, rate limiting, settings modal tab filtering, desktop runtime startup.

## Security, Privacy, And Trust Considerations

### Risk Level

- [x] **High** - This feature changes network reachability of a local BrainDrive instance and touches auth/network boundaries.

### Threat / Trust Assessment

- **User input:** Minimal in V1; owner actions include enable/disable/test. If custom names/ports are later added, validate strictly.
- **Code execution:** The desktop runtime may execute local Tailscale commands. Commands must be fixed/structured, not shell-concatenated from user input.
- **Data sensitivity:** Remote users who authenticate can access BrainDrive memory and tools according to existing authorization. Network exposure increases the importance of auth strength.
- **Network surface:** Adds new paths from trusted tailnet devices, borrowed devices, and optionally the public internet to local BrainDrive. Borrowed-device and public-link paths require warning-checkbox consent and visible running state.
- **Model/tool behavior:** No new model behavior. Remote access could allow model/tool usage from another device after auth, so existing auth/session protections matter.
- **Blast radius:** If misconfigured publicly or auth is bypassed, local BrainDrive memory and tools could be exposed.
- **Owner trust:** Owner must understand who can reach the endpoint, how to turn it off, and which mode is active.

### Required Mitigations

- [ ] Default off.
- [ ] Private tailnet-only default.
- [ ] No public-link access without warning-checkbox consent.
- [ ] No borrowed-device access without warning-checkbox consent.
- [ ] BrainDrive auth remains required.
- [ ] Local account initialization required before enabling.
- [ ] Visible off switch.
- [ ] Sanitized logs and client responses.
- [ ] Structured command execution with no shell interpolation.
- [ ] Endpoint cleanup and stale-state detection.
- [ ] Clear public/private language in UI.
- [ ] Manual cross-device security verification before handoff.

## Explicit Boundaries

### Do Not Modify

- [ ] Do not remove or degrade existing Browser Access functionality unless the spec is updated.
- [ ] Do not modify model provider settings, Ollama, OpenRouter/BYOK, BrainDrive Models, or provider credentials.
- [ ] Do not modify memory backup/migration semantics.
- [ ] Do not modify managed-hosting account flows for this feature.
- [ ] Do not edit Tailscale admin policies or ACLs in V1.

### Do Not Introduce

- [ ] Do not introduce BrainDrive-owned Tailscale provider keys or API tokens.
- [ ] Do not introduce router port forwarding, UPnP, ngrok-style tunnels, or raw public IP exposure.
- [ ] Do not collect Tailscale passwords, auth keys, OAuth client IDs/secrets, or admin API keys in V1.
- [ ] Do not enable a public link by default.
- [ ] Do not store network credentials in owner memory.
- [ ] Do not shell-concatenate user-controlled command strings.

### Security / Trust Boundaries

- [ ] Never commit secrets or credentials.
- [ ] Never bypass BrainDrive authentication for remote access.
- [ ] Never represent tailnet-only access as a public internet link.
- [ ] Never represent public access as safe or low-risk.
- [ ] Production configs are read-only unless explicitly in scope.

### Out Of Scope Even If Related

- [ ] Public access without warning-checkbox consent.
- [ ] Tailscale ACL editor.
- [ ] Tailscale SSH.
- [ ] Subnet router/exit node/app connector setup.
- [ ] Mobile app build work.
- [ ] Hosted BrainDrive access policy.
- [ ] Router/firewall automation outside the existing Browser Access local firewall helper.

## Open Questions

| Question | Recommendation | Blocks V1? |
|---|---|---|
| Should V1 include public internet access through Tailscale Funnel? | Yes, if the owner explicitly chooses `A public link anyone can open` and checks the warning acknowledgement. It must not be the default path. | Yes, decide exact mechanism before build plan. |
| Should the tab be named `Tailscale Access`, `Remote Access`, or merged into `Browser Access`? | Use `Tailscale Access` for V1 to avoid confusing LAN Browser Access with remote private-network access. Consider a later `Remote Access` umbrella if UX gets crowded. | No. |
| Should V1 require Tailscale Serve, or allow direct tailnet IP/port binding? | Prefer Tailscale Serve/private endpoint. Direct binding is an advanced fallback only if Serve is unavailable and the security review accepts it. | Yes, decide before build plan. |
| Should BrainDrive automatically install Tailscale? | No for V1. Provide guided install/open links. Automatic install creates OS/package-manager/elevation complexity. | No. |
| Should BrainDrive store a Tailscale endpoint URL after shutdown/restart? | Store sanitized last-known URL only for helpful status, but treat live status as authoritative. | No. |
| Should local Browser Access and Tailscale Access share the same bridge process? | Recommended if it preserves security and avoids duplicate services. Keep UX states separate. | No, build-plan decision. |
| How should Docker/headless local installs use Tailscale? | Separate spec. Desktop assumptions do not map cleanly to Docker/service installs. | No. |
| Should the panel support sharing BrainDrive with another person's Tailscale account/device? | Yes as a V1 access intent, but only after borrowed-device warning acknowledgement. Avoid ACL editing in V1; the build plan must define whether this is handled through Tailscale sharing, public-link mode, or another Tailscale-supported path. | Yes, decide exact mechanism before build plan. |
| Should remote access require stronger local auth/session settings? | Recommended security review item. At minimum do not ship if remote access bypasses existing auth; consider future 2FA/session controls. | Review before implementation approval. |
| Should the app generate QR codes for mobile setup? | Defer to V2 unless testing shows URL copy is a major obstacle. | No. |

## Recommended Product Decisions

1. **V1 access modes:** Own trusted devices, someone else's device, and a public link anyone can open.
2. **V1 public access policy:** Public-link access is available only after explicit warning-checkbox acknowledgement and must never be the default path.
3. **V1 user promise:** "Choose where you want to use BrainDrive; BrainDrive will make the risk clear before access is widened."
4. **V1 automation boundary:** Detect and configure local endpoint; do not create Tailscale accounts, auth keys, OAuth clients, or ACLs.
5. **V1 UX pattern:** Guided setup checklist plus one primary action per state.
6. **V1 technical preference:** Use Tailscale-supported endpoint mechanisms over direct interface binding; prefer private Serve for trusted-device mode.
7. **V1 persistence:** Desktop local config only; no owner-memory writes.
8. **V1 release gate:** Manual cross-device verification is required, not optional.

## Changelog

| Date | Change | Reason | Source | Decision |
|---|---|---|---|---|
| 2026-07-07 | Updated access-intent flow to support own device, someone else's device, and public link, with warning-checkbox gates for the latter two. | Product clarification. | Chat follow-up | Open |
| 2026-07-07 | Initial spec created. | Product request for a Settings Tailscale panel aimed at non-technical owners. | Chat request + repo/docs review | Open |

## Conversation References

| Date | Source | Topics Discussed | Link |
|---|---|---|---|
| 2026-07-07 | Codex chat | Need a Settings panel spec for connecting BrainDrive through Tailscale, beginner-first setup, scope/out-of-scope/goals/user stories/open questions with recommendations. | Local chat session |

## Approval

- [ ] Reviewed by: _______________
- [ ] Date: _______________
- [ ] Ready for Planning: [ ]

---

*Next: After this spec is reviewed and accepted, create a test plan that defines the required mocked states, real-device verification, security checks, and regression gates before writing the build plan.*