@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/transport/signature.js

@@ -0,0 +1,94 @@
+// D-Bus signature parsing and support checks.
+//
+// We keep our own tiny recursive-descent parser rather than reaching into the
+// underlying library's internal `lib/signature.js`: the parsed tree drives our
+// signature-aware encode/decode (below) and the tree shape is part of this seam's
+// contract, not the library's. The node shape intentionally mirrors the library's
+// (`{ type, child }`) so a tree the library hands us inside a decoded variant can be
+// re-serialised with `signatureFromNode` without a translation step.
+import { UnsupportedSignatureError } from './errors.js';
+const CONTAINER_CLOSE = {
+    '{': '}',
+    '(': ')',
+};
+// Every basic and container type char D-Bus defines. `h` (UNIX_FD) is deliberately
+// listed as *known* so the parser accepts it structurally — we reject it explicitly in
+// `assertSupportedSignature` with a typed error rather than as a vague parse failure.
+const KNOWN_TYPES = new Set('ybnqiuxtdsogarvhe{}()'.split(''));
+// UNIX_FD: file-descriptor passing. Unsupported everywhere in this transport.
+const UNSUPPORTED_TYPE = 'h';
+// Throws UnsupportedSignatureError if the signature contains `h` anywhere (including
+// nested inside arrays, structs, dict entries, or variants). Signatures are pure type
+// strings, so a plain character scan is exact.
+export function assertSupportedSignature(signature) {
+    const index = signature.indexOf(UNSUPPORTED_TYPE);
+    if (index !== -1) {
+        throw new UnsupportedSignatureError(signature, UNSUPPORTED_TYPE);
+    }
+}
+// Parse a full signature (which may contain several top-level complete types) into a
+// flat list of nodes.
+export function parseSignature(signature) {
+    let index = 0;
+    function next() {
+        if (index < signature.length) {
+            const char = signature[index];
+            index += 1;
+            return char;
+        }
+        return null;
+    }
+    function parseOne(char) {
+        if (!KNOWN_TYPES.has(char)) {
+            throw new Error(`Unknown D-Bus type "${char}" in signature "${signature}"`);
+        }
+        const children = [];
+        switch (char) {
+            case 'a': {
+                const element = next();
+                if (element === null) {
+                    throw new Error(`Bad signature "${signature}": array with no element type`);
+                }
+                children.push(parseOne(element));
+                return { type: 'a', child: children };
+            }
+            case '{':
+            case '(': {
+                const close = CONTAINER_CLOSE[char];
+                let element = next();
+                while (element !== null && element !== close) {
+                    children.push(parseOne(element));
+                    element = next();
+                }
+                if (element === null) {
+                    throw new Error(`Bad signature "${signature}": unterminated "${char}"`);
+                }
+                return { type: char, child: children };
+            }
+            default:
+                return { type: char, child: children };
+        }
+    }
+    const nodes = [];
+    let char = next();
+    while (char !== null) {
+        nodes.push(parseOne(char));
+        char = next();
+    }
+    return nodes;
+}
+// Re-serialise a single parsed node back to its signature string. Used to recover the
+// inner signature of a decoded variant, whose contained type the library hands us as a
+// parse tree rather than a string.
+export function signatureFromNode(node) {
+    switch (node.type) {
+        case 'a':
+            return `a${signatureFromNode(node.child[0])}`;
+        case '(':
+            return `(${node.child.map(signatureFromNode).join('')})`;
+        case '{':
+            return `{${node.child.map(signatureFromNode).join('')}}`;
+        default:
+            return node.type;
+    }
+}

package/dist/transport/transport.d.ts

@@ -0,0 +1,2 @@
+import type { DbusTransport, DbusTransportOptions } from './types.js';
+export declare function createDbusTransport(options?: DbusTransportOptions): DbusTransport;

package/dist/transport/transport.js

@@ -0,0 +1,202 @@
+// The D-Bus transport seam implementation.
+//
+// Wraps `@httptoolkit/dbus-native` behind the `DbusTransport` interface. This module owns the
+// connection lifecycle — handshake, a reconnect loop that re-issues every match rule after a
+// bus restart, and teardown — and delegates method-call dispatch to `./calls` and signal
+// subscription/match-rule tracking to `./signals`. Its single `message` listener fans out to
+// the signal registry, so subscribing never grows the listener count (the 100-cycle leak check).
+import { EventEmitter } from 'node:events';
+import { CallDispatcher, DEFAULT_CALL_TIMEOUT_MS } from './calls.js';
+import { createClient, } from './dbus-native.js';
+import { DisconnectedError, TransportError } from './errors.js';
+import { SignalRegistry } from './signals.js';
+// Bound a single connect/auth attempt so a stalled handshake cannot freeze the reconnect
+// loop. A local unix-socket D-Bus connect completes in milliseconds; 2s is ample headroom
+// while keeping reconnect responsive after a bus restart.
+const CONNECT_TIMEOUT_MS = 2_000;
+const DEFAULT_RECONNECT = {
+    enabled: true,
+    initialDelayMs: 50,
+    maxDelayMs: 2_000,
+    maxAttempts: 0,
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+class DbusTransportImpl {
+    #options;
+    #reconnect;
+    #emitter = new EventEmitter();
+    #calls;
+    #signals;
+    #bus = null;
+    #state = 'idle';
+    #closing = false;
+    // Bound once so the same references can be detached from a dead connection.
+    #onMessage = (message) => this.#signals.dispatch(message);
+    #onConnectionError = (cause) => this.#handleDrop(cause instanceof Error ? cause : new DisconnectedError(String(cause)));
+    #onConnectionEnd = () => this.#handleDrop(new DisconnectedError('bus connection ended'));
+    constructor(options) {
+        this.#options = options;
+        this.#calls = new CallDispatcher(options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS);
+        this.#signals = new SignalRegistry({
+            currentBus: () => this.#bus,
+            isConnected: () => this.#state === 'connected',
+            emitError: (error) => this.#emitter.emit('error', error),
+        });
+        this.#reconnect = {
+            enabled: options.reconnect?.enabled ?? DEFAULT_RECONNECT.enabled,
+            initialDelayMs: options.reconnect?.initialDelayMs ?? DEFAULT_RECONNECT.initialDelayMs,
+            maxDelayMs: options.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT.maxDelayMs,
+            maxAttempts: options.reconnect?.maxAttempts ?? DEFAULT_RECONNECT.maxAttempts,
+        };
+        // Avoid MaxListeners warnings when many consumers observe transport events.
+        this.#emitter.setMaxListeners(0);
+    }
+    async connect() {
+        if (this.#state === 'connected') {
+            return;
+        }
+        if (this.#closing) {
+            throw new TransportError('Transport is closed');
+        }
+        this.#state = 'connecting';
+        await this.#establish();
+        this.#emitter.emit('connected');
+    }
+    isConnected() {
+        return this.#state === 'connected';
+    }
+    async disconnect() {
+        this.#closing = true;
+        this.#state = 'closed';
+        const bus = this.#bus;
+        this.#bus = null;
+        this.#calls.rejectAll(new DisconnectedError('transport closed'));
+        if (bus) {
+            this.#quiesce(bus);
+            await bus.disconnect().catch(() => undefined);
+        }
+    }
+    callMethod(call) {
+        return this.#calls.call(this.#bus, this.#state === 'connected', call);
+    }
+    subscribeSignal(spec, listener) {
+        return this.#signals.subscribe(spec, listener);
+    }
+    subscriptionCount() {
+        return this.#signals.count();
+    }
+    on(event, handler) {
+        this.#emitter.on(event, handler);
+    }
+    off(event, handler) {
+        this.#emitter.off(event, handler);
+    }
+    // ── internals ──────────────────────────────────────────────────────────────────
+    async #establish() {
+        const options = { ReturnLongjs: true };
+        if (this.#options.socket !== undefined) {
+            options.socket = this.#options.socket;
+        }
+        else if (this.#options.busAddress !== undefined) {
+            options.busAddress = this.#options.busAddress;
+        }
+        const bus = createClient(options);
+        try {
+            await new Promise((resolve, reject) => {
+                const onConnect = () => {
+                    cleanup();
+                    resolve();
+                };
+                const onError = (error) => {
+                    cleanup();
+                    reject(error instanceof Error ? error : new TransportError(String(error)));
+                };
+                const timer = setTimeout(() => {
+                    cleanup();
+                    reject(new TransportError(`bus connect timed out after ${CONNECT_TIMEOUT_MS}ms`));
+                }, CONNECT_TIMEOUT_MS);
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    bus.connection.removeListener('connect', onConnect);
+                    bus.connection.removeListener('error', onError);
+                };
+                bus.connection.once('connect', onConnect);
+                bus.connection.once('error', onError);
+            });
+            bus.connection.on('message', this.#onMessage);
+            bus.connection.on('error', this.#onConnectionError);
+            bus.connection.on('end', this.#onConnectionEnd);
+            // Re-issue every live match rule so a reconnect resubscribes transparently.
+            await this.#signals.reissueRules(bus);
+            this.#bus = bus;
+            this.#state = 'connected';
+        }
+        catch (error) {
+            this.#detachHandlers(bus);
+            bus.connection.removeAllListeners();
+            bus.connection.on('error', () => undefined);
+            try {
+                bus.connection.end();
+            }
+            catch {
+                // The half-open connection is already dead; nothing to close.
+            }
+            throw error;
+        }
+    }
+    #detachHandlers(bus) {
+        bus.connection.removeListener('message', this.#onMessage);
+        bus.connection.removeListener('error', this.#onConnectionError);
+        bus.connection.removeListener('end', this.#onConnectionEnd);
+    }
+    // Detach our handlers from a dead connection, then swallow any late socket error it
+    // still emits — without a listener, Node re-throws an EventEmitter 'error' and crashes
+    // the process mid-reconnect.
+    #quiesce(bus) {
+        this.#detachHandlers(bus);
+        bus.connection.on('error', () => undefined);
+    }
+    #handleDrop(cause) {
+        if (this.#closing) {
+            return;
+        }
+        if (this.#state === 'disconnected' || this.#state === 'reconnecting') {
+            return;
+        }
+        this.#state = 'disconnected';
+        if (this.#bus) {
+            this.#quiesce(this.#bus);
+        }
+        this.#bus = null;
+        this.#calls.rejectAll(cause);
+        this.#emitter.emit('disconnected', cause);
+        if (this.#reconnect.enabled) {
+            void this.#reconnectLoop();
+        }
+    }
+    async #reconnectLoop() {
+        this.#state = 'reconnecting';
+        let delay = this.#reconnect.initialDelayMs;
+        let attempt = 0;
+        while (!this.#closing) {
+            attempt += 1;
+            try {
+                await this.#establish();
+                this.#emitter.emit('reconnected');
+                return;
+            }
+            catch (error) {
+                if (this.#reconnect.maxAttempts > 0 && attempt >= this.#reconnect.maxAttempts) {
+                    this.#state = 'disconnected';
+                    this.#emitter.emit('error', error);
+                    return;
+                }
+                await sleep(delay);
+                delay = Math.min(delay * 2, this.#reconnect.maxDelayMs);
+            }
+        }
+    }
+}
+export function createDbusTransport(options = {}) {
+    return new DbusTransportImpl(options);
+}

package/dist/transport/types.d.ts

@@ -0,0 +1,61 @@
+export type DbusValue = string | number | boolean | bigint | Uint8Array | DbusVariant | DbusValue[];
+export interface DbusVariant {
+    readonly signature: string;
+    readonly value: DbusValue;
+}
+export declare function variant(signature: string, value: DbusValue): DbusVariant;
+export declare function isVariant(value: DbusValue): value is DbusVariant;
+export interface MethodCall {
+    readonly destination: string;
+    readonly path: string;
+    readonly interface: string;
+    readonly member: string;
+    readonly signature?: string;
+    readonly args?: readonly DbusValue[];
+    readonly timeoutMs?: number;
+}
+export interface MethodReply {
+    readonly signature: string;
+    readonly body: DbusValue[];
+}
+export interface SignalSpec {
+    readonly interface: string;
+    readonly member: string;
+    readonly path?: string;
+    readonly sender?: string;
+}
+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;
+export interface Subscription {
+    unsubscribe(): Promise<void>;
+}
+export type TransportEvent = 'connected' | 'reconnected' | 'disconnected' | 'error';
+export interface DbusTransportOptions {
+    readonly busAddress?: string;
+    readonly socket?: string;
+    readonly callTimeoutMs?: number;
+    readonly reconnect?: ReconnectOptions;
+}
+export interface ReconnectOptions {
+    readonly enabled?: boolean;
+    readonly initialDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly maxAttempts?: number;
+}
+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;
+    subscriptionCount(): number;
+}

package/dist/transport/types.js

@@ -0,0 +1,19 @@
+// 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.
+// Construct a variant for encoding, e.g. `variant('u', 42)` or `variant('t', 5n)`.
+export function variant(signature, value) {
+    return { signature, value };
+}
+// Narrowing guard for a decoded variant.
+export function isVariant(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Uint8Array) &&
+        typeof value.signature === 'string' &&
+        'value' in value);
+}

package/dist/usb-mode/catalog-schema.d.ts

@@ -0,0 +1,139 @@
+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 declare const CANONICAL_USB_MODES: readonly ['qmi', 'mbim', 'ecm-ncm', 'rndis', 'router-ethernet'];
+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 declare const MM_USB_MODES: readonly ['qmi', 'mbim', 'ecm-ncm'];
+export type MmUsbMode = (typeof MM_USB_MODES)[number];
+/** The USB descriptors a device must present AFTER a transition — the postcondition. */
+export declare const expectedDescriptorsSchema: z.ZodObject<{
+    deviceClass: z.ZodNumber;
+    interfaces: z.ZodArray<z.ZodObject<{
+        interfaceClass: z.ZodNumber;
+        interfaceSubClass: z.ZodNumber;
+        interfaceProtocol: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ExpectedDescriptors = z.infer<typeof expectedDescriptorsSchema>;
+/** One permitted, certified transition between two MM modes. */
+export declare const permittedTransitionSchema: z.ZodObject<{
+    from: z.ZodEnum<{
+        "ecm-ncm": "ecm-ncm";
+        mbim: "mbim";
+        qmi: "qmi";
+    }>;
+    to: z.ZodEnum<{
+        "ecm-ncm": "ecm-ncm";
+        mbim: "mbim";
+        qmi: "qmi";
+    }>;
+    atCommand: z.ZodString;
+    applyCommand: z.ZodOptional<z.ZodString>;
+    expectedResponse: z.ZodString;
+    expectsPortDrop: z.ZodBoolean;
+    expectedDescriptors: z.ZodObject<{
+        deviceClass: z.ZodNumber;
+        interfaces: z.ZodArray<z.ZodObject<{
+            interfaceClass: z.ZodNumber;
+            interfaceSubClass: z.ZodNumber;
+            interfaceProtocol: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    evidenceBundleSha256: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PermittedTransition = z.infer<typeof permittedTransitionSchema>;
+/** One certified SKU: its discriminator, canonical mode, and permitted transitions. */
+export declare const catalogEntrySchema: z.ZodObject<{
+    vidPid: z.ZodString;
+    model: z.ZodString;
+    firmwarePrefix: z.ZodString;
+    canonicalMode: z.ZodEnum<{
+        "ecm-ncm": "ecm-ncm";
+        mbim: "mbim";
+        qmi: "qmi";
+        rndis: "rndis";
+        "router-ethernet": "router-ethernet";
+    }>;
+    permittedTransitions: z.ZodArray<z.ZodObject<{
+        from: z.ZodEnum<{
+            "ecm-ncm": "ecm-ncm";
+            mbim: "mbim";
+            qmi: "qmi";
+        }>;
+        to: z.ZodEnum<{
+            "ecm-ncm": "ecm-ncm";
+            mbim: "mbim";
+            qmi: "qmi";
+        }>;
+        atCommand: z.ZodString;
+        applyCommand: z.ZodOptional<z.ZodString>;
+        expectedResponse: z.ZodString;
+        expectsPortDrop: z.ZodBoolean;
+        expectedDescriptors: z.ZodObject<{
+            deviceClass: z.ZodNumber;
+            interfaces: z.ZodArray<z.ZodObject<{
+                interfaceClass: z.ZodNumber;
+                interfaceSubClass: z.ZodNumber;
+                interfaceProtocol: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        evidenceBundleSha256: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CatalogEntry = z.infer<typeof catalogEntrySchema>;
+/** The whole certified catalog file. */
+export declare const certifiedCatalogSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    entries: z.ZodArray<z.ZodObject<{
+        vidPid: z.ZodString;
+        model: z.ZodString;
+        firmwarePrefix: z.ZodString;
+        canonicalMode: z.ZodEnum<{
+            "ecm-ncm": "ecm-ncm";
+            mbim: "mbim";
+            qmi: "qmi";
+            rndis: "rndis";
+            "router-ethernet": "router-ethernet";
+        }>;
+        permittedTransitions: z.ZodArray<z.ZodObject<{
+            from: z.ZodEnum<{
+                "ecm-ncm": "ecm-ncm";
+                mbim: "mbim";
+                qmi: "qmi";
+            }>;
+            to: z.ZodEnum<{
+                "ecm-ncm": "ecm-ncm";
+                mbim: "mbim";
+                qmi: "qmi";
+            }>;
+            atCommand: z.ZodString;
+            applyCommand: z.ZodOptional<z.ZodString>;
+            expectedResponse: z.ZodString;
+            expectsPortDrop: z.ZodBoolean;
+            expectedDescriptors: z.ZodObject<{
+                deviceClass: z.ZodNumber;
+                interfaces: z.ZodArray<z.ZodObject<{
+                    interfaceClass: z.ZodNumber;
+                    interfaceSubClass: z.ZodNumber;
+                    interfaceProtocol: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            evidenceBundleSha256: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+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/dist/usb-mode/catalog-schema.js

@@ -0,0 +1,97 @@
+// 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'];
+/**
+ * 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'];
+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),
+});
+/** 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 EXACT AT command that COMMITS the switch on a SKU whose `atCommand` only
+     * writes non-volatile configuration; omitted for a SKU that re-enumerates on
+     * `atCommand` alone. Sent through the SAME allowlisted lease.
+     *
+     * Declaring it is a per-SKU hardware FACT, not a retry. Measured on the bench
+     * RM530N-GL: `AT+QCFG="usbnet",<n>` answers `OK`, reads back the new value, and
+     * leaves the device in the OLD composition for the whole port-drop budget — having
+     * already committed to NV. Undeclared, such a SKU fails on a timeout AFTER it was
+     * silently changed, then lands in the new composition at the next unrelated reboot.
+     */
+    applyCommand: z.string().min(1).optional(),
+    /** 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)' });
+/** 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.includes(e.canonicalMode), { message: 'only an MM-mode SKU (qmi/mbim/ecm-ncm) may declare permitted transitions' });
+/** The whole certified catalog file. */
+export const certifiedCatalogSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    entries: z.array(catalogEntrySchema),
+});

package/dist/usb-mode/catalog.d.ts

@@ -0,0 +1,21 @@
+import { type CatalogEntry, type CertifiedCatalog, type MmUsbMode, type PermittedTransition, type SkuDiscriminator } from './catalog-schema.js';
+/**
+ * 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 declare function loadCertifiedCatalog(value: unknown): CertifiedCatalog;
+/** The catalog shipped in this package, validated at module load. */
+export declare const CERTIFIED_CATALOG: CertifiedCatalog;
+/**
+ * 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 declare function findCatalogEntry(catalog: CertifiedCatalog, sku: SkuDiscriminator): CatalogEntry | undefined;
+/**
+ * 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 declare function findPermittedTransition(entry: CatalogEntry, from: MmUsbMode, to: MmUsbMode): PermittedTransition | undefined;