@ceralive/modem-control 0.1.0

package/src/transport/types.ts

@@ -0,0 +1,118 @@
+// Public value and message types for the D-Bus transport seam.
+//
+// These types are the transport's own vocabulary. None of the underlying
+// `@httptoolkit/dbus-native` types appear here or in `./index.ts`, so the package's
+// public surface never leaks the library — swapping the implementation (see README:
+// documented fallback `@particle/dbus-next`) would not change a single caller type.
+
+// A decoded / encodable D-Bus value.
+//
+// 64-bit integers (`x`, `t`) are ALWAYS `bigint`, never `number`. Byte arrays (`ay`)
+// are `Uint8Array`. Arrays, structs, and dict entries are all plain arrays; a dict
+// `a{KV}` decodes to an array of `[key, value]` entry pairs, preserving order and
+// tolerating duplicate/non-string keys losslessly. Variants are wrapped in
+// `DbusVariant` so their inner signature survives a round-trip.
+export type DbusValue = string | number | boolean | bigint | Uint8Array | DbusVariant | DbusValue[];
+
+// A D-Bus variant (`v`): a value tagged with the signature of its contained type.
+export interface DbusVariant {
+	readonly signature: string;
+	readonly value: DbusValue;
+}
+
+// Construct a variant for encoding, e.g. `variant('u', 42)` or `variant('t', 5n)`.
+export function variant(signature: string, value: DbusValue): DbusVariant {
+	return { signature, value };
+}
+
+// Narrowing guard for a decoded variant.
+export function isVariant(value: DbusValue): value is DbusVariant {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		!Array.isArray(value) &&
+		!(value instanceof Uint8Array) &&
+		typeof (value as DbusVariant).signature === 'string' &&
+		'value' in value
+	);
+}
+
+// An outgoing method call.
+export interface MethodCall {
+	readonly destination: string;
+	readonly path: string;
+	readonly interface: string;
+	readonly member: string;
+	// D-Bus signature of `args`. Omit (or empty) for a no-argument call.
+	readonly signature?: string;
+	readonly args?: readonly DbusValue[];
+	// Per-call reply timeout in ms. Defaults to the transport's configured timeout.
+	readonly timeoutMs?: number;
+}
+
+// A decoded method reply.
+export interface MethodReply {
+	readonly signature: string;
+	readonly body: DbusValue[];
+}
+
+// A signal subscription filter. `interface` and `member` are required; `path` and
+// `sender` narrow further when supplied (MM emits the same signal from many paths).
+export interface SignalSpec {
+	readonly interface: string;
+	readonly member: string;
+	readonly path?: string;
+	readonly sender?: string;
+}
+
+// A decoded signal delivered to a subscriber.
+export interface SignalEvent {
+	readonly path: string;
+	readonly interface: string;
+	readonly member: string;
+	readonly sender: string | undefined;
+	readonly signature: string;
+	readonly body: DbusValue[];
+}
+
+export type SignalListener = (event: SignalEvent) => void;
+
+// Handle returned by `subscribeSignal`; call `unsubscribe` to detach the listener and
+// (when it was the last subscriber for its match rule) drop the bus-side match.
+export interface Subscription {
+	unsubscribe(): Promise<void>;
+}
+
+export type TransportEvent = 'connected' | 'reconnected' | 'disconnected' | 'error';
+
+export interface DbusTransportOptions {
+	// Encoded bus address. Defaults to `DBUS_SESSION_BUS_ADDRESS`.
+	readonly busAddress?: string;
+	// Unix socket path (an alternative to `busAddress` for a private test bus).
+	readonly socket?: string;
+	// Default per-call reply timeout in ms (default 30000).
+	readonly callTimeoutMs?: number;
+	// Automatic reconnect after an unexpected bus drop (default enabled).
+	readonly reconnect?: ReconnectOptions;
+}
+
+export interface ReconnectOptions {
+	readonly enabled?: boolean;
+	readonly initialDelayMs?: number;
+	readonly maxDelayMs?: number;
+	// 0 = retry forever (default).
+	readonly maxAttempts?: number;
+}
+
+// The transport seam. This is the entire surface the A3.x D-Bus backend builds on.
+export interface DbusTransport {
+	connect(): Promise<void>;
+	disconnect(): Promise<void>;
+	isConnected(): boolean;
+	callMethod(call: MethodCall): Promise<MethodReply>;
+	subscribeSignal(spec: SignalSpec, listener: SignalListener): Promise<Subscription>;
+	on(event: TransportEvent, handler: (payload?: unknown) => void): void;
+	off(event: TransportEvent, handler: (payload?: unknown) => void): void;
+	// Number of live signal subscriptions — exposed for leak assertions in tests.
+	subscriptionCount(): number;
+}

package/src/usb-mode/catalog-schema.test.ts

@@ -0,0 +1,181 @@
+// The catalog schema is a SAFETY BOUNDARY: the two invariants it enforces (only
+// within-MM transitions are expressible; no unknown field slips through) are what
+// keep an uncertified or MM↔router switch from ever becoming valid catalog data.
+
+import { describe, expect, test } from 'bun:test';
+import {
+	CERTIFIED_CATALOG,
+	findCatalogEntry,
+	findPermittedTransition,
+	loadCertifiedCatalog,
+} from './catalog';
+import { catalogEntrySchema, certifiedCatalogSchema } from './catalog-schema';
+
+function validCatalog(): unknown {
+	return {
+		schemaVersion: 1,
+		entries: [
+			{
+				vidPid: '2c7c:0125',
+				model: 'TEST-SKU',
+				firmwarePrefix: 'FW01',
+				canonicalMode: 'qmi',
+				permittedTransitions: [
+					{
+						from: 'qmi',
+						to: 'mbim',
+						atCommand: 'AT+QCFG="usbnet",2',
+						expectedResponse: 'OK',
+						expectsPortDrop: true,
+						expectedDescriptors: {
+							deviceClass: 0,
+							interfaces: [{ interfaceClass: 2, interfaceSubClass: 14, interfaceProtocol: 0 }],
+						},
+					},
+				],
+			},
+		],
+	};
+}
+
+function firstTransition(catalog: ReturnType<typeof validCatalog>): Record<string, unknown> {
+	// biome-ignore lint/suspicious/noExplicitAny: test helper reaching into a plain fixture
+	return (catalog as any).entries[0].permittedTransitions[0];
+}
+
+function firstEntry(catalog: ReturnType<typeof validCatalog>): Record<string, unknown> {
+	// biome-ignore lint/suspicious/noExplicitAny: test helper reaching into a plain fixture
+	return (catalog as any).entries[0];
+}
+
+describe('certified catalog schema — accepts valid data', () => {
+	test('a well-formed catalog parses', () => {
+		expect(certifiedCatalogSchema.safeParse(validCatalog()).success).toBe(true);
+	});
+
+	test('a router-ethernet SKU with NO transitions is valid', () => {
+		const catalog = validCatalog() as { entries: Array<Record<string, unknown>> };
+		catalog.entries[0] = {
+			vidPid: '12d1:14db',
+			model: 'HILINK-STICK',
+			firmwarePrefix: 'HILINK',
+			canonicalMode: 'router-ethernet',
+			permittedTransitions: [],
+		};
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(true);
+	});
+});
+
+describe('certified catalog schema — rejects MM↔router transitions (schema-invalid)', () => {
+	test('a transition TO router-ethernet fails to parse', () => {
+		const catalog = validCatalog();
+		firstTransition(catalog).to = 'router-ethernet';
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('a transition FROM router-ethernet fails to parse', () => {
+		const catalog = validCatalog();
+		firstTransition(catalog).from = 'router-ethernet';
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('a transition touching rndis fails to parse', () => {
+		const catalog = validCatalog();
+		firstTransition(catalog).to = 'rndis';
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('a router-ethernet SKU may NOT declare any transition', () => {
+		const catalog = validCatalog();
+		firstEntry(catalog).canonicalMode = 'router-ethernet';
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+});
+
+describe('certified catalog schema — strict mode rejects unknown fields', () => {
+	test('an unknown field on the catalog root is rejected', () => {
+		const catalog = validCatalog() as Record<string, unknown>;
+		catalog.smuggled = true;
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('an unknown field on an entry is rejected', () => {
+		const catalog = validCatalog();
+		firstEntry(catalog).hidden = 'x';
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('an unknown field on a transition is rejected', () => {
+		const catalog = validCatalog();
+		firstTransition(catalog).sneaky = 1;
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+});
+
+describe('certified catalog schema — field validation', () => {
+	test('a self-transition (from === to) is rejected', () => {
+		const catalog = validCatalog();
+		firstTransition(catalog).to = 'qmi';
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('a malformed VID:PID is rejected', () => {
+		const catalog = validCatalog();
+		firstEntry(catalog).vidPid = '2c7c-0125';
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('a schemaVersion other than 1 is rejected', () => {
+		const catalog = validCatalog() as Record<string, unknown>;
+		catalog.schemaVersion = 2;
+		expect(certifiedCatalogSchema.safeParse(catalog).success).toBe(false);
+	});
+
+	test('a valid evidence-bundle sha256 is accepted; a malformed one is rejected', () => {
+		const good = validCatalog();
+		firstTransition(good).evidenceBundleSha256 = 'a'.repeat(64);
+		expect(certifiedCatalogSchema.safeParse(good).success).toBe(true);
+
+		const bad = validCatalog();
+		firstTransition(bad).evidenceBundleSha256 = 'nothex';
+		expect(certifiedCatalogSchema.safeParse(bad).success).toBe(false);
+	});
+
+	test('loadCertifiedCatalog throws on invalid input', () => {
+		expect(() => loadCertifiedCatalog({ schemaVersion: 1 })).toThrow();
+	});
+
+	test('a lone entry also validates against catalogEntrySchema', () => {
+		const entry = (validCatalog() as { entries: unknown[] }).entries[0];
+		expect(catalogEntrySchema.safeParse(entry).success).toBe(true);
+	});
+});
+
+describe('the shipped certified catalog', () => {
+	test('validates and exposes the synthetic test SKU with within-MM transitions', () => {
+		const sku = {
+			vidPid: '2c7c:0125',
+			model: 'CERALIVE-SYNTHETIC-TEST-SKU',
+			firmwarePrefix: 'SYNTHETICFW01',
+		};
+		const entry = findCatalogEntry(CERTIFIED_CATALOG, sku);
+		expect(entry).toBeDefined();
+		expect(entry?.canonicalMode).toBe('qmi');
+		const transition =
+			entry !== undefined ? findPermittedTransition(entry, 'qmi', 'mbim') : undefined;
+		expect(transition?.atCommand).toBe('AT+QCFG="usbnet",2');
+		// A transition the catalog does NOT declare is absent (never a guess).
+		expect(
+			entry !== undefined ? findPermittedTransition(entry, 'mbim', 'ecm-ncm') : undefined,
+		).toBeUndefined();
+	});
+
+	test('an unmatched SKU discriminator returns undefined (uncertified)', () => {
+		const entry = findCatalogEntry(CERTIFIED_CATALOG, {
+			vidPid: '2c7c:0125',
+			model: 'CERALIVE-SYNTHETIC-TEST-SKU',
+			firmwarePrefix: 'WRONGFW',
+		});
+		expect(entry).toBeUndefined();
+	});
+});

package/src/usb-mode/catalog-schema.ts

@@ -0,0 +1,113 @@
+// The certified USB-mode catalog schema — the contract that gates a mode switch.
+//
+// A catalog ENTRY is one server-derived SKU discriminator (VID:PID + model +
+// firmware prefix) plus everything a certified transition needs: the canonical mode
+// the SKU speaks, the AT commands that switch it, the expected AT response and
+// port-drop behaviour, the USB descriptors it should present AFTER the switch, and a
+// forward-reference to the evidence bundle that certified it. Certification is a
+// human-reviewed commit that adds an entry — evidence bundles are inputs to that
+// review, never read at runtime.
+//
+// TWO safety invariants are enforced by the SCHEMA ITSELF, not by convention:
+//   1. Permitted transitions are WITHIN-ModemManager only — `qmi ↔ mbim ↔ ecm-ncm`.
+//      A transition's `from`/`to` are typed to the MM-mode enum, so any attempt to
+//      declare an `MM ↔ router` (or `rndis`) transition FAILS to parse.
+//   2. `.strict()` everywhere — an entry carrying an unknown field is rejected, so a
+//      typo or a smuggled extra field can never slip past review as valid data.
+
+import { z } from 'zod';
+
+/**
+ * The full canonical USB composition-mode vocabulary. A SKU's `canonicalMode` may be
+ * any of these; only the first three are ModemManager-manageable. (Structurally
+ * identical to `PreferredUsbMode` in the power contract — A4.2 owns this vocabulary.)
+ */
+export const CANONICAL_USB_MODES = ['qmi', 'mbim', 'ecm-ncm', 'rndis', 'router-ethernet'] as const;
+export type CanonicalUsbMode = (typeof CANONICAL_USB_MODES)[number];
+
+/**
+ * The ModemManager-manageable modes — the ONLY modes a transition may move between.
+ * `rndis` and `router-ethernet` are deliberately absent: a device in either is not
+ * MM-managed, so switching to/from them crosses the MM↔router line the schema forbids.
+ */
+export const MM_USB_MODES = ['qmi', 'mbim', 'ecm-ncm'] as const;
+export type MmUsbMode = (typeof MM_USB_MODES)[number];
+
+const canonicalMode = z.enum(CANONICAL_USB_MODES);
+const mmMode = z.enum(MM_USB_MODES);
+
+/** A `bInterfaceClass`/`bInterfaceSubClass`/`bInterfaceProtocol` byte triple. */
+const usbByte = z.number().int().min(0).max(255);
+
+/** The USB descriptors a device must present AFTER a transition — the postcondition. */
+export const expectedDescriptorsSchema = z.strictObject({
+	deviceClass: usbByte,
+	interfaces: z
+		.array(
+			z.strictObject({
+				interfaceClass: usbByte,
+				interfaceSubClass: usbByte,
+				interfaceProtocol: usbByte,
+			}),
+		)
+		.min(1),
+});
+export type ExpectedDescriptors = z.infer<typeof expectedDescriptorsSchema>;
+
+/** One permitted, certified transition between two MM modes. */
+export const permittedTransitionSchema = z
+	.strictObject({
+		from: mmMode,
+		to: mmMode,
+		/** The EXACT AT command that performs the switch (allowlisted at send time). */
+		atCommand: z.string().min(1),
+		/** The AT response expected on success (e.g. `OK`) — never proof on its own. */
+		expectedResponse: z.string().min(1),
+		/** Whether the control port is expected to drop after the command is written. */
+		expectsPortDrop: z.boolean(),
+		/** The descriptors the device must present after re-enumerating — the postcondition. */
+		expectedDescriptors: expectedDescriptorsSchema,
+		/** sha256 of the evidence bundle that certified this transition (A6.2 fills it). */
+		evidenceBundleSha256: z
+			.string()
+			.regex(/^[0-9a-f]{64}$/)
+			.optional(),
+	})
+	.refine((t) => t.from !== t.to, { message: 'a transition must change mode (from !== to)' });
+export type PermittedTransition = z.infer<typeof permittedTransitionSchema>;
+
+/** One certified SKU: its discriminator, canonical mode, and permitted transitions. */
+export const catalogEntrySchema = z
+	.strictObject({
+		/** VID:PID, lowercase hex, `xxxx:xxxx`. */
+		vidPid: z.string().regex(/^[0-9a-f]{4}:[0-9a-f]{4}$/),
+		/** The server-derived model string (a discriminator, not free text). */
+		model: z.string().min(1),
+		/** The firmware-revision prefix that discriminates this personality. */
+		firmwarePrefix: z.string().min(1),
+		/** The mode this SKU speaks as certified. */
+		canonicalMode,
+		/** The certified transitions — empty for a non-MM (router/rndis) SKU. */
+		permittedTransitions: z.array(permittedTransitionSchema),
+	})
+	.refine(
+		(e) =>
+			e.permittedTransitions.length === 0 ||
+			(MM_USB_MODES as readonly string[]).includes(e.canonicalMode),
+		{ message: 'only an MM-mode SKU (qmi/mbim/ecm-ncm) may declare permitted transitions' },
+	);
+export type CatalogEntry = z.infer<typeof catalogEntrySchema>;
+
+/** The whole certified catalog file. */
+export const certifiedCatalogSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	entries: z.array(catalogEntrySchema),
+});
+export type CertifiedCatalog = z.infer<typeof certifiedCatalogSchema>;
+
+/** A live device's SKU discriminator — matched against the catalog. */
+export interface SkuDiscriminator {
+	readonly vidPid: string;
+	readonly model: string;
+	readonly firmwarePrefix: string;
+}

package/src/usb-mode/catalog.ts

@@ -0,0 +1,60 @@
+// Loading and querying the certified USB-mode catalog.
+//
+// The catalog is validated on load — a malformed file fails LOUDLY, never silently
+// half-parsed. The certified-catalog.json shipped in this package is validated once
+// at module load and exposed as `CERTIFIED_CATALOG`; a caller that wants to validate
+// an alternate file (e.g. A6.2's `certify` tool checking a candidate entry) uses
+// `loadCertifiedCatalog`. The evidence bundles the entries reference are NOT read
+// here — only the catalog metadata is.
+
+import {
+	type CatalogEntry,
+	type CertifiedCatalog,
+	certifiedCatalogSchema,
+	type MmUsbMode,
+	type PermittedTransition,
+	type SkuDiscriminator,
+} from './catalog-schema';
+import rawCatalog from './certified-catalog.json' with { type: 'json' };
+
+/**
+ * Parse and validate an untrusted value as a certified catalog. Throws a `ZodError`
+ * with a precise path if the value violates the schema (unknown field, an MM↔router
+ * transition, a bad VID:PID, etc.).
+ */
+export function loadCertifiedCatalog(value: unknown): CertifiedCatalog {
+	return certifiedCatalogSchema.parse(value);
+}
+
+/** The catalog shipped in this package, validated at module load. */
+export const CERTIFIED_CATALOG: CertifiedCatalog = loadCertifiedCatalog(rawCatalog);
+
+/**
+ * Find the catalog entry matching a live device's SKU discriminator. All three
+ * discriminators (VID:PID, model, firmware prefix) must match — a partial match is
+ * NOT a certified device. Returns `undefined` for an uncertified SKU (never a guess).
+ */
+export function findCatalogEntry(
+	catalog: CertifiedCatalog,
+	sku: SkuDiscriminator,
+): CatalogEntry | undefined {
+	return catalog.entries.find(
+		(entry) =>
+			entry.vidPid === sku.vidPid &&
+			entry.model === sku.model &&
+			entry.firmwarePrefix === sku.firmwarePrefix,
+	);
+}
+
+/**
+ * Find the permitted transition `from → to` in a catalog entry. Returns `undefined`
+ * when the entry declares no such transition — the caller MUST treat that as "not
+ * permitted", never as "permitted with no command".
+ */
+export function findPermittedTransition(
+	entry: CatalogEntry,
+	from: MmUsbMode,
+	to: MmUsbMode,
+): PermittedTransition | undefined {
+	return entry.permittedTransitions.find((t) => t.from === from && t.to === to);
+}

package/src/usb-mode/certified-catalog.json

@@ -0,0 +1,67 @@
+{
+	"schemaVersion": 1,
+	"entries": [
+		{
+			"vidPid": "2c7c:0125",
+			"model": "CERALIVE-SYNTHETIC-TEST-SKU",
+			"firmwarePrefix": "SYNTHETICFW01",
+			"canonicalMode": "qmi",
+			"permittedTransitions": [
+				{
+					"from": "qmi",
+					"to": "mbim",
+					"atCommand": "AT+QCFG=\"usbnet\",2",
+					"expectedResponse": "OK",
+					"expectsPortDrop": true,
+					"expectedDescriptors": {
+						"deviceClass": 0,
+						"interfaces": [
+							{ "interfaceClass": 2, "interfaceSubClass": 14, "interfaceProtocol": 0 },
+							{ "interfaceClass": 10, "interfaceSubClass": 0, "interfaceProtocol": 2 }
+						]
+					}
+				},
+				{
+					"from": "mbim",
+					"to": "qmi",
+					"atCommand": "AT+QCFG=\"usbnet\",0",
+					"expectedResponse": "OK",
+					"expectsPortDrop": true,
+					"expectedDescriptors": {
+						"deviceClass": 0,
+						"interfaces": [
+							{ "interfaceClass": 255, "interfaceSubClass": 255, "interfaceProtocol": 255 }
+						]
+					}
+				},
+				{
+					"from": "qmi",
+					"to": "ecm-ncm",
+					"atCommand": "AT+QCFG=\"usbnet\",1",
+					"expectedResponse": "OK",
+					"expectsPortDrop": true,
+					"expectedDescriptors": {
+						"deviceClass": 0,
+						"interfaces": [
+							{ "interfaceClass": 2, "interfaceSubClass": 6, "interfaceProtocol": 0 },
+							{ "interfaceClass": 255, "interfaceSubClass": 255, "interfaceProtocol": 255 }
+						]
+					}
+				},
+				{
+					"from": "ecm-ncm",
+					"to": "qmi",
+					"atCommand": "AT+QCFG=\"usbnet\",0",
+					"expectedResponse": "OK",
+					"expectsPortDrop": true,
+					"expectedDescriptors": {
+						"deviceClass": 0,
+						"interfaces": [
+							{ "interfaceClass": 255, "interfaceSubClass": 255, "interfaceProtocol": 255 }
+						]
+					}
+				}
+			]
+		}
+	]
+}

package/src/usb-mode/index.ts

@@ -0,0 +1,27 @@
+// The certified USB-mode catalog — schema, data, and lookups.
+//
+// A6.1's bench CLI (`set-usb-mode`) and A6.2's `certify` tool both consume this: the
+// CLI looks up the permitted transition for a target mode, `certify` validates a
+// candidate entry against the schema before a human commits it.
+
+export {
+	CERTIFIED_CATALOG,
+	findCatalogEntry,
+	findPermittedTransition,
+	loadCertifiedCatalog,
+} from './catalog';
+export {
+	CANONICAL_USB_MODES,
+	type CanonicalUsbMode,
+	type CatalogEntry,
+	type CertifiedCatalog,
+	catalogEntrySchema,
+	certifiedCatalogSchema,
+	type ExpectedDescriptors,
+	expectedDescriptorsSchema,
+	MM_USB_MODES,
+	type MmUsbMode,
+	type PermittedTransition,
+	permittedTransitionSchema,
+	type SkuDiscriminator,
+} from './catalog-schema';