wg-app-link/README.md

wg-app-link

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. Six 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. Both split the lookup from the decision, so the failure path can be tested on a machine that has a tunnel — every machine this runs on does.
• 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.
• certs — the CA generated once and never replaced, the leaf reissued every start. product names the organisation and common name and is the whole of what is per-project. Shared because being written twice is worst here: a trust anchor built two ways can be built differently two ways, and the difference surfaces as an opaque handshake failure on a phone.
• format — the two RON house rules, plus write, which renders a value and replaces a file with it atomically and owner-only. This was byte-identical in both projects, which made it the clearest thing in the evidence table and the easiest deletion.
• 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.
• xdg — where each project's state lives: config_home(product) and data_home(product), resolving the XDG variable, ignoring it unless absolute, and falling back under $HOME. Shared because the reason is shared and is not obvious from the code — the repo is a mount that resolves at different absolute paths on each side, so config inside it records paths that work on only one, and a CA private key inside it would let the untrusted side mint a leaf the pinned app trusts.

app/ — the Android library, com.example.wgapplink. The same test applied to Kotlin: the four files appeared in both apps and differed only in comments and a product name.

• PinnedTls — trusts one CA and not the system store, so a genuine certificate for another host is refused as firmly as a self-signed one. The PEM is constructed with, not read, because each app generates its own at build time from the machine doing the build.
• ServerStore — the enrollment: preferences, the <scheme>://enroll?… URI, and the token sealed under an Android Keystore key. Two parameters, both per-app and both load-bearing — see the warning below.
• EnrollmentScanActivity — zxing's capture activity with the 10% framing inset and the laser decorations removed, so framing is never the user's problem.
• localNetworkAllowed — whether ACCESS_LOCAL_NETWORK was granted. Android 17 made it mandatory and a denial is invisible at the socket, so without asking, a blocked app and an unreachable server produce the same timeout.

Adopting the app half takes two lines and one catalog entry. In settings.gradle.kts:

include(":link")
project(":link").projectDir = file("../wg-app-link/app")

and in the version catalog, because a subproject resolves plugin versions from the build including it rather than from its own:

androidLibrary = { id = "com.android.library", version.ref = "agp" }

It also needs androidx-core-ktx and zxing-embedded in that catalog, and alias(libs.plugins.androidLibrary) apply false in the root build file. Consumed as a subproject rather than a published artifact so the two stay locked to whatever commit the submodule points at — the same arrangement the Rust half uses with a path dependency.

The Keystore alias is persisted. Carry the existing value over exactly. ServerStore(scheme, keyAlias) takes both because both are per-app, but they fail differently. A wrong scheme means a scanned QR is ignored, which is visible immediately. A wrong keyAlias means the app can no longer unseal the token it already stored, so an enrolled phone silently reads as not enrolled with nothing on screen to say why. ai-app's is aiapp-token-key; dev-updater's is dev-updater-token-key.

Not moved: the PinnedCaCertificate.kt generator. It is ~40 lines of Gradle in each app's build file, and all three things it varies — the environment variable, the certificate path, and the package the constant is emitted into — are per-app, so sharing it means parameterising the whole of it and introducing a composite build that neither project has today. The one bug it has had is fixed identically in both copies: a PEM constant must start at the opening quotes, or CertificateFactory loses its -----BEGIN preamble sniff, tries DER, and fails at runtime with an ASN.1 decode error nowhere near the generator. Worth revisiting if it ever needs a second fix.

What should follow, and what should not

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

1. The Kotlin EnrollmentScanActivity, PinnedCert, and the enrollment/Keystore half of ServerConfig. Done — see app/ above. It paid as predicted: ai-app's ServerConfig had gained localNetworkAllowed and the KTX edit block while dev-updater's had not, so the two had drifted in both directions exactly as the evidence suggested.
2. Atomic owner-only config save. Done — format::write, since it is the RON house rules and the owner-only rules used together. The subtlety it now states once is that the temp file is not always new: a save killed partway leaves one behind, and reopening it keeps whatever mode it had, which is then renamed over the file holding the enrolled token hashes. There is a test for exactly that, because it cannot happen on a machine where nothing has ever crashed mid-save.

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.

Two decisions worth stating, rather than inheriting

WG_INTERFACE is a constant, not a parameter. For these two projects a second answer would mean two ideas of what "the tunnel" is, and there is one tunnel. That reasoning is about these projects rather than about the world, so it is the first thing a third user should expect to change.

local_addresses puts 10.0.2.2 in every certificate. It is the alias an Android emulator reaches its host by, and not an address the machine owns — so this is a SAN for something that is not this host, present so a debug build can reach a server running beside it. Inherited from ai-app and correct there; written down here because promoting it makes it every future project's default rather than one project's choice.

A review heuristic this repo keeps proving

When you find a rule stated somewhere, grep for its siblings. Three separate bugs today were the correct rule already written down, applied to one member of a set and not the others:

• create_dir set its mode a second time and explained why; create_file and append_file, three functions below, did not.
• ai-app explained one ssh failure and not its sibling.
• dev-updater's acceptance gate compared components by declaration, and BuildState::matches — which meant the same thing — compared them by full equality, so writing a measured field replaced a running build's state.

None was found by a test. All three were found by a second reader looking at code as a set, which is the thing this crate is actually buying.

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.