@ceralive/modem-control 1.0.0 → 1.2.0

package/src/backend/usage/store.test.ts

@@ -1,148 +0,0 @@
-// Persistence contract — mode 0600 (real fs.stat), fail-soft corruption recovery
-// with METADATA-ONLY logging, and the no-PII guarantee on the serialized bytes.
-
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import {
-	createUsageFileStore,
-	type PersistedUsage,
-	USAGE_SCHEMA_VERSION,
-	type UsageLogEvent,
-} from './store';
-
-let dir: string;
-let path: string;
-
-beforeEach(async () => {
-	dir = await mkdtemp(join(tmpdir(), 'usage-store-'));
-	path = join(dir, 'usage.json');
-});
-
-afterEach(async () => {
-	await rm(dir, { recursive: true, force: true });
-});
-
-const sample: PersistedUsage = {
-	schemaVersion: USAGE_SCHEMA_VERSION,
-	bootId: 'boot-uuid-1',
-	savedAtMs: 1_700_000_000_000,
-	slots: [
-		{ logicalSlotId: 'slot-a', cycleBytes: 1234, cycleStartMs: 1_699_000_000_000 },
-		{
-			logicalSlotId: 'slot-b',
-			cycleBytes: 42,
-			cycleStartMs: 1_699_000_000_000,
-			mappingGeneration: 2,
-			ifname: 'wwan0',
-			lastObserved: 999,
-		},
-	],
-};
-
-describe('UsageStore — versioned round-trip', () => {
-	test('save then load returns identical, schema-versioned state', async () => {
-		const store = createUsageFileStore({ path });
-		await store.save(sample);
-		const loaded = await store.load('boot-uuid-1', 1_700_000_100_000);
-		expect(loaded.schemaVersion).toBe(USAGE_SCHEMA_VERSION);
-		expect(loaded).toEqual(sample);
-	});
-
-	test('an absent file loads as fresh empty state (no write, no warning)', async () => {
-		const events: UsageLogEvent[] = [];
-		const store = createUsageFileStore({ path, logger: (e) => events.push(e) });
-		const loaded = await store.load('boot-uuid-9', 5);
-		expect(loaded.slots).toEqual([]);
-		expect(loaded.bootId).toBe('boot-uuid-9');
-		expect(events).toHaveLength(0);
-	});
-});
-
-describe('UsageStore — mode 0600 via chmod-after-write', () => {
-	test('the persisted file ends up owner-read/write only (real fs.stat)', async () => {
-		const store = createUsageFileStore({ path });
-		await store.save(sample);
-		const info = await stat(path);
-		expect(info.mode & 0o777).toBe(0o600);
-	});
-});
-
-describe('UsageStore — fail-soft corruption recovery', () => {
-	test('a corrupt file logs METADATA ONLY and recreates a fresh 0600 file', async () => {
-		// Corrupt content carrying a secret-looking token we must never echo in the log.
-		const corrupt = '{ this is not json ICCID=8988211000000123456 }';
-		await writeFile(path, corrupt);
-		const events: UsageLogEvent[] = [];
-		const store = createUsageFileStore({ path, logger: (e) => events.push(e) });
-
-		const loaded = await store.load('boot-uuid-2', 77);
-
-		// Exactly one metadata-only warning.
-		expect(events).toHaveLength(1);
-		const event = events[0];
-		expect(event?.kind).toBe('corrupt-state');
-		expect(event?.bytes).toBe(Buffer.byteLength(corrupt, 'utf8'));
-		expect(typeof event?.reason).toBe('string');
-		// The log NEVER contains the raw content (no secret token leak).
-		expect(JSON.stringify(event)).not.toContain('ICCID');
-		expect(JSON.stringify(event)).not.toContain('8988211000000123456');
-
-		// Fail-soft: fresh empty state returned and the file recreated at mode 0600.
-		expect(loaded.slots).toEqual([]);
-		expect(loaded.bootId).toBe('boot-uuid-2');
-		const info = await stat(path);
-		expect(info.mode & 0o777).toBe(0o600);
-
-		// The recreated file is now valid — a second load is clean (no new warning).
-		const reloaded = await store.load('boot-uuid-2', 78);
-		expect(reloaded.slots).toEqual([]);
-		expect(events).toHaveLength(1);
-	});
-
-	test('an incompatible schema version is treated as corruption and recreated', async () => {
-		await writeFile(
-			path,
-			JSON.stringify({ schemaVersion: 999, bootId: 'x', savedAtMs: 0, slots: [] }),
-		);
-		const events: UsageLogEvent[] = [];
-		const store = createUsageFileStore({ path, logger: (e) => events.push(e) });
-		const loaded = await store.load('boot-uuid-3', 1);
-		expect(events).toHaveLength(1);
-		expect(events[0]?.reason).toContain('schemaVersion');
-		expect(loaded.slots).toEqual([]);
-	});
-});
-
-describe('UsageStore — no PII in the persisted bytes', () => {
-	test('the serialized file contains only opaque ids and numbers', async () => {
-		const store = createUsageFileStore({ path });
-		await store.save(sample);
-		const raw = await readFile(path, 'utf8');
-
-		// No subscriber/device-identifying fields, by construction. Word-bounded so a
-		// benign key like `mappingGeneration` (contains "pin") is not a false positive.
-		expect(raw).not.toMatch(
-			/\b(iccid|imsi|imei|eid|msisdn|operator|manufacturer|subscriber|pin|puk|password)\b/i,
-		);
-
-		// Every slot object exposes only the allowed keys; ids are opaque strings.
-		const parsed = JSON.parse(raw) as PersistedUsage;
-		const allowed = new Set([
-			'logicalSlotId',
-			'cycleBytes',
-			'cycleStartMs',
-			'mappingGeneration',
-			'ifname',
-			'lastObserved',
-		]);
-		for (const slot of parsed.slots) {
-			for (const keyName of Object.keys(slot)) {
-				expect(allowed.has(keyName)).toBe(true);
-			}
-			expect(typeof slot.logicalSlotId).toBe('string');
-			expect(typeof slot.cycleBytes).toBe('number');
-		}
-	});
-});

package/src/backend/usage/store.ts

@@ -1,177 +0,0 @@
-// Versioned, fail-soft persistence for the usage sampler.
-//
-// The persisted file is a small JSON document carrying ONLY opaque slot ids,
-// interface names, and numbers — never any subscriber/device identity (no ICCID,
-// IMSI, IMEI, operator or model). By construction the sampler holds no such fields,
-// and `no-pii.test.ts` proves the serialized bytes stay clean.
-//
-// Two hard guarantees:
-//   - MODE 0600: the file is written to a temp path, chmod'd to 0600 AFTER the
-//     write, then atomically renamed over the target — so the on-disk file always
-//     ends up owner-read/write-only regardless of the process umask.
-//   - FAIL-SOFT ON CORRUPTION: an unparseable/incompatible file is never fatal. We
-//     log METADATA ONLY (byte length + a classification reason — never the raw,
-//     possibly-sensitive content), recreate a fresh empty 0600 file, and carry on.
-
-import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-
-/** The current on-disk schema version. Bump when the persisted shape changes. */
-export const USAGE_SCHEMA_VERSION = 1;
-
-/** One slot's persisted accounting row — opaque ids and numbers only. */
-export interface PersistedSlot {
-	readonly logicalSlotId: string;
-	readonly cycleBytes: number;
-	readonly cycleStartMs: number;
-	readonly mappingGeneration?: number;
-	readonly ifname?: string;
-	readonly lastObserved?: number;
-}
-
-/** The full persisted document. `bootId` scopes the baselines to one kernel session. */
-export interface PersistedUsage {
-	readonly schemaVersion: typeof USAGE_SCHEMA_VERSION;
-	readonly bootId: string;
-	readonly savedAtMs: number;
-	readonly slots: readonly PersistedSlot[];
-}
-
-/** A metadata-only log event. Corruption NEVER carries the raw file content. */
-export type UsageLogEvent = {
-	readonly kind: 'corrupt-state';
-	readonly bytes: number;
-	readonly reason: string;
-};
-
-/** Sink for sampler log events. Defaults to a metadata-only `console.warn`. */
-export type UsageLogger = (event: UsageLogEvent) => void;
-
-/** The persistence seam the sampler drives. */
-export interface UsageStore {
-	/** Load persisted state; recreate a fresh 0600 file if absent or corrupt. */
-	load(currentBootId: string, nowMs: number): Promise<PersistedUsage>;
-	/** Atomically write state with mode 0600 (temp → chmod → rename). */
-	save(state: PersistedUsage): Promise<void>;
-}
-
-export interface UsageFileStoreOptions {
-	readonly path: string;
-	readonly logger?: UsageLogger;
-}
-
-function defaultLogger(event: UsageLogEvent): void {
-	console.warn(`[usage-sampler] ${event.kind}: bytes=${event.bytes} reason=${event.reason}`);
-}
-
-function freshState(bootId: string, nowMs: number): PersistedUsage {
-	return { schemaVersion: USAGE_SCHEMA_VERSION, bootId, savedAtMs: nowMs, slots: [] };
-}
-
-function isFiniteNumber(value: unknown): value is number {
-	return typeof value === 'number' && Number.isFinite(value);
-}
-
-function validateSlot(raw: unknown): PersistedSlot {
-	if (typeof raw !== 'object' || raw === null) {
-		throw new SchemaError('slot');
-	}
-	const slot = raw as Record<string, unknown>;
-	if (typeof slot.logicalSlotId !== 'string') {
-		throw new SchemaError('logicalSlotId');
-	}
-	if (!isFiniteNumber(slot.cycleBytes) || !isFiniteNumber(slot.cycleStartMs)) {
-		throw new SchemaError('cycleBytes|cycleStartMs');
-	}
-	return {
-		logicalSlotId: slot.logicalSlotId,
-		cycleBytes: slot.cycleBytes,
-		cycleStartMs: slot.cycleStartMs,
-		...(isFiniteNumber(slot.mappingGeneration)
-			? { mappingGeneration: slot.mappingGeneration }
-			: {}),
-		...(typeof slot.ifname === 'string' ? { ifname: slot.ifname } : {}),
-		...(isFiniteNumber(slot.lastObserved) ? { lastObserved: slot.lastObserved } : {}),
-	};
-}
-
-/** Parse + validate the document. Throws `SchemaError` (metadata-only) on mismatch. */
-function validate(raw: unknown): PersistedUsage {
-	if (typeof raw !== 'object' || raw === null) {
-		throw new SchemaError('document');
-	}
-	const doc = raw as Record<string, unknown>;
-	if (doc.schemaVersion !== USAGE_SCHEMA_VERSION) {
-		throw new SchemaError('schemaVersion');
-	}
-	if (typeof doc.bootId !== 'string' || !isFiniteNumber(doc.savedAtMs)) {
-		throw new SchemaError('bootId|savedAtMs');
-	}
-	if (!Array.isArray(doc.slots)) {
-		throw new SchemaError('slots');
-	}
-	return {
-		schemaVersion: USAGE_SCHEMA_VERSION,
-		bootId: doc.bootId,
-		savedAtMs: doc.savedAtMs,
-		slots: doc.slots.map(validateSlot),
-	};
-}
-
-/** A schema violation naming only the offending FIELD (never file content). */
-class SchemaError extends Error {
-	constructor(field: string) {
-		super(`schema-mismatch: ${field}`);
-	}
-}
-
-/** Classify a load failure into a metadata-only reason string (no raw content). */
-function classifyFailure(error: unknown): string {
-	if (error instanceof SchemaError) {
-		return error.message;
-	}
-	if (error instanceof SyntaxError) {
-		const offset = /position (\d+)/.exec(error.message)?.[1];
-		return offset !== undefined ? `invalid-json at offset ${offset}` : 'invalid-json';
-	}
-	return 'unreadable';
-}
-
-export function createUsageFileStore(options: UsageFileStoreOptions): UsageStore {
-	const logger = options.logger ?? defaultLogger;
-	const { path } = options;
-
-	async function writeAtomic(state: PersistedUsage): Promise<void> {
-		await mkdir(dirname(path), { recursive: true });
-		const tmp = `${path}.tmp`;
-		await writeFile(tmp, JSON.stringify(state));
-		// chmod AFTER the write (not an open flag) so mode is 0600 regardless of umask.
-		await chmod(tmp, 0o600);
-		await rename(tmp, path);
-	}
-
-	return {
-		async load(currentBootId: string, nowMs: number): Promise<PersistedUsage> {
-			let text: string;
-			try {
-				text = await readFile(path, 'utf8');
-			} catch {
-				// Absent (or unreadable) → start empty; the first save lays down a 0600 file.
-				return freshState(currentBootId, nowMs);
-			}
-			try {
-				return validate(JSON.parse(text));
-			} catch (error) {
-				logger({
-					kind: 'corrupt-state',
-					bytes: Buffer.byteLength(text, 'utf8'),
-					reason: classifyFailure(error),
-				});
-				const fresh = freshState(currentBootId, nowMs);
-				await writeAtomic(fresh);
-				return fresh;
-			}
-		},
-		save: writeAtomic,
-	};
-}

package/src/backend/usb-enumerator.test.ts

@@ -1,87 +0,0 @@
-// The enumerator parses `udevadm info --export-db` into device snapshots: interface
-// class/subclass/protocol come from the parent device's `ID_USB_INTERFACES`, each
-// interface's driver from its own `usb_interface` record. The raw read is injectable
-// so this runs with canned udev text and no hardware, and `enumerate` re-reads every
-// call (refresh-triggered, never cached).
-
-import { describe, expect, test } from 'bun:test';
-import { createUsbEnumerator, parseUdevDatabase } from './usb-enumerator';
-
-const UDEV_DB = `P: /devices/pci0000:00/usb1/1-1
-E: SUBSYSTEM=usb
-E: DEVTYPE=usb_device
-E: ID_VENDOR_ID=2c7c
-E: ID_MODEL_ID=0125
-E: ID_MODEL=EG25-G
-E: ID_REVISION=0318
-E: ID_PATH=pci-0000:00-usb-0:1
-E: ID_USB_INTERFACES=:ff0000:ffffff:
-
-P: /devices/pci0000:00/usb1/1-1/1-1:1.0
-E: SUBSYSTEM=usb
-E: DEVTYPE=usb_interface
-E: DRIVER=option
-
-P: /devices/pci0000:00/usb1/1-1/1-1:1.1
-E: SUBSYSTEM=usb
-E: DEVTYPE=usb_interface
-E: DRIVER=qmi_wwan
-
-P: /devices/pci0000:00/usb2/2-1
-E: SUBSYSTEM=usb
-E: DEVTYPE=usb_device
-E: ID_VENDOR_ID=12d1
-E: ID_MODEL_ID=14db
-E: ID_MODEL=HUAWEI_HiLink
-E: ID_USB_INTERFACES=:020600:0a0000:
-`;
-
-describe('parseUdevDatabase', () => {
-	test('parses two devices with their vendor/product/model', () => {
-		const devices = parseUdevDatabase(UDEV_DB);
-		expect(devices).toHaveLength(2);
-		const quectel = devices.find((d) => d.vendorId === '2c7c');
-		expect(quectel?.productId).toBe('0125');
-		expect(quectel?.model).toBe('EG25-G');
-		expect(quectel?.firmwareRevision).toBe('0318');
-		expect(quectel?.physicalUid).toBe('pci-0000:00-usb-0:1');
-	});
-
-	test('parses interface class triples from ID_USB_INTERFACES', () => {
-		const devices = parseUdevDatabase(UDEV_DB);
-		const huawei = devices.find((d) => d.vendorId === '12d1');
-		expect(huawei?.interfaces).toEqual([
-			{ interfaceClass: 0x02, interfaceSubClass: 0x06, interfaceProtocol: 0x00 },
-			{ interfaceClass: 0x0a, interfaceSubClass: 0x00, interfaceProtocol: 0x00 },
-		]);
-	});
-
-	test('stitches each interface driver onto its parent device', () => {
-		const devices = parseUdevDatabase(UDEV_DB);
-		const quectel = devices.find((d) => d.vendorId === '2c7c');
-		expect(quectel?.interfaces[0]?.driver).toBe('option');
-		expect(quectel?.interfaces[1]?.driver).toBe('qmi_wwan');
-	});
-
-	test('a record without a vendor/product id is skipped', () => {
-		const devices = parseUdevDatabase('P: /devices/x\nE: DEVTYPE=usb_device\nE: SUBSYSTEM=usb\n');
-		expect(devices).toEqual([]);
-	});
-});
-
-describe('createUsbEnumerator', () => {
-	test('enumerate() re-reads the injected source every call (refresh-triggered)', async () => {
-		let reads = 0;
-		const enumerator = createUsbEnumerator({
-			readUdevDatabase: () => {
-				reads += 1;
-				return Promise.resolve(UDEV_DB);
-			},
-		});
-		const first = await enumerator.enumerate();
-		const second = await enumerator.enumerate();
-		expect(first).toHaveLength(2);
-		expect(second).toHaveLength(2);
-		expect(reads).toBe(2);
-	});
-});

package/src/backend/usb-enumerator.ts

@@ -1,181 +0,0 @@
-// Production USB enumeration — a refresh-triggered snapshot of udev/sysfs state.
-//
-// `enumerate()` shells out to `udevadm info --export-db` (via `Bun.spawn`) each call
-// — it is deliberately NOT cached, so a caller re-reads current state after a hot-plug
-// or a mode switch. The raw-database read is an injectable seam (`readUdevDatabase`)
-// so tests drive canned udev output with no real hardware, and the parser itself is a
-// pure, exported function. udev exports every interface's class/subclass/protocol on
-// the parent device as `ID_USB_INTERFACES` (`:ff0000:0a0000:` …), and each interface's
-// bound DRIVER on its own `usb_interface` record — this parser stitches the two.
-
-import type { UsbDeviceSnapshot, UsbInterface } from './device-classifier';
-
-/** The injectable dependencies for the enumerator. */
-export interface UsbEnumeratorDeps {
-	/** Provides the raw `udevadm info --export-db` text. Defaults to a `Bun.spawn` call. */
-	readonly readUdevDatabase?: () => Promise<string>;
-}
-
-/** A refresh-triggered USB device enumerator. */
-export interface UsbEnumerator {
-	/** Snapshot current USB state — re-reads udev every call (never cached). */
-	enumerate(): Promise<readonly UsbDeviceSnapshot[]>;
-}
-
-async function defaultReadUdevDatabase(): Promise<string> {
-	const proc = Bun.spawn(['udevadm', 'info', '--export-db'], { stdout: 'pipe', stderr: 'pipe' });
-	const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
-	if (exitCode !== 0) {
-		const stderr = await new Response(proc.stderr).text();
-		throw new Error(`udevadm info --export-db exited ${exitCode}: ${stderr.trim()}`);
-	}
-	return stdout;
-}
-
-interface UdevRecord {
-	readonly devpath: string;
-	readonly env: ReadonlyMap<string, string>;
-}
-
-function parseRecords(text: string): UdevRecord[] {
-	const records: UdevRecord[] = [];
-	let devpath = '';
-	let env = new Map<string, string>();
-	const flush = (): void => {
-		if (env.size > 0 || devpath !== '') {
-			records.push({ devpath, env });
-		}
-		devpath = '';
-		env = new Map<string, string>();
-	};
-	for (const line of text.split('\n')) {
-		if (line.trim() === '') {
-			flush();
-			continue;
-		}
-		const kind = line.slice(0, 2);
-		const rest = line.slice(3);
-		if (kind === 'P:') {
-			devpath = rest;
-		} else if (kind === 'E:') {
-			const eq = rest.indexOf('=');
-			if (eq > 0) {
-				env.set(rest.slice(0, eq), rest.slice(eq + 1));
-			}
-		}
-	}
-	flush();
-	return records;
-}
-
-/** Parse an `ID_USB_INTERFACES` value (`:ff0000:0a0000:`) into class/subclass/protocol triples. */
-function parseInterfaces(value: string | undefined): UsbInterface[] {
-	if (value === undefined) {
-		return [];
-	}
-	const interfaces: UsbInterface[] = [];
-	for (const token of value.split(':')) {
-		if (token.length !== 6) {
-			continue;
-		}
-		interfaces.push({
-			interfaceClass: Number.parseInt(token.slice(0, 2), 16),
-			interfaceSubClass: Number.parseInt(token.slice(2, 4), 16),
-			interfaceProtocol: Number.parseInt(token.slice(4, 6), 16),
-		});
-	}
-	return interfaces;
-}
-
-function interfaceIndex(devpath: string): number | undefined {
-	const dot = devpath.lastIndexOf('.');
-	if (dot < 0) {
-		return undefined;
-	}
-	const index = Number.parseInt(devpath.slice(dot + 1), 10);
-	return Number.isNaN(index) ? undefined : index;
-}
-
-function buildSnapshot(env: ReadonlyMap<string, string>): UsbDeviceSnapshot | undefined {
-	const vendorId = env.get('ID_VENDOR_ID');
-	const productId = env.get('ID_MODEL_ID');
-	if (vendorId === undefined || productId === undefined) {
-		return undefined;
-	}
-	const props: Record<string, string> = {};
-	for (const [key, value] of env) {
-		props[key] = value;
-	}
-	const model = env.get('ID_MODEL');
-	const firmwareRevision = env.get('ID_REVISION');
-	const physicalUid = env.get('ID_PATH');
-	return {
-		vendorId,
-		productId,
-		bDeviceClass: 0,
-		interfaces: parseInterfaces(env.get('ID_USB_INTERFACES')),
-		udevProperties: props,
-		...(model !== undefined ? { model } : {}),
-		...(firmwareRevision !== undefined ? { firmwareRevision } : {}),
-		...(physicalUid !== undefined ? { physicalUid } : {}),
-	};
-}
-
-/**
- * Parse `udevadm info --export-db` output into device snapshots. Pure and exported so
- * the production parse is unit-testable against canned udev text. Interface drivers
- * are stitched from each `usb_interface` record onto its parent `usb_device`.
- */
-export function parseUdevDatabase(text: string): UsbDeviceSnapshot[] {
-	const records = parseRecords(text);
-	const devices = new Map<string, UsbInterface[]>();
-	const snapshots = new Map<string, UsbDeviceSnapshot>();
-
-	for (const record of records) {
-		if (record.env.get('DEVTYPE') !== 'usb_device') {
-			continue;
-		}
-		const snapshot = buildSnapshot(record.env);
-		if (snapshot !== undefined) {
-			snapshots.set(record.devpath, snapshot);
-			devices.set(record.devpath, [...snapshot.interfaces]);
-		}
-	}
-
-	for (const record of records) {
-		if (record.env.get('DEVTYPE') !== 'usb_interface') {
-			continue;
-		}
-		const driver = record.env.get('DRIVER');
-		const index = interfaceIndex(record.devpath);
-		if (driver === undefined || index === undefined) {
-			continue;
-		}
-		const parent = record.devpath.slice(0, record.devpath.lastIndexOf('/'));
-		const ifaces = devices.get(parent);
-		const iface = ifaces?.[index];
-		if (ifaces !== undefined && iface !== undefined) {
-			ifaces[index] = { ...iface, driver };
-		}
-	}
-
-	return [...snapshots.entries()].map(([devpath, snapshot]) => ({
-		...snapshot,
-		interfaces: devices.get(devpath) ?? snapshot.interfaces,
-	}));
-}
-
-/** Create a refresh-triggered USB enumerator over an injectable udev reader. */
-export function createUsbEnumerator(deps: UsbEnumeratorDeps = {}): UsbEnumerator {
-	const read = deps.readUdevDatabase ?? defaultReadUdevDatabase;
-	return {
-		async enumerate(): Promise<readonly UsbDeviceSnapshot[]> {
-			return parseUdevDatabase(await read());
-		},
-	};
-}
-
-/** Convenience: enumerate current USB devices once via the default udev reader. */
-export function enumerateUsbDevices(): Promise<readonly UsbDeviceSnapshot[]> {
-	return createUsbEnumerator().enumerate();
-}