iOS 计划完成：流式发送 / 后台续传 / APNs / Share Extension / 控制中心控件 + 真机分发预备

- 发送端流式（R-iOS-4）：新增 FileSource 抽象（web/src/features/transfer/source.ts），iOS 经 HTTP Range 惰性拉取（原生 WKURLSchemeHandler 认 Range 头 seek 回 206），整文件不进 WebView 内存；web/桌面经 fileSource 包装字节不变。p2p/relay/transfer 改吃 FileSource
- 后台续传：iOS 26 BGContinuedProcessingTask（BackgroundTaskManager + AppDelegate 注册 + BGTaskSchedulerPermittedIdentifiers），引擎传输进度驱动系统进度 UI
- APNs：后端 internal/apns（ES256 .p8 JWT + HTTP/2，仿 internal/push）+ push_subscriptions.platform 列 + POST /api/push/apns/register + transfer/message 未投递分支分流；原生 PushRegistry 授权 + 设备令牌经引擎桥 registerPush 上报；aps-environment + remote-notification 后台模式
- Share Extension：CDropShare appex 抓文件 → App Group 收件箱 → cdrop://share 深链唤主程序选设备发送（只交接、不跑引擎）
- 控制中心剪贴板两控件：CDropWidgets widgetkit appex（ControlWidget + AppIntent + 纯原生 ClipboardClient REST）；用专用 broker 设备会话（主程序经引擎 provisionWidgetSession 代铸独立 device_id 会话存 App Group，控件自刷不与引擎抢 refresh 轮换）
- 真机分发预备：committed 签名改 ad-hoc 使模拟器 entitlement 生效；真机手动签名 scaffold（Signing.xcconfig 仅 device SDK 套 Manual + gitignore 的 Local.xcconfig 填 Team/profile）+ just ios-device / ios-devices 全 CLI 装机；包名改 net.commilitia.Commilitia-Drop（含 .share/.widgets，BG task 前缀同改）；REALDEVICE.md 重写为门户 + CLI 装机手册
- I18n.swift 移 Shared/ 供三 target 共用；i18n 加 ios.bg/share/control.* 键
- ultracode 多 agent 审查修复（0 HIGH，2 MED + 7 LOW）：分享 send 后留收件箱致重发→move 私有暂存；WidgetSession 锁屏文件保护→UntilFirstUserAuthentication；outgoing/安全作用域登出释放；控件 device_id 登出清理；并发控件 refresh CAS-before-clear；APNs 读 reason + prune bad token + bust 过期 JWT；APNSEnv 大小写归一；Share-ext completeRequest 挪进 open 回调

internal/httpapi/message.go

@@ -80,13 +80,20 @@ 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},
-			})
+		// only delivery left is a push notification (Web Push or APNs) carrying
+		// the text itself. If any push channel is enabled and may have a
+		// subscription, send and report 202; otherwise the message is truly gone.
+		n := push.Notification{
+			Type:   push.KindMessage,
+			Params: map[string]string{"sender": from, "text": req.Text},
+		}
+		if s.push.Enabled() || s.apns.Enabled() {
+			if s.push.Enabled() {
+				go s.push.Notify(context.Background(), claims.UserID, req.To, n)
+			}
+			if s.apns.Enabled() {
+				go s.apns.Notify(context.Background(), claims.UserID, req.To, n)
+			}
 			w.WriteHeader(http.StatusAccepted)
 			return
 		}

internal/httpapi/push.go

@@ -10,6 +10,10 @@ import (
 	"commilitia.net/cdrop/internal/push"
 )
 
+// maxAPNsRegisterBytes caps the register body. A device token is 64 hex chars
+// plus the locale field; 1 KB is generous headroom.
+const maxAPNsRegisterBytes = 1024
+
 // 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.
@@ -96,6 +100,62 @@ func (s *Server) handlePushSubscribe(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// apnsRegisterReq is the body for POST /api/push/apns/register.
+// DeviceToken is the hex-encoded APNs device token the iOS app received from
+// the system. Locale is optional; unknown or empty falls back to the server default.
+type apnsRegisterReq struct {
+	DeviceToken string `json:"device_token"`
+	Locale      string `json:"locale"`
+}
+
+// handleAPNsRegister stores (or refreshes) an iOS device's APNs token for the
+// calling session's device. Idempotent: re-registering the same token upserts
+// in place (SHA-256 of the token is the primary key). Returns 204 on success or
+// 503 when APNs is not configured.
+func (s *Server) handleAPNsRegister(w http.ResponseWriter, r *http.Request) {
+	if !s.apns.Enabled() {
+		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "apns 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, maxAPNsRegisterBytes)
+	var req apnsRegisterReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid json"})
+		return
+	}
+	if req.DeviceToken == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "missing device_token"})
+		return
+	}
+
+	locale := req.Locale
+	if !knownLocales[locale] {
+		locale = "zh-CN"
+	}
+
+	now := time.Now().Unix()
+	if err := s.queries.UpsertAPNsSubscription(r.Context(), db.UpsertAPNsSubscriptionParams{
+		ID:         push.SubscriptionID(req.DeviceToken),
+		UserID:     claims.UserID,
+		DeviceName: device,
+		Endpoint:   req.DeviceToken,
+		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"`
 }

internal/httpapi/push_test.go

@@ -0,0 +1,212 @@
+package httpapi
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/x509"
+	"encoding/json"
+	"encoding/pem"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"commilitia.net/cdrop/internal/apns"
+	"commilitia.net/cdrop/internal/db"
+	"commilitia.net/cdrop/internal/hub"
+	"commilitia.net/cdrop/internal/jwtauth"
+	"commilitia.net/cdrop/internal/push"
+)
+
+// apnsTestKeyPEM generates an ephemeral P-256 key and returns its PEM bytes so
+// tests can build an enabled apns.Sender without real Apple credentials.
+func apnsTestKeyPEM(t *testing.T) []byte {
+	t.Helper()
+	priv, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	der, err := x509.MarshalPKCS8PrivateKey(priv)
+	if err != nil {
+		t.Fatalf("marshal pkcs8: %v", err)
+	}
+	return pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: der})
+}
+
+// newAPNsTestServer builds a minimal Server with a real in-memory SQLite DB
+// and an enabled apns.Sender (using an ephemeral test key). The apns.Sender
+// base is left at the default; the endpoint test only exercises DB writes, so
+// the Sender never fires a real APNs request.
+func newAPNsTestServer(t *testing.T) *Server {
+	t.Helper()
+	conn, err := db.Open(filepath.Join(t.TempDir(), "push_test.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { _ = conn.Close() })
+	if err := db.Bootstrap(context.Background(), conn); err != nil {
+		t.Fatalf("bootstrap: %v", err)
+	}
+	q := db.New(conn)
+	apnsSender := apns.NewSender(q, apnsTestKeyPEM(t), "TESTKID", "TESTTEAM", "com.example.cdrop", "sandbox")
+	if !apnsSender.Enabled() {
+		t.Fatal("apns sender must be enabled for this test")
+	}
+	return &Server{
+		queries: q,
+		hub:     hub.New(q),
+		apns:    apnsSender,
+	}
+}
+
+// TestHandleAPNsRegister_DisabledReturns503 verifies that the register endpoint
+// returns 503 when APNs is not configured (inert Sender).
+func TestHandleAPNsRegister_DisabledReturns503(t *testing.T) {
+	conn, err := db.Open(filepath.Join(t.TempDir(), "push_test2.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { _ = conn.Close() })
+	if err := db.Bootstrap(context.Background(), conn); err != nil {
+		t.Fatalf("bootstrap: %v", err)
+	}
+	q := db.New(conn)
+	s := &Server{
+		queries: q,
+		hub:     hub.New(q),
+		apns:    apns.NewSender(nil, nil, "", "", "", ""), // inert
+	}
+
+	body := `{"device_token":"aabbccdd1234"}`
+	r := httptest.NewRequest(http.MethodPost, "/api/push/apns/register", strings.NewReader(body))
+	r = r.WithContext(jwtauth.ContextWithClaims(r.Context(), &jwtauth.Claims{UserID: "u", Scope: "full"}))
+	r = r.WithContext(jwtauth.ContextWithDeviceName(r.Context(), "iPhone"))
+	w := httptest.NewRecorder()
+	s.handleAPNsRegister(w, r)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Errorf("disabled: got %d, want 503", w.Code)
+	}
+}
+
+// TestHandleAPNsRegister_StoresRowIdempotently verifies that POST /api/push/apns/register
+// stores the subscription row and that a second call with the same token upserts
+// in place (idempotent: still exactly one row).
+func TestHandleAPNsRegister_StoresRowIdempotently(t *testing.T) {
+	s := newAPNsTestServer(t)
+
+	const deviceToken = "aabbccdd1234deadbeef"
+	const locale = "en-US"
+
+	callRegister := func() int {
+		body := `{"device_token":"` + deviceToken + `","locale":"` + locale + `"}`
+		r := httptest.NewRequest(http.MethodPost, "/api/push/apns/register", strings.NewReader(body))
+		r = r.WithContext(jwtauth.ContextWithClaims(r.Context(), &jwtauth.Claims{UserID: "u", Scope: "full"}))
+		r = r.WithContext(jwtauth.ContextWithDeviceName(r.Context(), "iPhone"))
+		w := httptest.NewRecorder()
+		s.handleAPNsRegister(w, r)
+		return w.Code
+	}
+
+	// First registration.
+	if code := callRegister(); code != http.StatusNoContent {
+		t.Fatalf("first register: got %d, want 204", code)
+	}
+
+	// Verify the row exists.
+	subs, err := s.queries.ListAPNsSubscriptionsByUserDevice(context.Background(), db.ListAPNsSubscriptionsByUserDeviceParams{
+		UserID:     "u",
+		DeviceName: "iPhone",
+	})
+	if err != nil {
+		t.Fatalf("list subs: %v", err)
+	}
+	if len(subs) != 1 {
+		t.Fatalf("after first register: got %d rows, want 1", len(subs))
+	}
+	sub := subs[0]
+	if sub.Endpoint != deviceToken {
+		t.Errorf("endpoint = %q, want %q", sub.Endpoint, deviceToken)
+	}
+	if sub.Locale != locale {
+		t.Errorf("locale = %q, want %q", sub.Locale, locale)
+	}
+	if sub.Platform != "apns" {
+		t.Errorf("platform = %q, want apns", sub.Platform)
+	}
+	if sub.UserID != "u" {
+		t.Errorf("user_id = %q, want u", sub.UserID)
+	}
+	expectedID := push.SubscriptionID(deviceToken)
+	if sub.ID != expectedID {
+		t.Errorf("id = %q, want %q (SHA-256 of token)", sub.ID, expectedID)
+	}
+
+	// Second registration with same token: must upsert in place.
+	if code := callRegister(); code != http.StatusNoContent {
+		t.Fatalf("second register: got %d, want 204", code)
+	}
+	subs2, err := s.queries.ListAPNsSubscriptionsByUserDevice(context.Background(), db.ListAPNsSubscriptionsByUserDeviceParams{
+		UserID:     "u",
+		DeviceName: "iPhone",
+	})
+	if err != nil {
+		t.Fatalf("list subs after second register: %v", err)
+	}
+	if len(subs2) != 1 {
+		t.Errorf("after second register: got %d rows, want 1 (should upsert not duplicate)", len(subs2))
+	}
+}
+
+// TestHandleAPNsRegister_MissingToken verifies that a missing device_token
+// returns 400.
+func TestHandleAPNsRegister_MissingToken(t *testing.T) {
+	s := newAPNsTestServer(t)
+
+	r := httptest.NewRequest(http.MethodPost, "/api/push/apns/register", strings.NewReader(`{}`))
+	r = r.WithContext(jwtauth.ContextWithClaims(r.Context(), &jwtauth.Claims{UserID: "u", Scope: "full"}))
+	r = r.WithContext(jwtauth.ContextWithDeviceName(r.Context(), "iPhone"))
+	w := httptest.NewRecorder()
+	s.handleAPNsRegister(w, r)
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("missing token: got %d, want 400", w.Code)
+	}
+	var resp map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err == nil {
+		if resp["error"] != "missing device_token" {
+			t.Errorf("error msg = %q", resp["error"])
+		}
+	}
+}
+
+// TestHandleAPNsRegister_UnknownLocaleFallsBack verifies that an unrecognized
+// locale falls back to the server default (zh-CN).
+func TestHandleAPNsRegister_UnknownLocaleFallsBack(t *testing.T) {
+	s := newAPNsTestServer(t)
+
+	body := `{"device_token":"tok123456","locale":"fr-FR"}`
+	r := httptest.NewRequest(http.MethodPost, "/api/push/apns/register", strings.NewReader(body))
+	r = r.WithContext(jwtauth.ContextWithClaims(r.Context(), &jwtauth.Claims{UserID: "u", Scope: "full"}))
+	r = r.WithContext(jwtauth.ContextWithDeviceName(r.Context(), "iPhone"))
+	w := httptest.NewRecorder()
+	s.handleAPNsRegister(w, r)
+	if w.Code != http.StatusNoContent {
+		t.Fatalf("register: got %d, want 204", w.Code)
+	}
+
+	subs, err := s.queries.ListAPNsSubscriptionsByUserDevice(context.Background(), db.ListAPNsSubscriptionsByUserDeviceParams{
+		UserID:     "u",
+		DeviceName: "iPhone",
+	})
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(subs) != 1 {
+		t.Fatalf("want 1 row, got %d", len(subs))
+	}
+	if subs[0].Locale != "zh-CN" {
+		t.Errorf("locale = %q, want zh-CN (fallback)", subs[0].Locale)
+	}
+}

internal/httpapi/server.go

@@ -12,6 +12,7 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/httprate"
 
+	"commilitia.net/cdrop/internal/apns"
 	"commilitia.net/cdrop/internal/brokerclient"
 	"commilitia.net/cdrop/internal/calls"
 	"commilitia.net/cdrop/internal/clipboard"
@@ -36,6 +37,7 @@ type Server struct {
 	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
+	apns      *apns.Sender       // inert when APNs keys unset → register endpoint 503
 	mux       *chi.Mux
 
 	// broker delegates session lifecycle to the Auth Broker (mint / revoke / refresh).
@@ -56,6 +58,7 @@ func New(
 	cp *calls.Provider,
 	clip *clipboard.Service,
 	pushSender *push.Sender,
+	apnsSender *apns.Sender,
 ) *Server {
 	s := &Server{
 		cfg:       cfg,
@@ -68,6 +71,7 @@ func New(
 		calls:     cp,
 		clipboard: clip,
 		push:      pushSender,
+		apns:      apnsSender,
 		mux:       chi.NewRouter(),
 
 		broker:     brokerclient.New(cfg.BrokerBaseURL, cfg.BrokerInternalKey, cfg.BrokerAppOrDefault()),
@@ -147,6 +151,7 @@ func (s *Server) routes() {
 			r.Get("/push/vapid-key", s.handlePushVAPIDKey)
 			r.Post("/push/subscribe", s.handlePushSubscribe)
 			r.Delete("/push/subscribe", s.handlePushUnsubscribe)
+			r.Post("/push/apns/register", s.handleAPNsRegister)
 			r.Get("/calls/credentials", s.handleCallsCredentials)
 
 			// Full sessions only — restricted guests (scan-login borrows) are