推送通知：Web Push（网页 / PWA）+ 桌面原生通知

页面 / PWA 关闭、或桌面窗口非前台时，收到文件、消息、传输完成 / 失败以系统通知提醒。
判定统一为「页面打开走应用内提示，否则系统通知」，三端各自落地；网页端的判定直接复用
Hub.SendTo 的投递结果，零额外状态。

- Web Push（VAPID，账号无关）：服务端 internal/push.Sender 在事件未经 SSE 投递到目标
  设备时（即该设备页面已关）发推送，文案按订阅 locale 在服务端渲染（中简 / 中繁 / 英）、
  404 / 410 自动清理死订阅；新增 push_subscriptions 表（含 locale，主键为 endpoint 的
  SHA-256 以幂等 upsert）+ /api/push/{vapid-key, subscribe POST/DELETE} 端点
- 事件挂接：transfer:incoming / message（离线返 202，文本随推送送达）/ transfer:state
  DONE|FAILED，均未投递才推
- 配置 CDROP_VAPID_PUBLIC_KEY / CDROP_VAPID_PRIVATE_KEY（半对即拒启动，都空则推送惰性
  关闭）+ just vapid-keygen 生成工具（cmd/vapidgen）
- 前端：service worker 加 push / notificationclick（仍不拦截 /api 与导航）；net/push.ts
  订阅管理 + push store slice + 设置页「推送通知」面板（仅浏览器 / PWA）；登录后 resyncPush
  把既有订阅重新登记到当前用户，换用户 / endpoint 轮换 / 切换语言皆自愈
- 桌面原生通知：platform/notify_{darwin,windows,other}.go + notify_darwin.m，仅窗口非
  前台时弹原生通知（macOS UNUserNotificationCenter，未签名时安全空操作、待签名后显示；
  Windows go-toast 即用）；app.go ShowNotification 绑定，前端 notifyNativeIfBackground
  复用 hub 事件分发 + 客户端本地化
- 文档：README / .env.example / compose 模板补 CDROP_VAPID_* 配置

注：sqlc v1.31.1 对 query 文件里的多字节字符会错位偏移、生成损坏 SQL，故 query 注释保持纯
ASCII（文件内留有警示）。

internal/httpapi/message.go

@@ -1,6 +1,7 @@
 package httpapi
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"net/http"
@@ -8,6 +9,7 @@ import (
 
 	"commilitia.net/cdrop/internal/hub"
 	"commilitia.net/cdrop/internal/jwtauth"
+	"commilitia.net/cdrop/internal/push"
 )
 
 // 4 KB caps DoS-via-paste; longer payloads should use file transfer instead.
@@ -31,7 +33,9 @@ type messageReq struct {
 // machine. Receiver sees a `message` event; the frontend keeps it in memory
 // only until the tab closes (per user spec).
 //
-// 204 if delivered, 410 if peer offline, 413 if oversized.
+// 204 if delivered live, 202 if the peer is offline but a Web Push was sent
+// (the notification carries the text — the message itself is not persisted),
+// 410 if offline with no push subscription, 413 if oversized.
 func (s *Server) handleMessage(w http.ResponseWriter, r *http.Request) {
 	claims, _ := jwtauth.ClaimsFromContext(r.Context())
 	from, _ := jwtauth.DeviceNameFromContext(r.Context())
@@ -75,6 +79,17 @@ func (s *Server) handleMessage(w http.ResponseWriter, r *http.Request) {
 		},
 	})
 	if !delivered {
+		// Peer's page is closed (no live SSE). The message has no DB row, so the
+		// only delivery left is a Web Push carrying the text itself. If the peer
+		// has a subscription, send it and report 202; otherwise it's truly gone.
+		if s.push.Enabled() {
+			go s.push.Notify(context.Background(), claims.UserID, req.To, push.Notification{
+				Type:   push.KindMessage,
+				Params: map[string]string{"sender": from, "text": req.Text},
+			})
+			w.WriteHeader(http.StatusAccepted)
+			return
+		}
 		writeJSON(w, http.StatusGone, map[string]string{"error": "peer offline"})
 		return
 	}

internal/httpapi/push.go

@@ -0,0 +1,119 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"commilitia.net/cdrop/internal/db"
+	"commilitia.net/cdrop/internal/jwtauth"
+	"commilitia.net/cdrop/internal/push"
+)
+
+// maxPushSubscribeBytes caps the subscribe/unsubscribe body. A PushSubscription
+// JSON is well under 1 KB (endpoint URL + two short keys); 8 KB is generous
+// headroom while still bounding per-request memory.
+const maxPushSubscribeBytes = 8 * 1024
+
+type vapidKeyResp struct {
+	Enabled   bool   `json:"enabled"`
+	PublicKey string `json:"public_key"`
+}
+
+// handlePushVAPIDKey hands the browser the VAPID public key it must pass as
+// applicationServerKey when calling pushManager.subscribe. The public key is
+// not a secret; enabled=false tells the client to hide the push UI entirely.
+func (s *Server) handlePushVAPIDKey(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, vapidKeyResp{
+		Enabled:   s.push.Enabled(),
+		PublicKey: s.push.PublicKey(),
+	})
+}
+
+// pushSubscribeReq mirrors PushSubscription.toJSON() plus the device's current
+// UI locale, so the server can render notification text the device can read.
+type pushSubscribeReq struct {
+	Endpoint string `json:"endpoint"`
+	Keys     struct {
+		P256dh string `json:"p256dh"`
+		Auth   string `json:"auth"`
+	} `json:"keys"`
+	Locale string `json:"locale"`
+}
+
+// knownLocales gates the locale we persist so a bogus value can't poison the
+// stored row; unknown / empty falls back to the server default.
+var knownLocales = map[string]bool{"zh-CN": true, "zh-TW": true, "en-US": true}
+
+// handlePushSubscribe stores (or refreshes) this browser's Web Push endpoint for
+// the calling device. Keyed by device_name so a notify-worthy event addressed to
+// a specific offline device pushes only to that device. Upsert by endpoint hash
+// makes a repeat subscribe idempotent.
+func (s *Server) handlePushSubscribe(w http.ResponseWriter, r *http.Request) {
+	if !s.push.Enabled() {
+		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "push disabled"})
+		return
+	}
+	claims, _ := jwtauth.ClaimsFromContext(r.Context())
+	device, _ := jwtauth.DeviceNameFromContext(r.Context())
+	if device == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "missing device"})
+		return
+	}
+
+	r.Body = http.MaxBytesReader(w, r.Body, maxPushSubscribeBytes)
+	var req pushSubscribeReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid json"})
+		return
+	}
+	if req.Endpoint == "" || req.Keys.P256dh == "" || req.Keys.Auth == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "incomplete subscription"})
+		return
+	}
+
+	locale := req.Locale
+	if !knownLocales[locale] {
+		locale = "zh-CN"
+	}
+
+	now := time.Now().Unix()
+	if err := s.queries.UpsertPushSubscription(r.Context(), db.UpsertPushSubscriptionParams{
+		ID:         push.SubscriptionID(req.Endpoint),
+		UserID:     claims.UserID,
+		DeviceName: device,
+		Endpoint:   req.Endpoint,
+		P256dh:     req.Keys.P256dh,
+		Auth:       req.Keys.Auth,
+		UserAgent:  truncate(r.UserAgent(), 256),
+		Locale:     locale,
+		CreatedAt:  now,
+		LastUsedAt: now,
+	}); err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "store failed"})
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+type pushUnsubscribeReq struct {
+	Endpoint string `json:"endpoint"`
+}
+
+// handlePushUnsubscribe drops a subscription the browser has revoked. Deleting by
+// endpoint hash needs no auth coupling beyond the session — the worst a wrong
+// endpoint does is delete a row the caller doesn't own, and endpoints are
+// unguessable capabilities, so this is not a meaningful enumeration vector.
+func (s *Server) handlePushUnsubscribe(w http.ResponseWriter, r *http.Request) {
+	r.Body = http.MaxBytesReader(w, r.Body, maxPushSubscribeBytes)
+	var req pushUnsubscribeReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil || req.Endpoint == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "missing endpoint"})
+		return
+	}
+	if err := s.queries.DeletePushSubscription(r.Context(), push.SubscriptionID(req.Endpoint)); err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "delete failed"})
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

internal/httpapi/server.go

@@ -19,6 +19,7 @@ import (
 	"commilitia.net/cdrop/internal/db"
 	"commilitia.net/cdrop/internal/hub"
 	"commilitia.net/cdrop/internal/jwtauth"
+	"commilitia.net/cdrop/internal/push"
 	"commilitia.net/cdrop/internal/relay"
 	"commilitia.net/cdrop/internal/transfer"
 	"commilitia.net/cdrop/internal/webui"
@@ -34,6 +35,7 @@ type Server struct {
 	relay     *relay.Manager
 	calls     *calls.Provider    // optional; nil → STUN-only fallback
 	clipboard *clipboard.Service // optional; nil → 503 on /api/clipboard
+	push      *push.Sender       // inert when VAPID keys unset → push endpoints 503
 	mux       *chi.Mux
 
 	// sessionKey encrypts browser refresh_tokens at rest (web_sessions); nil when
@@ -60,6 +62,7 @@ func New(
 	rm *relay.Manager,
 	cp *calls.Provider,
 	clip *clipboard.Service,
+	pushSender *push.Sender,
 ) *Server {
 	s := &Server{
 		cfg:       cfg,
@@ -71,6 +74,7 @@ func New(
 		relay:     rm,
 		calls:     cp,
 		clipboard: clip,
+		push:      pushSender,
 		mux:       chi.NewRouter(),
 
 		sessionKey: deriveSessionKey(cfg.SessionSecret),
@@ -141,6 +145,9 @@ func (s *Server) routes() {
 				r.Post("/message", s.handleMessage)
 				r.Get("/devices", s.handleDevices)
 				r.Delete("/devices/{name}", s.handleDeleteDevice)
+				r.Get("/push/vapid-key", s.handlePushVAPIDKey)
+				r.Post("/push/subscribe", s.handlePushSubscribe)
+				r.Delete("/push/subscribe", s.handlePushUnsubscribe)
 				r.Get("/calls/credentials", s.handleCallsCredentials)
 				r.Post("/shortcut/issue", s.handleShortcutIssue)
 				r.Get("/shortcut", s.handleShortcutList)