Skip to content
Merged
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
76 changes: 76 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,82 @@ before it can reach a release. (There was briefly a separate `sdk:plugin-api` mo
third-party plugin framework; it was removed before ever shipping — see Removed, below — so it never
joined this list.)

## Unreleased

Three default changes, aimed at the same complaint: a fresh integration showed a `127.0.0.1` URL
that needed `adb forward` before it displayed anything, and a Mocks screen that could not add a
mock. See [docs/MIGRATION.md](docs/MIGRATION.md#upgrading-from-120) for the upgrade path.

**Version note, deliberately unresolved here:** under this file's own
[policy](#versioning-and-stability-policy), adding a constant to a public enum is source-breaking
for any host that `when`s exhaustively over `BindingMode`/`BrowserBinding`, and flipping a security
default is a behavioural break. That reads as a major, not a minor. The number is left for the
release decision rather than assumed.

### Added

- **`BindingMode.AUTO` and `BrowserBinding.AUTO`**, now the default for `StartRequest.bindingMode`
and `BrowserConfig.binding`. AUTO binds a real network interface when the device has one and
quietly binds loopback when it does not, so a start always yields a working server and the
connect URL is scannable from another machine without configuration.

Introduced as a third mode rather than by re-pointing the default at `LAN`, because `LAN` earns
its keep by *not* degrading: a host sharing a connect URL with another device needs
`NoEligibleNetwork`/`PermissionRequired` back, not a `127.0.0.1` link that works for nobody but
itself. Explicit `LOOPBACK` and `LAN` behave exactly as before.

`BrowserEndpoint.bindingMode` never reports `AUTO` — it reports the socket that actually bound, so
the QR code, the connect URL, and the "LAN MODE — UNENCRYPTED" banner stay truthful. AUTO
fallbacks are logged with their reason.

The name is reused, not restored: the pre-1.0 `BindingMode.AUTO` came with zero-config auto-start
and NSD service discovery, both still removed. This one only picks a binding.

- **`MockEngineRegistry`** (`sdk:mocks`), a process-wide handle the enabled facade publishes its
`MockEngine` to at `initialize`. It exists to close a module-layering gap — `sdk:network-okhttp`
sits below the facade and cannot call `DevConsole.mockEngine()` — and is what lets
`installDevConsole` wire mocking without the host naming an engine. The protected build publishes
nothing, so a release APK reads `null` and wires no mock interceptor.

### Changed

- **The default binding now reaches the network.** This is a deliberate loosening of a security
default: the dashboard speaks plaintext HTTP, so on a network you do not administer, headers,
tokens, and bodies are readable by anyone who can see the traffic. Pass `BindingMode.LOOPBACK`
(and `BrowserConfig(binding = BrowserBinding.LOOPBACK)` for the on-device Start button) to keep
1.2.0 behaviour. [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) has been rewritten around the new
default rather than patched.

One consequence worth knowing: **AUTO never prompts for `ACCESS_LOCAL_NETWORK`.** It treats a
missing grant as a reason to bind loopback, not a reason to fail, so on an API 37+ device it
settles for `127.0.0.1` until something requests the grant. Hosts that want
`StartResult.PermissionRequired` back to drive a prompt ask for `BindingMode.LAN` by name — which
all three samples still do.

- **`installDevConsole` wires mock rules.** Both the Kotlin extension and the Java-friendly
`DevConsoleOkHttp.install` gained a `mockEngine` parameter defaulting to the published engine, so
the separate `.addInterceptor(DevConsoleMockInterceptor(DevConsole.mockEngine()))` line is no
longer needed. The mock interceptor is added after the capture interceptor, so a served mock is
still recorded and tagged `mocked`. Pass `mockEngine = null` to opt out.

The 2- and 3-argument overloads are still emitted, so Java call sites and existing bytecode are
unaffected; Kotlin callers relying on default arguments should recompile, since the synthetic
`$default` signature changed.

- **`EditingCapabilities.mocks` defaults to `true`**, and `DevConsoleConfig` seeds
`EditingCapabilities()` instead of `EditingCapabilities.readOnly()`. A mock rule writes nothing of
the host's — it only short-circuits DevConsole's own interceptor — so the read-only posture that
protects preferences, databases, and files had nothing to protect here. `readOnly()` is now
spelled out field by field rather than delegating to the constructor, so it still grants nothing
at all, mocks included.

### Fixed

- **A `Delay` mock rule is no longer applied twice** when a host keeps its own
`DevConsoleMockInterceptor` alongside the one `installDevConsole` now adds. The second interceptor
recognises the first one's request tag and stands down. Without this, upgrading would have
silently doubled every simulated latency that proceeds up the chain.

## 1.2.0 — 2026-08-15

A minor under the [policy](#versioning-and-stability-policy): the Remote Config inspector is
Expand Down
85 changes: 59 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,27 +76,37 @@ way your manifest needs `INTERNET`, which most apps already declare:

```kotlin
lifecycleScope.launch { // startBrowser is a suspend function; the server never starts on its own
val result = DevConsole.startBrowser(StartRequest(bindingMode = BindingMode.LOOPBACK))
val result = DevConsole.startBrowser(StartRequest())
val connectUrl = (result as? StartResult.Started)?.access?.connectUrl
// e.g. http://127.0.0.1:8080/#code=B7KQ2XWZ — surface this in your debug UI
// e.g. http://192.168.0.15:8080/#code=B7KQ2XWZ — surface this in your debug UI
}
```

The default binding is `BindingMode.AUTO`: it binds your device's network address when there is one,
so the URL opens from any machine on the same Wi-Fi, and falls back to `127.0.0.1` when there isn't.
If it fell back — or if you passed `BindingMode.LOOPBACK` to keep it off the network on purpose —
forward the port first:

```bash
adb forward tcp:8080 tcp:8080 # use the port from the DevConsole log line
```

Then open the **whole URL**. The `#code=` fragment is the credential, so a bare `http://host:port/`
gets you nothing.

> **The dashboard speaks plaintext HTTP.** On a network address, everything it shows — headers,
> tokens, bodies — is readable by anyone who can see your traffic. That is fine on a home or office
> Wi-Fi and a bad idea on a conference or café network. Pass `BindingMode.LOOPBACK` to rule it out,
> and read [the threat model](docs/THREAT_MODEL.md).

## What you get

| Area | What it does |
|---|---|
| **In-app inspector** | `DevConsole.open(context)` shows every inspector below as an on-device screen (included with `devconsole`), plus a QR code for pairing the browser. Opens by shake (adjustable intensity) or draggable floating button via the opt-in `DevConsoleConfig.openTriggers` flags. Its More screen can also start and stop the dashboard server. |
| **Network inspector** | Every HTTP call with headers, bodies, and a DNS/TCP/TLS/send/wait/receive timing bar. Live-tails as traffic happens. |
| **WebSocket & MQTT inspectors** | Connection lifecycles and every frame, inbound and outbound. MQTT rides the Eclipse Paho adapter. |
| **Mock rules** | Serve canned responses for matching requests (OkHttp), toggled from the dashboard, with deterministic priority matching. |
| **Mock rules** | Serve canned responses for matching requests (OkHttp), toggled from the dashboard, with deterministic priority matching. Wired by `installDevConsole` and editable out of the box. |
| **Request composer** | Make the device issue ad-hoc HTTP requests from the dashboard. Off by default, host-allowlist confinable. |
| **Crash & ANR capture** | Uncaught exceptions and a main-looper watchdog with bounded all-thread dumps and breadcrumbs. Always delegates to any crash reporter you already have. |
| **Push timeline** | Record FCM (or any) push messages and their lifecycle: received → displayed → opened. The Firebase adapter uses reflection — no compile-time Firebase dependency. |
Expand Down Expand Up @@ -165,16 +175,23 @@ scan from another machine.

<p align="center"><img src="docs/images/inspector-more-server.png" width="300" alt="More screen with the server started, showing the connect URL and QR code" /></p>

That button binds **loopback** by default, so the URL it shows needs `adb forward`. To bind LAN
instead, which is what makes the QR code scannable from another machine, declare it on the config.
The button issues no `StartRequest` of its own:
That button binds **AUTO** by default, so on a device with a live Wi-Fi or Ethernet connection the
QR code is scannable from another machine straight away, and on one without it the URL falls back to
`127.0.0.1` and needs `adb forward`. The button issues no `StartRequest` of its own, so if you want
to pin it, declare it on the config:

```kotlin
// Never touch the network:
DevConsoleConfig.default().withBrowserConfig(BrowserConfig(binding = BrowserBinding.LOOPBACK))

// Require the network — fails loudly instead of falling back, and surfaces the
// ACCESS_LOCAL_NETWORK prompt on API 37+ devices:
DevConsoleConfig.default().withBrowserConfig(BrowserConfig(binding = BrowserBinding.LAN))
```

This is independent of the `bindingMode` you pass to `startBrowser` yourself; set both if you start
the server from your own UI too. Read [the threat model](docs/THREAT_MODEL.md) before choosing LAN.
the server from your own UI too. Read [the threat model](docs/THREAT_MODEL.md) before leaving either
one on the network.

From code:

Expand All @@ -183,13 +200,14 @@ From code:
DevConsole.initialize(application, DevConsoleConfig.default())

// startBrowser and stop are suspend functions — call them from a coroutine:
val result = DevConsole.startBrowser(StartRequest(bindingMode = BindingMode.LOOPBACK))
val result = DevConsole.startBrowser(StartRequest()) // BindingMode.AUTO
when (result) {
is StartResult.Started -> {
result.endpoint // host + port actually bound
result.endpoint // host + port actually bound; bindingMode is LOOPBACK or LAN,
// never AUTO — it reports the socket, not the request
result.access.connectUrl // the full credential URL — treat as a secret
}
is StartResult.PermissionRequired -> { /* LAN only: request result.permission */ }
is StartResult.PermissionRequired -> { /* explicit LAN only: request result.permission */ }
else -> { /* NoEligibleNetwork, ServerUnavailable, ... */ }
}

Expand All @@ -214,7 +232,7 @@ DevConsole.startBrowserAsync(request, result -> runOnUiThread(() -> {
After `startBrowser`, filter Logcat on the `DevConsole` tag:

```text
I/DevConsole: Dashboard available at: http://127.0.0.1:8080/ (access link available through the DevConsole API/launcher; binding: LOOPBACK)
I/DevConsole: Dashboard available at: http://192.168.0.15:8080/ (access link available through the DevConsole API/launcher; binding: LAN)
```

**The session code is deliberately absent from Logcat.** The full URL, with its `#code=<session
Expand All @@ -224,11 +242,20 @@ free one in **8080–8099**, so read it from the log rather than assuming 8080.

### Connect from your browser

- **Loopback (default):** run `adb forward tcp:<port> tcp:<port>`, then open the connect URL.
- **LAN:** pass `BindingMode.LAN` and open the URL from any device on the same network. Read
[the threat model](docs/THREAT_MODEL.md) first, because the dashboard speaks plaintext HTTP. A
LAN start that finds no eligible network interface returns `StartResult.NoEligibleNetwork`. It
never quietly falls back to loopback, or the other way around.
- **AUTO (default):** binds your device's network address when it has one, so you open the connect
URL — or scan its QR code — from any machine on the same network with nothing else to set up. With
no usable interface, or without the `ACCESS_LOCAL_NETWORK` grant on an API 37+ device, it binds
`127.0.0.1` instead and the log line says so. Read [the threat model](docs/THREAT_MODEL.md),
because the dashboard speaks plaintext HTTP wherever it lands.
- **LOOPBACK:** run `adb forward tcp:<port> tcp:<port>`, then open the connect URL. Choose this to
keep the dashboard off the network entirely.
- **LAN:** like AUTO, except it refuses to settle. No eligible interface returns
`StartResult.NoEligibleNetwork` and a missing grant returns `StartResult.PermissionRequired` —
neither quietly becomes loopback. Ask for it when a `127.0.0.1` URL would be useless to you, or
when you want that `PermissionRequired` so your app can prompt for the permission. AUTO never
prompts; it just settles for loopback.

`StartResult.Started.endpoint.bindingMode` always tells you which one you actually got.

Open the **whole URL**. The `#code=` fragment is the credential. It is single-use, expires in five
minutes, and creates a session immediately with no approval step. A bare `http://host:port/` sits
Expand All @@ -237,10 +264,9 @@ unauthenticated forever. If a code lapses, issue a fresh one from the device.
### Wire up your network stack

```kotlin
// OkHttp / Retrofit — capture + timing in one call:
// OkHttp / Retrofit — capture, timing, and mock rules in one call:
val client = OkHttpClient.Builder()
.installDevConsole(DevConsole.networkRecorder())
.addInterceptor(DevConsoleMockInterceptor(DevConsole.mockEngine())) // optional, mocks
.build()

// Ktor client, any engine (captures request + response bodies, textual, up to 256 KiB each):
Expand Down Expand Up @@ -425,12 +451,16 @@ resolved runtime classpath, and the final APK/AAB bytes. See

## Security model

DevConsole deliberately exposes your app's internals to a browser. It defaults to the safe end of
every choice, but you should know where the edges are:
DevConsole deliberately exposes your app's internals to a browser, and two of its defaults trade
safety for a working first run. Know where the edges are:

- **The dashboard speaks plaintext HTTP.** There is no TLS. In LAN mode, anyone who can watch your
network packets can read everything it shows: headers, tokens, bodies, exports. That is why
loopback plus `adb forward` is the default and LAN is always an explicit opt-in.
- **The dashboard speaks plaintext HTTP, and the default binding reaches your network.** There is no
TLS. `BindingMode.AUTO` binds your device's network address whenever it can, so anyone who can
watch your Wi-Fi packets can read everything the dashboard shows: headers, tokens, bodies,
exports. This is a debug-build-only surface behind a single-use expiring credential, which is why
the default favours reachability — but on an untrusted network (a conference, a café, a shared
office VLAN) pass `BindingMode.LOOPBACK`, or set
`BrowserConfig(binding = BrowserBinding.LOOPBACK)`, and use `adb forward`.
- **The connect URL is a credential.** Holding a live `#code=` fragment creates a session, with no
approval step on the device. Codes are single-use and expire in five minutes; sessions last 30.
Treat the URL like a password. You can revoke sessions from the More screen.
Expand All @@ -439,9 +469,12 @@ every choice, but you should know where the edges are:
[docs/SECURITY_AND_REDACTION.md](docs/SECURITY_AND_REDACTION.md).
- **Screenshots cannot be redacted.** Pixels don't have field names. Capture is **off by default**
and everything it produces is marked `UNREDACTED`.
- **Editing is off by default.** Preferences/database/file writes, mock editing, and capture-rule
editing are each gated per surface via `EditingCapabilities`; the composer and state mutation
have their own `DevConsoleConfig` flags. Everything defaults to off/read-only.
- **Editing is off by default, except mocks.** Preferences/database/file writes and capture-rule
editing are each gated per surface via `EditingCapabilities`; the composer and state mutation have
their own `DevConsoleConfig` flags. All of those default to off/read-only. Mock editing is the one
exception: a mock rule writes nothing of yours, it only short-circuits DevConsole's own
interceptor, so it ships editable. `EditingCapabilities.readOnly()` still refuses everything
including mocks.

For the full analysis, including what a malicious network peer or a co-installed app can and cannot
do, read [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md).
Expand Down
36 changes: 24 additions & 12 deletions docs/COMPOSER_AND_MOCKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,22 +20,31 @@ collections never persist secret variable values by default.

## Mocks

Mocks need one line of host wiring — an OkHttp interceptor that consults the same `MockEngine`
instance the dashboard controls:
Mocks need no host wiring beyond the network installer you already have:

```kotlin
val client = OkHttpClient.Builder()
.installDevConsole(DevConsole.networkRecorder()) // capture + timing first
.addInterceptor(DevConsoleMockInterceptor(DevConsole.mockEngine())) // then mock
.installDevConsole(DevConsole.networkRecorder()) // capture + timing + mocks
.build()
```

`installDevConsole` (see [NETWORK_ADAPTERS.md](NETWORK_ADAPTERS.md)) is the recommended way to add
the capture interceptor — it also wires the event listener needed for the Network inspector's
timing bar, which a bare `DevConsoleOkHttpInterceptor(recorder)` does not.
`installDevConsole` (see [NETWORK_ADAPTERS.md](NETWORK_ADAPTERS.md)) adds the capture interceptor,
the event listener needed for the Network inspector's timing bar (which a bare
`DevConsoleOkHttpInterceptor(recorder)` does not), and — from the engine `DevConsole.initialize`
published to `MockEngineRegistry` — the mock interceptor, in that order. Order matters: the capture
interceptor goes first, so a mocked response is still captured and tagged like a normal response
(matching the interception order in the spec).

Order matters: put the capture interceptor before the mock interceptor, so a mocked response is
still captured and tagged like a normal response (matching the interception order in the spec).
Two escape hatches. Pass `mockEngine = null` to install no mock interceptor at all, or pass an
engine of your own to mock against something other than the live one:

```kotlin
.installDevConsole(DevConsole.networkRecorder(), mockEngine = null)
```

If you are upgrading and already had `.addInterceptor(DevConsoleMockInterceptor(DevConsole.mockEngine()))`,
you can delete it. Leaving it in place is safe — the second interceptor sees the first one's tag and
stands down, so a `Delay` rule is never applied twice — but it no longer does anything.

Rules are created from the dashboard, not from host code — a rule matches on method/scheme/host/
path (regex) plus optional query/header/body predicates, and resolves to an action: a static
Expand All @@ -59,9 +68,12 @@ The same dashboard button turns mocking back on (it reads its label from the eng
as does the Android inspector's Control screen. The two directions gate differently on purpose:
turning mocking *off* needs only an authenticated session, since falling back to real traffic is
always a safe thing to allow, while turning it back *on* also needs the host's `mocks` editing
capability, because it changes how the app behaves. A host that publishes rules read-only
(`EditingCapabilities(mocks = false)`) can therefore disable mocking from the browser but not
re-enable it — the engine is still switchable in-process through `DevConsole.mockEngine()`.
capability, because it changes how the app behaves. `mocks` is the one editing capability that
defaults to *on* — a mock rule writes nothing of the host's, it only short-circuits DevConsole's own
interceptor — so this asymmetry bites only a host that opted back out. One that publishes rules
read-only (`EditingCapabilities(mocks = false)`, or `EditingCapabilities.readOnly()`) can therefore
disable mocking from the browser but not re-enable it — the engine is still switchable in-process
through `DevConsole.mockEngine()`.
Individual rules toggle independently of this switch; with the engine off, no rule applies
regardless of its own state.

Expand Down
Loading
Loading