@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/providers/ufi-himi/provider.js

@@ -0,0 +1,204 @@
+// Qualcomm UFI / HIMI — a READ-ONLY provider, by construction rather than by policy.
+//
+// This provider normalizes the telemetry the pure parsers already own
+// (`hardware/router-parsers.ts` → `observations/sources/ufi.ts`, migrated in todo 17).
+// It adds a session and a transport around them and nothing else: there is no write
+// descriptor, no write command in the transport vocabulary, and no operation id outside
+// the closed read set that resolves to anything but a typed refusal.
+//
+// The Qualcomm safety model it encodes lives in two neighbouring modules —
+// `qualcomm-evidence.ts` (what a USB id proves) and `prohibitions.ts` (what may never be
+// attempted). Both are inert data; neither can act.
+import { epochMillis, sourceEpoch, stableKeyFromPhysicalModemId } from '../../domain/index.js';
+import { parseUfiDetails, parseUfiSignal } from '../../hardware/router-parsers.js';
+import { normalizeUfiObservation } from '../../observations/sources/ufi.js';
+import { planUfiOperation, UFI_PROFILE, ufiReadDescriptor, ufiReadResult, ufiRefusedResult, } from './operations.js';
+import { UFI_PROHIBITED_OPERATION_IDS } from './prohibitions.js';
+import { UFI_DIAG_PRODUCTION_ACCESS, UFI_MATCHED_USB_IDS } from './qualcomm-evidence.js';
+import { parseUfiReply, UFI_SESSION_REFUSAL, UfiSessionRuntime } from './session.js';
+import { UFI_API_PATH } from './transport.js';
+export class UfiHimiProvider extends UfiSessionRuntime {
+    async fingerprint(request) {
+        // The HIMI fingerprint needs a SESSION to read anything, so this probe is the one
+        // place a "harmless unauthenticated probe" would spend the provider's single
+        // bounded login. On a device that enumerated a USB id and it is not a HIMI id,
+        // that login would be aimed at somebody else's dongle — a credential attempt
+        // against hardware this provider has positive evidence it does not own. An
+        // ABSENT usb fact is still probed (nobody enumerated one; that is not a denial).
+        if (!this.usbEvidencePermitsProbe(request)) {
+            return {
+                signal: 'unknown',
+                strength: 'strong',
+                profiles: [],
+                detail: 'usb-id-is-not-himi',
+            };
+        }
+        const bodies = await this.fetch(request, ['getallstatus']);
+        const reply = parseUfiReply(bodies?.getallstatus ?? '');
+        const matched = reply?.reply === 'ok' && reply.params !== undefined;
+        return {
+            signal: matched ? 'match' : 'unknown',
+            strength: 'strong',
+            profiles: matched ? [UFI_PROFILE] : [],
+            detail: matched ? 'himi-json-shape' : 'himi-json-not-proven',
+        };
+    }
+    capability() {
+        return {
+            id: 'ufi-himi-telemetry',
+            read: async (context) => {
+                const bodies = await this.fetch(context, ['getsysinfo']);
+                const reply = parseUfiReply(bodies?.getsysinfo ?? '');
+                const supported = reply?.reply === 'ok' && reply.params !== undefined;
+                return {
+                    signal: supported ? 'match' : 'mismatch',
+                    strength: 'strong',
+                    detail: supported ? 'telemetry-reported' : 'telemetry-refused',
+                };
+            },
+        };
+    }
+    async observe(context) {
+        const bodies = await this.fetch(context, [
+            'getsysinfo',
+            'getoverview',
+            'getallstatus',
+            'getproduceinfo',
+        ]);
+        if (bodies === undefined)
+            return [];
+        const produceInfo = bodies.getproduceinfo;
+        return [
+            normalizeUfiObservation({
+                sysinfo: bodies.getsysinfo ?? '',
+                overview: bodies.getoverview ?? '',
+                status: bodies.getallstatus ?? '',
+                ...(produceInfo === undefined ? {} : { produceInfo }),
+            }, {
+                stableKey: stableKeyFromPhysicalModemId(context.physicalModemId),
+                generation: context.generation,
+                sourceEpoch: sourceEpoch(1),
+                observedAt: epochMillis(this.observedAt()),
+            }),
+        ];
+    }
+    operations(_profile) {
+        return {
+            access: 'read-only',
+            reads: [
+                {
+                    descriptor: ufiReadDescriptor('ufi.signal.read'),
+                    read: (context) => this.readSignal(context),
+                },
+                {
+                    descriptor: ufiReadDescriptor('ufi.details.read'),
+                    read: (context) => this.readDetails(context),
+                },
+            ],
+            prohibited: UFI_PROHIBITED_OPERATION_IDS,
+            diagAccess: UFI_DIAG_PRODUCTION_ACCESS,
+            plan: planUfiOperation,
+        };
+    }
+    async readSignal(context) {
+        const bodies = await this.fetch(context, ['getsysinfo', 'getoverview', 'getallstatus']);
+        if (bodies === undefined)
+            return ufiRefusedResult(context.generation, 'session-unavailable');
+        const value = parseUfiSignal({
+            sysinfo: bodies.getsysinfo ?? '',
+            overview: bodies.getoverview ?? '',
+            status: bodies.getallstatus ?? '',
+        });
+        return ufiReadResult(context.generation, value);
+    }
+    async readDetails(context) {
+        const bodies = await this.fetch(context, ['getoverview', 'getsysinfo', 'getproduceinfo']);
+        if (bodies === undefined)
+            return ufiRefusedResult(context.generation, 'session-unavailable');
+        const details = parseUfiDetails({
+            overview: bodies.getoverview ?? '',
+            sysinfo: bodies.getsysinfo ?? '',
+            produceInfo: bodies.getproduceinfo ?? '',
+        });
+        return details === undefined
+            ? ufiRefusedResult(context.generation, 'not-reported')
+            : ufiReadResult(context.generation, details);
+    }
+    usbEvidencePermitsProbe(request) {
+        const enumerated = request.passiveFacts.filter((fact) => fact.kind === 'usb');
+        return (enumerated.length === 0 ||
+            enumerated.some((fact) => UFI_MATCHED_USB_IDS.some((id) => id === fact.value)));
+    }
+    /**
+     * Reads are issued sequentially on ONE session. A `SessionOut` in any body drops the
+     * cached session so the NEXT generation may spend its own single login; it never
+     * re-authenticates inside this cycle.
+     */
+    async fetch(request, commands) {
+        const session = await this.session(request);
+        if (session === undefined)
+            return undefined;
+        const bodies = {};
+        for (const command of commands) {
+            const response = await this.read(command, session);
+            bodies[command] = response.status === 200 ? response.body : '';
+        }
+        const refused = Object.values(bodies).some((body) => parseUfiReply(body)?.reply === UFI_SESSION_REFUSAL);
+        if (refused)
+            this.forgetSession(request);
+        return bodies;
+    }
+}
+export function createUfiHimiDefinition(options) {
+    const runtime = new UfiHimiProvider(options);
+    return {
+        id: 'ufi-himi',
+        profileVersion: '1',
+        eligibleTransports: ['network'],
+        passiveMatchers: [
+            {
+                // ONE matcher over both ids. `9024` is the RNDIS+ADB composition and `9091` is
+                // a firmware-chosen product id; both identify a HIMI stick, and NEITHER is
+                // evidence of a DIAG channel (see qualcomm-evidence.ts).
+                id: 'usb-qualcomm-himi',
+                fact: 'usb',
+                expected: UFI_MATCHED_USB_IDS,
+                profiles: [UFI_PROFILE],
+                strength: 'strong',
+                required: true,
+            },
+        ],
+        unauthenticatedProbes: [
+            { id: 'ufi-himi-shape', run: (request) => runtime.fingerprint(request) },
+        ],
+        capabilityReaders: [runtime.capability()],
+        observe: (context) => runtime.observe(context),
+        operations: (profile) => runtime.operations(profile),
+        contractFixtures: [
+            {
+                profile: UFI_PROFILE,
+                request: {
+                    method: 'POST',
+                    path: UFI_API_PATH,
+                    cmdid: 'login',
+                    credentials: '[redacted]',
+                    interfaceBound: true,
+                    redirects: 'disabled',
+                },
+                response: { reply: 'ok', session: '[redacted]' },
+            },
+            {
+                profile: UFI_PROFILE,
+                request: {
+                    method: 'POST',
+                    path: UFI_API_PATH,
+                    cmdid: 'getsysinfo',
+                    authorization: '[redacted]',
+                    interfaceBound: true,
+                    redirects: 'disabled',
+                },
+                response: { reply: 'ok', params: '[verbatim-diagnostics]' },
+            },
+        ],
+    };
+}

package/dist/providers/ufi-himi/qualcomm-evidence.d.ts

@@ -0,0 +1,32 @@
+export declare const UFI_RNDIS_ADB_USB_ID = "05c6:9024";
+export declare const UFI_FIRMWARE_SPECIFIC_USB_ID = "05c6:9091";
+export type UfiUsbClaim = 'rndis-network' | 'adb-interface';
+export declare const UFI_USB_EVIDENCE: {
+    readonly "05c6:9024": readonly ["rndis-network", "adb-interface"];
+    /** Deliberately empty: a firmware-chosen product id claims nothing by itself. */
+    readonly "05c6:9091": readonly [];
+};
+export declare const UFI_MATCHED_USB_IDS: readonly ["05c6:9024", "05c6:9091"];
+export declare function ufiUsbClaims(usbId: string): readonly UfiUsbClaim[];
+export type UfiUsbInterfaceDescriptor = {
+    readonly number: number;
+    readonly interfaceClass: number;
+    readonly interfaceSubClass: number;
+    readonly interfaceProtocol: number;
+};
+export type UfiDiagEvidence = {
+    readonly state: 'descriptor-confirmed';
+    readonly interfaceNumber: number;
+} | {
+    readonly state: 'not-proven';
+    readonly reason: 'product-id-is-not-evidence' | 'no-diag-interface-descriptor';
+};
+export declare function classifyUfiDiagEvidence(input: {
+    readonly usbId: string;
+    readonly interfaces: readonly UfiUsbInterfaceDescriptor[];
+}): UfiDiagEvidence;
+/**
+ * Unconditional. A descriptor-confirmed DIAG channel raises what a SUPERVISED BENCH
+ * operator may attempt by hand; it never raises what this package may do on its own.
+ */
+export declare const UFI_DIAG_PRODUCTION_ACCESS: 'prohibited';

package/dist/providers/ufi-himi/qualcomm-evidence.js

@@ -0,0 +1,51 @@
+// What a Qualcomm USB id does and does not prove.
+//
+// `05c6:9024` is the composition the bench UFI sticks enumerate in: RNDIS networking
+// plus an ADB interface. That is EVIDENCE OF A COMPOSITION, not a permission — the ADB
+// interface being present is exactly why production must be explicit that it never uses
+// it (see `shell.transport-fallback` in prohibitions.ts).
+//
+// `05c6:9091` is a FIRMWARE-SPECIFIC product id. It is routinely read as "DIAG is
+// available", and that reading is wrong: `05c6` is Qualcomm's generic vendor id and the
+// product id is chosen by whoever built the firmware image, so it says nothing about
+// which interfaces the device actually exposes. Treating it as proof of DIAG is how a
+// tool ends up opening a channel that is not there, or worse, one that is there and
+// belongs to something else.
+//
+// The only thing that proves a DIAG channel is a DIAG INTERFACE DESCRIPTOR. And even a
+// confirmed one buys nothing in production: `UFI_DIAG_PRODUCTION_ACCESS` is `prohibited`
+// unconditionally, and the supervised read-only info probe is a bench runbook
+// (docs/UFI-DIAG-PROBE.md), never an operation this package can perform.
+export const UFI_RNDIS_ADB_USB_ID = '05c6:9024';
+export const UFI_FIRMWARE_SPECIFIC_USB_ID = '05c6:9091';
+export const UFI_USB_EVIDENCE = {
+    [UFI_RNDIS_ADB_USB_ID]: ['rndis-network', 'adb-interface'],
+    /** Deliberately empty: a firmware-chosen product id claims nothing by itself. */
+    [UFI_FIRMWARE_SPECIFIC_USB_ID]: [],
+};
+export const UFI_MATCHED_USB_IDS = [UFI_RNDIS_ADB_USB_ID, UFI_FIRMWARE_SPECIFIC_USB_ID];
+export function ufiUsbClaims(usbId) {
+    return Object.hasOwn(UFI_USB_EVIDENCE, usbId)
+        ? UFI_USB_EVIDENCE[usbId]
+        : [];
+}
+/** Qualcomm's DIAG interface: vendor-specific class/subclass with protocol 0x30. */
+const DIAG_INTERFACE_CLASS = 0xff;
+const DIAG_INTERFACE_SUBCLASS = 0xff;
+const DIAG_INTERFACE_PROTOCOL = 0x30;
+export function classifyUfiDiagEvidence(input) {
+    const diag = input.interfaces.find((descriptor) => descriptor.interfaceClass === DIAG_INTERFACE_CLASS &&
+        descriptor.interfaceSubClass === DIAG_INTERFACE_SUBCLASS &&
+        descriptor.interfaceProtocol === DIAG_INTERFACE_PROTOCOL);
+    if (diag !== undefined) {
+        return { state: 'descriptor-confirmed', interfaceNumber: diag.number };
+    }
+    return input.interfaces.length === 0
+        ? { state: 'not-proven', reason: 'product-id-is-not-evidence' }
+        : { state: 'not-proven', reason: 'no-diag-interface-descriptor' };
+}
+/**
+ * Unconditional. A descriptor-confirmed DIAG channel raises what a SUPERVISED BENCH
+ * operator may attempt by hand; it never raises what this package may do on its own.
+ */
+export const UFI_DIAG_PRODUCTION_ACCESS = 'prohibited';

package/dist/providers/ufi-himi/session.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import type { ProviderMatchRequest } from '../contracts.js';
+import { type UfiHttpResponse, type UfiReadCommand, type UfiTransport } from './transport.js';
+export type UfiCredentials = {
+    readonly username: string;
+    readonly password: string;
+};
+export type UfiOptions = {
+    readonly interfaceName: string;
+    readonly adminUrl: string;
+    readonly transport: UfiTransport;
+    /** Ephemeral bench input. Injected by the caller, never persisted, never logged. */
+    readonly credentials: UfiCredentials;
+    readonly now?: () => number;
+};
+/** The HIMI firmware's own word for "your session is gone". */
+export declare const UFI_SESSION_REFUSAL = "SessionOut";
+declare const ufiReplySchema: z.ZodObject<{
+    reply: z.ZodString;
+    session: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>;
+export type UfiReply = z.infer<typeof ufiReplySchema>;
+export declare function parseUfiReply(body: string): UfiReply | undefined;
+/**
+ * Session acquisition, bounded to ONE login per physical modem per generation.
+ *
+ * The bound is a set of spent keys rather than a counter reset on failure: a HIMI
+ * device that refused a credential refuses it again, and a provider that re-tries on
+ * every poll turns a wrong password into a lockout nobody asked for. A refused or
+ * expired session therefore surfaces as an honest auth-expired READING; the next
+ * enumeration (a new generation) gets the next single attempt.
+ */
+export declare class UfiSessionRuntime {
+    #private;
+    protected readonly options: UfiOptions;
+    constructor(options: UfiOptions);
+    protected session(request: ProviderMatchRequest): Promise<string | undefined>;
+    protected read(command: UfiReadCommand, session: string): Promise<UfiHttpResponse>;
+    /** A refused session is dropped so the NEXT generation may spend its own attempt. */
+    protected forgetSession(request: ProviderMatchRequest): void;
+    protected sessionKey(request: ProviderMatchRequest): string;
+    protected observedAt(): number;
+    private request;
+}
+export {};

package/dist/providers/ufi-himi/session.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { UFI_API_PATH, } from './transport.js';
+/** The HIMI firmware's own word for "your session is gone". */
+export const UFI_SESSION_REFUSAL = 'SessionOut';
+const flatRecordSchema = z.record(z.string(), z.union([z.string(), z.number()]));
+const ufiReplySchema = z.object({
+    reply: z.string(),
+    session: z.string().optional(),
+    params: flatRecordSchema.optional(),
+});
+export function parseUfiReply(body) {
+    const parsed = 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(ufiReplySchema)
+        .safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * Session acquisition, bounded to ONE login per physical modem per generation.
+ *
+ * The bound is a set of spent keys rather than a counter reset on failure: a HIMI
+ * device that refused a credential refuses it again, and a provider that re-tries on
+ * every poll turns a wrong password into a lockout nobody asked for. A refused or
+ * expired session therefore surfaces as an honest auth-expired READING; the next
+ * enumeration (a new generation) gets the next single attempt.
+ */
+export class UfiSessionRuntime {
+    options;
+    #sessions = new Map();
+    #spent = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    async session(request) {
+        const key = this.sessionKey(request);
+        const held = this.#sessions.get(key);
+        if (held !== undefined)
+            return held;
+        if (this.#spent.has(key))
+            return undefined;
+        this.#spent.add(key);
+        const response = await this.request('login', JSON.stringify({
+            cmdid: 'login',
+            username: this.options.credentials.username,
+            password: this.options.credentials.password,
+        }));
+        const reply = response.status === 200 ? parseUfiReply(response.body) : undefined;
+        const session = reply?.reply === 'ok' ? reply.session : undefined;
+        if (session === undefined || session === '')
+            return undefined;
+        this.#sessions.set(key, session);
+        return session;
+    }
+    read(command, session) {
+        return this.request(command, JSON.stringify({ cmdid: command, sessionId: session }), session);
+    }
+    /** A refused session is dropped so the NEXT generation may spend its own attempt. */
+    forgetSession(request) {
+        this.#sessions.delete(this.sessionKey(request));
+    }
+    sessionKey(request) {
+        return `${request.physicalModemId}:${request.generation}`;
+    }
+    observedAt() {
+        return this.options.now?.() ?? Date.now();
+    }
+    request(command, body, session) {
+        return this.options.transport.request({
+            method: 'POST',
+            url: `${this.options.adminUrl}${UFI_API_PATH}`,
+            command,
+            body,
+            headers: [
+                ...(session === undefined ? [] : [`Authorization: ${session}`]),
+                'Content-Type: application/json;charset=UTF-8',
+            ],
+            interfaceName: this.options.interfaceName,
+            redirect: 'error',
+        });
+    }
+}

package/dist/providers/ufi-himi/transport.d.ts

@@ -0,0 +1,29 @@
+/** The seven read commands the HIMI firmware answers. Bench-observed, not inferred. */
+export declare const UFI_READ_COMMANDS: readonly ['getoverview', 'getsysinfo', 'getallstatus', 'getapninfo', 'getnetworkmode', 'gethimiusbtether', 'getproduceinfo'];
+export type UfiReadCommand = (typeof UFI_READ_COMMANDS)[number];
+/**
+ * The ONE non-read command. It opens a server-side session and changes nothing on the
+ * device; the modem's configuration, radio and storage are untouched by it.
+ */
+export declare const UFI_SESSION_COMMANDS: readonly ['login'];
+export type UfiSessionCommand = (typeof UFI_SESSION_COMMANDS)[number];
+export declare const UFI_COMMANDS: readonly ["getoverview", "getsysinfo", "getallstatus", "getapninfo", "getnetworkmode", "gethimiusbtether", "getproduceinfo", "login"];
+export type UfiCommand = UfiReadCommand | UfiSessionCommand;
+export declare const UFI_API_PATH = "/himiapi/json";
+export type UfiHttpRequest = {
+    readonly method: 'POST';
+    readonly url: string;
+    /** Frozen vocabulary: the field a write would have to travel in cannot name one. */
+    readonly command: UfiCommand;
+    readonly body: string;
+    readonly headers: readonly string[];
+    readonly interfaceName: string;
+    readonly redirect: 'error';
+};
+export type UfiHttpResponse = {
+    readonly status: number;
+    readonly body: string;
+};
+export interface UfiTransport {
+    request(request: UfiHttpRequest): Promise<UfiHttpResponse>;
+}

package/dist/providers/ufi-himi/transport.js

@@ -0,0 +1,25 @@
+// Qualcomm UFI / HIMI transport shape.
+//
+// HIMI is not a REST surface: every call is `POST /himiapi/json` and the VERB lives in
+// the JSON body's `cmdid`. So "read-only" cannot be expressed here as an HTTP-method
+// restriction the way it can for HiLink. The command vocabulary is frozen as a union
+// instead — a request this transport can carry names a member of `UFI_COMMANDS`, and no
+// `set*` / flash / reset member exists — which makes a write UNREPRESENTABLE rather than
+// merely refused at runtime.
+/** The seven read commands the HIMI firmware answers. Bench-observed, not inferred. */
+export const UFI_READ_COMMANDS = [
+    'getoverview',
+    'getsysinfo',
+    'getallstatus',
+    'getapninfo',
+    'getnetworkmode',
+    'gethimiusbtether',
+    'getproduceinfo',
+];
+/**
+ * The ONE non-read command. It opens a server-side session and changes nothing on the
+ * device; the modem's configuration, radio and storage are untouched by it.
+ */
+export const UFI_SESSION_COMMANDS = ['login'];
+export const UFI_COMMANDS = [...UFI_READ_COMMANDS, ...UFI_SESSION_COMMANDS];
+export const UFI_API_PATH = '/himiapi/json';

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

@@ -0,0 +1,2 @@
+export * from './provider.js';
+export * from './transport.js';

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

@@ -0,0 +1,2 @@
+export * from './provider.js';
+export * from './transport.js';

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

@@ -0,0 +1,56 @@
+import type { ObservationEnvelope } from '../../domain/index.js';
+import type { NormalizedModemObservation } from '../../observations/index.js';
+import type { CapabilityReader, ProviderDefinition, ProviderExecutionContext, ProviderMatchRequest, ProviderOperationsSurface } from '../contracts.js';
+import { ZteSessionRuntime } from './session.js';
+import type { ZteTransport } from './transport.js';
+export declare const ZTE_PATHS: {
+    readonly get: '/goform/goform_get_cmd_process';
+    readonly set: '/goform/goform_set_cmd_process';
+};
+export declare const ZTE_EVIDENCE_CMD = "LD,psw_fail_num_str,login_lock_time,wa_inner_version,cr_version";
+export type ZteProfile = {
+    readonly id: 'mf79u-legacy' | 'mf79u-ld-salted' | 'mf266-salted';
+    readonly firmware: 'MF79U' | 'MF266';
+    readonly algorithm: 'legacy-base64' | 'login-salted-sha256' | 'multi-user-salted-sha256';
+};
+export declare const ZTE_PROFILES: readonly [{
+    readonly id: 'mf79u-legacy';
+    readonly firmware: 'MF79U';
+    readonly algorithm: 'legacy-base64';
+}, {
+    readonly id: 'mf79u-ld-salted';
+    readonly firmware: 'MF79U';
+    readonly algorithm: 'login-salted-sha256';
+}, {
+    readonly id: 'mf266-salted';
+    readonly firmware: 'MF266';
+    readonly algorithm: 'multi-user-salted-sha256';
+}];
+export declare const ZTE_UNKNOWN_PROFILE = "zte-unknown-read-only";
+export type ZteCredentials = {
+    readonly username: string;
+    readonly password: string;
+};
+export type ZteOptions = {
+    readonly interfaceName: string;
+    readonly adminUrl: string;
+    readonly transport: ZteTransport;
+    readonly credentials: ZteCredentials;
+    readonly now?: () => number;
+};
+type ZteOperations = ProviderOperationsSurface;
+export declare function zteProfilesForFirmware(firmware: string | undefined): readonly ZteProfile[];
+export declare function zteProfileById(profileId: string): ZteProfile | undefined;
+export declare class ZteGoformProvider extends ZteSessionRuntime {
+    fingerprint(request: ProviderMatchRequest): Promise<{
+        signal: "match" | "unknown";
+        strength: 'strong';
+        profiles: string[];
+        detail: string;
+    }>;
+    capability(): CapabilityReader;
+    observe(context: ProviderExecutionContext): Promise<readonly ObservationEnvelope<NormalizedModemObservation>[]>;
+    operations(_profile: string): ZteOperations;
+}
+export declare function createZteGoformDefinition(options: ZteOptions): ProviderDefinition<NormalizedModemObservation, ZteOperations>;
+export {};

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

@@ -0,0 +1,101 @@
+import { normalizeZteObservation } from '../../observations/sources/zte.js';
+import { parseZteRecord, ZteSessionRuntime } from './session.js';
+export const ZTE_PATHS = {
+    get: '/goform/goform_get_cmd_process',
+    set: '/goform/goform_set_cmd_process',
+};
+export const ZTE_EVIDENCE_CMD = 'LD,psw_fail_num_str,login_lock_time,wa_inner_version,cr_version';
+export const ZTE_PROFILES = [
+    { id: 'mf79u-legacy', firmware: 'MF79U', algorithm: 'legacy-base64' },
+    { id: 'mf79u-ld-salted', firmware: 'MF79U', algorithm: 'login-salted-sha256' },
+    { id: 'mf266-salted', firmware: 'MF266', algorithm: 'multi-user-salted-sha256' },
+];
+export const ZTE_UNKNOWN_PROFILE = 'zte-unknown-read-only';
+export function zteProfilesForFirmware(firmware) {
+    return ZTE_PROFILES.filter((profile) => profile.firmware === firmware);
+}
+export function zteProfileById(profileId) {
+    return ZTE_PROFILES.find((profile) => profile.id === profileId);
+}
+export class ZteGoformProvider extends ZteSessionRuntime {
+    async fingerprint(request) {
+        const evidence = await this.probeEvidence(request);
+        const matches = evidence !== undefined;
+        return {
+            signal: matches ? 'match' : 'unknown',
+            strength: 'strong',
+            profiles: matches ? [evidence.profile?.id ?? ZTE_UNKNOWN_PROFILE] : [],
+            detail: matches ? 'zte-goform-shape' : 'zte-goform-not-proven',
+        };
+    }
+    capability() {
+        return {
+            id: 'zte-telemetry',
+            read: async () => {
+                const response = await this.get('network_type,signalbar,rssi,lte_rsrp,lte_rsrq,lte_snr');
+                const supported = response.status === 200 && parseZteRecord(response.body) !== undefined;
+                return {
+                    signal: supported ? 'match' : 'mismatch',
+                    strength: 'strong',
+                    detail: supported ? 'telemetry-reported' : 'telemetry-refused',
+                };
+            },
+        };
+    }
+    async observe(context) {
+        const response = await this.get('network_type,signalbar,rssi,lte_rsrp,lte_rsrq,lte_snr,network_provider,cell_id', this.sessionCookie(context));
+        if (response.status !== 200)
+            return [];
+        return [
+            normalizeZteObservation({ body: response.body }, {
+                stableKey: `modem:${this.options.interfaceName}`,
+                generation: context.generation,
+                sourceEpoch: 1,
+                observedAt: (this.options.now?.() ?? Date.now()),
+            }),
+        ];
+    }
+    operations(_profile) {
+        return { access: 'read-only' };
+    }
+}
+export function createZteGoformDefinition(options) {
+    const runtime = new ZteGoformProvider(options);
+    return {
+        id: 'zte-goform',
+        profileVersion: '2',
+        eligibleTransports: ['network'],
+        passiveMatchers: ['MF79U', 'MF266'].map((firmware) => ({
+            id: `firmware-${firmware}`,
+            fact: 'firmware',
+            expected: [firmware],
+            profiles: zteProfilesForFirmware(firmware).map((profile) => profile.id),
+            strength: 'strong',
+            required: true,
+        })),
+        unauthenticatedProbes: [
+            { id: 'zte-goform-shape', run: (request) => runtime.fingerprint(request) },
+        ],
+        authenticatedProfile: {
+            algorithm: 'evidence-selected-zte-goform',
+            attemptLimit: 1,
+            authenticate: (request, candidates) => runtime.authenticateProfile(request, candidates),
+        },
+        capabilityReaders: [runtime.capability()],
+        observe: (context) => runtime.observe(context),
+        operations: (profile) => runtime.operations(profile),
+        contractFixtures: ZTE_PROFILES.map((profile) => ({
+            profile: profile.id,
+            request: {
+                method: 'POST',
+                path: ZTE_PATHS.set,
+                goformId: profile.algorithm === 'multi-user-salted-sha256' ? 'LOGIN_MULTI_USER' : 'LOGIN',
+                interfaceBound: true,
+                redirects: 'disabled',
+            },
+            response: profile.algorithm === 'multi-user-salted-sha256'
+                ? { status: 'matched', sessionMaterial: '[redacted]', ad: '[redacted]' }
+                : { status: 'matched', sessionMaterial: '[redacted]' },
+        })),
+    };
+}