@ceralive/modem-control 0.2.0 → 1.1.0

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

@@ -1,181 +0,0 @@
-// 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

@@ -1,113 +0,0 @@
-// 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/certified-catalog.json

@@ -1,67 +0,0 @@
-{
-	"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

@@ -1,27 +0,0 @@
-// 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';