chainlesschain 0.162.148 → 0.162.150

package/src/harness/remote-command-ledger.js

@@ -0,0 +1,189 @@
+/**
+ * RemoteCommandLedger (Phase 5, Remote Control) — application-level idempotency
+ * + total ordering + device revocation for commands arriving from remote
+ * endpoints (terminal / web / mobile).
+ *
+ * The transport layer (remote-session-crypto) already rejects a replayed or
+ * out-of-order ENVELOPE within one connection — but a reconnect starts a fresh
+ * crypto session with a reset sequence baseline, so a command the client
+ * re-sends after a dropped ACK would sail through and EXECUTE A SECOND TIME. That
+ * is exactly the Phase 5 acceptance this guards: "断网恢复后不会重复执行工具调用".
+ *
+ * Guarantees:
+ *   - Idempotency: a command carries a stable `commandId`; the side effect runs
+ *     AT MOST ONCE. A re-delivered command returns its cached result flagged
+ *     `replayed` — it never re-executes.
+ *   - Total order: every applied command gets a monotonic `applyIndex`, so all
+ *     three endpoints agree on one order; `appliedSince(cursor)` lets a
+ *     reconnecting endpoint catch up deterministically.
+ *   - Revocation: a revoked device's commands are rejected (can't read/control).
+ *
+ * Pure + injectable clock → fully unit-testable without any transport/hardware.
+ */
+
+export class RemoteCommandLedger {
+  constructor({ now = () => Date.now(), revokedDevices = [] } = {}) {
+    this._now = typeof now === "function" ? now : () => now;
+    this._applied = new Map(); // commandId → { applyIndex, result, deviceId, ts }
+    this._order = []; // applyIndex → commandId (total order)
+    this._revoked = new Set(revokedDevices);
+    this._perDeviceSeq = new Map(); // deviceId → highest accepted seq
+    this._inFlight = new Map(); // commandId → Promise<record> for an in-progress apply
+  }
+
+  isRevoked(deviceId) {
+    return this._revoked.has(deviceId);
+  }
+
+  revokeDevice(deviceId) {
+    this._revoked.add(deviceId);
+  }
+
+  /**
+   * Apply a command idempotently. `execute` (async, side-effecting) runs AT MOST
+   * ONCE per commandId; a re-delivery returns the cached result without calling
+   * it again.
+   *
+   * @param {{commandId:string, deviceId:string, seq?:number, payload?:any}} command
+   * @param {(command)=>Promise<any>|any} execute
+   * @returns {Promise<{status:"applied"|"replayed"|"rejected", result?, reason?, applyIndex?}>}
+   */
+  async apply(command, execute) {
+    if (
+      !command ||
+      typeof command.commandId !== "string" ||
+      !command.commandId
+    ) {
+      return { status: "rejected", reason: "missing commandId" };
+    }
+    const { commandId, deviceId } = command;
+
+    // A revoked device can neither read nor control the session.
+    if (deviceId != null && this._revoked.has(deviceId)) {
+      return { status: "rejected", reason: "device revoked" };
+    }
+
+    // Idempotent replay: already applied → return the cached result, DO NOT
+    // re-run the side effect. This is the reconnect-safety guarantee.
+    const prior = this._applied.get(commandId);
+    if (prior) {
+      return {
+        status: "replayed",
+        result: prior.result,
+        applyIndex: prior.applyIndex,
+      };
+    }
+
+    // Coalesce CONCURRENT deliveries of the same commandId. `execute` is awaited
+    // below, so without this a second delivery arriving while the first is still
+    // running would ALSO pass the `prior` check (nothing is recorded until
+    // execute resolves) and run the side effect a SECOND time — the exact
+    // double-exec this ledger exists to prevent on reconnect. An already-in-flight
+    // same-commandId delivery waits for it and returns its result as `replayed`.
+    const inflight = this._inFlight.get(commandId);
+    if (inflight) {
+      try {
+        const rec = await inflight;
+        return {
+          status: "replayed",
+          result: rec.result,
+          applyIndex: rec.applyIndex,
+        };
+      } catch {
+        // The in-flight execution failed → it recorded nothing and is retryable;
+        // report rejection to this caller too (it can retry the same commandId).
+        return { status: "rejected", reason: "concurrent execution failed" };
+      }
+    }
+
+    // Optional per-device monotonic sequence check: a STALE seq (below what we've
+    // already accepted from this device) with a NEW commandId is a protocol
+    // violation (a genuine reconnect resends the SAME commandId, caught above).
+    if (
+      deviceId != null &&
+      Number.isFinite(command.seq) &&
+      this._perDeviceSeq.has(deviceId) &&
+      command.seq <= this._perDeviceSeq.get(deviceId)
+    ) {
+      return { status: "rejected", reason: "stale sequence" };
+    }
+
+    // Reserve the commandId BEFORE the first await so a concurrent same-id
+    // delivery (above) sees it in flight. The promise records the applied result
+    // on success and rejects on failure (so a retry can re-run the side effect).
+    const runPromise = (async () => {
+      const result = await execute(command);
+      const applyIndex = this._order.length;
+      const rec = { applyIndex, result, deviceId, ts: this._now() };
+      this._applied.set(commandId, rec);
+      this._order.push(commandId);
+      if (deviceId != null && Number.isFinite(command.seq)) {
+        this._perDeviceSeq.set(deviceId, command.seq);
+      }
+      return rec;
+    })();
+    this._inFlight.set(commandId, runPromise);
+    try {
+      const rec = await runPromise;
+      return {
+        status: "applied",
+        result: rec.result,
+        applyIndex: rec.applyIndex,
+      };
+    } catch (err) {
+      // A failed execution is NOT recorded as applied — the command may be
+      // retried (with the same commandId) and will run again. Surfacing the
+      // error lets the caller decide; idempotency only protects SUCCESSES.
+      return { status: "rejected", reason: `execute failed: ${err.message}` };
+    } finally {
+      this._inFlight.delete(commandId);
+    }
+  }
+
+  /**
+   * The ordered tail of applied commands after `cursor` (an applyIndex), so a
+   * reconnecting endpoint can replay missed state in the one agreed order.
+   * @returns {Array<{applyIndex, commandId, result, deviceId}>}
+   */
+  appliedSince(cursor = -1) {
+    const out = [];
+    for (let i = cursor + 1; i < this._order.length; i++) {
+      const commandId = this._order[i];
+      const rec = this._applied.get(commandId);
+      out.push({
+        applyIndex: i,
+        commandId,
+        result: rec.result,
+        deviceId: rec.deviceId,
+      });
+    }
+    return out;
+  }
+
+  /** Highest assigned applyIndex (−1 when nothing applied). */
+  cursor() {
+    return this._order.length - 1;
+  }
+
+  appliedCount() {
+    return this._order.length;
+  }
+
+  snapshot() {
+    return {
+      order: [...this._order],
+      applied: Array.from(this._applied.entries()),
+      revoked: Array.from(this._revoked),
+      perDeviceSeq: Array.from(this._perDeviceSeq.entries()),
+    };
+  }
+
+  static restore(snap, { now = () => Date.now() } = {}) {
+    const l = new RemoteCommandLedger({ now });
+    l._order = [...(snap?.order || [])];
+    l._applied = new Map(snap?.applied || []);
+    l._revoked = new Set(snap?.revoked || []);
+    l._perDeviceSeq = new Map(snap?.perDeviceSeq || []);
+    return l;
+  }
+}

package/src/harness/remote-session-push-apns.js

@@ -0,0 +1,246 @@
+// Remote Session vendor push — Apple Push Notification service (APNs) sender.
+//
+// A concrete implementation of the RemoteSessionPushDispatcher `sender` contract
+// for iOS/macOS devices, using APNs' HTTP/2 provider API with token-based
+// (JWT ES256) auth: a short-lived bearer signed with the .p8 auth key
+// (key id + team id). APNs mandates HTTP/2, so the network transport is an
+// injectable `request` function (default: node:http2) — everything else is
+// injectable too (clock, signer), so the whole chain is unit-testable with a
+// generated EC keypair and a fake transport, no real credentials or network.
+// The payload carries NO session content, only routing ids.
+
+import { sign as cryptoSign } from "node:crypto";
+import http2 from "node:http2";
+import fs from "node:fs";
+import { PushTokenUnregisteredError } from "./remote-session-push-errors.js";
+
+const PROD_HOST = "https://api.push.apple.com";
+const SANDBOX_HOST = "https://api.sandbox.push.apple.com";
+// APNs auth tokens are valid up to 60 min; refresh well inside that window.
+const JWT_TTL_MS = 50 * 60 * 1000;
+const JWT_SKEW_MS = 60 * 1000;
+
+function base64url(input) {
+  return Buffer.from(input)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function dropUndefined(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/** Default HTTP/2 transport for APNs. Resolves `{ status, headers, body }`. */
+function http2Request({ url, headers, body }) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const client = http2.connect(`${target.protocol}//${target.host}`);
+    client.on("error", reject);
+    const req = client.request({
+      ":method": "POST",
+      ":path": `${target.pathname}${target.search}`,
+      ...headers,
+    });
+    let status = 0;
+    let responseHeaders = {};
+    let data = "";
+    req.on("response", (h) => {
+      status = Number(h[":status"]) || 0;
+      responseHeaders = h;
+    });
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      data += chunk;
+    });
+    req.on("end", () => {
+      client.close();
+      resolve({ status, headers: responseHeaders, body: data });
+    });
+    req.on("error", (error) => {
+      client.close();
+      reject(error);
+    });
+    req.end(body);
+  });
+}
+
+/** Mints + caches the ES256 provider JWT from a .p8 auth key. */
+export class ApnsTokenProvider {
+  constructor(options = {}) {
+    if (!options.keyId) throw new Error("ApnsTokenProvider requires a keyId");
+    if (!options.teamId) throw new Error("ApnsTokenProvider requires a teamId");
+    if (!options.privateKey) {
+      throw new Error("ApnsTokenProvider requires a privateKey (.p8 contents)");
+    }
+    this.keyId = options.keyId;
+    this.teamId = options.teamId;
+    this.privateKey = options.privateKey;
+    this.now = options.now || Date.now;
+    // ES256 = ECDSA P-256 / SHA-256 with a raw R||S signature (JOSE form).
+    this.sign =
+      options.sign ||
+      ((input, key) =>
+        cryptoSign("sha256", Buffer.from(input), {
+          key,
+          dsaEncoding: "ieee-p1363",
+        }));
+    this._cached = null; // { token, expiresAt }
+  }
+
+  getToken() {
+    const now = this.now();
+    if (this._cached && this._cached.expiresAt - JWT_SKEW_MS > now) {
+      return this._cached.token;
+    }
+    const header = base64url(
+      JSON.stringify({ alg: "ES256", kid: this.keyId, typ: "JWT" }),
+    );
+    const payload = base64url(
+      JSON.stringify({ iss: this.teamId, iat: Math.floor(now / 1000) }),
+    );
+    const signingInput = `${header}.${payload}`;
+    const signature = base64url(this.sign(signingInput, this.privateKey));
+    const token = `${signingInput}.${signature}`;
+    this._cached = { token, expiresAt: now + JWT_TTL_MS };
+    return token;
+  }
+}
+
+/** Sends one high-priority alert to a device token via APNs HTTP/2. */
+export class ApnsPushSender {
+  constructor(options = {}) {
+    if (!options.tokenProvider) {
+      throw new Error("ApnsPushSender requires a tokenProvider");
+    }
+    if (!options.topic) {
+      throw new Error("ApnsPushSender requires a topic (app bundle id)");
+    }
+    this.tokenProvider = options.tokenProvider;
+    this.topic = options.topic;
+    this.host = options.host || (options.production ? PROD_HOST : SANDBOX_HOST);
+    this.request = options.request || http2Request;
+  }
+
+  /** Bound function matching the dispatcher's `sender` contract. */
+  get handler() {
+    return (payload) => this.send(payload);
+  }
+
+  async send({ token, notification, sessionId, clientId } = {}) {
+    if (!token) throw new Error("APNs send requires a device token");
+    const jwt = this.tokenProvider.getToken();
+    const payload = {
+      aps: dropUndefined({
+        alert: notification
+          ? dropUndefined({
+              title: notification.title,
+              body: notification.body,
+            })
+          : undefined,
+        sound: "default",
+      }),
+      // Routing ids only; no session content.
+      "remote-session": dropUndefined({
+        type: "approval-request",
+        sessionId: sessionId != null ? String(sessionId) : undefined,
+        clientId: clientId != null ? String(clientId) : undefined,
+      }),
+    };
+    const res = await this.request({
+      url: `${this.host}/3/device/${token}`,
+      headers: {
+        authorization: `bearer ${jwt}`,
+        "apns-topic": this.topic,
+        "apns-push-type": "alert",
+        "apns-priority": "10",
+      },
+      body: JSON.stringify(payload),
+    });
+    if (res.status === 200) {
+      return { id: res.headers?.["apns-id"] || null };
+    }
+    const reason = parseReason(res.body);
+    // A retired/invalid device token: 410 Unregistered or 400 BadDeviceToken —
+    // prune it rather than retry forever.
+    if (
+      res.status === 410 ||
+      reason === "Unregistered" ||
+      reason === "BadDeviceToken"
+    ) {
+      throw new PushTokenUnregisteredError(
+        `APNs token unregistered: ${reason || res.status}`,
+      );
+    }
+    throw new Error(`APNs send failed (${res.status}): ${reason || res.body}`);
+  }
+}
+
+function parseReason(body) {
+  if (!body) return null;
+  try {
+    return JSON.parse(body).reason || null;
+  } catch {
+    return null;
+  }
+}
+
+function loadPrivateKey(env, options) {
+  if (options.privateKey) return options.privateKey;
+  const inline = env.CHAINLESSCHAIN_REMOTE_SESSION_APNS_KEY_P8;
+  if (inline) return inline;
+  const filePath = env.CHAINLESSCHAIN_REMOTE_SESSION_APNS_KEY;
+  if (filePath) {
+    const fsMod = options.fs || fs;
+    try {
+      return fsMod.readFileSync(filePath, "utf8");
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a bound APNs `sender` from env, or null when APNs is not configured.
+ *
+ * APNs env:
+ *   CHAINLESSCHAIN_REMOTE_SESSION_APNS_KEY       (path to .p8), or
+ *   CHAINLESSCHAIN_REMOTE_SESSION_APNS_KEY_P8    (inline .p8 PEM)
+ *   CHAINLESSCHAIN_REMOTE_SESSION_APNS_KEY_ID
+ *   CHAINLESSCHAIN_REMOTE_SESSION_APNS_TEAM_ID
+ *   CHAINLESSCHAIN_REMOTE_SESSION_APNS_TOPIC      (app bundle id)
+ *   CHAINLESSCHAIN_REMOTE_SESSION_APNS_PRODUCTION ("true" → prod host)
+ */
+export function createApnsPushSender(env = {}, options = {}) {
+  const privateKey = loadPrivateKey(env, options);
+  const keyId = options.keyId || env.CHAINLESSCHAIN_REMOTE_SESSION_APNS_KEY_ID;
+  const teamId =
+    options.teamId || env.CHAINLESSCHAIN_REMOTE_SESSION_APNS_TEAM_ID;
+  const topic = options.topic || env.CHAINLESSCHAIN_REMOTE_SESSION_APNS_TOPIC;
+  if (!privateKey || !keyId || !teamId || !topic) return null;
+  let tokenProvider;
+  try {
+    tokenProvider =
+      options.tokenProvider ||
+      new ApnsTokenProvider({ keyId, teamId, privateKey, ...options });
+  } catch {
+    return null; // Malformed credentials — stay disabled rather than crash.
+  }
+  const production =
+    options.production !== undefined
+      ? options.production
+      : String(env.CHAINLESSCHAIN_REMOTE_SESSION_APNS_PRODUCTION) === "true";
+  const sender = new ApnsPushSender({
+    tokenProvider,
+    topic,
+    production,
+    ...options,
+  });
+  return sender.handler;
+}

package/src/harness/remote-session-push-errors.js

@@ -0,0 +1,15 @@
+// Shared error types for Remote Session vendor push senders.
+
+/**
+ * A device token the vendor reports as no longer valid (uninstalled app, token
+ * rotated). The caller should prune it so it is never retried. Raised by every
+ * provider (FCM UNREGISTERED, APNs 410/BadDeviceToken, …) so the dispatcher and
+ * ws-server pruning logic can key off a single `code`.
+ */
+export class PushTokenUnregisteredError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PushTokenUnregisteredError";
+    this.code = "PUSH_TOKEN_UNREGISTERED";
+  }
+}

package/src/harness/remote-session-push-fcm.js

@@ -14,6 +14,11 @@
 
 import { createSign } from "node:crypto";
 import fs from "node:fs";
+import { PushTokenUnregisteredError } from "./remote-session-push-errors.js";
+
+// Re-exported for existing importers; canonical definition lives in the shared
+// errors module so every provider raises the same type.
+export { PushTokenUnregisteredError };
 
 const FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
 const DEFAULT_TOKEN_URI = "https://oauth2.googleapis.com/token";
@@ -45,18 +50,6 @@ function dropUndefined(obj) {
   return out;
 }
 
-/**
- * A device token the vendor reports as no longer valid (uninstalled app, token
- * rotated). The caller should prune it so it is never retried.
- */
-export class PushTokenUnregisteredError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "PushTokenUnregisteredError";
-    this.code = "PUSH_TOKEN_UNREGISTERED";
-  }
-}
-
 /** Mints + caches OAuth2 access tokens from a Google service account. */
 export class GoogleServiceAccountTokenProvider {
   constructor(serviceAccount = {}, options = {}) {
@@ -215,26 +208,17 @@ function loadServiceAccount(env, options) {
 }
 
 /**
- * Build a concrete push `sender` from env, or null when unconfigured / for a
- * provider that is not yet implemented. Returns the bound sender function the
- * RemoteSessionPushDispatcher expects.
+ * Build a bound FCM `sender` from env, or null when FCM is not configured. The
+ * provider dispatch (fcm vs apns vs …) is the caller's job — see
+ * remote-session-push-senders.js.
  *
  * FCM env:
- *   CHAINLESSCHAIN_REMOTE_SESSION_PUSH_PROVIDER      = "fcm" (default)
  *   CHAINLESSCHAIN_REMOTE_SESSION_FCM_SERVICE_ACCOUNT      (path to JSON), or
  *   CHAINLESSCHAIN_REMOTE_SESSION_FCM_SERVICE_ACCOUNT_JSON (inline JSON)
  *   CHAINLESSCHAIN_REMOTE_SESSION_FCM_PROJECT_ID     (optional; else service
  *                                                     account project_id)
  */
-export function createRemoteSessionPushSender(env = {}, options = {}) {
-  const provider = (
-    env.CHAINLESSCHAIN_REMOTE_SESSION_PUSH_PROVIDER || "fcm"
-  ).toLowerCase();
-  if (provider !== "fcm") {
-    // APNs / HMS / Xiaomi / OPPO senders are not implemented yet; the injection
-    // seam means they can be added without touching the dispatcher.
-    return null;
-  }
+export function createFcmPushSender(env = {}, options = {}) {
   const serviceAccount = loadServiceAccount(env, options);
   if (!serviceAccount) return null;
   const projectId =

package/src/harness/remote-session-push-huawei.js

@@ -0,0 +1,174 @@
+// Remote Session vendor push — Huawei (HMS Push Kit) sender.
+//
+// A concrete implementation of the RemoteSessionPushDispatcher `sender` contract
+// for Huawei/HarmonyOS devices via HMS Push Kit. Auth is OAuth2 client
+// credentials (app id + secret) exchanged for a short-lived access token —
+// simpler than FCM's signed JWT — then a Bearer POST to messages:send. Plain
+// HTTPS with an injectable `fetch` (default global), fully unit-testable with a
+// fake transport. The payload carries only routing ids (no session content).
+
+import { PushTokenUnregisteredError } from "./remote-session-push-errors.js";
+
+const DEFAULT_TOKEN_URI =
+  "https://oauth-login.cloud.huawei.com/oauth2/v3/token";
+const DEFAULT_PUSH_HOST = "https://push-api.cloud.huawei.com";
+const ACCESS_TOKEN_SKEW_MS = 60_000;
+// HMS success + invalid-token result codes (single-token send).
+const CODE_SUCCESS = "80000000";
+const CODE_ALL_TOKENS_INVALID = "80300007";
+const CODE_SOME_TOKENS_INVALID = "80100000";
+const INVALID_TOKEN_RE = /invalid.*token|token.*invalid|unregist/i;
+
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+function dropUndefined(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/** Mints + caches an OAuth2 access token from HMS client credentials. */
+export class HuaweiTokenProvider {
+  constructor(options = {}) {
+    if (!options.appId)
+      throw new Error("HuaweiTokenProvider requires an appId");
+    if (!options.appSecret) {
+      throw new Error("HuaweiTokenProvider requires an appSecret");
+    }
+    this.appId = options.appId;
+    this.appSecret = options.appSecret;
+    this.tokenUri = options.tokenUri || DEFAULT_TOKEN_URI;
+    this.now = options.now || Date.now;
+    this.fetch = options.fetch || globalThis.fetch;
+    this._cached = null; // { token, expiresAt }
+  }
+
+  async getAccessToken() {
+    const now = this.now();
+    if (this._cached && this._cached.expiresAt - ACCESS_TOKEN_SKEW_MS > now) {
+      return this._cached.token;
+    }
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: this.appId,
+      client_secret: this.appSecret,
+    });
+    const res = await this.fetch(this.tokenUri, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `Huawei OAuth failed (${res.status}): ${await safeText(res)}`,
+      );
+    }
+    const json = await res.json();
+    if (!json.access_token) {
+      throw new Error("Huawei OAuth response missing access_token");
+    }
+    const ttl = (Number(json.expires_in) || 3600) * 1000;
+    this._cached = { token: json.access_token, expiresAt: now + ttl };
+    return this._cached.token;
+  }
+}
+
+/** Sends one notification to an HMS device token. */
+export class HuaweiPushSender {
+  constructor(options = {}) {
+    if (!options.appId) throw new Error("HuaweiPushSender requires an appId");
+    if (!options.tokenProvider) {
+      throw new Error("HuaweiPushSender requires a tokenProvider");
+    }
+    this.appId = options.appId;
+    this.tokenProvider = options.tokenProvider;
+    this.fetch = options.fetch || globalThis.fetch;
+    this.endpoint =
+      options.endpoint ||
+      `${options.host || DEFAULT_PUSH_HOST}/v1/${options.appId}/messages:send`;
+  }
+
+  /** Bound function matching the dispatcher's `sender` contract. */
+  get handler() {
+    return (payload) => this.send(payload);
+  }
+
+  async send({ token, notification, sessionId, clientId } = {}) {
+    if (!token) throw new Error("Huawei send requires a device token");
+    const accessToken = await this.tokenProvider.getAccessToken();
+    const data = { type: "remote-session.approval-request" };
+    if (sessionId != null) data.sessionId = String(sessionId);
+    if (clientId != null) data.clientId = String(clientId);
+    const message = {
+      message: dropUndefined({
+        notification: notification
+          ? dropUndefined({
+              title: notification.title,
+              body: notification.body,
+            })
+          : undefined,
+        android: { urgency: "HIGH" },
+        data: JSON.stringify(data), // routing ids only, no session content
+        token: [token],
+      }),
+    };
+    const res = await this.fetch(this.endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(message),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (res.ok && json.code === CODE_SUCCESS) {
+      return { id: json.requestId || null };
+    }
+    const code = json.code || `HTTP ${res.status}`;
+    const msg = json.msg || "";
+    // A single-token send that reports invalid/all-invalid tokens means this
+    // token is dead — prune it rather than retry.
+    if (
+      code === CODE_ALL_TOKENS_INVALID ||
+      code === CODE_SOME_TOKENS_INVALID ||
+      INVALID_TOKEN_RE.test(String(msg))
+    ) {
+      throw new PushTokenUnregisteredError(
+        `Huawei token invalid (${code}): ${msg}`.trim(),
+      );
+    }
+    throw new Error(`Huawei push failed (${code}): ${msg}`.trim());
+  }
+}
+
+/**
+ * Build a bound Huawei `sender` from env, or null when unconfigured.
+ *
+ * Huawei env:
+ *   CHAINLESSCHAIN_REMOTE_SESSION_HUAWEI_APP_ID
+ *   CHAINLESSCHAIN_REMOTE_SESSION_HUAWEI_APP_SECRET
+ */
+export function createHuaweiPushSender(env = {}, options = {}) {
+  const appId =
+    options.appId || env.CHAINLESSCHAIN_REMOTE_SESSION_HUAWEI_APP_ID;
+  const appSecret =
+    options.appSecret || env.CHAINLESSCHAIN_REMOTE_SESSION_HUAWEI_APP_SECRET;
+  if (!appId || !appSecret) return null;
+  let tokenProvider;
+  try {
+    tokenProvider =
+      options.tokenProvider ||
+      new HuaweiTokenProvider({ appId, appSecret, ...options });
+  } catch {
+    return null; // Malformed credentials — stay disabled rather than crash.
+  }
+  return new HuaweiPushSender({ appId, tokenProvider, ...options }).handler;
+}