@ceralive/modem-control 0.1.0

package/src/ports/reconcile.ts

@@ -0,0 +1,338 @@
+// The desired-state planner — pure. Given the currently-applied state, a desired
+// policy, and the modem's capabilities, it produces the port-tagged ops needed to
+// converge PLUS an honest receipt per policy dimension. It performs no I/O and no
+// side effects: the same inputs always yield the same ops and receipts, which is
+// what makes re-applying a policy idempotent (see reconcile.test.ts).
+
+import type { DesiredCellularPolicy, NmActivation, RadioAccessTechnology } from '../domain';
+import type { ConnectionId, DeviceIfname, GsmProfileInput } from './network-manager';
+import { mmOp, nmOp, type PortTaggedOp } from './ops';
+import { type Receipt, receipt } from './receipts';
+
+/** What the modem / stack can actually do — the capability set the planner honors. */
+export interface ModemCapabilities {
+	readonly supportedRats: ReadonlySet<RadioAccessTechnology>;
+	readonly simSlotCount: number;
+	readonly supportsAutoApn: boolean;
+}
+
+/**
+ * The currently-applied cellular configuration, as the planner sees it — the "is"
+ * state, distinct from the observational snapshot: it tracks what has actually been
+ * written (profile, radio preference, primary slot) plus the live NM activation.
+ */
+export interface AppliedCellularState {
+	readonly nmActivation: NmActivation;
+	readonly hasProfile: boolean;
+	readonly connectionId?: ConnectionId;
+	readonly deviceIfname?: DeviceIfname;
+	readonly appliedApn?: 'auto' | string;
+	readonly appliedRoaming?: boolean;
+	readonly appliedRadioPreference?: readonly RadioAccessTechnology[];
+	readonly activePrimarySlot?: number;
+	readonly activationFailureReason?: string;
+}
+
+/** A reconcile plan: the ops to run and one receipt per policy dimension. */
+export interface Plan {
+	readonly ops: readonly PortTaggedOp[];
+	readonly receipts: readonly Receipt[];
+}
+
+interface DimensionResult {
+	readonly receipt: Receipt;
+	readonly op?: PortTaggedOp;
+}
+
+interface ProfilePlan {
+	readonly connection: Receipt;
+	readonly roaming: Receipt;
+	readonly op?: PortTaggedOp;
+}
+
+/** Reconcile a desired policy against the applied state into ops + receipts. */
+export function planReconcile(
+	current: AppliedCellularState,
+	desired: DesiredCellularPolicy,
+	capabilities: ModemCapabilities,
+): Plan {
+	const profile = planNmProfile(current, desired, capabilities);
+	const results: readonly DimensionResult[] = [
+		planRadio(current, desired, capabilities),
+		planSimSlot(current, desired, capabilities),
+		planEnabled(current, desired),
+		{ receipt: planRecovery(desired) },
+		{ receipt: planUsage(desired) },
+	];
+
+	const ops: PortTaggedOp[] = [];
+	const receipts: Receipt[] = [profile.connection, profile.roaming];
+	if (profile.op !== undefined) {
+		ops.push(profile.op);
+	}
+	for (const result of results) {
+		receipts.push(result.receipt);
+		if (result.op !== undefined) {
+			ops.push(result.op);
+		}
+	}
+	return { ops, receipts };
+}
+
+function profileFromPolicy(desired: DesiredCellularPolicy): GsmProfileInput {
+	const auto = desired.connection.apn === 'auto';
+	const base: GsmProfileInput = {
+		connectionName: 'ceralive-cellular',
+		apn: auto ? '' : desired.connection.apn,
+		homeOnly: !desired.roaming,
+		autoConfig: auto,
+	};
+	// SENSITIVE creds only when explicitly provided AND not in auto-config mode.
+	if (!auto && desired.connection.auth !== undefined) {
+		const { username, password } = desired.connection.auth;
+		return {
+			...base,
+			...(username !== undefined ? { username } : {}),
+			...(password !== undefined ? { password } : {}),
+		};
+	}
+	return base;
+}
+
+// NM owns APN / auth / roaming / autoconnect: one profile write converges all of
+// them, so connection + roaming share a single op and each get their own receipt.
+function planNmProfile(
+	current: AppliedCellularState,
+	desired: DesiredCellularPolicy,
+	capabilities: ModemCapabilities,
+): ProfilePlan {
+	const auto = desired.connection.apn === 'auto';
+	if (auto && !capabilities.supportsAutoApn) {
+		return {
+			connection: receipt(
+				'connection',
+				'unsupported',
+				'Auto-APN is not available on this NetworkManager / modem',
+			),
+			roaming: receipt(
+				'roaming',
+				'unsupported',
+				'roaming cannot be applied without a connection profile',
+			),
+		};
+	}
+	const needsWrite =
+		!current.hasProfile ||
+		current.appliedApn !== desired.connection.apn ||
+		current.appliedRoaming !== desired.roaming;
+	if (!needsWrite) {
+		return {
+			connection: receipt(
+				'connection',
+				'applied',
+				`connection APN '${desired.connection.apn}' already configured`,
+			),
+			roaming: receipt(
+				'roaming',
+				'applied',
+				`roaming already ${desired.roaming ? 'enabled' : 'disabled'}`,
+			),
+		};
+	}
+	const op =
+		current.hasProfile && current.connectionId !== undefined
+			? nmOp({
+					kind: 'updateGsmProfile',
+					connectionId: current.connectionId,
+					patch: profileFromPolicy(desired),
+				})
+			: nmOp({ kind: 'createGsmProfile', profile: profileFromPolicy(desired) });
+	const verb = current.hasProfile ? 'updating' : 'creating';
+	return {
+		connection: receipt(
+			'connection',
+			'pending',
+			`${verb} connection profile for APN '${desired.connection.apn}'`,
+		),
+		roaming: receipt(
+			'roaming',
+			'pending',
+			`roaming ${desired.roaming ? 'enabled' : 'disabled'} via connection profile`,
+		),
+		op,
+	};
+}
+
+function radioMatches(
+	applied: readonly RadioAccessTechnology[] | undefined,
+	desired: readonly RadioAccessTechnology[],
+): boolean {
+	if (applied === undefined || applied.length !== desired.length) {
+		return false;
+	}
+	return applied.every((rat, index) => rat === desired[index]);
+}
+
+function planRadio(
+	current: AppliedCellularState,
+	desired: DesiredCellularPolicy,
+	capabilities: ModemCapabilities,
+): DimensionResult {
+	const preference = desired.radio.preferenceOrdered;
+	const top = preference[0];
+	if (top === undefined) {
+		return {
+			receipt: receipt(
+				'radio',
+				'failed',
+				'radio preference must list at least one access technology',
+			),
+		};
+	}
+	if (!capabilities.supportedRats.has(top)) {
+		const supported = [...capabilities.supportedRats].join(', ') || 'none';
+		return {
+			receipt: receipt(
+				'radio',
+				'unsupported',
+				`preferred radio access technology '${top}' is not supported by this modem (supports ${supported})`,
+			),
+		};
+	}
+	if (radioMatches(current.appliedRadioPreference, preference)) {
+		return {
+			receipt: receipt('radio', 'applied', `radio preference already ${preference.join(' > ')}`),
+		};
+	}
+	return {
+		receipt: receipt('radio', 'pending', `setting radio preference to ${preference.join(' > ')}`),
+		op: mmOp({ kind: 'setRadioModes', preference: desired.radio }),
+	};
+}
+
+function planSimSlot(
+	current: AppliedCellularState,
+	desired: DesiredCellularPolicy,
+	capabilities: ModemCapabilities,
+): DimensionResult {
+	if (desired.simSlot === undefined) {
+		return { receipt: receipt('simSlot', 'applied', 'no primary SIM slot preference set') };
+	}
+	if (capabilities.simSlotCount <= 1) {
+		return {
+			receipt: receipt(
+				'simSlot',
+				'unsupported',
+				`primary SIM slot selection requires a multi-slot modem (this modem has ${capabilities.simSlotCount})`,
+			),
+		};
+	}
+	if (desired.simSlot < 1 || desired.simSlot > capabilities.simSlotCount) {
+		return {
+			receipt: receipt(
+				'simSlot',
+				'failed',
+				`SIM slot ${desired.simSlot} is out of range (1..${capabilities.simSlotCount})`,
+			),
+		};
+	}
+	if (current.activePrimarySlot === desired.simSlot) {
+		return {
+			receipt: receipt('simSlot', 'applied', `SIM slot ${desired.simSlot} already primary`),
+		};
+	}
+	return {
+		receipt: receipt('simSlot', 'pending', `switching primary SIM slot to ${desired.simSlot}`),
+		op: mmOp({ kind: 'setPrimarySimSlot', slotIndex: desired.simSlot }),
+	};
+}
+
+function planEnabled(
+	current: AppliedCellularState,
+	desired: DesiredCellularPolicy,
+): DimensionResult {
+	const nm = current.nmActivation;
+	const addressable = current.connectionId !== undefined && current.deviceIfname !== undefined;
+	if (desired.enabled) {
+		switch (nm) {
+			case 'activated':
+				return { receipt: receipt('enabled', 'applied', 'connection is active') };
+			case 'activating':
+				return { receipt: receipt('enabled', 'pending', 'connection activation in progress') };
+			case 'failed':
+				return {
+					receipt: receipt(
+						'enabled',
+						'failed',
+						`connection activation failed${current.activationFailureReason ? `: ${current.activationFailureReason}` : ''}`,
+					),
+				};
+			case 'unmanaged':
+				return {
+					receipt: receipt('enabled', 'unsupported', 'device is not managed by NetworkManager'),
+				};
+			default:
+				if (
+					!addressable ||
+					current.connectionId === undefined ||
+					current.deviceIfname === undefined
+				) {
+					return {
+						receipt: receipt(
+							'enabled',
+							'pending',
+							'awaiting connection profile and data interface before activation',
+						),
+					};
+				}
+				return {
+					receipt: receipt('enabled', 'pending', 'activating connection'),
+					op: nmOp({
+						kind: 'activate',
+						connectionId: current.connectionId,
+						deviceIfname: current.deviceIfname,
+					}),
+				};
+		}
+	}
+	if (
+		(nm === 'activated' || nm === 'activating') &&
+		current.connectionId !== undefined &&
+		current.deviceIfname !== undefined
+	) {
+		return {
+			receipt: receipt('enabled', 'pending', 'deactivating connection'),
+			op: nmOp({
+				kind: 'deactivate',
+				connectionId: current.connectionId,
+				deviceIfname: current.deviceIfname,
+			}),
+		};
+	}
+	return { receipt: receipt('enabled', 'applied', 'connection is inactive') };
+}
+
+// Recovery + usage are LOCAL-CONTROLLER owned (README ownership table): they emit no
+// MM / NM op, only a receipt recording that the local policy was accepted.
+function planRecovery(desired: DesiredCellularPolicy): Receipt {
+	return receipt(
+		'recovery',
+		'applied',
+		desired.recovery.enabled ? 'recovery policy recorded (enabled)' : 'recovery disabled (default)',
+	);
+}
+
+function planUsage(desired: DesiredCellularPolicy): Receipt {
+	const parts: string[] = [];
+	if (desired.usage.cycleDay !== undefined) {
+		parts.push(`cycle day ${desired.usage.cycleDay}`);
+	}
+	if (desired.usage.thresholdBytes !== undefined) {
+		parts.push(`threshold ${desired.usage.thresholdBytes} bytes`);
+	}
+	return receipt(
+		'usage',
+		'applied',
+		parts.length > 0 ? `usage policy recorded (${parts.join(', ')})` : 'no usage policy set',
+	);
+}

package/src/ports/router.ts

@@ -0,0 +1,29 @@
+// The router port — for devices MM cannot control (HiLink, router-ethernet class).
+//
+// This port is DELIBERATELY tiny: presence and advisory health ONLY. Health never
+// drives activation or recovery — a degraded router stays in the routing set (it is
+// never evicted on health alone). A router device is an Ethernet uplink we OBSERVE,
+// not a modem we configure; there is no bearer / APN / radio verb here.
+
+import type { EpochMillis } from '../domain';
+import type { DeviceIfname } from './network-manager';
+
+/** Whether a router-class device is present on an interface. */
+export type RouterPresence = 'present' | 'absent';
+
+/**
+ * Advisory health of a router-class uplink. Every field is informational — a
+ * degraded router is reported, never removed from the routing set on health alone.
+ */
+export interface RouterHealth {
+	readonly presence: RouterPresence;
+	readonly gatewayReachable: boolean;
+	readonly egressHealthy: boolean;
+	readonly observedAt: EpochMillis;
+}
+
+/** The router port — presence and advisory health only. No mutation verbs. */
+export interface RouterPort {
+	probePresence(ifname: DeviceIfname): Promise<RouterPresence>;
+	checkHealth(ifname: DeviceIfname): Promise<RouterHealth>;
+}

package/src/redact.test.ts

@@ -0,0 +1,82 @@
+// Redaction classes — ICCID, IMSI, EID, PIN, PUK, and APN/connection passwords are
+// stripped, including deeply nested occurrences and inside arrays; non-secret
+// siblings survive and the input is never mutated.
+
+import { expect, test } from 'bun:test';
+import { REDACTED, redact } from './redact';
+
+test('redacts every sensitive class at the top level, keeping non-secret siblings', () => {
+	const input = {
+		iccid: '8988303000000000000',
+		imsi: '310150123456789',
+		eid: '89049032000000000000000000000000',
+		pin: '1234',
+		puk: '12345678',
+		password: 's3cret',
+		apn: 'internet',
+		username: 'operator-user',
+	};
+	const out = redact(input) as Record<string, unknown>;
+
+	expect(out.iccid).toBe(REDACTED);
+	expect(out.imsi).toBe(REDACTED);
+	expect(out.eid).toBe(REDACTED);
+	expect(out.pin).toBe(REDACTED);
+	expect(out.puk).toBe(REDACTED);
+	expect(out.password).toBe(REDACTED);
+	expect(out.apn).toBe('internet');
+	expect(out.username).toBe('operator-user');
+});
+
+test('redacts an APN password nested three levels deep', () => {
+	const policy = { connection: { auth: { username: 'u', password: 'hunter2' } } };
+	const out = redact(policy) as { connection: { auth: { username: string; password: string } } };
+	expect(out.connection.auth.password).toBe(REDACTED);
+	expect(out.connection.auth.username).toBe('u');
+});
+
+test('redacts ICCID inside an array of SIM slots', () => {
+	const input = {
+		simSlots: [
+			{ index: 1, iccid: '8988000000000000001' },
+			{ index: 2, iccid: '8988000000000000002' },
+		],
+	};
+	const out = redact(input) as { simSlots: Array<{ index: number; iccid: string }> };
+	expect(out.simSlots[0]?.iccid).toBe(REDACTED);
+	expect(out.simSlots[1]?.iccid).toBe(REDACTED);
+	expect(out.simSlots[0]?.index).toBe(1);
+	expect(out.simSlots[1]?.index).toBe(2);
+});
+
+test('redacts NM-style gsm.password but keeps the gsm.password-flags flag', () => {
+	const input = { 'gsm.password': 'secret', 'gsm.password-flags': '0', 'gsm.apn': 'internet' };
+	const out = redact(input) as Record<string, unknown>;
+	expect(out['gsm.password']).toBe(REDACTED);
+	expect(out['gsm.password-flags']).toBe('0');
+	expect(out['gsm.apn']).toBe('internet');
+});
+
+test('redacts subscriptionId, newPin, and puk2 variants', () => {
+	const input = { subscriptionId: '8988303000000000000', newPin: '4321', puk2: '87654321' };
+	const out = redact(input) as Record<string, unknown>;
+	expect(out.subscriptionId).toBe(REDACTED);
+	expect(out.newPin).toBe(REDACTED);
+	expect(out.puk2).toBe(REDACTED);
+});
+
+test('does not mutate the input', () => {
+	const input = { pin: '1234', nested: { iccid: '5678' } };
+	const before = JSON.stringify(input);
+	redact(input);
+	expect(JSON.stringify(input)).toBe(before);
+});
+
+test('passes primitives and empty containers through unchanged', () => {
+	expect(redact('plain')).toBe('plain');
+	expect(redact(42)).toBe(42);
+	expect(redact(null)).toBe(null);
+	expect(redact(undefined)).toBe(undefined);
+	expect(redact({})).toEqual({});
+	expect(redact([])).toEqual([]);
+});

package/src/redact.ts

@@ -0,0 +1,73 @@
+// Redaction — strip sensitive identifiers from any value before it is logged,
+// serialized into a receipt, or written to a bundle.
+//
+// The sensitive CLASSES (draft §Oracle #1, round-5 auth semantics): ICCID, IMSI,
+// EID, SIM PIN, SIM PUK, and APN / connection passwords. Redaction is KEY-BASED and
+// RECURSIVE: it walks nested objects and arrays and replaces the value under any
+// sensitive key with a fixed marker, no matter how deep — e.g. a password at
+// `policy.connection.auth.password`, or an `iccid` inside an array of SIM slots.
+
+/** The marker substituted for every redacted value. */
+export const REDACTED = '[redacted]';
+
+// Leaf key names carrying a sensitive value, matched case-insensitively. The match
+// is EXACT (or exact on the last dotted segment), so NM-style keys like
+// `gsm.password` are caught while non-secret siblings like `gsm.password-flags`
+// (a "0"/"4" flag, not a secret) are not.
+const SENSITIVE_KEYS: ReadonlySet<string> = new Set<string>([
+	'iccid',
+	'imsi',
+	'eid',
+	'pin',
+	'pin2',
+	'newpin',
+	'puk',
+	'puk2',
+	'password',
+	'passwd',
+	'subscriptionid',
+]);
+
+function isSensitiveKey(key: string): boolean {
+	const lower = key.toLowerCase();
+	if (SENSITIVE_KEYS.has(lower)) {
+		return true;
+	}
+	const dot = lower.lastIndexOf('.');
+	return dot >= 0 && SENSITIVE_KEYS.has(lower.slice(dot + 1));
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (typeof value !== 'object' || value === null) {
+		return false;
+	}
+	const proto = Object.getPrototypeOf(value) as unknown;
+	return proto === Object.prototype || proto === null;
+}
+
+function redactValue(value: unknown, underSensitiveKey: boolean): unknown {
+	if (underSensitiveKey) {
+		return REDACTED;
+	}
+	if (Array.isArray(value)) {
+		return value.map((item) => redactValue(item, false));
+	}
+	if (isPlainObject(value)) {
+		const out: Record<string, unknown> = {};
+		for (const [key, child] of Object.entries(value)) {
+			out[key] = redactValue(child, isSensitiveKey(key));
+		}
+		return out;
+	}
+	return value;
+}
+
+/**
+ * Return a deep copy of `value` with every sensitive field redacted. Plain objects
+ * and arrays are walked recursively; all other values (primitives, and opaque
+ * objects like `Date` / `Set` / `Map`) are returned unchanged. The input is never
+ * mutated.
+ */
+export function redact(value: unknown): unknown {
+	return redactValue(value, false);
+}

package/src/transport/README.md

@@ -0,0 +1,65 @@
+# D-Bus transport seam
+
+A minimal internal transport interface over [`@httptoolkit/dbus-native`](https://www.npmjs.com/package/@httptoolkit/dbus-native).
+Everything the rest of `@ceralive/modem-control` needs to talk to ModemManager over
+D-Bus goes through the `DbusTransport` interface exported by [`index.ts`](./index.ts) —
+method calls, signal subscriptions, and reconnect. The A3.x D-Bus backend builds
+directly on this shape.
+
+## Why this library
+
+`@httptoolkit/dbus-native` is a pure-JavaScript D-Bus client (no libdbus / native
+addon), which is the deciding factor: it imports and runs under **Bun 1.3.14** with
+**EXTERNAL** auth on a session bus — session-verified during A2.4, and pinned exactly at
+`0.1.5`. A native-addon client (anything binding libdbus) is a portability and
+cross-compile liability for the arm64 + amd64 device image; a pure-JS client is not.
+
+## The fallback
+
+If `@httptoolkit/dbus-native` proves inadequate — an un-fixable marshalling bug, an
+unmaintained upstream, or a Bun incompatibility introduced by a future runtime bump —
+the documented fallback is [`@particle/dbus-next`](https://www.npmjs.com/package/@particle/dbus-next),
+which is also pure-JS and was verified importable under Bun during planning (draft
+ledger §dbus-native). It is **not** implemented here; this note records the escape hatch.
+Because the entire library surface is quarantined behind this seam (see below), swapping
+to it would touch only [`dbus-native.ts`](./dbus-native.ts), [`transport.ts`](./transport.ts),
+and [`codec.ts`](./codec.ts) — never a caller.
+
+## The seam contract
+
+* **No library types leak.** `index.ts` re-exports only the transport's own types
+  (`DbusValue`, `DbusVariant`, `MethodCall`, `SignalEvent`, …). The raw library types
+  live in [`dbus-native.ts`](./dbus-native.ts) and go no further. A guard test asserts
+  the package entry (`../index.ts`) never re-exports the library.
+* **Lossless 64-bit.** D-Bus `x` (INT64) and `t` (UINT64) are `bigint` end-to-end, never
+  a JS `number`. On decode the library runs with `ReturnLongjs: true` and we convert its
+  Long.js objects to `bigint` via their exact decimal string; on encode we require a
+  `bigint` and hand the library a decimal string (its only lossless 64-bit input).
+  Passing a `number` for a 64-bit field throws `BigIntRequiredError`.
+* **`h` is unsupported.** UNIX_FD / file-descriptor passing is rejected up front with a
+  typed `UnsupportedSignatureError` — in an outgoing signature, a reply/signal signature,
+  or nested in a variant — never silently dropped or coerced.
+* **Variants round-trip.** A decoded variant keeps its inner signature
+  (`DbusVariant { signature, value }`), so encode/decode is symmetric.
+
+## Conformance
+
+Tests run under `dbus-run-session -- bun test control/src/transport` and prove the seam
+two independent ways:
+
+1. **Same library** ([`conformance-same-lib.test.ts`](./conformance-same-lib.test.ts)) —
+   round-trips representative signatures against a minimal fake service built on the same
+   `@httptoolkit/dbus-native`.
+2. **Independent producer** ([`conformance-python.test.ts`](./conformance-python.test.ts)) —
+   round-trips against a `python3-dbus` (`dbus-python`) service in a subprocess,
+   exercising `a{oa{sa{sv}}}`, `x`/`t` above 2^53, variants, and `PropertiesChanged`
+   invalidations. A different implementation on the wire is the real proof our codec is
+   correct, not merely self-consistent.
+
+Plus [`reliability.test.ts`](./reliability.test.ts): reconnect after a bus restart
+(against a dedicated private `dbus-daemon`), a ≥5000-event signal stream, late replies,
+and a 100-cycle subscribe/unsubscribe listener-leak check.
+
+The `test-support/` fakes here are intentionally minimal — just enough to round-trip the
+signatures under test. The MM-faithful fake service (root ObjectManager, `Modem` /
+`Modem3gpp` interfaces, SIM objects, bearer tripwires) is a separate, later task (A2.3).