Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,30 @@

All notable changes to bolt-daemon. Newest first.

## fix: pairing UI shows the peer HELLO name, never a socket address — 2026-10-24

`pairing.request` under `--pairing-policy ask` was built from the transport
address. The QUIC answerer passes a synthetic `0.0.0.0:0`, and the WS
answerer passes the real TCP peer (`192.168.4.25:55170`). `remote_device_type`
was always the literal `unknown`. HELLO carried no device name, so the Accept
sheet and the post-accept session label had nothing else to show.

- HELLO inner JSON gains optional `deviceName` and `deviceType`. Both are
omitted when this daemon has no usable name, so legacy peers and golden
vectors stay valid. A bind address or `ip:port` is never sealed in.
- This daemon advertises `--device-name`, or the hostname with one trailing
`.local` removed. `--device-type` defaults to `desktop`.
- The answerer reads the peer HELLO before Stage A and puts that name and
type on `pairing.request`. `session.connected` carries the same pair.
When the peer sent nothing usable, both events use `Unknown device` /
`unknown`.
- CLI: `--device-name`, `--device-type`. Stderr: `[DEVICE] advertising name=`
or `[DEVICE] no usable local name`.

An inbound MacBook running this build seals its computer/host name into the
HELLO it sends the Studio. The Studio Accept sheet shows that name. An older
MacBook that omits `deviceName` shows as `Unknown device`.

## docs: retire WebRTC-era operator docs/scripts, rewrite contract for current CLI — 2026-07-21

Public-tree cleanup; no protocol or runtime behavior change.
Expand Down
10 changes: 9 additions & 1 deletion docs/DAEMON_CONTRACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ longer exist.
| `--socket-path` | `/tmp/bolt-daemon.sock` | IPC Unix socket path (Windows: named pipe). |
| `--data-dir` | identity `~/.bolt`, trust `~/.config/bolt-daemon` | Unified data directory. When set: identity at `<dir>/identity.key`, trust at `<dir>/pins/trust.json`, signal files and endpoint metadata in `<dir>`. |
| `--pairing-policy` | `ask` | `ask`, `allow`, or `deny`. Invalid value → exit 1. |
| `--device-name` | hostname | Human name sealed into this daemon's HELLO as `deviceName`. A blank, over-long, or address-shaped value is ignored and the hostname is used (one trailing `.local` removed). When neither is usable, HELLO omits `deviceName`. |
| `--device-type` | `desktop` | Type sealed into HELLO as `deviceType` when a name is advertised. Accepted values: `phone`, `tablet`, `laptop`, `desktop`, `browser`. Anything else stays `desktop`. |
| `--phase-timeout-secs` | `30` | Per-phase timeout in seconds. Unparseable values are ignored and the default applies (the flag is not validated). |

### WsEndpoint Mode
Expand Down Expand Up @@ -97,6 +99,8 @@ NOT change these without a `docs/CHANGELOG.md` entry.
| `[bolt-daemon] mode=` | Startup | Banner; mode/pairing/timeout/paths echo |
| `[bolt-daemon] FATAL:` | Any | Fatal error, exit 1 follows |
| `[bolt-daemon] parent-death watchdog active` | Sidecar | Watchdog armed against parent PID |
| `[DEVICE] advertising name=` | Startup | Usable local name will be sealed into HELLO |
| `[DEVICE] no usable local name` | Startup | HELLO omits `deviceName` |
| `[IPC] listening on` | Startup | IPC server bound |
| `[WS_ENDPOINT] starting on` | Startup | WS endpoint about to serve |
| `[WT_CERT] hash=` | Startup | Ephemeral WT certificate generated |
Expand Down Expand Up @@ -145,7 +149,11 @@ The app SHOULD NOT enable transfer UI until `daemon.status` is received.
feature-gated endpoints. Zero WebRTC at runtime.
- **Session protection:** NaCl-box encrypted HELLO with capability
negotiation, Profile Envelope v1 framing post-HELLO, BTR-encrypted
transfers when negotiated. Protocol violations fail closed.
transfers when negotiated. Protocol violations fail closed. HELLO may
include optional `deviceName` and `deviceType`. Legacy HELLOs that omit
them still parse. The answerer copies those fields onto `pairing.request`
and `session.connected`. A missing or address-shaped name becomes
`Unknown device`.
- **Discovery/signaling** is an app-layer concern. The daemon takes direct
connect instructions (`connect_remote.signal`) and serves inbound
connections; it does not talk to a rendezvous server at runtime.
Expand Down
20 changes: 13 additions & 7 deletions docs/IPC_CONTRACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,14 +164,20 @@ A peer session has been established.
```json
{
"remote_peer_id": "base64-encoded-identity-public-key",
"negotiated_capabilities": ["file_transfer"]
"negotiated_capabilities": ["file_transfer"],
"remote_device_name": "Evan's MacBook Pro",
"remote_device_type": "laptop"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `remote_peer_id` | string | Remote peer's identity public key (base64) |
| `negotiated_capabilities` | string[] | Capabilities negotiated for this session |
| `remote_device_name` | string | Human name from the peer HELLO. `"Unknown device"` when the peer omitted `deviceName` or sent a bind/socket address. |
| `remote_device_type` | string | `phone`, `tablet`, `laptop`, `desktop`, `browser`, or `"unknown"` |

Older consumers that ignore unknown fields keep working. A payload missing these two fields deserializes as `"Unknown device"` / `"unknown"`.

### `session.sas`

Expand Down Expand Up @@ -216,8 +222,8 @@ A remote peer is requesting to pair. Consumer must respond with a `pairing.decis
```json
{
"request_id": "evt-5",
"remote_device_name": "iPhone 15",
"remote_device_type": "mobile",
"remote_device_name": "Evan's MacBook Pro",
"remote_device_type": "laptop",
"remote_identity_pk_b64": "base64-encoded-key",
"sas": "A1B2C3",
"capabilities_requested": ["file_transfer"]
Expand All @@ -227,10 +233,10 @@ A remote peer is requesting to pair. Consumer must respond with a `pairing.decis
| Field | Type | Description |
|-------|------|-------------|
| `request_id` | string | Correlation ID — MUST be echoed in the decision response |
| `remote_device_name` | string | Human-readable name of the remote device |
| `remote_device_type` | string | Device type (e.g., "mobile", "desktop") |
| `remote_identity_pk_b64` | string | Remote identity public key (base64) |
| `sas` | string | Short Authentication String for verification |
| `remote_device_name` | string | Human name from the peer HELLO (`deviceName`). `"Unknown device"` when that field is absent or is a bind address / socket address (`0.0.0.0:0`, `192.168.4.25:55170`). The transport address is never copied here. |
| `remote_device_type` | string | `phone`, `tablet`, `laptop`, `desktop`, `browser`, or `"unknown"` |
| `remote_identity_pk_b64` | string | Remote identity public key (base64). Empty when Stage A has not yet filled it. |
| `sas` | string | Short Authentication String for verification. Empty when Stage A has not yet filled it. |
| `capabilities_requested` | string[] | Capabilities the remote peer is requesting |

### `transfer.incoming.request`
Expand Down
Loading
Loading