agentus 0.4.3 → 0.4.5

package/packages/server/src/notify/center.ts

@@ -17,6 +17,7 @@ import type { Duplex } from "node:stream";
 import { WebSocketServer, WebSocket } from "ws";
 import type { PermissionRequestView, PlanSnapshot, ServerEvent } from "../../../shared/src/index.js";
 import { DEFAULT_NOTIFY_RULES } from "./types.js";
+import { WebPushService } from "./webpush.js";
 import type {
   ActionCallback,
   ActivityObject,
@@ -98,6 +99,33 @@ function tapTarget(url: string, prefer: OpenTarget["prefer"] = "app"): Pick<Acti
   return { deeplink: url, open: { url, prefer: prefer ?? "auto" } };
 }
 
+/** The session a notice points at, from its `open` URL (`/?session=<id>`). */
+function sessionOfOpen(open: string | null | undefined): string | null {
+  if (!open) return null;
+  try {
+    return new URL(open, "http://local").searchParams.get("session");
+  } catch {
+    return null;
+  }
+}
+
+/** A subscription as the settings card may see it: the device, never the endpoint.
+ *  The endpoint is a long-lived capability URL (whoever holds it can post to that browser's push
+ *  service) — the card only needs to tell one device from another, so host + tail is enough. */
+function publicSub(rec: { endpoint: string; ua?: string; createdAt: number; lastOkAt?: number; fails: number; lastError?: string }) {
+  let host = "";
+  try { host = new URL(rec.endpoint).host; } catch { host = "?"; }
+  return {
+    host,
+    tail: rec.endpoint.slice(-6),
+    ua: rec.ua,
+    createdAt: rec.createdAt,
+    lastOkAt: rec.lastOkAt,
+    fails: rec.fails,
+    lastError: rec.lastError,
+  };
+}
+
 /** How a finished turn reads on a lock screen: 「用时 1m12s」.
  *
  *  The protocol's own answer (`stopReason: end_turn`) is a fact about the wire, not about the
@@ -166,6 +194,8 @@ export class NotifyCenter {
   private onActionCb: ((e: ActionEvent) => void) | null = null;
   /** The page channel's sink: index.ts fans this out to every cockpit websocket. */
   private onNoticeCb: ((n: WebNotice) => void) | null = null;
+  /** The third channel: the only one that reaches a LOCKED screen (see webpush.ts). */
+  private readonly push: WebPushService;
   private timers: NodeJS.Timeout[] = [];
   private wss: WebSocketServer | null = null;
   /** Which session the cockpit is showing, and whether its tab is visible. Deliberately in
@@ -278,6 +308,7 @@ export class NotifyCenter {
     this.sessionPlan = opts.sessionPlan ?? null;
     this.apkPath = opts.apkPath ?? null;
     this.onFocus = opts.onFocus ?? null;
+    this.push = new WebPushService(opts.dataDir, { log: (l) => this.log(l) });
     this.state = this.loadState();
     this.events = this.loadEvents();
   }
@@ -528,11 +559,56 @@ export class NotifyCenter {
     this.onNoticeCb = cb;
   }
 
-  /** Emit one page notice, gated on the web channel's own switches. */
+  /** Emit one page notice, gated on the web channel's own switches — and hand the same notice to the
+   *  push services, so 「关屏也能收」 needs no second decision path (and cannot drift from the page's). */
   private notice(n: Omit<WebNotice, "at">, rule: keyof Omit<NotifyWebRules, "enabled">): void {
     const web = this.rules().web;
     if (!web.enabled || !web[rule]) return;
+    this.emitNotice(n);
+  }
+
+  /** The page + push half of a notice, without any rule gate — for the two cleanups (「跑完了」撤掉
+   *  「运行中」卡、批准后撤掉批准卡) that must happen even when the rule that would have SENT the card
+   *  is off. Taking a dead card off the screen is not an interruption, which is why these two calls
+   *  skip the switches; the push side follows the same logic, or a locked phone would keep a card
+   *  advertising a decision that was already made. */
+  private emitNotice(n: Omit<WebNotice, "at">): void {
     this.onNoticeCb?.({ ...n, at: Date.now() });
+    this.pushNotice(n);
+  }
+
+  /** The push renderer of a notice. Narrower than the page channel on purpose:
+   *
+   *   · 「运行中」 never pushes. A lock-screen card saying "still running" is noise by definition, and
+   *     what was asked for is 完成 and 需要批准 — the two things that want a human.
+   *   · a notice about the session he is LOOKING AT never pushes. The page channel leaves presence to
+   *     the page (`document.hidden`); a push cannot see that, so the server judges here. A phone
+   *     buzzing about the window already on screen is pure interruption.
+   *   · a dismiss IS pushed: it takes the stale card off the lock screen (the worker closes the
+   *     notification by tag), which is the same unconditional cleanup the other two channels do.
+   *
+   *  Fire-and-forget: a push service being slow or dead must never delay the frame to the phone or the
+   *  page. Each send records its own outcome on the subscription (fails / lastError) for the UI to show. */
+  private pushNotice(n: Omit<WebNotice, "at">): void {
+    if (!this.push.subscriptions().length) return;
+    if (n.kind === "agent_running") return; // never pushed, so a dismiss for it has nothing to close
+    const sessionId = sessionOfOpen(n.open);
+    if (sessionId && this.watching(sessionId)) return;
+    const dismiss = n.op === "dismiss";
+    const payload = dismiss
+      ? { op: "dismiss", noticeId: n.noticeId }
+      : { op: "upsert", noticeId: n.noticeId, kind: n.kind, title: n.title, body: n.body, open: n.open, sticky: Boolean(n.sticky) };
+    // 审批卡要活到有人动手：TTL 一天，urgency high（叫醒设备）。完成/出错一小时就够。
+    const approval = n.kind === "approval";
+    void this.push
+      .broadcast(payload, dismiss
+        ? { urgency: "very-low", ttlSec: 300 }
+        : { urgency: approval ? "high" : "normal", ttlSec: approval ? 86_400 : 3_600 })
+      .then((results) => {
+        const bad = results.filter((r) => !r.ok);
+        if (bad.length) this.log(`[notify] web push: ${bad.length}/${results.length} 未送达（${bad[0]?.error ?? ""}）`);
+      })
+      .catch((e: Error) => this.log(`[notify] web push threw: ${e.message}`));
   }
 
   // ---- actions -------------------------------------------------------------
@@ -609,6 +685,54 @@ export class NotifyCenter {
       }) && true;
     }
 
+    // ---- 网页推送（关屏也能收）-----------------------------------------------------
+    // The public key has to reach the browser to subscribe; the SUBSCRIPTION LIST must not — it says
+    // how many devices listen to this cockpit. So the whole group sits behind the operator gate, the
+    // same reason the APK and the root certificate do.
+    if (p === "/api/notify/webpush" || p.startsWith("/api/notify/webpush/")) {
+      if (!isOperator()) return json(401, { error: "operator auth required" }) && true;
+      const subs = () => this.push.subscriptions().map(publicSub);
+
+      if (p === "/api/notify/webpush" && req.method === "GET") {
+        return json(200, { ok: true, publicKey: this.push.publicKey(), subs: subs() }) && true;
+      }
+
+      if (p === "/api/notify/webpush/subscribe" && req.method === "POST") {
+        const body = await readBody();
+        const rec = this.push.subscribe({
+          endpoint: body.endpoint,
+          keys: (body.keys ?? {}) as { p256dh?: unknown; auth?: unknown },
+          ua: body.ua,
+        });
+        if ("error" in rec) return json(400, { error: rec.error }) && true;
+        this.log(`[notify] 网页推送已订阅：${new URL(rec.endpoint).host}（共 ${this.push.subscriptions().length} 台）`);
+        return json(200, { ok: true, subs: subs() }) && true;
+      }
+
+      if (p === "/api/notify/webpush/unsubscribe" && req.method === "POST") {
+        const body = await readBody();
+        const removed = this.push.unsubscribe(String(body.endpoint ?? ""));
+        return json(200, { ok: true, removed, subs: subs() }) && true;
+      }
+
+      // The test button: proves the WHOLE chain (our VAPID key → push service → service worker →
+      // lock screen). A test that only logged to the server would prove none of it.
+      if (p === "/api/notify/webpush/test" && req.method === "POST") {
+        if (!this.push.subscriptions().length) return json(400, { error: "这台服务器还没有任何浏览器订阅" }) && true;
+        const results = await this.push.broadcast({
+          op: "upsert", noticeId: "test:webpush", kind: "agent_done", sticky: false,
+          title: "推送测试", body: "锁屏上能看到这条，就说明关屏也能收", open: "/",
+        }, { urgency: "high", ttlSec: 300 });
+        return json(200, {
+          ok: results.every((r) => r.ok),
+          results: results.map((r) => ({ ok: r.ok, status: r.status, error: r.error, gone: r.gone })),
+          subs: subs(),
+        }) && true;
+      }
+
+      return json(404, { error: "unknown webpush route" }) && true;
+    }
+
     if (p === "/api/notify/presence" && req.method === "POST") {
       // The cockpit telling us what it is showing. Operator-authenticated (the SPA has the
       // cookie); a missing report just means presence goes stale and quiet-when-watching stops
@@ -1037,17 +1161,13 @@ export class NotifyCenter {
         // taking a dead card off the screen is not an interruption, and gating it on a preference
         // would leave a card nobody can answer.
         this.dismiss(`perm:${evt.requestId}`);
-        this.onNoticeCb?.({
-          op: "dismiss", noticeId: `perm:${evt.requestId}`, kind: "approval", title: "", body: "", at: Date.now(),
-        });
+        this.emitNotice({ op: "dismiss", noticeId: `perm:${evt.requestId}`, kind: "approval", title: "", body: "" });
         return;
       case "turn-end": {
         // The running card goes away unconditionally — a zombie "still running" on the phone is worse
         // than no card at all, even when the frame that started it was suppressed.
         this.dismiss(`turn:${evt.sessionId}`);
-        this.onNoticeCb?.({
-          op: "dismiss", noticeId: `turn:${evt.sessionId}`, kind: "agent_running", title: "", body: "", at: Date.now(),
-        });
+        this.emitNotice({ op: "dismiss", noticeId: `turn:${evt.sessionId}`, kind: "agent_running", title: "", body: "" });
         // Both gates belong here and both were missing: `completion` was stored but never read, and
         // presence was only consulted for turn-start — so the completion card fired while the operator was watching
         // the very session (and, mid-call, with a sound: the reported bug).

package/packages/server/src/notify/webpush.ts

@@ -0,0 +1,295 @@
+// Web Push — the third renderer of the same notification decision.
+//
+// The three channels and why they exist:
+//
+//   phone (WS)   — the Android companion holds one long connection; only works while the phone is awake.
+//   page         — the open tab draws a notification through the page's own Notification API.
+//   push (here)  — the ONLY channel that survives a locked screen: the page is frozen by iOS/Android
+//                  the moment it leaves the foreground, and no JS runs to notice anything. A push
+//                  service holds the message until the device is reachable, wakes the service worker,
+//                  and the worker draws the card. That is why this exists and the page renderer cannot
+//                  replace it.
+//
+// Nothing here decides WHAT is worth notifying — `center.ts` owns that (one decision, three renderers).
+// This module only knows how to hand bytes to a push service: encryption (RFC 8291 / aes128gcm) and
+// VAPID authorization (RFC 8292).
+//
+// No dependency on `web-push`: the whole job is ~120 lines of node:crypto, and a dependency here would
+// mean an npm install on a machine whose registry access is already the flakiest part of a release.
+// The RFC's own test vector is checked by `scripts/qa/webpush-crypto.mts` — see the note at encryptPush().
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+
+/** One browser's subscription, as `pushManager.subscribe()` returned it. */
+export interface PushSubscriptionRecord {
+  endpoint: string;
+  /** base64url of the UA's uncompressed P-256 point (65 bytes) — the `keys.p256dh` the browser gave us. */
+  p256dh: string;
+  /** base64url of the 16-byte auth secret — `keys.auth`. */
+  auth: string;
+  ua?: string;
+  createdAt: number;
+  /** Last time a push was accepted by the push service (HTTP 201). */
+  lastOkAt?: number;
+  fails: number;
+  lastError?: string;
+}
+
+interface VapidFile {
+  /** base64url uncompressed point (65 bytes) — what the browser needs as applicationServerKey. */
+  publicKey: string;
+  /** The private half, kept as a JWK because that is what createPrivateKey() eats. */
+  jwk: { kty: string; crv: string; x: string; y: string; d: string };
+  subject: string;
+}
+
+interface SubscriptionFile {
+  subs: PushSubscriptionRecord[];
+}
+
+// ---- base64url ----------------------------------------------------------------
+
+export const b64u = (buf: Buffer): string => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+export const unb64u = (str: string): Buffer => Buffer.from(str.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+
+// ---- RFC 8291: encrypting one push message ------------------------------------
+
+/** The message body a push service carries for us: `aes128gcm` single record (RFC 8188 §2, RFC 8291 §4).
+ *
+ *  Layout of the body: 16-byte salt ‖ rs (u32 BE = 4096) ‖ idlen (u8 = 65) ‖ AS public key ‖ ciphertext.
+ *  The plaintext gets the padding delimiter 0x02 appended, because it is the last (only) record.
+ *
+ *  `opts` exists ONLY so the RFC 8291 §5 test vector can be reproduced byte-for-byte: it pins the salt
+ *  and the application-server keypair. Production calls always pass no salt and a fresh keypair — the
+ *  whole security property rests on both being random per message.
+ *
+ *  Verified against that vector (Appendix A gives every intermediate: ecdh_secret, PRK_key, IKM, PRK,
+ *  CEK, NONCE, and the final body). If this function and the vector disagree, the push is silently
+ *  undecryptable by the browser and nothing else in the system would tell us — hence a test, not hope. */
+export function encryptPush(
+  uaPublicRaw: Buffer,
+  authSecret: Buffer,
+  plaintext: Buffer,
+  opts: { salt?: Buffer; asKeys?: crypto.KeyObject[] } = {},
+): Buffer {
+  const salt = opts.salt ?? crypto.randomBytes(16);
+  const pair = opts.asKeys ?? (() => {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+    return [privateKey, publicKey];
+  })();
+  const [asPrivate, asPublic] = pair;
+
+  const uaPublic = crypto.createPublicKey({
+    key: { kty: "EC", crv: "P-256", x: b64u(uaPublicRaw.subarray(1, 33)), y: b64u(uaPublicRaw.subarray(33, 65)) },
+    format: "jwk",
+  });
+  const ecdhSecret = crypto.diffieHellman({ privateKey: asPrivate, publicKey: uaPublic });
+  const asPoint = pointFromJwk(asPublic.export({ format: "jwk" }) as { x: string; y: string });
+
+  // IKM = HKDF-Extract(auth_secret, ecdh_secret) then Expand with "WebPush: info\0" ‖ ua ‖ as.
+  const keyInfo = Buffer.concat([Buffer.from("WebPush: info\0", "utf8"), uaPublicRaw, asPoint]);
+  const ikm = Buffer.from(crypto.hkdfSync("sha256", ecdhSecret, authSecret, keyInfo, 32));
+
+  // CEK/NONCE come from RFC 8188's HKDF with the per-message salt.
+  const cek = Buffer.from(crypto.hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: aes128gcm\0", "utf8"), 16));
+  const nonce = Buffer.from(crypto.hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: nonce\0", "utf8"), 12));
+
+  const record = Buffer.concat([plaintext, Buffer.from([0x02])]);
+  const cipher = crypto.createCipheriv("aes-128-gcm", cek, nonce);
+  const ct = Buffer.concat([cipher.update(record), cipher.final(), cipher.getAuthTag()]);
+
+  const rs = Buffer.alloc(4);
+  rs.writeUInt32BE(4096, 0);
+  return Buffer.concat([salt, rs, Buffer.from([asPoint.length]), asPoint, ct]);
+}
+
+function pointFromJwk(jwk: { x: string; y: string }): Buffer {
+  return Buffer.concat([Buffer.from([0x04]), unb64u(jwk.x), unb64u(jwk.y)]);
+}
+
+// ---- VAPID + delivery ---------------------------------------------------------
+
+export interface SendResult { ok: boolean; status: number; error?: string; gone?: boolean }
+
+export class WebPushService {
+  private readonly dir: string;
+  private readonly subject: string;
+  private readonly log: (line: string) => void;
+  private vapidCache: VapidFile | null = null;
+  private subsCache: PushSubscriptionRecord[] | null = null;
+
+  constructor(dataDir: string, opts: { subject?: string; log?: (line: string) => void } = {}) {
+    this.dir = path.join(dataDir, "notify");
+    this.subject = opts.subject ?? process.env.AGENTUS_VAPID_SUBJECT ?? "mailto:agentus@localhost";
+    this.log = opts.log ?? ((l) => console.log(l));
+  }
+
+  private get vapidFile(): string { return path.join(this.dir, "vapid.json"); }
+  private get subsFile(): string { return path.join(this.dir, "webpush.json"); }
+
+  /** The server's identity to push services. Generated on first use and then never rotated by itself:
+   *  rotating the VAPID key invalidates every existing subscription, so that must stay a deliberate act. */
+  private vapid(): VapidFile {
+    if (this.vapidCache) return this.vapidCache;
+    try {
+      this.vapidCache = JSON.parse(fs.readFileSync(this.vapidFile, "utf8")) as VapidFile;
+      return this.vapidCache;
+    } catch { /* first boot */ }
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+    const jwk = privateKey.export({ format: "jwk" }) as VapidFile["jwk"];
+    const record: VapidFile = { publicKey: b64u(pointFromJwk(jwk)), jwk, subject: this.subject };
+    fs.mkdirSync(this.dir, { recursive: true });
+    fs.writeFileSync(this.vapidFile, JSON.stringify(record, null, 1), { mode: 0o600 });
+    this.log(`[notify] generated a VAPID keypair (${this.vapidFile}) — back it up with the rest of <data>`);
+    this.vapidCache = record;
+    return record;
+  }
+
+  /** `applicationServerKey` for `pushManager.subscribe()`. */
+  publicKey(): string { return this.vapid().publicKey; }
+
+  subscriptions(): PushSubscriptionRecord[] {
+    if (this.subsCache) return this.subsCache;
+    try {
+      const raw = JSON.parse(fs.readFileSync(this.subsFile, "utf8")) as SubscriptionFile;
+      this.subsCache = Array.isArray(raw.subs) ? raw.subs : [];
+    } catch {
+      this.subsCache = [];
+    }
+    return this.subsCache;
+  }
+
+  private save(): void {
+    fs.mkdirSync(this.dir, { recursive: true });
+    fs.writeFileSync(this.subsFile, JSON.stringify({ subs: this.subsCache ?? [] }, null, 1), { mode: 0o600 });
+  }
+
+  /** Idempotent by endpoint: re-subscribing the same browser replaces its keys instead of piling up rows.
+   *  A browser re-subscribes on every page load in some engines, so this must not grow. */
+  subscribe(input: { endpoint?: unknown; keys?: { p256dh?: unknown; auth?: unknown }; ua?: unknown }): PushSubscriptionRecord | { error: string } {
+    const endpoint = typeof input.endpoint === "string" ? input.endpoint : "";
+    const p256dh = typeof input.keys?.p256dh === "string" ? input.keys.p256dh : "";
+    const auth = typeof input.keys?.auth === "string" ? input.keys.auth : "";
+    if (!/^https?:\/\//.test(endpoint)) return { error: "endpoint must be an https URL from the browser" };
+    if (unb64u(p256dh).length !== 65) return { error: "keys.p256dh must be an uncompressed P-256 point (65 bytes)" };
+    if (unb64u(auth).length !== 16) return { error: "keys.auth must be 16 bytes" };
+    const subs = this.subscriptions();
+    const prior = subs.find((s) => s.endpoint === endpoint);
+    const rec: PushSubscriptionRecord = {
+      endpoint, p256dh, auth,
+      ua: typeof input.ua === "string" ? input.ua.slice(0, 200) : undefined,
+      createdAt: prior?.createdAt ?? Date.now(),
+      lastOkAt: prior?.lastOkAt,
+      fails: 0,
+    };
+    this.subsCache = [...subs.filter((s) => s.endpoint !== endpoint), rec];
+    this.save();
+    return rec;
+  }
+
+  unsubscribe(endpoint: string): boolean {
+    const subs = this.subscriptions();
+    const next = subs.filter((s) => s.endpoint !== endpoint);
+    if (next.length === subs.length) return false;
+    this.subsCache = next;
+    this.save();
+    return true;
+  }
+
+  /** ES256 JWT over the endpoint's own origin (RFC 8292 §2). `aud` is per-endpoint on purpose: a token
+   *  minted for one push service must not be replayable at another. */
+  private vapidAuth(endpoint: string, now = Date.now()): string {
+    const { publicKey, jwk } = this.vapid();
+    const header = b64u(Buffer.from(JSON.stringify({ typ: "JWT", alg: "ES256" })));
+    const claims = b64u(Buffer.from(JSON.stringify({
+      aud: new URL(endpoint).origin,
+      exp: Math.floor(now / 1000) + 12 * 3600,
+      sub: this.subject,
+    })));
+    const signingInput = `${header}.${claims}`;
+    const key = crypto.createPrivateKey({ key: jwk, format: "jwk" });
+    // ieee-p1363 = raw R‖S; JWS wants exactly that, DER would be rejected.
+    const sig = crypto.sign("sha256", Buffer.from(signingInput), { key, dsaEncoding: "ieee-p1363" });
+    return `vapid t=${signingInput}.${b64u(sig)}, k=${publicKey}`;
+  }
+
+  /** Hand one message to one push service. `urgency` maps to the RFC 8030 header the platforms honour:
+   *  a lock-screen approval is `high` (deliver immediately, wake the device), a "finished" is `normal`,
+   *  and taking a stale card back is `very-low` (do not wake anything for it). */
+  async send(
+    rec: PushSubscriptionRecord,
+    payload: unknown,
+    opts: { ttlSec?: number; urgency?: "very-low" | "low" | "normal" | "high"; timeoutMs?: number } = {},
+  ): Promise<SendResult> {
+    let body: Buffer;
+    try {
+      body = encryptPush(unb64u(rec.p256dh), unb64u(rec.auth), Buffer.from(JSON.stringify(payload), "utf8"));
+    } catch (e) {
+      return { ok: false, status: 0, error: `encrypt: ${(e as Error).message}` };
+    }
+    let auth: string;
+    try {
+      auth = this.vapidAuth(rec.endpoint);
+    } catch (e) {
+      return { ok: false, status: 0, error: `vapid: ${(e as Error).message}` };
+    }
+    const url = new URL(rec.endpoint);
+    const mod = url.protocol === "http:" ? http : https;
+    return await new Promise<SendResult>((resolve) => {
+      const req = mod.request({
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "http:" ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: "POST",
+        headers: {
+          authorization: auth,
+          "content-encoding": "aes128gcm",
+          "content-type": "application/octet-stream",
+          "content-length": String(body.length),
+          ttl: String(opts.ttlSec ?? 3600),
+          urgency: opts.urgency ?? "normal",
+        },
+        timeout: opts.timeoutMs ?? 8000,
+      }, (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (c) => chunks.push(Buffer.from(c)));
+        res.on("end", () => {
+          const status = res.statusCode ?? 0;
+          const ok = status >= 200 && status < 300;
+          const text = Buffer.concat(chunks).toString("utf8").slice(0, 300);
+          const gone = status === 404 || status === 410;
+          if (ok) {
+            rec.lastOkAt = Date.now();
+            rec.fails = 0;
+            rec.lastError = undefined;
+            this.save();
+          } else {
+            rec.fails += 1;
+            rec.lastError = `${status} ${text}`.trim();
+            // 404/410 = the browser threw the subscription away (app uninstalled, permission reset).
+            // Keeping it would retry a dead endpoint forever and log a failure on every notification.
+            if (gone) this.unsubscribe(rec.endpoint);
+            else this.save();
+          }
+          resolve({ ok, status, error: ok ? undefined : `${status} ${text}`.trim(), gone });
+        });
+      });
+      req.on("timeout", () => { req.destroy(new Error("push service timed out")); });
+      req.on("error", (e) => resolve({ ok: false, status: 0, error: e.message }));
+      req.end(body);
+    });
+  }
+
+  /** Send the same payload to every subscription. Returns one result per device so the settings card can
+   *  say "2 台设备都收到了" or which one is dead — a silent broadcast would hide a broken device. */
+  async broadcast(payload: unknown, opts: { ttlSec?: number; urgency?: "very-low" | "low" | "normal" | "high" } = {}): Promise<SendResult[]> {
+    const subs = this.subscriptions();
+    if (!subs.length) return [];
+    return await Promise.all(subs.map((s) => this.send(s, payload, opts)));
+  }
+}