@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/providers/zte-goform/session.d.ts

@@ -0,0 +1,23 @@
+import type { AuthenticatedProfileResult, ProviderMatchRequest } from '../contracts.js';
+import { type ZteOptions, type ZteProfile } from './provider.js';
+import type { ZteHttpResponse } from './transport.js';
+type ZteEvidence = {
+    readonly record: Readonly<Record<string, string | number>>;
+    readonly profile: ZteProfile | undefined;
+};
+export declare function parseZteRecord(body: string): Readonly<Record<string, string | number>> | undefined;
+export declare class ZteSessionRuntime {
+    #private;
+    protected readonly options: ZteOptions;
+    constructor(options: ZteOptions);
+    authenticateProfile(request: ProviderMatchRequest, candidates: readonly string[]): Promise<AuthenticatedProfileResult>;
+    protected probeEvidence(request: ProviderMatchRequest): Promise<ZteEvidence | undefined>;
+    protected sessionCookie(request: ProviderMatchRequest): string | undefined;
+    protected get(cmd: string, cookie?: string, multiData?: boolean): Promise<ZteHttpResponse>;
+    private login;
+    private loginSalted;
+    private sessionKey;
+    private post;
+    private request;
+}
+export {};

package/dist/providers/zte-goform/session.js

@@ -0,0 +1,197 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { ZTE_EVIDENCE_CMD, ZTE_PATHS, ZTE_UNKNOWN_PROFILE, zteProfileById, zteProfilesForFirmware, } from './provider.js';
+const flatRecordSchema = z.record(z.string(), z.union([z.string(), z.number()]));
+export function parseZteRecord(body) {
+    const result = z
+        .string()
+        .transform((value, context) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            context.addIssue({ code: 'custom', message: 'invalid JSON' });
+            return z.NEVER;
+        }
+    })
+        .pipe(flatRecordSchema)
+        .safeParse(body);
+    return result.success ? result.data : undefined;
+}
+function stokCookie(response) {
+    const expected = 'set-cookie';
+    const header = Object.entries(response.headers ?? {}).find(([key]) => key.toLowerCase() === expected)?.[1];
+    const cookie = header?.split(';', 1)[0]?.trim();
+    return cookie?.startsWith('stok=') ? cookie : undefined;
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex').toUpperCase();
+}
+function evidenceNumber(value) {
+    if (typeof value === 'string' && value.trim() === '')
+        return undefined;
+    const parsed = typeof value === 'number' ? value : Number(value);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+function profileFromEvidence(firmware, record) {
+    const versionEvidence = `${record.wa_inner_version ?? ''} ${record.cr_version ?? ''}`.toUpperCase();
+    const family = versionEvidence.includes('MF266')
+        ? 'MF266'
+        : versionEvidence.includes('MF79U')
+            ? 'MF79U'
+            : firmware;
+    const hasLd = typeof record.LD === 'string' && record.LD.length > 0;
+    const profileId = family === 'MF266'
+        ? hasLd
+            ? 'mf266-salted'
+            : undefined
+        : family === 'MF79U'
+            ? hasLd
+                ? 'mf79u-ld-salted'
+                : 'mf79u-legacy'
+            : undefined;
+    return zteProfilesForFirmware(family).find((profile) => profile.id === profileId);
+}
+function classifyLogin(response) {
+    const result = parseZteRecord(response.body)?.result;
+    if (response.status !== 200 || result === '1') {
+        return { status: 'refused', detail: 'protocol-mismatch' };
+    }
+    if (result === '3')
+        return { status: 'refused', detail: 'auth-rejection' };
+    const cookie = stokCookie(response);
+    return result === '0' && cookie !== undefined
+        ? { status: 'accepted', cookie }
+        : { status: 'refused', detail: 'protocol-mismatch' };
+}
+export class ZteSessionRuntime {
+    options;
+    #sessions = new Map();
+    #evidence = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async authenticateProfile(request, candidates) {
+        const candidate = candidates.length === 1 ? candidates[0] : undefined;
+        if (candidate === ZTE_UNKNOWN_PROFILE) {
+            return { status: 'matched', profile: ZTE_UNKNOWN_PROFILE, detail: 'read-only-fingerprint' };
+        }
+        const profile = zteProfileById(candidate ?? '');
+        if (profile === undefined) {
+            return { status: 'refused', detail: 'profile-mismatch' };
+        }
+        const evidence = this.#evidence.get(this.sessionKey(request)) ?? (await this.probeEvidence(request));
+        if (evidence === undefined)
+            return { status: 'refused', detail: 'protocol-mismatch' };
+        const remainingAttempts = evidenceNumber(evidence.record.psw_fail_num_str);
+        const lockTime = evidenceNumber(evidence.record.login_lock_time);
+        if (remainingAttempts === undefined || lockTime === undefined) {
+            return { status: 'refused', detail: 'protocol-mismatch' };
+        }
+        if (lockTime > 0 || remainingAttempts === 0) {
+            return { status: 'refused', detail: 'lockout' };
+        }
+        if (evidence.profile?.id !== profile.id) {
+            return { status: 'refused', detail: 'protocol-mismatch' };
+        }
+        switch (profile.algorithm) {
+            case 'legacy-base64':
+                return this.login(request, profile, Buffer.from(this.options.credentials.password).toString('base64'));
+            case 'login-salted-sha256': {
+                const ld = evidence.record.LD;
+                if (typeof ld !== 'string')
+                    return { status: 'refused', detail: 'protocol-mismatch' };
+                return this.login(request, profile, sha256(`${sha256(this.options.credentials.password)}${ld}`));
+            }
+            case 'multi-user-salted-sha256':
+                return this.loginSalted(request, profile, evidence.record);
+            default: {
+                const exhaustive = profile.algorithm;
+                return exhaustive;
+            }
+        }
+    }
+    async probeEvidence(request) {
+        const response = await this.get(ZTE_EVIDENCE_CMD, undefined, true);
+        const record = response.status === 200 ? parseZteRecord(response.body) : undefined;
+        if (record === undefined)
+            return undefined;
+        const evidence = { record, profile: profileFromEvidence(request.firmware, record) };
+        this.#evidence.set(this.sessionKey(request), evidence);
+        return evidence;
+    }
+    sessionCookie(request) {
+        return this.#sessions.get(this.sessionKey(request))?.cookie;
+    }
+    get(cmd, cookie, multiData = false) {
+        const query = new URLSearchParams({ isTest: 'false', cmd });
+        if (multiData)
+            query.set('multi_data', '1');
+        return this.request('GET', `${ZTE_PATHS.get}?${query.toString()}`, undefined, cookie);
+    }
+    async login(request, profile, password) {
+        const response = await this.post(new URLSearchParams({
+            goformId: 'LOGIN',
+            isTest: 'false',
+            password,
+        }).toString());
+        const result = classifyLogin(response);
+        if (result.status === 'refused')
+            return result;
+        this.#sessions.set(this.sessionKey(request), { cookie: result.cookie });
+        return { status: 'matched', profile: profile.id, detail: 'login-ok' };
+    }
+    async loginSalted(request, profile, evidence) {
+        const ld = evidence.LD;
+        if (typeof ld !== 'string') {
+            return { status: 'refused', detail: 'protocol-mismatch' };
+        }
+        const login = await this.post(new URLSearchParams({
+            goformId: 'LOGIN_MULTI_USER',
+            isTest: 'false',
+            password: sha256(`${sha256(this.options.credentials.password)}${ld}`),
+            IP: 'localhost',
+            user: this.options.credentials.username,
+        }).toString());
+        const result = classifyLogin(login);
+        if (result.status === 'refused')
+            return result;
+        const rd = parseZteRecord((await this.get('RD', result.cookie)).body)?.RD;
+        const waVersion = evidence.wa_inner_version;
+        const crVersion = evidence.cr_version;
+        if (typeof waVersion !== 'string' || typeof crVersion !== 'string' || typeof rd !== 'string') {
+            return { status: 'refused', detail: 'protocol-mismatch' };
+        }
+        this.#sessions.set(this.sessionKey(request), {
+            cookie: result.cookie,
+            ad: sha256(`${sha256(`${waVersion}${crVersion}`)}${rd}`),
+        });
+        return { status: 'matched', profile: profile.id, detail: 'login-ok' };
+    }
+    sessionKey(request) {
+        return `${request.physicalModemId}:${request.generation}`;
+    }
+    post(body) {
+        return this.request('POST', ZTE_PATHS.set, body);
+    }
+    request(method, path, body, cookie) {
+        const headers = [
+            ...(method === 'POST'
+                ? ['Content-Type: application/x-www-form-urlencoded; charset=UTF-8']
+                : []),
+            ...(cookie === undefined ? [] : [`Cookie: ${cookie}`]),
+            `Origin: ${this.options.adminUrl}`,
+            `Referer: ${this.options.adminUrl}/index.html`,
+        ];
+        return this.options.transport.request({
+            method,
+            url: `${this.options.adminUrl}${path}`,
+            ...(body === undefined ? {} : { body }),
+            headers,
+            interfaceName: this.options.interfaceName,
+            redirect: 'error',
+        });
+    }
+}

package/dist/providers/zte-goform/transport.d.ts

@@ -0,0 +1,16 @@
+export type ZteHttpRequest = {
+    readonly method: 'GET' | 'POST';
+    readonly url: string;
+    readonly body?: string;
+    readonly headers: readonly string[];
+    readonly interfaceName: string;
+    readonly redirect: 'error';
+};
+export type ZteHttpResponse = {
+    readonly status: number;
+    readonly body: string;
+    readonly headers?: Readonly<Record<string, string>>;
+};
+export interface ZteTransport {
+    request(request: ZteHttpRequest): Promise<ZteHttpResponse>;
+}

package/dist/providers/zte-goform/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/radio/band-truth.d.ts

@@ -0,0 +1,50 @@
+import { type BandCertificationEntry, type BandName } from '../band/index.js';
+import { type OperationDescriptor } from '../domain/index.js';
+import type { ModemBands } from '../ports/index.js';
+export declare const BAND_WRITE_OPERATION_ID = "modemmanager.bands";
+/** The refusal reasons a band write may carry. Certification is the first gate. */
+export declare const BAND_WRITE_REFUSAL = "band-certification-required";
+export declare const BAND_READ_REFUSAL = "band-read-unsupported";
+export declare const BAND_NONE_OFFERABLE_REFUSAL = "no-offerable-certified-bands";
+/**
+ * The band-lock certification decision for one device, as a descriptor consumer sees it.
+ *
+ * `required` is `true` unconditionally and is typed as the literal, so no code path can
+ * produce a band-write decision that does not require certification. This is the one
+ * capability module documented as STRICTER than `support-claim.ts`'s `capable` floor.
+ */
+export type BandWriteCertification = {
+    readonly required: true;
+    readonly satisfied: boolean;
+    readonly reason: 'band-certification-proven' | typeof BAND_WRITE_REFUSAL;
+    /** What the catalog proves is settable, intersected with what the modem advertises. */
+    readonly offerable: readonly BandName[];
+};
+export declare function describeBandWriteCertification(input: {
+    readonly entry: BandCertificationEntry | undefined;
+    readonly supported: readonly BandName[];
+}): BandWriteCertification;
+export type BandWriteDescriptorInput = {
+    readonly provider: string;
+    readonly profile: string;
+    readonly certification: BandWriteCertification;
+    readonly readSupported: boolean;
+};
+/**
+ * Whether a band readback confirms the write.
+ *
+ * A NARROWING lock must match exactly — a superset is a different lock from the one
+ * that was asked for. The reset (`['any']`) is the exception ModemManager forces:
+ * releasing a lock is `SetCurrentBands([ANY])`, and a modem afterwards reports either
+ * `any` or its whole supported set, both of which mean "no lock is in force".
+ */
+export declare function bandWriteReadbackMatches(requested: readonly BandName[], observed: ModemBands): boolean;
+/**
+ * The live band-write descriptor.
+ *
+ * `mutationImpact: 'disruptive'` because `SetCurrentBands` re-registers the radio and
+ * drops the bearer underneath NetworkManager; `readback` is REQUIRED because an
+ * accepted-but-ignored band write is the failure mode the catalog's own `readback`
+ * proof exists to catch, and it looks like success from the call site alone.
+ */
+export declare function buildBandWriteDescriptor(input: BandWriteDescriptorInput): OperationDescriptor<readonly BandName[], ModemBands>;

package/dist/radio/band-truth.js

@@ -0,0 +1,92 @@
+// The band-write descriptor — the certification gate, expressed as an operation contract.
+//
+// It ADDS NOTHING to `band/certification.ts`. That module already owns the four-proof
+// per-SKU catalog, the fail-closed lookup, and the `offerableBands` narrowing, and it
+// is the only place a SKU may be declared certified. What was missing was the other
+// end of the wire: a band write's OPERATION DESCRIPTOR did not say that it is
+// disruptive-with-a-certification-requirement, so the gate lived only inside the
+// provider's capability flag and a consumer reading the descriptor could not see it.
+//
+// TWO INDEPENDENT FENCES, deliberately. `availability: refused` is what a consumer
+// reads to decide whether to offer the control at all; the provider's own
+// `bandWrite` capability check is what refuses the call if one is made anyway. A gate
+// that exists only in the descriptor is advisory, and a gate that exists only in the
+// provider is invisible — a band lock can take a working uplink off the air, so it
+// gets both.
+import { offerableBands } from '../band/index.js';
+import { defineOperationDescriptor } from '../domain/index.js';
+export const BAND_WRITE_OPERATION_ID = 'modemmanager.bands';
+/** The refusal reasons a band write may carry. Certification is the first gate. */
+export const BAND_WRITE_REFUSAL = 'band-certification-required';
+export const BAND_READ_REFUSAL = 'band-read-unsupported';
+export const BAND_NONE_OFFERABLE_REFUSAL = 'no-offerable-certified-bands';
+export function describeBandWriteCertification(input) {
+    const offerable = offerableBands(input.entry, input.supported);
+    return input.entry === undefined
+        ? { required: true, satisfied: false, reason: BAND_WRITE_REFUSAL, offerable }
+        : { required: true, satisfied: true, reason: 'band-certification-proven', offerable };
+}
+function sameBandSet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const sorted = [...right].sort();
+    return [...left].sort().every((band, index) => band === sorted[index]);
+}
+/**
+ * Whether a band readback confirms the write.
+ *
+ * A NARROWING lock must match exactly — a superset is a different lock from the one
+ * that was asked for. The reset (`['any']`) is the exception ModemManager forces:
+ * releasing a lock is `SetCurrentBands([ANY])`, and a modem afterwards reports either
+ * `any` or its whole supported set, both of which mean "no lock is in force".
+ */
+export function bandWriteReadbackMatches(requested, observed) {
+    if (requested.length === 1 && requested[0] === 'any') {
+        return ((observed.current.length === 1 && observed.current[0] === 'any') ||
+            sameBandSet(observed.current, observed.supported));
+    }
+    return sameBandSet(requested, observed.current);
+}
+/**
+ * The live band-write descriptor.
+ *
+ * `mutationImpact: 'disruptive'` because `SetCurrentBands` re-registers the radio and
+ * drops the bearer underneath NetworkManager; `readback` is REQUIRED because an
+ * accepted-but-ignored band write is the failure mode the catalog's own `readback`
+ * proof exists to catch, and it looks like success from the call site alone.
+ */
+export function buildBandWriteDescriptor(input) {
+    const refusal = !input.certification.satisfied
+        ? BAND_WRITE_REFUSAL
+        : input.certification.offerable.length === 0
+            ? BAND_NONE_OFFERABLE_REFUSAL
+            : undefined;
+    return defineOperationDescriptor({
+        id: BAND_WRITE_OPERATION_ID,
+        support: {
+            read: input.readSupported
+                ? { supported: true }
+                : { supported: false, reason: BAND_READ_REFUSAL },
+            write: input.certification.satisfied
+                ? { supported: true }
+                : { supported: false, reason: BAND_WRITE_REFUSAL },
+        },
+        authority: 'provider',
+        provider: input.provider,
+        constraints: { kind: 'allowed-values', values: [input.certification.offerable] },
+        livePreconditions: ['modem-present', 'runtime-interface-present', 'band-certification-present'],
+        availability: refusal === undefined ? { state: 'available' } : { state: 'refused', reason: refusal },
+        mutationImpact: 'disruptive',
+        retryClass: 'never',
+        readback: {
+            required: true,
+            reason: 'band-write-readback',
+            matches: bandWriteReadbackMatches,
+        },
+        rollback: { required: false },
+        journal: { required: true, reason: 'disruptive-radio-write' },
+        admission: { required: true, reason: 'provider-mutation' },
+        evidence: { profiles: [input.profile], firmware: [] },
+        confidence: 'high',
+    });
+}

package/dist/radio/index.d.ts

@@ -0,0 +1,3 @@
+export * from './band-truth.js';
+export * from './mode-combinations.js';
+export * from './mode-truth.js';

package/dist/radio/index.js

@@ -0,0 +1,10 @@
+// Radio capability TRUTH: the modem's own mode catalog and band-write gate, verbatim.
+//
+// It sits beside `src/band/` (the band vocabulary and per-SKU certification catalog)
+// rather than inside it, because a mode combination is not a band and the two have
+// different safety models — a mode change is disruptive-but-reversible, a band lock
+// can strand a radio where nothing registers. Reachable through the package ROOT
+// entry, deliberately NOT a new package subpath (the todo 17/18/23 precedent).
+export * from './band-truth.js';
+export * from './mode-combinations.js';
+export * from './mode-truth.js';

package/dist/radio/mode-combinations.d.ts

@@ -0,0 +1,88 @@
+/** A mode as every operator-facing surface spells it. Opaque; compare by equality. */
+export type ModeName = string;
+/**
+ * `MM_MODEM_MODE_NONE` (0) — the modem expresses no preference within its allowed set.
+ * A legal, load-bearing value; never a stand-in for "not reported".
+ */
+export declare const MODE_NONE = "none";
+/** `MM_MODEM_MODE_ANY` (0xFFFFFFFF) — every mode the modem has. */
+export declare const MODE_ANY = "any";
+/** Decode one `MMModemMode` bit. Total: an unnamed bit round-trips. */
+export declare function modeName(bit: number): ModeName;
+/** Encode one mode name. `undefined` for a name this build cannot place. */
+export declare function modeValue(name: ModeName): number | undefined;
+/** True when this build recognises the name (a `mode-bit-<n>` passthrough does not). */
+export declare function isNamedMode(name: ModeName): boolean;
+/**
+ * Split a mask into its set bits, named where this build can and passed through where
+ * it cannot. A zero mask is the EMPTY set — the caller decides whether that reads as
+ * `none` (a preference) or as an anomaly (an allowed set nothing can be chosen from).
+ */
+export declare function modeNames(mask: number): readonly ModeName[];
+/** Encode a set of mode names into one mask. Fails closed on an unplaceable name. */
+export declare function encodeModeNames(names: readonly ModeName[]): {
+    readonly ok: true;
+    readonly mask: number;
+} | {
+    readonly ok: false;
+    readonly unknown: ModeName;
+};
+/** Why a combination could not be fully placed. Never a reason to hide it. */
+export declare const MODE_COMBINATION_ANOMALIES: readonly [
+/** The allowed mask carries a bit this build does not name. */
+'unnamed-allowed-bit', 
+/** The preferred mask carries a bit this build does not name. */
+'unnamed-preferred-bit', 
+/** The preferred mode is not a member of the allowed set. */
+'preferred-not-in-allowed', 
+/** The preferred mask names more than one mode; MM's contract is at most one. */
+'preferred-not-singular', 
+/** The allowed mask is zero — nothing can be selected from this combination. */
+'empty-allowed'];
+export type ModeCombinationAnomaly = (typeof MODE_COMBINATION_ANOMALIES)[number];
+export type ModeCombinationClassification = 'named' | 'unknown-combination';
+/**
+ * One `(allowed, preferred)` pair, decoded without loss.
+ *
+ * The masks are retained ALONGSIDE the names so a consumer can always reproduce the
+ * exact bytes the modem reported, whatever this build managed to name.
+ */
+export type ModeCombination = {
+    readonly allowedMask: number;
+    readonly allowed: readonly ModeName[];
+    readonly preferredMask: number;
+    /** `none` when the modem stated no preference — verbatim, never a substitute. */
+    readonly preferred: ModeName;
+    readonly classification: ModeCombinationClassification;
+    readonly anomalies: readonly ModeCombinationAnomaly[];
+};
+/**
+ * A `SupportedModes` catalog: everything decoded, plus everything that could not be.
+ *
+ * `undecodable` exists so the no-drop property is structural rather than a promise —
+ * `combinations.length + undecodable.length` is the member count the provider sent.
+ */
+export type ModeCombinationSet = {
+    readonly combinations: readonly ModeCombination[];
+    /** Members that were not a `(uu)` pair, retained exactly as the provider sent them. */
+    readonly undecodable: readonly unknown[];
+};
+/** Build a combination from two raw masks, recording every anomaly it carries. */
+export declare function modeCombination(allowedMask: number, preferredMask: number): ModeCombination;
+/** True when the modem stated no preference within this combination's allowed set. */
+export declare function statesNoPreference(combination: ModeCombination): boolean;
+/** Decode one `CurrentModes` `(uu)`. `undefined` only when the value is not a pair. */
+export declare function decodeModeCombination(value: unknown): ModeCombination | undefined;
+/**
+ * Decode a `SupportedModes` `a(uu)`.
+ *
+ * Nothing is dropped: a member that is not a pair lands in `undecodable`, and a pair
+ * this build cannot fully name lands in `combinations` classified
+ * `unknown-combination`. A non-array value is an empty catalog, not an error — a modem
+ * that advertises no mode control is a real reading.
+ */
+export declare function decodeSupportedModeCombinations(value: unknown): ModeCombinationSet;
+/** True when any advertised combination carries an anomaly this build could not place. */
+export declare function hasUnknownCombination(set: ModeCombinationSet): boolean;
+/** Whether a mask names a mode this build recognises across every set bit. */
+export declare function isFullyNamedMask(mask: number): boolean;