chainlesschain 0.162.148 → 0.162.150

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

@@ -0,0 +1,171 @@
+// Remote Session vendor push — OPPO (HeyTap / ColorOS push) sender.
+//
+// A concrete implementation of the RemoteSessionPushDispatcher `sender` contract
+// for OPPO/OnePlus/realme devices via the OPPO Push (HeyTap) server API. Auth is
+// a two-step handshake: sign = SHA256(app_key + timestamp + master_secret) is
+// exchanged for a short-lived `auth_token` (valid ~24h), then a form POST to the
+// unicast endpoint carries that token. 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 } from "node:crypto";
+import { PushTokenUnregisteredError } from "./remote-session-push-errors.js";
+
+const DEFAULT_HOST = "https://api.push.oppomobile.com";
+const AUTH_PATH = "/server/v1/auth";
+const SEND_PATH = "/server/v1/message/notification/unicast";
+// OPPO auth_token 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 CODE_SUCCESS = 0;
+// OPPO has no single canonical "unregistered" code for a stale registration id;
+// match the message text it returns alongside the failing code.
+const INVALID_TOKEN_RE =
+  /invalid.*registration|registration.*invalid|invalid.*token|token.*invalid|unregist|not ?exist|无效|不存在/i;
+
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+function sha256Hex(input) {
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+/** Mints + caches an OPPO auth_token from app key + master secret. */
+export class OppoAuthProvider {
+  constructor(options = {}) {
+    if (!options.appKey) throw new Error("OppoAuthProvider requires an appKey");
+    if (!options.masterSecret) {
+      throw new Error("OppoAuthProvider requires a masterSecret");
+    }
+    this.appKey = options.appKey;
+    this.masterSecret = options.masterSecret;
+    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 = String(now);
+    const sign = sha256Hex(`${this.appKey}${timestamp}${this.masterSecret}`);
+    const body = new URLSearchParams({
+      app_key: this.appKey,
+      sign,
+      timestamp,
+    });
+    const res = await this.fetch(`${this.host}${AUTH_PATH}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `OPPO auth failed (${res.status}): ${await safeText(res)}`,
+      );
+    }
+    const json = await res.json();
+    const token = json?.data?.auth_token;
+    if (Number(json.code) !== CODE_SUCCESS || !token) {
+      throw new Error(
+        `OPPO auth response missing auth_token: ${json.message || json.code}`,
+      );
+    }
+    this._cached = { token, expiresAt: now + AUTH_TOKEN_TTL_MS };
+    return token;
+  }
+}
+
+/** Sends one notification to an OPPO registration id. */
+export class OppoPushSender {
+  constructor(options = {}) {
+    if (!options.authProvider) {
+      throw new Error("OppoPushSender requires an authProvider");
+    }
+    this.authProvider = options.authProvider;
+    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("OPPO send requires a registration id");
+    const authToken = await this.authProvider.getAuthToken();
+    // Routing ids only — no session content.
+    const data = { type: "remote-session.approval-request" };
+    if (sessionId != null) data.sessionId = String(sessionId);
+    if (clientId != null) data.clientId = String(clientId);
+    const message = {
+      target_type: 2, // 2 = single registration_id
+      target_value: token,
+      notification: {
+        title: notification?.title || "Approval requested",
+        content: notification?.body || "A coding session needs your approval",
+        click_action_type: 0, // open the app
+        action_parameters: JSON.stringify(data),
+      },
+    };
+    const body = new URLSearchParams({
+      auth_token: authToken,
+      message: JSON.stringify(message),
+    });
+    const res = await this.fetch(`${this.host}${SEND_PATH}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        auth_token: authToken,
+      },
+      body: body.toString(),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (res.ok && Number(json.code) === CODE_SUCCESS) {
+      return { id: json.data?.messageId || null };
+    }
+    const reason = json.message || `HTTP ${res.status}`;
+    if (INVALID_TOKEN_RE.test(String(reason))) {
+      throw new PushTokenUnregisteredError(
+        `OPPO registration id invalid: ${reason}`,
+      );
+    }
+    throw new Error(`OPPO push failed (${json.code ?? res.status}): ${reason}`);
+  }
+}
+
+/**
+ * Build a bound OPPO `sender` from env, or null when unconfigured.
+ *
+ * OPPO env:
+ *   CHAINLESSCHAIN_REMOTE_SESSION_OPPO_APP_KEY
+ *   CHAINLESSCHAIN_REMOTE_SESSION_OPPO_MASTER_SECRET
+ *   CHAINLESSCHAIN_REMOTE_SESSION_OPPO_HOST  (optional; override the API host)
+ */
+export function createOppoPushSender(env = {}, options = {}) {
+  const appKey =
+    options.appKey || env.CHAINLESSCHAIN_REMOTE_SESSION_OPPO_APP_KEY;
+  const masterSecret =
+    options.masterSecret ||
+    env.CHAINLESSCHAIN_REMOTE_SESSION_OPPO_MASTER_SECRET;
+  if (!appKey || !masterSecret) return null;
+  const host = options.host || env.CHAINLESSCHAIN_REMOTE_SESSION_OPPO_HOST;
+  let authProvider;
+  try {
+    authProvider =
+      options.authProvider ||
+      new OppoAuthProvider({ appKey, masterSecret, host, ...options });
+  } catch {
+    return null; // Malformed credentials — stay disabled rather than crash.
+  }
+  return new OppoPushSender({ authProvider, host, ...options }).handler;
+}

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

@@ -0,0 +1,42 @@
+// Remote Session vendor push — provider dispatch.
+//
+// Picks a concrete `sender` implementation by CHAINLESSCHAIN_REMOTE_SESSION_
+// PUSH_PROVIDER (default "fcm"). Each provider factory returns a bound sender
+// or null when unconfigured; unknown/unimplemented providers yield null so the
+// dispatcher stays a no-op. Adding a provider (HMS / Xiaomi / …) is one import
+// + one case here.
+
+import { createFcmPushSender } from "./remote-session-push-fcm.js";
+import { createApnsPushSender } from "./remote-session-push-apns.js";
+import { createWebPushSender } from "./remote-session-push-web.js";
+import { createXiaomiPushSender } from "./remote-session-push-xiaomi.js";
+import { createHuaweiPushSender } from "./remote-session-push-huawei.js";
+import { createOppoPushSender } from "./remote-session-push-oppo.js";
+import { createVivoPushSender } from "./remote-session-push-vivo.js";
+
+export function createRemoteSessionPushSender(env = {}, options = {}) {
+  const provider = (
+    env.CHAINLESSCHAIN_REMOTE_SESSION_PUSH_PROVIDER || "fcm"
+  ).toLowerCase();
+  switch (provider) {
+    case "fcm":
+      return createFcmPushSender(env, options);
+    case "apns":
+      return createApnsPushSender(env, options);
+    case "web":
+      return createWebPushSender(env, options);
+    case "xiaomi":
+    case "mi":
+      return createXiaomiPushSender(env, options);
+    case "huawei":
+    case "hms":
+      return createHuaweiPushSender(env, options);
+    case "oppo":
+    case "heytap":
+      return createOppoPushSender(env, options);
+    case "vivo":
+      return createVivoPushSender(env, options);
+    default:
+      return null;
+  }
+}

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;
+}