@domicile-desktop/system-network 0.0.0-alpha-d3ee6fbb3e64 → 0.0.0-alpha-1fcbde657613

package/README.md

@@ -2,7 +2,9 @@
 
 The network for a Domicile shell, from NetworkManager, iwd or wpa_supplicant:
 connectivity and the primary connection, with the Wi-Fi network's name and
-signal. Built on [`@domicile-desktop/sdk/system`](../chrome-sdk/README.md).
+signal. The Wi-Fi device, from NetworkManager or iwd: its networks and
+connection, and the requests that change them. Built on
+[`@domicile-desktop/sdk/system`](../chrome-sdk/README.md).
 
 ## Usage
 
@@ -37,6 +39,37 @@ const stop = watchNetwork(system(domicile), (network) => {
 - An `Err` is a D-Bus failure, such as the service not running.
 - A bug or an unexpected reply shape throws, logged to the console.
 
+## Wi-Fi
+
+```ts
+import { connectWifi, watchWifi } from "@domicile-desktop/system-network/wifi";
+
+const stop = watchWifi(host, (wifi) => {
+  wifi.match({
+    Err: () => hide(),
+    Ok: (found) => found.match({ None: () => hide(), Some: (device) => show(device) }),
+  });
+});
+await connectWifi(host, device, network, "passphrase");
+```
+
+- `watchWifi` watches the first Wi-Fi device of NetworkManager, else iwd, by
+  `NameHasOwner`. `None` is no device, or neither service. wpa_supplicant is
+  not controlled.
+- Requests: `setWifiEnabled`, `scanWifi`, `connectWifi`, `disconnectWifi`.
+  Each resolves `Ok` once the service accepts it; the watch reports the
+  outcome.
+- `connectWifi` uses a network's saved profile when it has one. A new secured
+  network needs a passphrase:
+  - NetworkManager: a new WPA-PSK profile, saved.
+  - iwd: `iwctl --passphrase … station <interface> connect <ssid>`, since iwd
+    asks an agent for it and a page cannot serve one. `iwctl` must be on the
+    compositor's `PATH`.
+- NetworkManager reads re-run on each property change of an object read, an
+  access point coming or going, or a device coming or going. It does not say
+  when a scan runs, so `scanning` is always `false`.
+- iwd does not report addresses, so `connection.ip` is `undefined`.
+
 See [SHELL-SYSTEM-ACCESS.md](/docs/SHELL-SYSTEM-ACCESS.md).
 
 ## Test

package/dist/follow.d.ts

@@ -1,13 +1,13 @@
 import type { Result } from "@cprussin/option-result";
 import type { DbusMatch, DbusSignal, SystemError } from "@domicile-desktop/sdk/system";
-import type { Network, NetworkSystem } from "./network-state";
+import type { NetworkSystem } from "./network-state";
 /** What one read found, and which signals can change it. */
-export type Reading = {
-    network: Result<Network, SystemError>;
+export type Reading<T extends NonNullable<unknown>> = {
+    value: Result<T, SystemError>;
     matters: (signal: DbusSignal) => boolean;
 };
 /**
- * Calls `onNetwork` with what `read` finds now and after each signal that
+ * Calls `onValue` with what `read` finds now and after each signal that
  * matters, and returns a function that stops watching.
  */
-export declare const followNetwork: (system: NetworkSystem, match: DbusMatch, read: () => Promise<Reading>, onNetwork: (network: Result<Network, SystemError>) => void) => (() => void);
+export declare const followBus: <T extends NonNullable<unknown>>(system: NetworkSystem, match: DbusMatch, read: () => Promise<Reading<T>>, onValue: (value: Result<T, SystemError>) => void) => (() => void);

package/dist/follow.js

@@ -1,15 +1,15 @@
-// The loop each backend runs: listen, read, then read again on each signal
-// that can change what was read.
+// The loop each watch runs: listen, read, then read again on each signal that
+// can change what was read.
 import { Err } from "@cprussin/option-result";
 /**
- * Calls `onNetwork` with what `read` finds now and after each signal that
+ * Calls `onValue` with what `read` finds now and after each signal that
  * matters, and returns a function that stops watching.
  */
-export const followNetwork = (system, match, read, onNetwork) => {
+export const followBus = (system, match, read, onValue) => {
     const watch = { listening: undefined, stopped: false };
-    const report = (network) => {
+    const report = (value) => {
         if (!watch.stopped) {
-            onNetwork(network);
+            onValue(value);
         }
     };
     follow(system, match, read, watch, report).catch((error) => {
@@ -50,12 +50,12 @@ const follow = async (system, match, read, watch, report) => {
 const changes = async (listening, read, report) => {
     const reader = listening.items.getReader();
     const first = await read();
-    report(first.network);
+    report(first.value);
     let matters = first.matters;
     for (let next = await reader.read(); !next.done; next = await reader.read()) {
         if (matters(next.value)) {
             const again = await read();
-            report(again.network);
+            report(again.value);
             matters = again.matters;
         }
     }

package/dist/has-owner.d.ts

@@ -0,0 +1,8 @@
+import type { Result } from "@cprussin/option-result";
+import type { SystemError } from "@domicile-desktop/sdk/system";
+import type { NetworkSystem } from "./network-state";
+/**
+ * Whether `name` has an owner on the system bus. `NameHasOwner` does not start
+ * a service that D-Bus can activate, as a call to the service would.
+ */
+export declare const hasOwner: (system: NetworkSystem, name: string) => Promise<Result<boolean, SystemError>>;

package/dist/has-owner.js

@@ -0,0 +1,15 @@
+import { Bus } from "@domicile-desktop/sdk/system";
+import { z } from "zod";
+/**
+ * Whether `name` has an owner on the system bus. `NameHasOwner` does not start
+ * a service that D-Bus can activate, as a call to the service would.
+ */
+export const hasOwner = async (system, name) => (await system.dbusCall({
+    body: [name],
+    bus: Bus.System,
+    destination: "org.freedesktop.DBus",
+    interface: "org.freedesktop.DBus",
+    member: "NameHasOwner",
+    path: "/org/freedesktop/DBus",
+    signature: "s",
+})).map(({ body }) => z.tuple([z.boolean()]).parse(body)[0]);

package/dist/iwd-wifi.d.ts

@@ -0,0 +1,24 @@
+import type { Option, Result } from "@cprussin/option-result";
+import type { SystemError } from "@domicile-desktop/sdk/system";
+import type { NetworkSystem } from "./network-state";
+import type { Wifi, WifiDevice, WifiNetwork, WifiSystem } from "./wifi-state";
+/**
+ * Calls `onWifi` with the first station device now and after each change, and
+ * returns a function that stops watching. `None` is a machine without one.
+ *
+ * An `Err` is a D-Bus failure, such as iwd not running. The watch keeps
+ * listening after one, so a later change reads again.
+ */
+export declare const watchIwdWifi: (system: NetworkSystem, onWifi: (wifi: Result<Option<Wifi>, SystemError>) => void) => (() => void);
+/** Turn the device on or off. */
+export declare const setIwdWifiEnabled: (system: NetworkSystem, wifi: WifiDevice, enabled: boolean) => Promise<Result<"done", SystemError>>;
+/** Ask for a scan. Networks it finds arrive as changes. */
+export declare const scanIwdWifi: (system: NetworkSystem, wifi: WifiDevice) => Promise<Result<"done", SystemError>>;
+/**
+ * Join `network`. A known or open network joins over D-Bus. A new secured one
+ * joins through `iwctl`, which answers iwd's request for the passphrase: iwd
+ * asks an agent for it, and a page cannot serve one.
+ */
+export declare const connectIwdWifi: (system: WifiSystem, wifi: WifiDevice, network: WifiNetwork, passphrase: string | undefined) => Promise<Result<"done", SystemError>>;
+/** Leave the current network, until asked to join one. */
+export declare const disconnectIwdWifi: (system: NetworkSystem, wifi: WifiDevice) => Promise<Result<"done", SystemError>>;

package/dist/iwd-wifi.js

@@ -0,0 +1,204 @@
+// iwd's Wi-Fi device over the system bus: its networks and connection, kept
+// current, and the requests that change them. See docs/SHELL-SYSTEM-ACCESS.md.
+import { Err, None, Ok, Some } from "@cprussin/option-result";
+import { Bus, SystemErrorKind } from "@domicile-desktop/sdk/system";
+import { z } from "zod";
+import { followBus } from "./follow";
+import { strengthOfDbm } from "./signal-strength";
+import { variant } from "./variant";
+import { WifiBackend } from "./wifi-state";
+const SERVICE = "net.connman.iwd";
+const DEVICE = `${SERVICE}.Device`;
+const STATION = `${SERVICE}.Station`;
+const NETWORK = `${SERVICE}.Network`;
+const DIAGNOSTIC = `${SERVICE}.StationDiagnostic`;
+/** The interfaces whose property changes alter a {@link Wifi}. */
+const WATCHED = [DEVICE, STATION, NETWORK];
+/**
+ * Calls `onWifi` with the first station device now and after each change, and
+ * returns a function that stops watching. `None` is a machine without one.
+ *
+ * An `Err` is a D-Bus failure, such as iwd not running. The watch keeps
+ * listening after one, so a later change reads again.
+ */
+export const watchIwdWifi = (system, onWifi) => followBus(system, { bus: Bus.System, sender: SERVICE }, async () => ({ matters, value: await read(system) }), onWifi);
+/** Turn the device on or off. */
+export const setIwdWifiEnabled = async (system, wifi, enabled) => done(await system.dbusCall({
+    ...request(wifi.device, "org.freedesktop.DBus.Properties", "Set"),
+    body: [DEVICE, "Powered", { signature: "b", value: enabled }],
+    signature: "ssv",
+}));
+/** Ask for a scan. Networks it finds arrive as changes. */
+export const scanIwdWifi = async (system, wifi) => done(await system.dbusCall(request(wifi.device, STATION, "Scan")));
+/**
+ * Join `network`. A known or open network joins over D-Bus. A new secured one
+ * joins through `iwctl`, which answers iwd's request for the passphrase: iwd
+ * asks an agent for it, and a page cannot serve one.
+ */
+export const connectIwdWifi = async (system, wifi, network, passphrase) => {
+    if (network.profile !== undefined || !network.secured) {
+        return done(await system.dbusCall(request(network.path, NETWORK, "Connect")));
+    }
+    else if (passphrase === undefined) {
+        throw new Error(`joining ${network.ssid} needs a passphrase`);
+    }
+    else {
+        const ran = await system.run([
+            "iwctl",
+            "--passphrase",
+            passphrase,
+            "station",
+            wifi.interface,
+            "connect",
+            network.ssid,
+        ]);
+        return ran.andThen(({ code, stderr, stdout }) => code === 0
+            ? Ok("done")
+            : Err({
+                kind: SystemErrorKind.Other,
+                message: `${stdout}${stderr}`.trim(),
+            }));
+    }
+};
+/** Leave the current network, until asked to join one. */
+export const disconnectIwdWifi = async (system, wifi) => done(await system.dbusCall(request(wifi.device, STATION, "Disconnect")));
+const request = (path, iface, member) => ({
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: iface,
+    member,
+    path,
+});
+const done = (reply) => reply.map(() => "done");
+/** Whether `signal` can change Wi-Fi: an object coming or going, or a property. */
+const matters = (signal) => {
+    switch (signal.member) {
+        case "InterfacesAdded":
+        case "InterfacesRemoved": {
+            return true;
+        }
+        case "PropertiesChanged": {
+            const [iface] = propertiesChangedSchema.parse(signal.body);
+            return WATCHED.includes(iface);
+        }
+        default: {
+            return false;
+        }
+    }
+};
+const read = async (system) => (await system.dbusCall({
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: "org.freedesktop.DBus.ObjectManager",
+    member: "GetManagedObjects",
+    path: "/",
+})).andThenAsync(async ({ body }) => {
+    const objects = managedObjectsSchema.parse(body)[0];
+    const station = Object.entries(objects).flatMap(([path, held]) => {
+        const device = held[DEVICE];
+        return device?.Mode === "station" ? [{ device, held, path }] : [];
+    })[0];
+    return station === undefined
+        ? Ok(None())
+        : (await wifiOf(system, objects, station.path, station.device, station.held)).map((wifi) => Some(wifi));
+});
+const wifiOf = async (system, objects, path, device, held) => {
+    const off = {
+        backend: WifiBackend.Iwd,
+        connection: undefined,
+        device: path,
+        enabled: device.Powered,
+        hardwareAddress: device.Address,
+        interface: device.Name,
+        networks: [],
+        scanning: false,
+    };
+    const station = held[STATION];
+    return station === undefined
+        ? Ok(off)
+        : (await stationOf(system, objects, path, station, held[DIAGNOSTIC])).map((found) => ({ ...off, ...found }));
+};
+const stationOf = async (system, objects, path, station, diagnostic) => (await system.dbusCall(request(path, STATION, "GetOrderedNetworks"))).andThenAsync(async ({ body }) => {
+    const networks = orderedNetworksSchema
+        .parse(body)[0]
+        .map(([network, signal]) => networkOf(objects, network, signal));
+    const connected = networks.find(({ connected: on }) => on);
+    const connection = connected === undefined
+        ? Ok(None())
+        : (await diagnosticsOf(system, path, diagnostic)).map((found) => Some({
+            ...found,
+            ip: undefined,
+            ssid: connected.ssid,
+            strength: connected.strength,
+        }));
+    return connection.map((current) => ({
+        connection: current.match({
+            None: () => undefined,
+            Some: (found) => found,
+        }),
+        networks,
+        scanning: station.Scanning,
+    }));
+});
+const networkOf = (objects, path, signal) => {
+    const network = objects[path]?.[NETWORK];
+    if (network === undefined) {
+        throw new Error(`iwd ordered a network it does not have: ${path}`);
+    }
+    else {
+        return {
+            connected: network.Connected,
+            path,
+            profile: network.KnownNetwork,
+            secured: network.Type !== "open",
+            ssid: network.Name,
+            strength: strengthOfDbm(signal / 100),
+        };
+    }
+};
+/** The link's frequency and bitrate, when iwd offers diagnostics. */
+const diagnosticsOf = async (system, path, diagnostic) => diagnostic === undefined
+    ? Ok({ bitrate: undefined, frequency: undefined })
+    : (await system.dbusCall(request(path, DIAGNOSTIC, "GetDiagnostics"))).map(({ body }) => {
+        const [found] = diagnosticsSchema.parse(body);
+        return { bitrate: found.RxBitrate / 10, frequency: found.Frequency };
+    });
+const stationSchema = z.object({ Scanning: variant(z.boolean()) });
+const managedObjectsSchema = z.tuple([
+    z.record(z.string(), z.object({
+        [DEVICE]: z
+            .object({
+            Address: variant(z.string()),
+            Mode: variant(z.string()),
+            Name: variant(z.string()),
+            Powered: variant(z.boolean()),
+        })
+            .optional(),
+        [DIAGNOSTIC]: z.object({}).optional(),
+        [NETWORK]: z
+            .object({
+            Connected: variant(z.boolean()),
+            KnownNetwork: variant(z.string()).optional(),
+            Name: variant(z.string()),
+            Type: variant(z.string()),
+        })
+            .optional(),
+        [STATION]: stationSchema.optional(),
+    })),
+]);
+/** Each network's path and signal, in 100 * dBm. */
+const orderedNetworksSchema = z.tuple([
+    z.array(z.tuple([z.string(), z.number()])),
+]);
+/** `RxBitrate` is in 100 kbit/s. */
+const diagnosticsSchema = z.tuple([
+    z.object({
+        Frequency: variant(z.number()),
+        RxBitrate: variant(z.number()),
+    }),
+]);
+const propertiesChangedSchema = z.tuple([
+    z.string(),
+    z.record(z.string(), z.unknown()),
+    z.array(z.string()),
+]);

package/dist/iwd.js

@@ -3,7 +3,7 @@
 import { Err, Ok } from "@cprussin/option-result";
 import { Bus } from "@domicile-desktop/sdk/system";
 import { z } from "zod";
-import { followNetwork } from "./follow";
+import { followBus } from "./follow";
 import { Connectivity, Link } from "./network-state";
 import { strengthOfDbm } from "./signal-strength";
 import { variant } from "./variant";
@@ -24,7 +24,7 @@ const WATCHED = ["ConnectedNetwork", "Scanning", "State"];
  * not running. The watch keeps listening after one, so a later change reads
  * again.
  */
-export const watchIwd = (system, onNetwork) => followNetwork(system, { bus: Bus.System, sender: SERVICE }, async () => ({ matters, network: await read(system) }), onNetwork);
+export const watchIwd = (system, onNetwork) => followBus(system, { bus: Bus.System, sender: SERVICE }, async () => ({ matters, value: await read(system) }), onNetwork);
 /**
  * Whether `signal` can change the network: an object coming or going, or a
  * watched station property.

package/dist/network.js

@@ -3,8 +3,7 @@
 // types, which live in `network-state` so the backends can import them
 // without a cycle. See docs/SHELL-SYSTEM-ACCESS.md.
 import { Err, Ok } from "@cprussin/option-result";
-import { Bus } from "@domicile-desktop/sdk/system";
-import { z } from "zod";
+import { hasOwner } from "./has-owner";
 import { watchIwd } from "./iwd";
 import { watchNetworkManager } from "./networkmanager";
 import { watchWpaSupplicant } from "./wpa-supplicant";
@@ -63,16 +62,3 @@ const detect = async (system, backends) => {
         });
     }
 };
-/**
- * Whether `name` has an owner. `NameHasOwner` does not start a service that
- * D-Bus can activate, as a call to the service would.
- */
-const hasOwner = async (system, name) => (await system.dbusCall({
-    body: [name],
-    bus: Bus.System,
-    destination: "org.freedesktop.DBus",
-    interface: "org.freedesktop.DBus",
-    member: "NameHasOwner",
-    path: "/org/freedesktop/DBus",
-    signature: "s",
-})).map(({ body }) => z.tuple([z.boolean()]).parse(body)[0]);

package/dist/networkmanager-wifi.d.ts

@@ -0,0 +1,27 @@
+import type { Option } from "@cprussin/option-result";
+import { Result } from "@cprussin/option-result";
+import type { SystemError } from "@domicile-desktop/sdk/system";
+import type { NetworkSystem } from "./network-state";
+import type { Wifi, WifiDevice, WifiNetwork } from "./wifi-state";
+/** A read's outcome: Wi-Fi, if there is a device, or the first failure. */
+type Found = Result<Option<Wifi>, SystemError>;
+/**
+ * Calls `onWifi` with the first Wi-Fi device now and after each change, and
+ * returns a function that stops watching. `None` is a machine without one.
+ *
+ * An `Err` is a D-Bus failure, such as NetworkManager not running. The watch
+ * keeps listening after one, so a later change reads again.
+ */
+export declare const watchNetworkManagerWifi: (system: NetworkSystem, onWifi: (wifi: Found) => void) => (() => void);
+/** Turn the Wi-Fi radio on or off. */
+export declare const setNetworkManagerWifiEnabled: (system: NetworkSystem, _wifi: WifiDevice, enabled: boolean) => Promise<Result<"done", SystemError>>;
+/** Ask for a scan. Networks it finds arrive as changes. */
+export declare const scanNetworkManagerWifi: (system: NetworkSystem, wifi: WifiDevice) => Promise<Result<"done", SystemError>>;
+/**
+ * Join `network`: through its saved profile if it has one, or with a new
+ * profile, which needs `passphrase` when the network is secured.
+ */
+export declare const connectNetworkManagerWifi: (system: NetworkSystem, wifi: WifiDevice, network: WifiNetwork, passphrase: string | undefined) => Promise<Result<"done", SystemError>>;
+/** Leave the current network, until asked to join one. */
+export declare const disconnectNetworkManagerWifi: (system: NetworkSystem, wifi: WifiDevice) => Promise<Result<"done", SystemError>>;
+export {};

package/dist/networkmanager-wifi.js

@@ -0,0 +1,257 @@
+// NetworkManager's Wi-Fi device over the system bus: its networks and
+// connection, kept current, and the requests that change them. See
+// docs/SHELL-SYSTEM-ACCESS.md.
+import { None, Ok, Result, Some } from "@cprussin/option-result";
+import { Bus } from "@domicile-desktop/sdk/system";
+import { z } from "zod";
+import { followBus } from "./follow";
+import { variant } from "./variant";
+import { WifiBackend } from "./wifi-state";
+const SERVICE = "org.freedesktop.NetworkManager";
+const ROOT = "/org/freedesktop/NetworkManager";
+const DEVICE = `${SERVICE}.Device`;
+const WIRELESS = `${SERVICE}.Device.Wireless`;
+/** The object path NetworkManager uses for "none". */
+const NO_OBJECT = "/";
+/** `NM_DEVICE_TYPE_WIFI`. */
+const WIFI_DEVICE = 2;
+/**
+ * Calls `onWifi` with the first Wi-Fi device now and after each change, and
+ * returns a function that stops watching. `None` is a machine without one.
+ *
+ * An `Err` is a D-Bus failure, such as NetworkManager not running. The watch
+ * keeps listening after one, so a later change reads again.
+ */
+export const watchNetworkManagerWifi = (system, onWifi) => followBus(system, { bus: Bus.System, sender: SERVICE }, () => read(system), onWifi);
+/** Turn the Wi-Fi radio on or off. */
+export const setNetworkManagerWifiEnabled = async (system, _wifi, enabled) => done(await system.dbusCall(request(ROOT, "org.freedesktop.DBus.Properties", "Set", "ssv", [
+    SERVICE,
+    "WirelessEnabled",
+    { signature: "b", value: enabled },
+])));
+/** Ask for a scan. Networks it finds arrive as changes. */
+export const scanNetworkManagerWifi = async (system, wifi) => done(await system.dbusCall(request(wifi.device, WIRELESS, "RequestScan", "a{sv}", [{}])));
+/**
+ * Join `network`: through its saved profile if it has one, or with a new
+ * profile, which needs `passphrase` when the network is secured.
+ */
+export const connectNetworkManagerWifi = async (system, wifi, network, passphrase) => done(await system.dbusCall(network.profile === undefined
+    ? request(ROOT, SERVICE, "AddAndActivateConnection", "a{sa{sv}}oo", [
+        newProfile(network, passphrase),
+        wifi.device,
+        network.path,
+    ])
+    : request(ROOT, SERVICE, "ActivateConnection", "ooo", [
+        network.profile,
+        wifi.device,
+        network.path,
+    ])));
+/** Leave the current network, until asked to join one. */
+export const disconnectNetworkManagerWifi = async (system, wifi) => done(await system.dbusCall({
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: DEVICE,
+    member: "Disconnect",
+    path: wifi.device,
+}));
+const request = (path, iface, member, signature, body) => ({
+    body,
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: iface,
+    member,
+    path,
+    signature,
+});
+const done = (reply) => reply.map(() => "done");
+/** The settings NetworkManager fills in a profile from, past the access point. */
+const newProfile = (network, passphrase) => {
+    if (!network.secured) {
+        return {};
+    }
+    else if (passphrase === undefined) {
+        throw new Error(`joining ${network.ssid} needs a passphrase`);
+    }
+    else {
+        return {
+            "802-11-wireless-security": {
+                "key-mgmt": { signature: "s", value: "wpa-psk" },
+                psk: { signature: "s", value: passphrase },
+            },
+        };
+    }
+};
+/**
+ * Read Wi-Fi. A property change on an object read for it matters, as does an
+ * access point or a device coming or going.
+ */
+const read = async (system) => {
+    const paths = new Set([ROOT]);
+    const value = await readWifi(system, paths);
+    return { matters: (signal) => matters(paths, signal), value };
+};
+const matters = (paths, signal) => {
+    switch (signal.member) {
+        case "AccessPointAdded":
+        case "AccessPointRemoved":
+        case "DeviceAdded":
+        case "DeviceRemoved": {
+            return true;
+        }
+        case "PropertiesChanged": {
+            return (signal.interface === "org.freedesktop.DBus.Properties" &&
+                paths.has(signal.path));
+        }
+        default: {
+            return false;
+        }
+    }
+};
+/** Read Wi-Fi, adding each object read to `paths`. */
+const readWifi = async (system, paths) => (await properties(system, ROOT, SERVICE, rootSchema)).andThenAsync(async ({ WirelessEnabled: enabled }) => (await call(system, ROOT, SERVICE, "GetDevices")).andThenAsync(async ({ body }) => {
+    const listed = devicesSchema.parse(body)[0];
+    for (const path of listed) {
+        paths.add(path);
+    }
+    const devices = Result.collect(await Promise.all(listed.map(async (path) => (await properties(system, path, DEVICE, deviceSchema)).map((device) => ({ device, path })))));
+    return devices.andThenAsync(async (read) => {
+        const found = read.find(({ device }) => device.DeviceType === WIFI_DEVICE);
+        return found === undefined
+            ? Ok(None())
+            : (await wifiOf(system, paths, found.path, found.device, enabled)).map((wifi) => Some(wifi));
+    });
+}));
+/** The Wi-Fi device at `path`. */
+const wifiOf = async (system, paths, path, device, enabled) => (await properties(system, path, WIRELESS, wirelessSchema)).andThenAsync(async (radio) => {
+    for (const point of radio.AccessPoints) {
+        paths.add(point);
+    }
+    paths.add(device.Ip4Config);
+    const [points, profiles, ip] = await Promise.all([
+        accessPoints(system, radio.AccessPoints),
+        savedProfiles(system, device.AvailableConnections),
+        radio.ActiveAccessPoint === NO_OBJECT || device.Ip4Config === NO_OBJECT
+            ? Promise.resolve(Ok(None()))
+            : ipOf(system, device.Ip4Config),
+    ]);
+    return points.andThen((read) => profiles.andThen((saved) => ip.map((address) => ({
+        backend: WifiBackend.NetworkManager,
+        connection: connectionOf(read, radio, address),
+        device: path,
+        enabled,
+        hardwareAddress: device.HwAddress,
+        interface: device.Interface,
+        networks: networksOf(read, saved, radio.ActiveAccessPoint),
+        scanning: false,
+    }))));
+});
+const accessPoints = async (system, listed) => Result.collect(await Promise.all(listed.map(async (path) => (await properties(system, path, `${SERVICE}.AccessPoint`, accessPointSchema)).map((point) => ({ ...point, path })))));
+/** Each saved Wi-Fi profile's path, by its network's name. */
+const savedProfiles = async (system, listed) => Result.collect(await Promise.all(listed.map(async (path) => (await call(system, path, `${SERVICE}.Settings.Connection`, "GetSettings")).map(({ body }) => ({
+    path,
+    settings: settingsSchema.parse(body)[0],
+}))))).map((saved) => new Map(saved.flatMap(({ path, settings }) => {
+    const ssid = settings["802-11-wireless"]?.ssid;
+    return ssid === undefined ? [] : [[ssid, path]];
+})));
+const ipOf = async (system, path) => (await properties(system, path, `${SERVICE}.IP4Config`, ip4Schema)).map((config) => Some({
+    addresses: config.AddressData.map(({ address, prefix }) => `${address}/${prefix}`),
+    dns: config.NameserverData.map(({ address }) => address),
+    gateway: config.Gateway === "" ? undefined : config.Gateway,
+}));
+/** The named networks, one per name: its strongest access point. */
+const networksOf = (points, profiles, active) => {
+    const byName = new Map();
+    for (const point of points.filter(({ Ssid }) => Ssid !== "")) {
+        byName.set(point.Ssid, [...(byName.get(point.Ssid) ?? []), point]);
+    }
+    return [...byName.values()]
+        .map((named) => {
+        const [strongest] = named.toSorted((a, b) => b.Strength - a.Strength);
+        if (strongest === undefined) {
+            throw new Error("a network with no access point");
+        }
+        else {
+            return {
+                connected: named.some(({ path }) => path === active),
+                path: strongest.path,
+                profile: profiles.get(strongest.Ssid),
+                secured: isSecured(strongest),
+                ssid: strongest.Ssid,
+                strength: strongest.Strength / 100,
+            };
+        }
+    })
+        .toSorted((a, b) => b.strength - a.strength);
+};
+const connectionOf = (points, radio, ip) => {
+    const active = points.find(({ path }) => path === radio.ActiveAccessPoint);
+    return active === undefined
+        ? undefined
+        : {
+            bitrate: radio.Bitrate / 1000,
+            frequency: active.Frequency,
+            ip: ip.match({ None: () => undefined, Some: (address) => address }),
+            ssid: active.Ssid,
+            strength: active.Strength / 100,
+        };
+};
+/** `NM_802_11_AP_FLAGS_PRIVACY`, or any WPA or RSN flag. */
+const isSecured = (point) => (point.Flags & 1) !== 0 || point.WpaFlags !== 0 || point.RsnFlags !== 0;
+const call = (system, path, iface, member) => system.dbusCall({
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: iface,
+    member,
+    path,
+});
+/** `Properties.GetAll` on one of NetworkManager's objects, parsed. */
+const properties = async (system, path, interfaceName, schema) => (await system.dbusCall({
+    body: [interfaceName],
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: "org.freedesktop.DBus.Properties",
+    member: "GetAll",
+    path,
+    signature: "s",
+})).map(({ body }) => z.tuple([schema]).parse(body)[0]);
+/** An SSID's bytes, as text. */
+const ssid = z
+    .array(z.number())
+    .transform((bytes) => new TextDecoder().decode(new Uint8Array(bytes)));
+const rootSchema = z.object({ WirelessEnabled: variant(z.boolean()) });
+const devicesSchema = z.tuple([z.array(z.string())]);
+const deviceSchema = z.object({
+    AvailableConnections: variant(z.array(z.string())),
+    DeviceType: variant(z.number()),
+    HwAddress: variant(z.string()),
+    Interface: variant(z.string()),
+    Ip4Config: variant(z.string()),
+});
+const wirelessSchema = z.object({
+    AccessPoints: variant(z.array(z.string())),
+    ActiveAccessPoint: variant(z.string()),
+    /** In kbit/s. */
+    Bitrate: variant(z.number()),
+});
+const accessPointSchema = z.object({
+    Flags: variant(z.number()),
+    Frequency: variant(z.number()),
+    RsnFlags: variant(z.number()),
+    Ssid: variant(ssid),
+    Strength: variant(z.number()),
+    WpaFlags: variant(z.number()),
+});
+const settingsSchema = z.tuple([
+    z.object({
+        "802-11-wireless": z.object({ ssid: variant(ssid).optional() }).optional(),
+    }),
+]);
+const ip4Schema = z.object({
+    AddressData: variant(z.array(z.object({
+        address: variant(z.string()),
+        prefix: variant(z.number()),
+    }))),
+    Gateway: variant(z.string()),
+    NameserverData: variant(z.array(z.object({ address: variant(z.string()) }))),
+});

package/dist/networkmanager.js

@@ -3,7 +3,7 @@
 import { Err, Ok } from "@cprussin/option-result";
 import { Bus } from "@domicile-desktop/sdk/system";
 import { z } from "zod";
-import { followNetwork } from "./follow";
+import { followBus } from "./follow";
 import { Connectivity, Link } from "./network-state";
 import { variant } from "./variant";
 const SERVICE = "org.freedesktop.NetworkManager";
@@ -17,7 +17,7 @@ const NO_OBJECT = "/";
  * An `Err` is a D-Bus failure, such as NetworkManager not running. The watch
  * keeps listening after one, so a later change reads again.
  */
-export const watchNetworkManager = (system, onNetwork) => followNetwork(system, {
+export const watchNetworkManager = (system, onNetwork) => followBus(system, {
     bus: Bus.System,
     interface: "org.freedesktop.DBus.Properties",
     member: "PropertiesChanged",
@@ -29,14 +29,14 @@ const read = async (system) => {
     return root.match({
         Err: (error) => Promise.resolve({
             matters: ({ path }) => path === ROOT,
-            network: Err(error),
+            value: Err(error),
         }),
         Ok: async ({ Connectivity: connectivity, PrimaryConnection: primary }) => {
             const link = await linkOf(system, primary);
             const paths = new Set([ROOT, ...link.paths]);
             return {
                 matters: ({ path }) => paths.has(path),
-                network: link.result.map((found) => ({
+                value: link.result.map((found) => ({
                     connectivity,
                     link: found,
                 })),

package/dist/wifi-state.d.ts

@@ -0,0 +1,54 @@
+import type { System } from "@domicile-desktop/sdk/system";
+/** The service that manages the Wi-Fi device. */
+export declare enum WifiBackend {
+    NetworkManager = 0,
+    Iwd = 1
+}
+/** A network in range. */
+export type WifiNetwork = {
+    /** The service's object for it: an access point (NetworkManager) or a network (iwd). */
+    path: string;
+    ssid: string;
+    /** 0 through 1. */
+    strength: number;
+    secured: boolean;
+    /** The saved profile: a connection (NetworkManager) or a known network (iwd). */
+    profile: string | undefined;
+    connected: boolean;
+};
+/** The addresses the service configured. */
+export type Ip = {
+    /** Each with its prefix, as `192.168.1.23/24`. */
+    addresses: string[];
+    gateway: string | undefined;
+    dns: string[];
+};
+export type WifiConnection = {
+    ssid: string;
+    /** 0 through 1. */
+    strength: number;
+    /** In MHz. */
+    frequency: number | undefined;
+    /** In Mbit/s. */
+    bitrate: number | undefined;
+    /** `undefined` from iwd, which does not report addresses over D-Bus. */
+    ip: Ip | undefined;
+};
+export type Wifi = {
+    backend: WifiBackend;
+    /** The device's object, which requests address. */
+    device: string;
+    interface: string;
+    hardwareAddress: string;
+    /** Whether the radio is on. */
+    enabled: boolean;
+    /** Whether a scan is running. Always `false` from NetworkManager, which does not say. */
+    scanning: boolean;
+    /** One per name, strongest first. Hidden networks are left out. */
+    networks: WifiNetwork[];
+    connection: WifiConnection | undefined;
+};
+/** What a request needs of the device. */
+export type WifiDevice = Pick<Wifi, "backend" | "device" | "interface">;
+/** The calls this library makes for Wi-Fi. */
+export type WifiSystem = Pick<System, "dbusCall" | "dbusMatch" | "run">;

package/dist/wifi-state.js

@@ -0,0 +1,8 @@
+// The Wi-Fi device as every backend reports it: its networks and its
+// connection. See docs/SHELL-SYSTEM-ACCESS.md.
+/** The service that manages the Wi-Fi device. */
+export var WifiBackend;
+(function (WifiBackend) {
+    WifiBackend[WifiBackend["NetworkManager"] = 0] = "NetworkManager";
+    WifiBackend[WifiBackend["Iwd"] = 1] = "Iwd";
+})(WifiBackend || (WifiBackend = {}));

package/dist/wifi.d.ts

@@ -0,0 +1,25 @@
+import type { Option, Result } from "@cprussin/option-result";
+import type { SystemError } from "@domicile-desktop/sdk/system";
+import type { Wifi, WifiDevice, WifiNetwork, WifiSystem } from "./wifi-state";
+export type { Ip, Wifi, WifiConnection, WifiDevice, WifiNetwork, WifiSystem, } from "./wifi-state";
+export { WifiBackend } from "./wifi-state";
+/**
+ * Calls `onWifi` with the Wi-Fi device now and after each change, and returns
+ * a function that stops watching.
+ *
+ * Watches the first of NetworkManager and iwd on the system bus when called.
+ * `None` is no Wi-Fi device, or neither service: wpa_supplicant alone is not
+ * controlled. An `Err` is a D-Bus failure.
+ */
+export declare const watchWifi: (system: WifiSystem, onWifi: (wifi: Result<Option<Wifi>, SystemError>) => void) => (() => void);
+/** Turn the radio on or off. */
+export declare const setWifiEnabled: (system: WifiSystem, wifi: WifiDevice, enabled: boolean) => Promise<Result<"done", SystemError>>;
+/** Ask for a scan. Networks it finds arrive through the watch. */
+export declare const scanWifi: (system: WifiSystem, wifi: WifiDevice) => Promise<Result<"done", SystemError>>;
+/**
+ * Join `network`. A secured network with no saved profile needs `passphrase`;
+ * the call throws without one.
+ */
+export declare const connectWifi: (system: WifiSystem, wifi: WifiDevice, network: WifiNetwork, passphrase: string | undefined) => Promise<Result<"done", SystemError>>;
+/** Leave the current network. */
+export declare const disconnectWifi: (system: WifiSystem, wifi: WifiDevice) => Promise<Result<"done", SystemError>>;

package/dist/wifi.js

@@ -0,0 +1,116 @@
+// The Wi-Fi device from whichever service manages it, NetworkManager or iwd,
+// and the requests that change it. It also forwards the Wi-Fi types, which
+// live in `wifi-state` so the backends can import them without a cycle. See
+// docs/SHELL-SYSTEM-ACCESS.md.
+import { Err, None, Ok, Some } from "@cprussin/option-result";
+import { hasOwner } from "./has-owner";
+import { connectIwdWifi, disconnectIwdWifi, scanIwdWifi, setIwdWifiEnabled, watchIwdWifi, } from "./iwd-wifi";
+import { connectNetworkManagerWifi, disconnectNetworkManagerWifi, scanNetworkManagerWifi, setNetworkManagerWifiEnabled, watchNetworkManagerWifi, } from "./networkmanager-wifi";
+import { WifiBackend } from "./wifi-state";
+export { WifiBackend } from "./wifi-state";
+/** Each backend's bus name, in the order they are tried. */
+const BACKENDS = [
+    ["org.freedesktop.NetworkManager", WifiBackend.NetworkManager],
+    ["net.connman.iwd", WifiBackend.Iwd],
+];
+/**
+ * Calls `onWifi` with the Wi-Fi device now and after each change, and returns
+ * a function that stops watching.
+ *
+ * Watches the first of NetworkManager and iwd on the system bus when called.
+ * `None` is no Wi-Fi device, or neither service: wpa_supplicant alone is not
+ * controlled. An `Err` is a D-Bus failure.
+ */
+export const watchWifi = (system, onWifi) => {
+    const watch = { stop: undefined, stopped: false };
+    detect(system, BACKENDS)
+        .then((found) => {
+        if (!watch.stopped) {
+            found.match({
+                Err: (error) => {
+                    onWifi(Err(error));
+                },
+                Ok: (backend) => {
+                    backend.match({
+                        None: () => {
+                            onWifi(Ok(None()));
+                        },
+                        Some: (chosen) => {
+                            watch.stop = watchBackend(chosen)(system, onWifi);
+                        },
+                    });
+                },
+            });
+        }
+    })
+        .catch((error) => {
+        // biome-ignore lint/suspicious/noConsole: surfacing a background failure
+        console.error("Failed to find a Wi-Fi service", error);
+    });
+    return () => {
+        watch.stopped = true;
+        watch.stop?.();
+    };
+};
+/** Turn the radio on or off. */
+export const setWifiEnabled = (system, wifi, enabled) => {
+    switch (wifi.backend) {
+        case WifiBackend.NetworkManager:
+            return setNetworkManagerWifiEnabled(system, wifi, enabled);
+        case WifiBackend.Iwd:
+            return setIwdWifiEnabled(system, wifi, enabled);
+    }
+};
+/** Ask for a scan. Networks it finds arrive through the watch. */
+export const scanWifi = (system, wifi) => {
+    switch (wifi.backend) {
+        case WifiBackend.NetworkManager:
+            return scanNetworkManagerWifi(system, wifi);
+        case WifiBackend.Iwd:
+            return scanIwdWifi(system, wifi);
+    }
+};
+/**
+ * Join `network`. A secured network with no saved profile needs `passphrase`;
+ * the call throws without one.
+ */
+export const connectWifi = (system, wifi, network, passphrase) => {
+    switch (wifi.backend) {
+        case WifiBackend.NetworkManager:
+            return connectNetworkManagerWifi(system, wifi, network, passphrase);
+        case WifiBackend.Iwd:
+            return connectIwdWifi(system, wifi, network, passphrase);
+    }
+};
+/** Leave the current network. */
+export const disconnectWifi = (system, wifi) => {
+    switch (wifi.backend) {
+        case WifiBackend.NetworkManager:
+            return disconnectNetworkManagerWifi(system, wifi);
+        case WifiBackend.Iwd:
+            return disconnectIwdWifi(system, wifi);
+    }
+};
+const watchBackend = (backend) => {
+    switch (backend) {
+        case WifiBackend.NetworkManager:
+            return watchNetworkManagerWifi;
+        case WifiBackend.Iwd:
+            return watchIwdWifi;
+    }
+};
+/** The first backend whose service has an owner on the bus, if any. */
+const detect = async (system, backends) => {
+    const [first, ...rest] = backends;
+    if (first === undefined) {
+        return Ok(None());
+    }
+    else {
+        const [name, backend] = first;
+        const owned = await hasOwner(system, name);
+        return owned.match({
+            Err: (error) => Promise.resolve(Err(error)),
+            Ok: (has) => has ? Promise.resolve(Ok(Some(backend))) : detect(system, rest),
+        });
+    }
+};

package/dist/wpa-supplicant.js

@@ -3,7 +3,7 @@
 import { Err, Ok, Result } from "@cprussin/option-result";
 import { Bus } from "@domicile-desktop/sdk/system";
 import { z } from "zod";
-import { followNetwork } from "./follow";
+import { followBus } from "./follow";
 import { Connectivity, Link } from "./network-state";
 import { strengthOfDbm } from "./signal-strength";
 import { variant } from "./variant";
@@ -19,7 +19,7 @@ const ROOT = "/fi/w1/wpa_supplicant1";
  * such as wpa_supplicant not on the bus. The watch keeps listening after one,
  * so a later change reads again.
  */
-export const watchWpaSupplicant = (system, onNetwork) => followNetwork(system, { bus: Bus.System, sender: SERVICE }, () => read(system), onNetwork);
+export const watchWpaSupplicant = (system, onNetwork) => followBus(system, { bus: Bus.System, sender: SERVICE }, () => read(system), onNetwork);
 /**
  * Read the network. An interface coming or going matters, as does a property
  * change on an object read for it.
@@ -28,7 +28,7 @@ const read = async (system) => {
     const found = await readPaths(system);
     return {
         matters: (signal) => matters(found.paths, signal),
-        network: found.network.map((link) => ({
+        value: found.network.map((link) => ({
             connectivity: Connectivity.Unknown,
             link,
         })),

package/package.json

@@ -1,7 +1,7 @@
 {
   "dependencies": {
     "@cprussin/option-result": "^2.0.1",
-    "@domicile-desktop/sdk": "0.0.0-alpha-d3ee6fbb3e64",
+    "@domicile-desktop/sdk": "0.0.0-alpha-1fcbde657613",
     "zod": "^4.5.4"
   },
   "description": "The network for a Domicile shell, from NetworkManager, iwd or wpa_supplicant: connectivity and the primary connection, with its Wi-Fi network and signal, kept current.",
@@ -23,6 +23,10 @@
       "types": "./dist/networkmanager.d.ts",
       "default": "./dist/networkmanager.js"
     },
+    "./wifi": {
+      "types": "./dist/wifi.d.ts",
+      "default": "./dist/wifi.js"
+    },
     "./wpa-supplicant": {
       "types": "./dist/wpa-supplicant.d.ts",
       "default": "./dist/wpa-supplicant.js"
@@ -48,5 +52,5 @@
     "test:unit": "bun test"
   },
   "type": "module",
-  "version": "0.0.0-alpha-d3ee6fbb3e64"
+  "version": "0.0.0-alpha-1fcbde657613"
 }