chainlesschain 0.162.147 → 0.162.149

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

@@ -0,0 +1,179 @@
+// Remote Session vendor push — vivo (vpush) sender.
+//
+// A concrete implementation of the RemoteSessionPushDispatcher `sender` contract
+// for vivo/iQOO devices via the vivo Push server API. Auth is a two-step
+// handshake: sign = MD5(appId + appKey + timestamp + appSecret) is exchanged for
+// a short-lived `authToken` (valid ~24h), then a JSON POST to the single-send
+// endpoint carries that token in the `authToken` header. 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 { createHash, randomUUID } from "node:crypto";
+import { PushTokenUnregisteredError } from "./remote-session-push-errors.js";
+
+const DEFAULT_HOST = "https://api-push.vivo.com.cn";
+const AUTH_PATH = "/message/auth";
+const SEND_PATH = "/message/send";
+// vivo authToken is valid for ~24h; refresh a few minutes early.
+const AUTH_TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
+const AUTH_TOKEN_SKEW_MS = 5 * 60_000;
+const RESULT_SUCCESS = 0;
+// vivo regId-invalid result codes (single-send). 10302/10303 cover an illegal
+// regId or one that does not belong to this app.
+const INVALID_TOKEN_CODES = new Set([10302, 10303]);
+// vivo has no single canonical string either; also match the desc text.
+const INVALID_TOKEN_RE =
+  /invalid.*reg|reg.*invalid|illegal|unregist|not ?exist|无效|不存在|非法/i;
+
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+function md5Hex(input) {
+  return createHash("md5").update(input, "utf8").digest("hex");
+}
+
+/** Mints + caches a vivo authToken from app id + key + secret. */
+export class VivoAuthProvider {
+  constructor(options = {}) {
+    if (!options.appId) throw new Error("VivoAuthProvider requires an appId");
+    if (!options.appKey) throw new Error("VivoAuthProvider requires an appKey");
+    if (!options.appSecret) {
+      throw new Error("VivoAuthProvider requires an appSecret");
+    }
+    this.appId = options.appId;
+    this.appKey = options.appKey;
+    this.appSecret = options.appSecret;
+    this.host = options.host || DEFAULT_HOST;
+    this.now = options.now || Date.now;
+    this.fetch = options.fetch || globalThis.fetch;
+    this._cached = null; // { token, expiresAt }
+  }
+
+  async getAuthToken() {
+    const now = this.now();
+    if (this._cached && this._cached.expiresAt - AUTH_TOKEN_SKEW_MS > now) {
+      return this._cached.token;
+    }
+    const timestamp = now;
+    const sign = md5Hex(
+      `${this.appId}${this.appKey}${timestamp}${this.appSecret}`,
+    );
+    const res = await this.fetch(`${this.host}${AUTH_PATH}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        appId: this.appId,
+        appKey: this.appKey,
+        timestamp,
+        sign,
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `vivo auth failed (${res.status}): ${await safeText(res)}`,
+      );
+    }
+    const json = await res.json();
+    if (Number(json.result) !== RESULT_SUCCESS || !json.authToken) {
+      throw new Error(
+        `vivo auth response missing authToken: ${json.desc || json.result}`,
+      );
+    }
+    this._cached = {
+      token: json.authToken,
+      expiresAt: now + AUTH_TOKEN_TTL_MS,
+    };
+    return this._cached.token;
+  }
+}
+
+/** Sends one notification to a vivo regId. */
+export class VivoPushSender {
+  constructor(options = {}) {
+    if (!options.authProvider) {
+      throw new Error("VivoPushSender requires an authProvider");
+    }
+    this.authProvider = options.authProvider;
+    this.host = options.host || DEFAULT_HOST;
+    this.fetch = options.fetch || globalThis.fetch;
+    // vivo requires a unique requestId per message; injectable for tests.
+    this.requestId =
+      options.requestId || (() => randomUUID().replace(/-/g, ""));
+  }
+
+  /** 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("vivo send requires a regId");
+    const authToken = await this.authProvider.getAuthToken();
+    // Routing ids only — no session content.
+    const custom = { type: "remote-session.approval-request" };
+    if (sessionId != null) custom.sessionId = String(sessionId);
+    if (clientId != null) custom.clientId = String(clientId);
+    const message = {
+      regId: token,
+      notifyType: 1, // 1 = notification bar
+      title: notification?.title || "Approval requested",
+      content: notification?.body || "A coding session needs your approval",
+      skipType: 1, // 1 = open the app
+      requestId: this.requestId(),
+      clientCustomMap: custom,
+    };
+    const res = await this.fetch(`${this.host}${SEND_PATH}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        authToken,
+      },
+      body: JSON.stringify(message),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (res.ok && Number(json.result) === RESULT_SUCCESS) {
+      return { id: json.taskId || null };
+    }
+    const code = Number(json.result);
+    const desc = json.desc || `HTTP ${res.status}`;
+    if (INVALID_TOKEN_CODES.has(code) || INVALID_TOKEN_RE.test(String(desc))) {
+      throw new PushTokenUnregisteredError(`vivo regId invalid: ${desc}`);
+    }
+    throw new Error(
+      `vivo push failed (${Number.isNaN(code) ? res.status : code}): ${desc}`,
+    );
+  }
+}
+
+/**
+ * Build a bound vivo `sender` from env, or null when unconfigured.
+ *
+ * vivo env:
+ *   CHAINLESSCHAIN_REMOTE_SESSION_VIVO_APP_ID
+ *   CHAINLESSCHAIN_REMOTE_SESSION_VIVO_APP_KEY
+ *   CHAINLESSCHAIN_REMOTE_SESSION_VIVO_APP_SECRET
+ *   CHAINLESSCHAIN_REMOTE_SESSION_VIVO_HOST  (optional; override the API host)
+ */
+export function createVivoPushSender(env = {}, options = {}) {
+  const appId = options.appId || env.CHAINLESSCHAIN_REMOTE_SESSION_VIVO_APP_ID;
+  const appKey =
+    options.appKey || env.CHAINLESSCHAIN_REMOTE_SESSION_VIVO_APP_KEY;
+  const appSecret =
+    options.appSecret || env.CHAINLESSCHAIN_REMOTE_SESSION_VIVO_APP_SECRET;
+  if (!appId || !appKey || !appSecret) return null;
+  const host = options.host || env.CHAINLESSCHAIN_REMOTE_SESSION_VIVO_HOST;
+  let authProvider;
+  try {
+    authProvider =
+      options.authProvider ||
+      new VivoAuthProvider({ appId, appKey, appSecret, host, ...options });
+  } catch {
+    return null; // Malformed credentials — stay disabled rather than crash.
+  }
+  return new VivoPushSender({ authProvider, host, ...options }).handler;
+}

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

@@ -0,0 +1,299 @@
+// Remote Session vendor push — Web Push (browser) sender.
+//
+// A concrete implementation of the RemoteSessionPushDispatcher `sender` contract
+// for browser clients, using the Web Push protocol: VAPID (RFC 8292) auth via an
+// ES256 JWT signed with the server VAPID key, and RFC 8291 (aes128gcm) payload
+// encryption bound to the subscription's ECDH public key + auth secret. The
+// "token" is the browser PushSubscription (endpoint + keys) as JSON.
+//
+// Web Push endpoints accept plain HTTPS, so the network transport is an
+// injectable `fetch` (default global). Encryption/signing use node:crypto and
+// are exercised by a real encrypt→decrypt round-trip in the tests — no live
+// push service or credentials needed. The payload carries only routing ids.
+
+import crypto from "node:crypto";
+import { PushTokenUnregisteredError } from "./remote-session-push-errors.js";
+
+const VAPID_TTL_MS = 12 * 60 * 60 * 1000;
+const VAPID_SKEW_MS = 60 * 1000;
+const RECORD_SIZE = 4096;
+const DEFAULT_TTL_SECONDS = 2419200; // 28 days, capped by the push service
+
+function base64url(buf) {
+  return Buffer.from(buf)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function fromBase64url(value) {
+  return Buffer.from(String(value), "base64url");
+}
+
+function hmac(key, data) {
+  return crypto.createHmac("sha256", key).update(data).digest();
+}
+
+// HKDF-Expand for a single output block (len <= 32).
+function hkdfExpand(prk, info, len) {
+  return hmac(prk, Buffer.concat([info, Buffer.from([0x01])])).subarray(0, len);
+}
+
+// HKDF(salt, ikm, info, len) = Expand(Extract(salt, ikm), info, len).
+function hkdf(salt, ikm, info, len) {
+  return hkdfExpand(hmac(salt, ikm), info, len);
+}
+
+function uint32be(value) {
+  const buf = Buffer.alloc(4);
+  buf.writeUInt32BE(value);
+  return buf;
+}
+
+// RFC 8291 §3.4 + RFC 8188 §2.1 content-encryption key + nonce.
+function deriveContentKeys({
+  ecdhSecret,
+  authSecret,
+  salt,
+  uaPublic,
+  asPublic,
+}) {
+  const keyInfo = Buffer.concat([
+    Buffer.from("WebPush: info\0", "utf8"),
+    uaPublic,
+    asPublic,
+  ]);
+  const ikm = hkdf(authSecret, ecdhSecret, keyInfo, 32);
+  const prk = hmac(salt, ikm); // HKDF-Extract(salt, IKM)
+  const cek = hkdfExpand(
+    prk,
+    Buffer.from("Content-Encoding: aes128gcm\0", "utf8"),
+    16,
+  );
+  const nonce = hkdfExpand(
+    prk,
+    Buffer.from("Content-Encoding: nonce\0", "utf8"),
+    12,
+  );
+  return { cek, nonce };
+}
+
+/**
+ * Encrypt a payload for a Web Push subscription (RFC 8291, aes128gcm). Returns
+ * the full content-encoded body (header + ciphertext). Generates a fresh
+ * ephemeral key each call unless one is injected (tests).
+ */
+export function encryptWebPushPayload({
+  payload,
+  uaPublicKey,
+  authSecret,
+  ecdh,
+  salt,
+}) {
+  const server = ecdh || crypto.createECDH("prime256v1");
+  if (!ecdh) server.generateKeys();
+  const asPublic = server.getPublicKey();
+  const ecdhSecret = server.computeSecret(uaPublicKey);
+  const useSalt = salt || crypto.randomBytes(16);
+  const { cek, nonce } = deriveContentKeys({
+    ecdhSecret,
+    authSecret,
+    salt: useSalt,
+    uaPublic: uaPublicKey,
+    asPublic,
+  });
+  const data = Buffer.isBuffer(payload)
+    ? payload
+    : Buffer.from(payload, "utf8");
+  const record = Buffer.concat([data, Buffer.from([0x02])]); // last-record delimiter
+  const cipher = crypto.createCipheriv("aes-128-gcm", cek, nonce);
+  const ciphertext = Buffer.concat([
+    cipher.update(record),
+    cipher.final(),
+    cipher.getAuthTag(),
+  ]);
+  const header = Buffer.concat([
+    useSalt,
+    uint32be(RECORD_SIZE),
+    Buffer.from([asPublic.length]),
+    asPublic,
+  ]);
+  return Buffer.concat([header, ciphertext]);
+}
+
+/** Inverse of {@link encryptWebPushPayload}; used for interop tests. */
+export function decryptWebPushPayload({ body, uaEcdh, authSecret }) {
+  const salt = body.subarray(0, 16);
+  const idlen = body.readUInt8(20);
+  const asPublic = body.subarray(21, 21 + idlen);
+  const ciphertext = body.subarray(21 + idlen);
+  const ecdhSecret = uaEcdh.computeSecret(asPublic);
+  const { cek, nonce } = deriveContentKeys({
+    ecdhSecret,
+    authSecret,
+    salt,
+    uaPublic: uaEcdh.getPublicKey(),
+    asPublic,
+  });
+  const tag = ciphertext.subarray(ciphertext.length - 16);
+  const body2 = ciphertext.subarray(0, ciphertext.length - 16);
+  const decipher = crypto.createDecipheriv("aes-128-gcm", cek, nonce);
+  decipher.setAuthTag(tag);
+  const record = Buffer.concat([decipher.update(body2), decipher.final()]);
+  let end = record.length - 1;
+  while (end >= 0 && record[end] === 0x00) end -= 1; // strip padding
+  return record.subarray(0, end); // drop the 0x02 delimiter
+}
+
+/** Builds an EC private key object from raw base64url VAPID keys. */
+function importVapidKey(publicKeyB64url, privateKeyB64url) {
+  const pub = fromBase64url(publicKeyB64url);
+  if (pub.length !== 65 || pub[0] !== 0x04) {
+    throw new Error(
+      "VAPID public key must be a 65-byte uncompressed P-256 key",
+    );
+  }
+  return crypto.createPrivateKey({
+    key: {
+      kty: "EC",
+      crv: "P-256",
+      d: privateKeyB64url,
+      x: base64url(pub.subarray(1, 33)),
+      y: base64url(pub.subarray(33, 65)),
+    },
+    format: "jwk",
+  });
+}
+
+/** Mints + caches a VAPID (RFC 8292) ES256 JWT per push-endpoint origin. */
+export class VapidTokenProvider {
+  constructor(options = {}) {
+    if (!options.publicKey)
+      throw new Error("VapidTokenProvider requires publicKey");
+    if (!options.privateKey)
+      throw new Error("VapidTokenProvider requires privateKey");
+    if (!options.subject) {
+      throw new Error("VapidTokenProvider requires a subject (mailto: or URL)");
+    }
+    this.publicKey = options.publicKey;
+    this.subject = options.subject;
+    this.now = options.now || Date.now;
+    this._key =
+      options.key || importVapidKey(options.publicKey, options.privateKey);
+    this.sign =
+      options.sign ||
+      ((input, key) =>
+        crypto.sign("sha256", Buffer.from(input), {
+          key,
+          dsaEncoding: "ieee-p1363",
+        }));
+    this._cache = new Map(); // origin → { token, expiresAt }
+  }
+
+  getToken(aud) {
+    const now = this.now();
+    const cached = this._cache.get(aud);
+    if (cached && cached.expiresAt - VAPID_SKEW_MS > now) return cached.token;
+    const header = base64url(JSON.stringify({ typ: "JWT", alg: "ES256" }));
+    const payload = base64url(
+      JSON.stringify({
+        aud,
+        exp: Math.floor((now + VAPID_TTL_MS) / 1000),
+        sub: this.subject,
+      }),
+    );
+    const signingInput = `${header}.${payload}`;
+    const token = `${signingInput}.${base64url(this.sign(signingInput, this._key))}`;
+    this._cache.set(aud, { token, expiresAt: now + VAPID_TTL_MS });
+    return token;
+  }
+}
+
+/** Sends one encrypted Web Push message to a browser PushSubscription. */
+export class WebPushSender {
+  constructor(options = {}) {
+    if (!options.vapid)
+      throw new Error("WebPushSender requires a vapid provider");
+    this.vapid = options.vapid;
+    this.fetch = options.fetch || globalThis.fetch;
+    this.ttl = options.ttl || DEFAULT_TTL_SECONDS;
+  }
+
+  get handler() {
+    return (payload) => this.send(payload);
+  }
+
+  async send({ token, notification, sessionId, clientId } = {}) {
+    if (!token) throw new Error("Web Push send requires a subscription");
+    const subscription = typeof token === "string" ? JSON.parse(token) : token;
+    const endpoint = subscription?.endpoint;
+    const p256dh = subscription?.keys?.p256dh;
+    const auth = subscription?.keys?.auth;
+    if (!endpoint || !p256dh || !auth) {
+      throw new Error("Web Push subscription is missing endpoint/keys");
+    }
+    const message = { type: "remote-session.approval-request" };
+    if (notification?.title) message.title = notification.title;
+    if (notification?.body) message.body = notification.body;
+    if (sessionId != null) message.sessionId = String(sessionId);
+    if (clientId != null) message.clientId = String(clientId);
+
+    const body = encryptWebPushPayload({
+      payload: JSON.stringify(message),
+      uaPublicKey: fromBase64url(p256dh),
+      authSecret: fromBase64url(auth),
+    });
+    const origin = new URL(endpoint).origin;
+    const res = await this.fetch(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `vapid t=${this.vapid.getToken(origin)}, k=${this.vapid.publicKey}`,
+        "Content-Encoding": "aes128gcm",
+        "Content-Type": "application/octet-stream",
+        TTL: String(this.ttl),
+        Urgency: "high",
+      },
+      body,
+    });
+    if (res.status === 201 || res.ok) {
+      return { id: res.headers?.get?.("location") || null };
+    }
+    // 404/410 mean the subscription is gone — prune it rather than retry.
+    if (res.status === 404 || res.status === 410) {
+      throw new PushTokenUnregisteredError(
+        `Web Push subscription expired (${res.status})`,
+      );
+    }
+    throw new Error(`Web Push failed (${res.status})`);
+  }
+}
+
+/**
+ * Build a bound Web Push `sender` from env, or null when VAPID is unconfigured.
+ *
+ * Web env:
+ *   CHAINLESSCHAIN_REMOTE_SESSION_VAPID_PUBLIC_KEY  (base64url, 65-byte P-256)
+ *   CHAINLESSCHAIN_REMOTE_SESSION_VAPID_PRIVATE_KEY (base64url, 32-byte scalar)
+ *   CHAINLESSCHAIN_REMOTE_SESSION_VAPID_SUBJECT     (mailto: or https URL)
+ */
+export function createWebPushSender(env = {}, options = {}) {
+  const publicKey =
+    options.vapidPublicKey ||
+    env.CHAINLESSCHAIN_REMOTE_SESSION_VAPID_PUBLIC_KEY;
+  const privateKey =
+    options.vapidPrivateKey ||
+    env.CHAINLESSCHAIN_REMOTE_SESSION_VAPID_PRIVATE_KEY;
+  const subject =
+    options.vapidSubject || env.CHAINLESSCHAIN_REMOTE_SESSION_VAPID_SUBJECT;
+  if (!publicKey || !privateKey || !subject) return null;
+  let vapid;
+  try {
+    vapid =
+      options.vapid ||
+      new VapidTokenProvider({ publicKey, privateKey, subject, ...options });
+  } catch {
+    return null; // Malformed VAPID keys — stay disabled rather than crash.
+  }
+  return new WebPushSender({ vapid, ...options }).handler;
+}

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

@@ -0,0 +1,99 @@
+// Remote Session vendor push — Xiaomi (小米) push sender.
+//
+// A concrete implementation of the RemoteSessionPushDispatcher `sender` contract
+// for MIUI devices, using the Xiaomi Push server API. Unlike FCM/APNs there is
+// no JWT — auth is a static app AppSecret in the `Authorization: key=` header —
+// so this sender is a straight form-encoded POST over 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_HOST = "https://api.xmpush.xiaomi.com";
+const SEND_PATH = "/v3/message/regid";
+
+// Xiaomi does not use a single canonical "unregistered" code; match the reason
+// text it returns for a stale/invalid registration id.
+const INVALID_TOKEN_RE = /invalid|not valid|unregist|not ?exist|无效|不存在/i;
+
+/** Sends one notification to a Xiaomi registration id. */
+export class XiaomiPushSender {
+  constructor(options = {}) {
+    if (!options.appSecret) {
+      throw new Error("XiaomiPushSender requires an appSecret");
+    }
+    if (!options.packageName) {
+      throw new Error("XiaomiPushSender requires a packageName");
+    }
+    this.appSecret = options.appSecret;
+    this.packageName = options.packageName;
+    this.host = options.host || DEFAULT_HOST;
+    this.fetch = options.fetch || globalThis.fetch;
+  }
+
+  /** 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("Xiaomi send requires a registration id");
+    const params = new URLSearchParams({
+      registration_id: token,
+      restricted_package_name: this.packageName,
+      pass_through: "0", // 0 = show a notification, 1 = data-only
+      notify_type: "-1", // default sound/vibrate
+      title: notification?.title || "Approval requested",
+      description: notification?.body || "A coding session needs your approval",
+    });
+    // Routing ids only — no session content.
+    const payload = { type: "remote-session.approval-request" };
+    if (sessionId != null) payload.sessionId = String(sessionId);
+    if (clientId != null) payload.clientId = String(clientId);
+    params.set("payload", JSON.stringify(payload));
+
+    const res = await this.fetch(`${this.host}${SEND_PATH}`, {
+      method: "POST",
+      headers: {
+        Authorization: `key=${this.appSecret}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: params.toString(),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (res.ok && json.result === "ok" && Number(json.code) === 0) {
+      return { id: json.data?.id || null };
+    }
+    const reason = json.reason || json.description || `HTTP ${res.status}`;
+    if (INVALID_TOKEN_RE.test(String(reason))) {
+      throw new PushTokenUnregisteredError(
+        `Xiaomi registration id invalid: ${reason}`,
+      );
+    }
+    throw new Error(`Xiaomi push failed: ${reason}`);
+  }
+}
+
+/**
+ * Build a bound Xiaomi `sender` from env, or null when unconfigured.
+ *
+ * Xiaomi env:
+ *   CHAINLESSCHAIN_REMOTE_SESSION_XIAOMI_APP_SECRET
+ *   CHAINLESSCHAIN_REMOTE_SESSION_XIAOMI_PACKAGE_NAME
+ *   CHAINLESSCHAIN_REMOTE_SESSION_XIAOMI_HOST  (optional; e.g. the global host)
+ */
+export function createXiaomiPushSender(env = {}, options = {}) {
+  const appSecret =
+    options.appSecret || env.CHAINLESSCHAIN_REMOTE_SESSION_XIAOMI_APP_SECRET;
+  const packageName =
+    options.packageName ||
+    env.CHAINLESSCHAIN_REMOTE_SESSION_XIAOMI_PACKAGE_NAME;
+  if (!appSecret || !packageName) return null;
+  const host = options.host || env.CHAINLESSCHAIN_REMOTE_SESSION_XIAOMI_HOST;
+  return new XiaomiPushSender({
+    appSecret,
+    packageName,
+    host,
+    ...options,
+  }).handler;
+}

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

@@ -0,0 +1,104 @@
+// Remote Session push notifications (vendor push).
+//
+// Wakes a paired device for time-sensitive events (an approval request) even
+// when its relay WebSocket is suspended — the case a foreground-only local
+// notification can't cover. The actual delivery (FCM / APNs / Xiaomi / Huawei /
+// OPPO) is a pluggable `sender` injected by the host, so this layer stays
+// credential-free and fully unit-testable; with no sender it degrades to a
+// recorded no-op. Payloads carry NO session content, only the shape needed to
+// route the wake-up (aligns with the audit log's privacy-first stance).
+
+const DEFAULT_DEDUPE_WINDOW_MS = 30_000;
+
+/**
+ * True for host events that should wake a backgrounded device. Approval /
+ * permission requests qualify; their `resolved` counterparts do not.
+ */
+export function isApprovalRequestEvent(type) {
+  const value = String(type || "");
+  return /approval|permission/i.test(value) && !/resolv/i.test(value);
+}
+
+export class RemoteSessionPushDispatcher {
+  constructor(options = {}) {
+    this.now = options.now || Date.now;
+    this.sender = typeof options.sender === "function" ? options.sender : null;
+    this.provider = options.provider || null;
+    this.dedupeWindowMs = options.dedupeWindowMs || DEFAULT_DEDUPE_WINDOW_MS;
+    this.recent = new Map();
+    this.stats = { sent: 0, skipped: 0, failed: 0 };
+  }
+
+  get enabled() {
+    return Boolean(this.sender);
+  }
+
+  /**
+   * Deliver one wake-up. Never throws — a push is best-effort; the relay event
+   * and in-app notification remain the primary channels. Returns a structured
+   * outcome the caller can audit.
+   */
+  async dispatch({
+    token,
+    provider,
+    sessionId,
+    clientId,
+    notification,
+    dedupeKey,
+  } = {}) {
+    if (!token) return this._skip("no-token");
+    if (!this.sender) return this._skip("no-sender");
+    if (dedupeKey && this._isDuplicate(clientId, dedupeKey)) {
+      return this._skip("deduplicated");
+    }
+    try {
+      const result = await this.sender({
+        token,
+        provider: provider || this.provider,
+        sessionId,
+        clientId,
+        notification,
+      });
+      this.stats.sent += 1;
+      return { status: "sent", provider: provider || this.provider, result };
+    } catch (error) {
+      this.stats.failed += 1;
+      // Propagate a typed code (e.g. PUSH_TOKEN_UNREGISTERED) so the caller can
+      // prune a dead device token instead of retrying it forever.
+      return {
+        status: "failed",
+        error: error.message,
+        code: error.code || null,
+      };
+    }
+  }
+
+  _skip(reason) {
+    this.stats.skipped += 1;
+    return { status: "skipped", reason };
+  }
+
+  _isDuplicate(clientId, dedupeKey) {
+    const key = `${clientId || ""}:${dedupeKey}`;
+    const now = this.now();
+    const last = this.recent.get(key);
+    if (last != null && now - last < this.dedupeWindowMs) return true;
+    this.recent.set(key, now);
+    this._gc(now);
+    return false;
+  }
+
+  _gc(now) {
+    if (this.recent.size < 500) return;
+    for (const [key, ts] of this.recent) {
+      if (now - ts >= this.dedupeWindowMs) this.recent.delete(key);
+    }
+  }
+
+  static fromEnv(env = {}, options = {}) {
+    return new RemoteSessionPushDispatcher({
+      provider: env.CHAINLESSCHAIN_REMOTE_SESSION_PUSH_PROVIDER || null,
+      ...options,
+    });
+  }
+}