@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/fcc/policy-store.d.ts

@@ -0,0 +1,40 @@
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export declare const FCC_UNLOCK_SCHEMA_VERSION = 1;
+/** The pinned location of the policy of record. `/data` survives a slot swap. */
+export declare const FCC_UNLOCK_POLICY_PATH = "/data/ceralive/fcc-unlock-policy.json";
+/**
+ * The persisted document.
+ *
+ * `unlock` is a TOTAL map from `<vid>:<pid>` to the operator's answer. An absent key
+ * and an explicit `false` are the same fact (not opted in) and both are legal on
+ * disk: a `false` is what an opt-OUT leaves behind, and keeping it is what lets the
+ * shell reconciler prove it parsed a real answer rather than an empty document.
+ */
+export interface PersistedFccUnlockPolicy {
+    readonly schemaVersion: typeof FCC_UNLOCK_SCHEMA_VERSION;
+    readonly savedAtMs: number;
+    readonly unlock: Readonly<Record<string, boolean>>;
+}
+/** A metadata-only log event. Corruption NEVER carries the raw file content. */
+export type FccUnlockLogEvent = {
+    readonly kind: 'corrupt-policy';
+    readonly bytes: number;
+    readonly reason: string;
+};
+export type FccUnlockLogger = (event: FccUnlockLogEvent) => void;
+/** The persistence seam `setFccUnlockPolicy` drives. */
+export interface FccUnlockPolicyStore {
+    /** Load persisted policy; an absent or unreadable file loads as EMPTY. */
+    load(nowMs: number): Promise<PersistedFccUnlockPolicy>;
+    /** Atomically write policy with mode 0600 (temp → chmod → rename). */
+    save(state: PersistedFccUnlockPolicy): Promise<void>;
+}
+export interface FccUnlockPolicyFileStoreOptions {
+    readonly path?: string;
+    readonly logger?: FccUnlockLogger;
+}
+/** The `<vid>:<pid>` models the policy positively enables. Sorted, for stability. */
+export declare function enabledFccUnlockKeys(state: PersistedFccUnlockPolicy): string[];
+/** One model's answer. An unmentioned model is NOT enabled — absence is not consent. */
+export declare function isFccUnlockEnabled(state: PersistedFccUnlockPolicy, key: string): boolean;
+export declare function createFccUnlockPolicyFileStore(options?: FccUnlockPolicyFileStoreOptions): FccUnlockPolicyStore;

package/dist/fcc/policy-store.js

@@ -0,0 +1,146 @@
+// Durable persistence for the operator's FCC-auto-unlock POLICY.
+//
+// WHY THE FILE IS THE RECORD AND THE SYMLINK IS NOT. ModemManager's opt-in
+// mechanism is a symlink in `/etc/ModemManager/fcc-unlock.d/<vid>:<pid>`. `/etc` is
+// on the rootfs, and the rootfs is exactly what a RAUC A/B slot swap REPLACES
+// (`image-building-pipeline/docs/partition-contract.md`), so that symlink survives a
+// reboot and does NOT survive an OTA. `/data` is the only update-surviving store, so
+// the durable record lives there and the symlink is a derived artifact re-created
+// from it on every boot by `ceralive-fcc-reconcile`.
+//
+// The two hard guarantees are the SAME ones `backend/usage/policy-store.ts` makes,
+// and deliberately implemented the same way so the pair can be read side by side:
+//   - MODE 0600 via temp → chmod → atomic rename, regardless of umask.
+//   - FAIL-SAFE ON CORRUPTION: an unparseable/incompatible file logs METADATA ONLY
+//     (byte length + a classification reason, never the content) and is treated as
+//     EMPTY. Note the divergence from the usage store, and it is load-bearing: the
+//     usage store REWRITES a fresh file, while this one leaves the damaged bytes on
+//     disk for an operator to look at and simply refuses to act on them. Enabling a
+//     regulatory-unlock procedure is not something to infer from a file we could not
+//     read, and silently replacing the evidence would make the next person's
+//     diagnosis impossible.
+//
+// A policy row carries ONLY a `<vid>:<pid>` MODEL identifier and a boolean. There is
+// no per-unit identity here by construction — no serial, no ICCID, no ID_PATH —
+// because ModemManager's mechanism is model-wide and a per-unit key would be a
+// promise the dispatcher cannot keep.
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { isFccUnlockKey } from './coverage.js';
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export const FCC_UNLOCK_SCHEMA_VERSION = 1;
+/** The pinned location of the policy of record. `/data` survives a slot swap. */
+export const FCC_UNLOCK_POLICY_PATH = '/data/ceralive/fcc-unlock-policy.json';
+function defaultLogger(event) {
+    console.warn(`[fcc-unlock-policy] ${event.kind}: bytes=${event.bytes} reason=${event.reason}`);
+}
+function emptyState(nowMs) {
+    return { schemaVersion: FCC_UNLOCK_SCHEMA_VERSION, savedAtMs: nowMs, unlock: {} };
+}
+/** A schema violation naming only the offending FIELD (never file content). */
+class FccPolicySchemaError extends Error {
+    constructor(field) {
+        super(`schema-mismatch: ${field}`);
+    }
+}
+/**
+ * Parse + validate the document. Throws `FccPolicySchemaError` (metadata-only).
+ *
+ * WHOLE-DOCUMENT rejection, never per-key skipping: a half-applied policy is a
+ * policy nobody wrote, and the shell reconciler makes the same all-or-nothing
+ * judgement, so the two halves agree on what a damaged file means.
+ */
+function validate(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new FccPolicySchemaError('document');
+    }
+    const doc = raw;
+    if (doc.schemaVersion !== FCC_UNLOCK_SCHEMA_VERSION) {
+        throw new FccPolicySchemaError('schemaVersion');
+    }
+    if (typeof doc.savedAtMs !== 'number' || !Number.isFinite(doc.savedAtMs)) {
+        throw new FccPolicySchemaError('savedAtMs');
+    }
+    if (typeof doc.unlock !== 'object' || doc.unlock === null || Array.isArray(doc.unlock)) {
+        throw new FccPolicySchemaError('unlock');
+    }
+    const unlock = {};
+    for (const [key, value] of Object.entries(doc.unlock)) {
+        if (!isFccUnlockKey(key)) {
+            throw new FccPolicySchemaError('unlock.key');
+        }
+        if (typeof value !== 'boolean') {
+            throw new FccPolicySchemaError('unlock.value');
+        }
+        unlock[key] = value;
+    }
+    return {
+        schemaVersion: FCC_UNLOCK_SCHEMA_VERSION,
+        savedAtMs: doc.savedAtMs,
+        unlock,
+    };
+}
+/** Classify a load failure into a metadata-only reason string (no raw content). */
+function classifyFailure(error) {
+    if (error instanceof FccPolicySchemaError) {
+        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';
+}
+/** The `<vid>:<pid>` models the policy positively enables. Sorted, for stability. */
+export function enabledFccUnlockKeys(state) {
+    return Object.entries(state.unlock)
+        .filter(([, enabled]) => enabled)
+        .map(([key]) => key)
+        .sort();
+}
+/** One model's answer. An unmentioned model is NOT enabled — absence is not consent. */
+export function isFccUnlockEnabled(state, key) {
+    return state.unlock[key] === true;
+}
+export function createFccUnlockPolicyFileStore(options = {}) {
+    const logger = options.logger ?? defaultLogger;
+    const path = options.path ?? FCC_UNLOCK_POLICY_PATH;
+    async function writeAtomic(state) {
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp`;
+        // The trailing newline is for the shell reconciler's benefit, not decoration:
+        // it reads the file with `tr -d`, and a newline-terminated document is what a
+        // human `cat`ing it on a board expects to see.
+        await writeFile(tmp, `${JSON.stringify(state)}\n`);
+        // 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(nowMs) {
+            let text;
+            try {
+                text = await readFile(path, 'utf8');
+            }
+            catch {
+                // Absent (or unreadable) → EMPTY, which activates nothing. This is the
+                // state on every device that never opted in, and it is the safe default.
+                return emptyState(nowMs);
+            }
+            try {
+                return validate(JSON.parse(text));
+            }
+            catch (error) {
+                logger({
+                    kind: 'corrupt-policy',
+                    bytes: Buffer.byteLength(text, 'utf8'),
+                    reason: classifyFailure(error),
+                });
+                // Deliberately NOT rewritten — see the header. Refuse to act, keep the
+                // evidence, and let the next write replace it wholesale.
+                return emptyState(nowMs);
+            }
+        },
+        save: writeAtomic,
+    };
+}

package/dist/fcc/policy-write.d.ts

@@ -0,0 +1,32 @@
+import type { FccUnlockPolicyStore, PersistedFccUnlockPolicy } from './policy-store.js';
+export interface SetFccUnlockPolicyDeps {
+    readonly store: FccUnlockPolicyStore;
+    /** Injectable clock (defaults to `Date.now`). */
+    readonly now?: () => number;
+}
+export interface SetFccUnlockPolicyRequest {
+    readonly vid: string;
+    readonly pid: string;
+    readonly enabled: boolean;
+}
+export type SetFccUnlockPolicyRejection = 'invalid-vid-pid' | 'not-covered';
+export type SetFccUnlockPolicyResult = {
+    readonly status: 'applied';
+    /** The dispatcher key this write is about, normalized. */
+    readonly key: string;
+    readonly enabled: boolean;
+    /** The whole document now on disk, so a caller need not re-read it. */
+    readonly policy: PersistedFccUnlockPolicy;
+    /**
+     * True when the persisted value CHANGED. A caller uses this to decide
+     * whether the modem needs a re-probe: ModemManager runs the dispatcher
+     * during initialization only, so a genuine change needs
+     * `mmcli -m <id> --disable && --enable` (or a replug) to take effect on an
+     * already-enumerated modem — and an unchanged write must not cost one.
+     */
+    readonly changed: boolean;
+} | {
+    readonly status: 'rejected';
+    readonly reason: SetFccUnlockPolicyRejection;
+};
+export declare function setFccUnlockPolicy(request: SetFccUnlockPolicyRequest, deps: SetFccUnlockPolicyDeps): Promise<SetFccUnlockPolicyResult>;

package/dist/fcc/policy-write.js

@@ -0,0 +1,37 @@
+// `setFccUnlockPolicy` — the WRITE half of the FCC auto-unlock surface.
+//
+// TYPED RESULTS, NEVER A THROW ON BAD INPUT. Following the `PowerHook` and
+// `setUsagePolicy` precedents, a malformed key or an uncovered model is a `rejected`
+// result carrying a named reason rather than an exception — this is called from an
+// RPC boundary, where a throw becomes an opaque 500.
+//
+// THE COVERAGE CHECK IS PART OF THE WRITE, not a UI nicety. Persisting `true` for a
+// model ModemManager ships no procedure for would leave the operator staring at an
+// enabled toggle that provably cannot do anything: the reconciler would find no
+// `<vid>:<pid>` in the available tier and skip it forever, silently. Refusing at the
+// write is the only place that fact can be reported to the person who asked for it.
+//
+// Disabling is deliberately NOT coverage-checked. A `false` must always be
+// persistable — including for a model whose coverage answer has since changed, or
+// which a previous release wrote — because a fail-closed opt-OUT is not a thing.
+import { normalizeVidPid, resolveFccUnlockCoverage } from './coverage.js';
+export async function setFccUnlockPolicy(request, deps) {
+    const key = normalizeVidPid(request.vid, request.pid);
+    if (key === undefined) {
+        return { status: 'rejected', reason: 'invalid-vid-pid' };
+    }
+    if (request.enabled && resolveFccUnlockCoverage(request.vid, request.pid) !== 'present') {
+        return { status: 'rejected', reason: 'not-covered' };
+    }
+    const now = deps.now ?? Date.now;
+    const nowMs = now();
+    const current = await deps.store.load(nowMs);
+    const changed = (current.unlock[key] === true) !== request.enabled;
+    const next = {
+        schemaVersion: current.schemaVersion,
+        savedAtMs: nowMs,
+        unlock: { ...current.unlock, [key]: request.enabled },
+    };
+    await deps.store.save(next);
+    return { status: 'applied', key, enabled: request.enabled, policy: next, changed };
+}

package/dist/hardware/hilink-protocol.d.ts

@@ -0,0 +1,39 @@
+export declare function parseHilinkXmlValue(body: string, tag: string): string | undefined;
+export type HilinkSessionDocument = {
+    readonly cookie: string;
+    readonly token: string;
+};
+export declare function parseHilinkSession(body: string): HilinkSessionDocument | undefined;
+export type HilinkUserState = {
+    readonly state: string;
+    readonly passwordType: 3 | 4;
+};
+export declare function parseHilinkUserState(body: string): HilinkUserState | undefined;
+export type HilinkProtocolUnknownReason = 'unsupported' | 'not-reported' | 'malformed' | 'auth-expired' | 'unreachable';
+export type HilinkDataCapability = {
+    readonly state: 'reported';
+    readonly enabled: boolean;
+} | {
+    readonly state: 'unavailable';
+    readonly reason: HilinkProtocolUnknownReason | 'refused';
+    readonly code?: string;
+};
+export declare function parseHilinkDataCapability(body: string): HilinkDataCapability;
+export type HilinkNetModeCapability = {
+    readonly state: 'reported';
+    readonly modes: readonly {
+        readonly id: string;
+        readonly name?: string;
+    }[];
+    readonly current?: string;
+} | {
+    readonly state: 'unavailable';
+    readonly reason: HilinkProtocolUnknownReason | 'refused';
+    readonly code?: string;
+};
+export declare function parseHilinkCapabilities(input: {
+    readonly netModeList: string;
+    readonly netMode?: string;
+}): {
+    readonly net_mode: HilinkNetModeCapability;
+};

package/dist/hardware/hilink-protocol.js

@@ -0,0 +1,58 @@
+export function parseHilinkXmlValue(body, tag) {
+    const match = body.match(new RegExp(`<${tag}>([^<]*)</${tag}>`, 'i'));
+    return match?.[1]?.trim();
+}
+export function parseHilinkSession(body) {
+    const cookie = parseHilinkXmlValue(body, 'SesInfo');
+    const token = parseHilinkXmlValue(body, 'TokInfo');
+    return cookie === undefined || cookie === '' || token === undefined || token === ''
+        ? undefined
+        : { cookie, token };
+}
+export function parseHilinkUserState(body) {
+    const state = parseHilinkXmlValue(body, 'State');
+    const rawPasswordType = parseHilinkXmlValue(body, 'password_type');
+    if (state === undefined || (rawPasswordType !== '3' && rawPasswordType !== '4'))
+        return undefined;
+    return { state, passwordType: rawPasswordType === '3' ? 3 : 4 };
+}
+export function parseHilinkDataCapability(body) {
+    const code = parseHilinkXmlValue(body, 'code');
+    if (code === '125002')
+        return { state: 'unavailable', reason: 'auth-expired' };
+    if (code !== undefined)
+        return { state: 'unavailable', reason: 'refused', code };
+    const value = parseHilinkXmlValue(body, 'dataswitch');
+    if (value === undefined)
+        return { state: 'unavailable', reason: body === '' ? 'unreachable' : 'malformed' };
+    if (value !== '0' && value !== '1')
+        return { state: 'unavailable', reason: 'malformed' };
+    return { state: 'reported', enabled: value === '1' };
+}
+export function parseHilinkCapabilities(input) {
+    const code = parseHilinkXmlValue(input.netModeList, 'code');
+    if (code === '125002')
+        return { net_mode: { state: 'unavailable', reason: 'auth-expired' } };
+    if (code !== undefined)
+        return { net_mode: { state: 'unavailable', reason: 'refused', code } };
+    if (input.netModeList.trim() === '')
+        return { net_mode: { state: 'unavailable', reason: 'unreachable' } };
+    // `malformed` is a statement about the BODY — something that is not this API
+    // answered. A `<response>` carrying no mode list IS this API, saying nothing,
+    // which is `not-reported` below.
+    if (!/<response>/i.test(input.netModeList))
+        return { net_mode: { state: 'unavailable', reason: 'malformed' } };
+    const modes = [...input.netModeList.matchAll(/<NetworkMode>([\s\S]*?)<\/NetworkMode>/gi)].flatMap((match) => {
+        const id = parseHilinkXmlValue(match[1] ?? '', 'Index');
+        if (id === undefined || id === '')
+            return [];
+        const name = parseHilinkXmlValue(match[1] ?? '', 'Name');
+        return name === undefined || name === '' ? [{ id }] : [{ id, name }];
+    });
+    if (modes.length === 0)
+        return { net_mode: { state: 'unavailable', reason: 'not-reported' } };
+    const current = parseHilinkXmlValue(input.netMode ?? '', 'NetworkMode');
+    return current === undefined || current === ''
+        ? { net_mode: { state: 'reported', modes } }
+        : { net_mode: { state: 'reported', modes, current } };
+}

package/dist/hardware/index.d.ts

@@ -0,0 +1,3 @@
+export * from '../band/index.js';
+export * from '../usb-mode/index.js';
+export * from './router-parsers.js';

package/dist/hardware/index.js

@@ -0,0 +1,15 @@
+// `@ceralive/modem-control/hardware` — the per-SKU hardware model.
+//
+// This subpath is the narrow entry for everything keyed on the PHYSICAL unit rather
+// than on a live D-Bus object: which USB composition a SKU may be switched into and
+// which transitions were certified for it (`../usb-mode`), and the MMModemBand
+// vocabulary plus the per-SKU band-lock certification catalog (`../band`).
+//
+// Both halves are evidence-gated catalogs plus their pure lookups — no transport, no
+// mutation verb. The D-Bus verbs that ACT on these facts stay where they live
+// (`../backend/mm-mutations.ts`, declared on `ModemManagerPort`); a consumer that only
+// needs to know what a SKU is capable of should not have to import a bus client to
+// find out. That asymmetry is the reason this entry exists.
+export * from '../band/index.js';
+export * from '../usb-mode/index.js';
+export * from './router-parsers.js';

package/dist/hardware/router-parsers.d.ts

@@ -0,0 +1,89 @@
+export * from './hilink-protocol.js';
+export type SimPresence = 'present' | 'absent' | 'unknown';
+export type SimPresenceFacts = {
+    readonly sim?: string;
+    readonly simSlots?: readonly string[];
+    readonly failedReason?: string;
+};
+/** The mmcli spelling of `MM_MODEM_STATE_FAILED_REASON_SIM_MISSING` — the ONLY proof of absence. */
+export declare const SIM_MISSING_FAILED_REASON = "sim-missing";
+/** The fields a presence decision may be drawn from, in the order they are inspected. */
+export declare const SIM_PRESENCE_FIELDS: readonly ['sim', 'simSlots', 'failedReason'];
+export type SimPresenceField = (typeof SIM_PRESENCE_FIELDS)[number];
+/**
+ * WHICH FACT decided a SIM presence — the whole point of this type.
+ *
+ * `absent` is reachable through exactly ONE member (`state-failed-reason`), so a
+ * consumer can prove that no code path inferred "there is no SIM" from a blank or
+ * missing field. A modem that exports `Sim: '/'` and says nothing else is
+ * `no-evidence`/`unknown`: an empty object path is ModemManager's answer for "no SIM
+ * object is bound right now", which a modem also reports while it is still
+ * initializing, while its SIM is locked out, and while a slot switch is in flight.
+ *
+ * `vendor-code-unclaimed` is the router half. HiLink, goform and HIMI each report
+ * their own presence code with vendor semantics no migrated decoder covers, so the
+ * code is NAMED here and its value stays verbatim in the diagnostics block, rather
+ * than being guessed into a presence.
+ */
+export type SimPresenceEvidence = {
+    readonly kind: 'sim-object-path';
+    readonly field: 'sim';
+    readonly value: string;
+} | {
+    readonly kind: 'sim-slot-object-path';
+    readonly field: 'simSlots';
+    readonly value: string;
+} | {
+    readonly kind: 'state-failed-reason';
+    readonly field: 'failedReason';
+    readonly value: typeof SIM_MISSING_FAILED_REASON;
+} | {
+    readonly kind: 'no-evidence';
+    readonly inspected: readonly SimPresenceField[];
+} | {
+    readonly kind: 'vendor-code-unclaimed';
+    readonly field: string;
+};
+export type SimPresenceReading = {
+    readonly presence: SimPresence;
+    readonly evidence: SimPresenceEvidence;
+};
+/** The presence decision together with the fact that produced it. */
+export declare function readSimPresence(facts: SimPresenceFacts): SimPresenceReading;
+export declare function deriveSimPresence(facts: SimPresenceFacts): SimPresence;
+export type RouterSignalUnknownReason = 'unsupported' | 'not-reported' | 'malformed' | 'auth-expired' | 'unreachable';
+export type RouterSignalMetric = {
+    readonly state: 'known';
+    readonly value: number;
+} | {
+    readonly state: 'unknown';
+    readonly reason: RouterSignalUnknownReason;
+};
+export type RouterSignalModel = {
+    readonly provenance: 'hilink-admin-api' | 'zte-goform' | 'ufi-himiapi';
+    readonly freshness: 'live' | 'unknown';
+    readonly bars: RouterSignalMetric;
+    readonly max_bars: RouterSignalMetric;
+    readonly dbm: RouterSignalMetric;
+    readonly rsrp: RouterSignalMetric;
+    readonly rsrq: RouterSignalMetric;
+    readonly snr: RouterSignalMetric;
+    readonly sinr: RouterSignalMetric;
+};
+export declare function parseHilinkSignal(input: {
+    readonly status: string;
+    readonly signal: string;
+}): RouterSignalModel;
+export declare function parseZteSignal(body: string): RouterSignalModel;
+export declare function parseUfiSignal(input: {
+    readonly sysinfo: string;
+    readonly overview: string;
+    readonly status: string;
+}): RouterSignalModel;
+export type RouterDetails = Readonly<Record<string, string>>;
+export declare function parseZteDetails(body: string): RouterDetails | undefined;
+export declare function parseUfiDetails(input: {
+    readonly overview?: string;
+    readonly sysinfo?: string;
+    readonly produceInfo?: string;
+}): RouterDetails | undefined;