wg-app-link/README.md

# wg-server-app

The private link between a phone and a machine you run, extracted from the
two projects that had each written it.

`dev-updater` serves locally-built APKs to a phone. `ai-app` runs model
sessions for one. They have nothing in common above the waterline — and
underneath they are the same program: a server bound to a WireGuard
interface so it is not on the LAN, presenting a certificate from a CA the
app pins, answering only requests carrying a bearer token that was enrolled
by scanning a QR code off the terminal, and keeping its state in
owner-only files outside the repo.

That link was written twice. This is it written once.

> **Status: proposal with a working core.** Nothing has been removed from
> either project yet. The Rust modules here are real, tested and
> lint-clean; the rest of this file is the case for what should follow and
> what should not.

## The evidence

Measured, not estimated — `difflib` over the two working trees on
2026-08-28:

| file | dev-updater | ai-app | identical |
|---|---|---|---|
| `EnrollmentScanActivity.kt` | 32 lines | 32 lines | **98%** |
| `ServerConfig.kt` | 139 | 122 | **89%** |
| `auth.rs` | 250 | 230 | **83%** |
| `PinnedCert.kt` | 60 | 59 | **75%** |
| `certs.rs` | 218 | 199 | **70%** |
| RON `format` module | — | — | **byte-identical** |

The percentages understate it, because the differences are almost entirely
a product name and a type parameter:

- **`EnrollmentScanActivity.kt`** differs by its `package` line. That is all.
- **`PinnedCert.kt`** differs by `package` and one string, `"dev-updater-dev-ca"` against `"ai-app-dev-ca"`.
- **`certs.rs`** differs by the organisation name in the certificate, and by ai-app having factored the file-mode handling into a `private` module that dev-updater still has inline in two places.
- **`auth.rs`** differs by the state type the middleware is generic over (`AppState` against `SessionManager`), and by dev-updater keeping `print_enrollment` in `auth.rs` where ai-app keeps the same function in `main.rs`.
- **`wg_address` and `local_addresses`** are the same logic in both, in files that are otherwise 8% alike.

ai-app's own `Cargo.toml` already says the quiet part: RON is used there
because it is *"the same choice, and the same house rules, as the sibling
dev-updater project's config."*

## Why this is worth doing, in one observation

**The two copies have each drifted into holding an improvement the other
lacks.** Not hypothetically — as of the day this was written:

| improvement | in dev-updater | in ai-app |
|---|---|---|
| `private::` module owning every file mode | no, inline twice | yes |
| `SharedPreferences.edit { }` instead of the deprecated builder | no | yes |
| `existingTokenKey()` — reads the key without creating one, so a stored blob with no key means "not enrolled" rather than leaving a stray key behind | yes | no |
| `hasLocalNetworkPermission` — tells a denied permission apart from an unreachable server, which are identical at the socket | yes | no |
| Catppuccin theme with colour-by-consequence buttons | yes | no, ad-hoc `Color(0xFF…)` per screen |

Every one of those is a fix somebody made once, in one repo, that the other
will either never get or get by being written a third time. That is the
cost this repo removes, and it is already being paid.

## It found a bug in all three before shipping a line

`private` was lifted from ai-app because that copy was the better one. Two
sessions then read it as a module rather than as scattered helpers, and
found that `OpenOptions::mode` applies **only when a file is created** — so
opening one that already exists keeps whatever mode it had.

Both projects rewrite existing files holding private material. `certs.rs`
reissues the TLS leaf on every start, so a `leaf-key.pem` that had ever
existed world-readable would have stayed that way for the rest of its life,
with every start looking like it was setting the mode. The config's temp
file is the other: normally fresh, but one left by a crashed save is
reopened with its old mode and then renamed over the file holding the
enrolled token hashes.

It was latent in both — the modes on both machines were checked, and were
correct — but it was present three times: dev-updater, ai-app, and this
crate's first commit.

The reason nobody caught it is the argument for this repo, and it is not
about duplication. The correct reasoning was already written down, in a
comment, three functions above the code that needed it: `create_dir` sets
the mode a second time and explains exactly why. It stayed invisible for as
long as nobody had cause to read those functions as a set. Two readers
looking at one module found it in under an hour.

Fixed here (`67ac924`), in ai-app (`d0b6b66`), and in dev-updater
(`bdaade4`), which also adopted the `private` module wholesale — the first
time the sharing paid rather than merely being argued for.

## What is here

`server/` — the `wg-app-link` crate. Three modules, each extracted only after
diffing the two copies and finding nothing but a name between them.

- **`netif`** — `wg_address()`, which fails closed when the tunnel is down, and `local_addresses()` for the certificate's SANs. The product name is a parameter so the failure reads as advice rather than as a library complaining.
- **`enroll`** — token generation, hex-SHA-256 storage, constant-time comparison, the `<scheme>://enroll?…` URI, and the terminal QR. The URI scheme is the parameter, because it is what routes a scan back to the right app.
- **`private`** — owner-only files and directories, taken from ai-app's version, with an `append_file` alongside `create_file` because a transcript must never be truncated by being opened.

## What should follow, and what should not

**Should follow, in this order.** Each is already near-identical:

1. `certs` — CA generated once and never replaced, leaf reissued every start. One `product: &str`.
2. The RON `format` house rules — byte-identical today, so this is pure deletion.
3. The Kotlin `EnrollmentScanActivity`, `PinnedCert`, and the enrollment/Keystore half of `ServerConfig`, as an Android library module. This is where the sharing pays most, because it is where the two copies have drifted furthest apart in *both* directions.
4. Atomic owner-only config save. Both do temp-file-then-rename with the mode set before the rename; only the schema differs.

**Should not.** Naming these is the point of the exercise:

- **The auth middleware itself.** It is generic over each project's state type. Share the primitives (`enroll`), let each keep the six lines that wire them to its own state — the alternative is a trait that exists only to let one function be shared.
- **The HTTP clients.** dev-updater's `DownloadServer.kt` and ai-app's `Api.kt` are 14% alike and 135 against 494 lines. They have diverged because they are genuinely different programs. A shared *pinned transport* underneath them may be worth it later; a shared API is not.
- **Config schemas.** Shared house rules, separate contents.
- **Anything above the link.** Projects, builds, sessions, providers. If a third project would not want it, it does not belong here.

## The name

`wg-app-link`: the link between an app and the machine it talks to, over
WireGuard.

Two earlier names were worse. `wg-server-app` names the two projects this
came out of rather than what it is, which stops being useful the moment a
third one uses it. `wg-link` was worse still, and not merely vague —
`wg` and `ip link` are both real network tools, so it reads as something
that manages a WireGuard interface. `app` is what rules that reading out.

The `wg-` prefix does slightly oversell WireGuard's share of the code:
only `netif` is about the tunnel, while `enroll`, `private` and the
certificate work are not. It earns its place anyway, because binding the
tunnel is the architectural premise the rest follows from — it is why
there is no LAN exposure to defend, and why a plain-HTTP bootstrap port is
safe to offer at all.

## Testing

`./run-tests.sh`. The crate is warning-clean under `cargo clippy
--all-targets` and formatted with plain `cargo fmt` at its defaults, per
the house rules.