@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/ports/sms.js

@@ -0,0 +1,24 @@
+// The SMS port — LIST / READ and Added/Deleted observation. NOTHING ELSE.
+//
+// READ-ONLY IS PERMANENT, NOT A PHASE LIMITATION. There is no verb here that
+// composes, stores, sends, or deletes a message, and none may ever be added.
+// Sending or deleting an SMS is billable and irreversible, and it turns a
+// diagnostic read into real modem-control capability over the subscriber's
+// account. CeraUI carries the same contract on its own side, enforced by a grep
+// gate (`tests/modem-sms-readonly-gate.test.ts`); `sms/readonly-gate.test.ts`
+// is this package's half. Neither may be weakened to land a write path — that
+// is a new spec change with its own confirmation/interlock design.
+//
+// THE OBSERVATION MODEL IS "LIST ONCE, THEN FOLLOW THE SIGNALS". ModemManager's
+// Messaging interface emits `Added` and `Deleted` for every inbox change, so a
+// consumer lists once at start and folds events from then on. Re-listing on a
+// poll tick is the anti-pattern this port exists to remove: it costs one method
+// call per message per tick and still cannot report an arrival any sooner than
+// the tick it lands on.
+//
+// CONTENT NEVER RIDES A DIAGNOSTIC. A message body routinely carries a one-time
+// code and its originator identifies the subscriber, so nothing on this port
+// puts either into a reason string, a receipt, or a log line — see
+// `../redact.ts` for the key class and `../sms/mmcli-parse.ts` for the
+// content-free parse errors.
+export {};

package/dist/ports/uhubctl.d.ts

@@ -0,0 +1,6 @@
+import type { PowerCapability, PowerCycleContext, PowerCycleResult } from '../backend/power-contract.js';
+/** Consumer-supplied USB-hub actuator. This package intentionally ships no implementation. */
+export interface UhubctlPort {
+    readonly capability: PowerCapability;
+    cycle(context: PowerCycleContext): Promise<PowerCycleResult>;
+}

package/dist/ports/uhubctl.js

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

package/dist/providers/contracts.d.ts

@@ -0,0 +1,124 @@
+import type { DeviceGeneration, ObservationEnvelope, OperationDescriptor, OperationResult, PhysicalModemId } from '../domain/index.js';
+export declare const PROVIDER_TRANSPORTS: readonly ["usb", "pci", "network", "modemmanager"];
+export type ProviderTransport = (typeof PROVIDER_TRANSPORTS)[number];
+export declare const PASSIVE_FACT_KINDS: readonly ["usb", "pci", "interface", "driver", "gateway", "model", "firmware"];
+export type PassiveFactKind = (typeof PASSIVE_FACT_KINDS)[number];
+export type EvidenceStrength = 'none' | 'weak' | 'moderate' | 'strong';
+export type MatcherScore = 'unsupported' | 'maybe' | 'likely' | 'supported';
+export type PassiveFact = {
+    readonly kind: PassiveFactKind;
+    readonly value: string;
+};
+export type ProviderMatchRequest = {
+    readonly physicalModemId: PhysicalModemId;
+    readonly generation: DeviceGeneration;
+    readonly transport: ProviderTransport;
+    readonly passiveFacts: readonly PassiveFact[];
+    readonly composition: string;
+    readonly firmware?: string;
+};
+export type ProviderExecutionContext = ProviderMatchRequest & {
+    readonly profile: string;
+};
+export type PassiveMatcher = {
+    readonly id: string;
+    readonly fact: PassiveFactKind;
+    readonly expected: readonly string[];
+    readonly profiles: readonly string[];
+    readonly strength: Exclude<EvidenceStrength, 'none'>;
+    readonly required: boolean;
+};
+export type FingerprintResult = {
+    readonly signal: 'match' | 'mismatch' | 'unknown';
+    readonly strength: Exclude<EvidenceStrength, 'none'>;
+    readonly profiles: readonly string[];
+    readonly detail: string;
+};
+export type UnauthenticatedProbe = {
+    readonly id: string;
+    readonly run: (context: ProviderMatchRequest) => Promise<FingerprintResult>;
+};
+export type CapabilityReader = {
+    readonly id: string;
+    readonly read: (context: ProviderExecutionContext) => Promise<Omit<FingerprintResult, 'profiles'>>;
+};
+export type AuthenticatedProfileResult = {
+    readonly status: 'matched';
+    readonly profile: string;
+    readonly detail: string;
+} | {
+    readonly status: 'refused';
+    readonly detail: string;
+} | {
+    readonly status: 'unavailable';
+    readonly detail: string;
+};
+/** One algorithm and one call per generation-scoped evaluation; cycling is unrepresentable. */
+export type AuthenticatedProfile = {
+    readonly algorithm: string;
+    readonly attemptLimit: 1;
+    readonly authenticate: (context: ProviderMatchRequest, profileCandidates: readonly string[]) => Promise<AuthenticatedProfileResult>;
+};
+export type ProviderOperationsSurface = {
+    readonly access: 'read-only' | 'read-write';
+};
+export interface ProviderReadOperations<O> {
+    readonly descriptor: OperationDescriptor<never, O>;
+    readonly read: (context: ProviderExecutionContext) => Promise<OperationResult<O>>;
+}
+export interface ProviderWriteOperations<I, O> {
+    readonly descriptor: OperationDescriptor<I, O>;
+    readonly read: (context: ProviderExecutionContext) => Promise<OperationResult<O>>;
+    readonly write: (context: ProviderExecutionContext, input: I) => Promise<OperationResult<O>>;
+}
+export type ProviderContractFixture = {
+    readonly profile: string;
+    readonly request: Readonly<Record<string, unknown>>;
+    readonly response: Readonly<Record<string, unknown>>;
+};
+export interface ProviderDefinition<TObservation = unknown, TOperations extends ProviderOperationsSurface = ProviderOperationsSurface> {
+    readonly id: string;
+    readonly profileVersion: string;
+    readonly eligibleTransports: readonly ProviderTransport[];
+    readonly passiveMatchers: readonly PassiveMatcher[];
+    readonly unauthenticatedProbes: readonly UnauthenticatedProbe[];
+    readonly authenticatedProfile?: AuthenticatedProfile;
+    readonly capabilityReaders: readonly CapabilityReader[];
+    readonly observe: (context: ProviderExecutionContext) => Promise<readonly ObservationEnvelope<TObservation>[]>;
+    readonly operations: (profile: string) => TOperations;
+    readonly contractFixtures: readonly ProviderContractFixture[];
+}
+export type MatcherEvidence = {
+    readonly provider: string;
+    readonly profile: string | null;
+    readonly stage: 'transport-eligibility' | 'passive-facts' | 'unauthenticated-fingerprint' | 'authenticated-profile' | 'capability-read';
+    readonly source: string;
+    readonly signal: 'match' | 'mismatch' | 'unknown';
+    readonly strength: EvidenceStrength;
+    readonly detail: string;
+};
+type MatchResultBase = {
+    readonly score: MatcherScore;
+    readonly confidence: number;
+    readonly evidence: readonly MatcherEvidence[];
+    readonly conflicts: readonly MatcherEvidence[];
+    readonly generation: DeviceGeneration;
+    readonly physicalModemId: PhysicalModemId;
+};
+export type ProviderMatchResult = (MatchResultBase & {
+    readonly status: 'unsupported' | 'ambiguous';
+    readonly provider: null;
+    readonly profile: null;
+    readonly operations: null;
+    readonly writable: false;
+}) | (MatchResultBase & {
+    readonly status: 'selected';
+    readonly provider: string;
+    readonly profile: string;
+    readonly operations: ProviderOperationsSurface;
+    readonly writable: boolean;
+});
+export interface ProviderMatcher {
+    match(request: ProviderMatchRequest): Promise<ProviderMatchResult>;
+}
+export {};

package/dist/providers/contracts.js

@@ -0,0 +1,10 @@
+export const PROVIDER_TRANSPORTS = ['usb', 'pci', 'network', 'modemmanager'];
+export const PASSIVE_FACT_KINDS = [
+    'usb',
+    'pci',
+    'interface',
+    'driver',
+    'gateway',
+    'model',
+    'firmware',
+];

package/dist/providers/huawei-hilink/index.d.ts

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

package/dist/providers/huawei-hilink/index.js

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

package/dist/providers/huawei-hilink/operations.d.ts

@@ -0,0 +1,20 @@
+import type { DeviceGeneration, OperationDescriptor, OperationResult } from '../../domain/index.js';
+import type { ProviderExecutionContext } from '../contracts.js';
+import { type HilinkProfile } from './provider.js';
+export type ReadValue = Readonly<Record<string, unknown>>;
+export type ReadOperation = {
+    readonly descriptor: OperationDescriptor<never, ReadValue>;
+    readonly read: (context: ProviderExecutionContext) => Promise<OperationResult<ReadValue>>;
+};
+export type WriteOperation = {
+    readonly descriptor: OperationDescriptor<string | boolean, ReadValue>;
+    readonly read: ReadOperation['read'];
+    readonly write: (context: ProviderExecutionContext, value: string | boolean) => Promise<OperationResult<ReadValue>>;
+};
+export declare function applied(generation: DeviceGeneration, value: ReadValue): OperationResult<ReadValue>;
+export declare function refused(generation: DeviceGeneration, reason: string): OperationResult<ReadValue>;
+export declare function operationDescriptor<I>(id: string, write: boolean, profile: HilinkProfile): OperationDescriptor<I, ReadValue>;
+export declare function requestSucceeded(status: number, body: string): boolean;
+export declare function capabilityPath(kind: 'status' | 'signal' | 'mode' | 'data'): string;
+export declare function writeDocument(kind: 'mode' | 'data', value: string | boolean): string;
+export declare function readbackMatches(kind: 'mode' | 'data', body: string, value: string | boolean): boolean;

package/dist/providers/huawei-hilink/operations.js

@@ -0,0 +1,56 @@
+import { defineOperationDescriptor } from '../../domain/index.js';
+import { parseHilinkDataCapability, parseHilinkXmlValue } from '../../hardware/router-parsers.js';
+import { HILINK_PATHS } from './provider.js';
+export function applied(generation, value) {
+    return { status: 'applied', value, generation, requiresReconciliation: false };
+}
+export function refused(generation, reason) {
+    return { status: 'refused', reason, generation, requiresReconciliation: false };
+}
+export function operationDescriptor(id, write, profile) {
+    return defineOperationDescriptor({
+        id,
+        support: {
+            read: { supported: true },
+            write: write ? { supported: true } : { supported: false, reason: 'read-only' },
+        },
+        authority: 'provider',
+        provider: 'huawei-hilink',
+        constraints: { kind: 'unconstrained' },
+        livePreconditions: ['fresh-session', 'capability-evidence'],
+        availability: { state: 'available' },
+        mutationImpact: write ? 'write' : 'read',
+        retryClass: 'never',
+        readback: write
+            ? { required: true, reason: 'fresh-readback', matches: () => true }
+            : { required: false },
+        rollback: { required: false },
+        journal: { required: false },
+        admission: { required: true, reason: 'router-session' },
+        evidence: { profiles: [profile.id], firmware: [profile.firmware] },
+        confidence: 'high',
+    });
+}
+export function requestSucceeded(status, body) {
+    return status >= 200 && status < 300 && /<response>\s*OK\s*<\/response>/i.test(body);
+}
+export function capabilityPath(kind) {
+    return kind === 'status'
+        ? HILINK_PATHS.status
+        : kind === 'signal'
+            ? HILINK_PATHS.signal
+            : kind === 'mode'
+                ? HILINK_PATHS.modeList
+                : HILINK_PATHS.data;
+}
+export function writeDocument(kind, value) {
+    return kind === 'mode'
+        ? `<?xml version="1.0" encoding="UTF-8"?><request><NetworkMode>${String(value)}</NetworkMode></request>`
+        : `<?xml version="1.0" encoding="UTF-8"?><request><dataswitch>${value ? 1 : 0}</dataswitch></request>`;
+}
+export function readbackMatches(kind, body, value) {
+    if (kind === 'mode')
+        return parseHilinkXmlValue(body, 'NetworkMode') === String(value);
+    const parsed = parseHilinkDataCapability(body);
+    return parsed.state === 'reported' && parsed.enabled === Boolean(value);
+}

package/dist/providers/huawei-hilink/provider.d.ts

@@ -0,0 +1,52 @@
+import type { NormalizedModemObservation } from '../../observations/index.js';
+import type { ResourceOwnershipPort } from '../../ports/resource-ownership.js';
+import type { ProviderDefinition, ProviderOperationsSurface } from '../contracts.js';
+import { HuaweiProvider, type ReadOperation, type WriteOperation } from './runtime.js';
+import type { HilinkTransport } from './transport.js';
+export declare const HILINK_PATHS: {
+    readonly session: "/api/webserver/SesTokInfo";
+    readonly loginState: "/api/user/state-login";
+    readonly login: "/api/user/login";
+    readonly status: "/api/monitoring/status";
+    readonly signal: "/api/device/signal";
+    readonly modeList: "/api/net/net-mode-list";
+    readonly mode: "/api/net/net-mode";
+    readonly data: "/api/dialup/mobile-dataswitch";
+};
+export type HilinkProfile = {
+    readonly id: string;
+    readonly firmware: string;
+    readonly passwordType: 3 | 4;
+};
+export declare const HILINK_PROFILES: readonly [{
+    readonly id: "e3372h-22.200-password-type-3";
+    readonly firmware: "22.200.05.00.1080";
+    readonly passwordType: 3;
+}, {
+    readonly id: "e3372h-22.333-password-type-4";
+    readonly firmware: "22.333.01.00.00";
+    readonly passwordType: 4;
+}];
+export type HilinkCredentials = {
+    readonly username: string;
+    readonly password: string;
+};
+export type HilinkOptions = {
+    readonly interfaceName: string;
+    readonly adminUrl: string;
+    readonly transport: HilinkTransport;
+    readonly ownership: ResourceOwnershipPort;
+    readonly credentials: HilinkCredentials;
+    readonly now?: () => number;
+};
+export type HilinkObservation = NormalizedModemObservation;
+export type HuaweiOperations = ProviderOperationsSurface & {
+    readonly status: ReadOperation;
+    readonly signal: ReadOperation;
+    readonly mode: WriteOperation;
+    readonly data: WriteOperation;
+};
+export declare function hilinkProfile(profileId: string): HilinkProfile | undefined;
+export declare function createHuaweiHiLinkProvider(options: HilinkOptions): HuaweiProvider;
+export declare function createHuaweiHiLinkDefinition(options: HilinkOptions): ProviderDefinition<HilinkObservation, HuaweiOperations>;
+export { HuaweiProvider as HuaweiHiLinkProvider };

package/dist/providers/huawei-hilink/provider.js

@@ -0,0 +1,76 @@
+import { HuaweiProvider } from './runtime.js';
+export const HILINK_PATHS = {
+    session: '/api/webserver/SesTokInfo',
+    loginState: '/api/user/state-login',
+    login: '/api/user/login',
+    status: '/api/monitoring/status',
+    signal: '/api/device/signal',
+    modeList: '/api/net/net-mode-list',
+    mode: '/api/net/net-mode',
+    data: '/api/dialup/mobile-dataswitch',
+};
+export const HILINK_PROFILES = [
+    {
+        id: 'e3372h-22.200-password-type-3',
+        firmware: '22.200.05.00.1080',
+        passwordType: 3,
+    },
+    {
+        id: 'e3372h-22.333-password-type-4',
+        firmware: '22.333.01.00.00',
+        passwordType: 4,
+    },
+];
+export function hilinkProfile(profileId) {
+    return HILINK_PROFILES.find((profile) => profile.id === profileId);
+}
+export function createHuaweiHiLinkProvider(options) {
+    return new HuaweiProvider(options);
+}
+export function createHuaweiHiLinkDefinition(options) {
+    const runtime = createHuaweiHiLinkProvider(options);
+    return {
+        id: 'huawei-hilink',
+        profileVersion: '1',
+        eligibleTransports: ['network'],
+        passiveMatchers: HILINK_PROFILES.map((profile) => ({
+            id: `firmware-${profile.firmware}`,
+            fact: 'firmware',
+            expected: [profile.firmware],
+            profiles: [profile.id],
+            strength: 'strong',
+            required: true,
+        })),
+        unauthenticatedProbes: [
+            {
+                id: 'hilink-session-shape',
+                run: (request) => runtime.sessionProbe(request),
+            },
+        ],
+        authenticatedProfile: {
+            algorithm: 'firmware-selected-hilink-password',
+            attemptLimit: 1,
+            authenticate: (request, candidates) => runtime.authenticateProfile(request, candidates),
+        },
+        capabilityReaders: [
+            runtime.capability('status'),
+            runtime.capability('signal'),
+            runtime.capability('mode'),
+            runtime.capability('data'),
+        ],
+        observe: (context) => runtime.observe(context),
+        operations: (profile) => runtime.operations(profile),
+        contractFixtures: HILINK_PROFILES.map((profile) => ({
+            profile: profile.id,
+            request: {
+                method: 'POST',
+                path: HILINK_PATHS.login,
+                passwordType: profile.passwordType,
+                interfaceBound: true,
+                redirects: 'disabled',
+            },
+            response: { status: 'matched', sessionMaterial: '[redacted]' },
+        })),
+    };
+}
+export { HuaweiProvider as HuaweiHiLinkProvider };

package/dist/providers/huawei-hilink/runtime.d.ts

@@ -0,0 +1,22 @@
+import type { ObservationEnvelope } from '../../domain/index.js';
+import type { AuthenticatedProfileResult, CapabilityReader, ProviderExecutionContext, ProviderMatchRequest } from '../contracts.js';
+import { type HilinkObservation, type HuaweiOperations } from './provider.js';
+import { HilinkSessionRuntime } from './session.js';
+export type { ReadOperation, WriteOperation } from './operations.js';
+export declare class HuaweiProvider extends HilinkSessionRuntime {
+    sessionProbe(request: ProviderMatchRequest): Promise<{
+        signal: "unknown" | "match";
+        strength: "strong";
+        profiles: ("e3372h-22.200-password-type-3" | "e3372h-22.333-password-type-4")[];
+        detail: string;
+    }>;
+    authenticateProfile(request: ProviderMatchRequest, candidates: readonly string[]): Promise<AuthenticatedProfileResult>;
+    observe(context: ProviderExecutionContext): Promise<readonly ObservationEnvelope<HilinkObservation>[]>;
+    capability(kind: 'status' | 'signal' | 'mode' | 'data'): CapabilityReader;
+    operations(profileId: string): HuaweiOperations;
+    private sessionFor;
+    private capabilitySupported;
+    private readOperation;
+    private writeOperation;
+    private write;
+}

package/dist/providers/huawei-hilink/runtime.js

@@ -0,0 +1,171 @@
+import { parseHilinkCapabilities, parseHilinkDataCapability, parseHilinkSession, parseHilinkXmlValue, } from '../../hardware/router-parsers.js';
+import { normalizeHilinkObservation } from '../../observations/sources/hilink.js';
+import { applied, capabilityPath, operationDescriptor, readbackMatches, refused, requestSucceeded, writeDocument, } from './operations.js';
+import { HILINK_PATHS, HILINK_PROFILES, hilinkProfile, } from './provider.js';
+import { HilinkSessionRuntime } from './session.js';
+export class HuaweiProvider extends HilinkSessionRuntime {
+    async sessionProbe(request) {
+        const profile = HILINK_PROFILES.find((candidate) => candidate.firmware === request.firmware);
+        const response = await this.request('GET', HILINK_PATHS.session);
+        const matches = response.status === 200 && parseHilinkSession(response.body) !== undefined;
+        return {
+            signal: matches && profile !== undefined ? 'match' : 'unknown',
+            strength: 'strong',
+            profiles: profile === undefined ? [] : [profile.id],
+            detail: matches ? 'session-token-evidence' : 'session-token-not-proven',
+        };
+    }
+    async authenticateProfile(request, candidates) {
+        const candidate = candidates.length === 1 ? hilinkProfile(candidates[0] ?? '') : undefined;
+        if (candidate === undefined)
+            return { status: 'refused', detail: 'profile-mismatch' };
+        const result = await this.authenticate(request, candidate, true);
+        if (result.status === 'ready')
+            return { status: 'matched', profile: candidate.id, detail: 'login-ok' };
+        return {
+            status: result.reason === 'unreachable' ? 'unavailable' : 'refused',
+            detail: result.reason,
+        };
+    }
+    async observe(context) {
+        const ready = await this.sessionFor(context);
+        if (ready === undefined)
+            return [];
+        const [status, signal, modeList, mode] = await Promise.all([
+            this.getResponse(HILINK_PATHS.status, ready),
+            this.getResponse(HILINK_PATHS.signal, ready),
+            this.getResponse(HILINK_PATHS.modeList, ready),
+            this.getResponse(HILINK_PATHS.mode, ready),
+        ]);
+        const input = {
+            status: status.body,
+            signal: signal.body,
+            netModeList: modeList.body,
+            netMode: mode.body,
+        };
+        return [
+            normalizeHilinkObservation(input, {
+                stableKey: `modem:${this.options.interfaceName}`,
+                generation: context.generation,
+                sourceEpoch: 1,
+                observedAt: (this.options.now?.() ?? Date.now()),
+            }),
+        ];
+    }
+    capability(kind) {
+        return {
+            id: `hilink-${kind}`,
+            read: async (context) => {
+                const session = await this.sessionFor(context);
+                if (session === undefined)
+                    return { signal: 'unknown', strength: 'strong', detail: 'session-unavailable' };
+                const path = capabilityPath(kind);
+                const response = await this.getResponse(path, session);
+                const supported = this.capabilitySupported(kind, response.body) && !this.authExpired(response);
+                return {
+                    signal: supported ? 'match' : 'mismatch',
+                    strength: 'strong',
+                    detail: supported ? 'capability-reported' : 'capability-refused',
+                };
+            },
+        };
+    }
+    operations(profileId) {
+        const profile = hilinkProfile(profileId);
+        if (profile === undefined)
+            return unsupportedOperations(profileId);
+        return {
+            access: 'read-write',
+            status: this.readOperation('status', HILINK_PATHS.status, profile),
+            signal: this.readOperation('signal', HILINK_PATHS.signal, profile),
+            mode: this.writeOperation('mode', HILINK_PATHS.mode, profile),
+            data: this.writeOperation('data', HILINK_PATHS.data, profile),
+        };
+    }
+    async sessionFor(context) {
+        const cached = this.cachedSession(context);
+        if (cached !== undefined)
+            return cached;
+        const profile = hilinkProfile(context.profile);
+        if (profile === undefined)
+            return undefined;
+        const result = await this.authenticate(context, profile, true);
+        return result.status === 'ready' ? result.session : undefined;
+    }
+    capabilitySupported(kind, body) {
+        if (kind === 'mode')
+            return parseHilinkCapabilities({ netModeList: body }).net_mode.state === 'reported';
+        if (kind === 'data')
+            return parseHilinkDataCapability(body).state === 'reported';
+        return parseHilinkXmlValue(body, 'code') === undefined && /<response>/i.test(body);
+    }
+    readOperation(id, path, profile) {
+        return {
+            descriptor: operationDescriptor(id, false, profile),
+            read: async (context) => {
+                const result = await this.authenticate(context, profile, false);
+                if (result.status === 'refused')
+                    return refused(context.generation, result.reason);
+                const response = await this.getResponse(path, result.session);
+                if (this.authExpired(response))
+                    return refused(context.generation, 'auth-expired');
+                if (response.status < 200 || response.status >= 300)
+                    return refused(context.generation, 'http-failure');
+                return applied(context.generation, { body: response.body });
+            },
+        };
+    }
+    writeOperation(id, path, profile) {
+        return {
+            descriptor: operationDescriptor(id, true, profile),
+            read: this.readOperation(`${id}-read`, path, profile).read,
+            write: (context, value) => this.write(context, profile, id, path, value),
+        };
+    }
+    async write(context, profile, kind, path, value) {
+        return this.withDevice(context, async () => {
+            const ownership = await this.options.ownership.acquire({ resource: 'router-session' });
+            if (ownership.status === 'refused')
+                return refused(context.generation, 'busy');
+            try {
+                const ready = await this.authenticate(context, profile, false);
+                if (ready.status === 'refused')
+                    return refused(context.generation, ready.reason);
+                const capabilityPath = kind === 'mode' ? HILINK_PATHS.modeList : HILINK_PATHS.data;
+                const capability = await this.getResponse(capabilityPath, ready.session);
+                if (this.authExpired(capability))
+                    return refused(context.generation, 'auth-expired');
+                if (!this.capabilitySupported(kind, capability.body))
+                    return refused(context.generation, 'capability-unavailable');
+                if (kind === 'mode') {
+                    const offered = parseHilinkCapabilities({ netModeList: capability.body }).net_mode;
+                    if (offered.state !== 'reported' ||
+                        !offered.modes.some((mode) => mode.id === String(value)))
+                        return refused(context.generation, 'capability-unavailable');
+                }
+                const body = writeDocument(kind, value);
+                const posted = await this.postResponse(path, body, ready.session);
+                if (this.authExpired(posted))
+                    return refused(context.generation, 'auth-expired');
+                if (!requestSucceeded(posted.status, posted.body))
+                    return refused(context.generation, 'http-failure');
+                const fresh = await this.authenticate(context, profile, false);
+                if (fresh.status === 'refused')
+                    return refused(context.generation, fresh.reason);
+                const readback = await this.getResponse(path, fresh.session);
+                if (this.authExpired(readback))
+                    return refused(context.generation, 'auth-expired');
+                const matches = readbackMatches(kind, readback.body, value);
+                return matches
+                    ? applied(context.generation, { body: readback.body })
+                    : refused(context.generation, 'not-applied');
+            }
+            finally {
+                await ownership.lease.release();
+            }
+        });
+    }
+}
+function unsupportedOperations(_profileId) {
+    throw new Error('unsupported-hilink-profile');
+}

package/dist/providers/huawei-hilink/session.d.ts

@@ -0,0 +1,28 @@
+import type { ProviderExecutionContext, ProviderMatchRequest } from '../contracts.js';
+import { type HilinkOptions, type HilinkProfile } from './provider.js';
+import type { HilinkHttpResponse } from './transport.js';
+export type HilinkSession = {
+    readonly cookie: string;
+    readonly token: string;
+};
+export type HilinkSessionFailure = 'auth-expired' | 'http-failure' | 'malformed' | 'profile-mismatch' | 'unreachable';
+export type HilinkSessionResult = {
+    readonly status: 'ready';
+    readonly session: HilinkSession;
+} | {
+    readonly status: 'refused';
+    readonly reason: HilinkSessionFailure;
+};
+export declare class HilinkSessionRuntime {
+    #private;
+    protected readonly options: HilinkOptions;
+    constructor(options: HilinkOptions);
+    protected withDevice<T>(context: ProviderExecutionContext, run: () => Promise<T>): Promise<T>;
+    protected sessionKey(context: ProviderMatchRequest): string;
+    protected cachedSession(context: ProviderMatchRequest): HilinkSession | undefined;
+    protected authenticate(context: ProviderMatchRequest, profile: HilinkProfile, cache: boolean): Promise<HilinkSessionResult>;
+    protected authExpired(response: HilinkHttpResponse): boolean;
+    protected getResponse(path: string, session: HilinkSession): Promise<HilinkHttpResponse>;
+    protected postResponse(path: string, body: string, session: HilinkSession): Promise<HilinkHttpResponse>;
+    protected request(method: 'GET' | 'POST', path: string, body?: string, headers?: readonly string[]): Promise<HilinkHttpResponse>;
+}