feat(license): challenge-response device binding via device keypair

Replaces the replayable device_hash check with a real proof of device
possession. The client generates an Ed25519 device keypair, persists the
private key next to license.json (never in the token), and binds only the
public key into the token at activation. Pack-key resolution now fetches a
server-signed one-time challenge and signs it with the device private key;
the server verifies the signature against the bound public key.

A copied license.json (token + public key, no private key) can no longer
resolve keys — replaying the token's own values or a captured signature
fails against a fresh nonce. Contract docs and token schema updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: y2hlbg

contracts/license/v1/README.md

@@ -39,26 +39,31 @@
 
 | 接口 | 说明 |
 |---|---|
-| `POST /api/v1/activate` | 激活码 → 签名 token（token.schema.json 结构；wire 格式 `base64url(payload).base64url(ed25519sig)`） |
-| `POST /api/v1/pack-keys/resolve` | Bearer token → 按 `key_id` 下发 pack 对称密钥 |
+| `POST /api/v1/activate` | 激活码 + 设备公钥 → 签名 token（token.schema.json 结构；wire 格式 `base64url(payload).base64url(ed25519sig)`） |
+| `POST /api/v1/pack-keys/challenge` | Bearer token → 一次性设备质询（server 签名，含 nonce） |
+| `POST /api/v1/pack-keys/resolve` | Bearer token + `challenge` + `device_signature` → 按 `key_id` 下发 pack 对称密钥 |
 | `GET /api/v1/publisher-keys` | 受信发布者公钥环 |
 | `GET /api/v1/license/public-key` | token 验签公钥（客户端激活时获取并与 token 一起保存本地） |
 
 未配置 `MEDIAGO_LICENSE_SERVER_URL` 时，客户端回退到开发期环境变量授权（见下）。
 
-## 设备绑定
+## 设备绑定（质询-应答）
 
-激活时客户端上报设备指纹（来自 license 目录下持久化的随机 `device-id`），license server 把它写进签名 token 的 `device_hash`。换取 pack 密钥时客户端带上当前设备指纹，server 校验其与 token 中的 `device_hash` 一致；不一致返回 403（错误码 40314）。`/api/v1/activate` 要求 `device_hash` 非空，避免签发"无绑定"的万能 token。
+采用**质询-应答**，绑定的是"持有设备私钥的证明"，而非 token 里可读出的明文值：
 
-**当前强度（务必如实理解，勿夸大）**：这道绑定**只挡住"拷贝 license.json + 运行原版客户端"**这种非技术性共享——原版客户端在新机器上算出的本地指纹不同，本地校验先拦，且上报给 server 的指纹也不匹配。
+1. **激活**：客户端本机生成 Ed25519 **设备密钥对**，只把**公钥**随 `activation_code` 上报；server 把公钥写进签名 token 的 `device_public_key`。**私钥永远留在本机**（`<license 目录>/device-key`，0600），不进 token、不随 `license.json` 传播。`/api/v1/activate` 要求 `device_public_key` 非空，避免签发"无绑定"的万能 token。
+2. **换密钥**：客户端先 `POST /pack-keys/challenge` 取一个 server 签名的一次性质询（含随机 nonce，2 分钟有效）；用**设备私钥**对质询整串签名；`POST /pack-keys/resolve` 带上 `challenge` + `device_signature`。server 校验质询由本 server 签发且未过期、`license_id` 与 token 一致、签名由 token 绑定的公钥所验。任一不过返回 403（40114 质询缺失/无效，40314 设备不符）。
 
-它**挡不住**稍有技术的复制者：
-- `device_hash` 以明文写在 token 里（`base64url(payload)` 可直接解出），所以持有被拷 token 的人能读出 `device_hash`，再手工发一个 HTTP 请求把同一个值回填过去——**server 端校验会通过**。即 server 端校验**并非真正权威**，一条 curl 即可绕过，无需改二进制。
-- `device-id` 是明文文件、与 `license.json` 同目录，整目录拷贝会一并带走指纹。
+**为什么真正有效**：换密钥要验证的是"对一个**每次都新**的 nonce 的签名"，而签名必须用**不在 token 里**的设备私钥。所以——
 
-要做到真正防"传已激活凭证"，需要**质询-应答**：激活时客户端生成设备密钥对、只上报公钥（server 把公钥哈希写进 token）；换密钥时 server 下发 nonce，客户端用**设备私钥**签名，server 用绑定的公钥验签。私钥不进 token、不随 `license.json` 传播，一条 HTTP 请求无法伪造。此为待实现项。
+- 拷贝 `license.json`（只有 token、公钥）到别的机器：没有私钥 → 签不出质询 → **拿不到密钥**。一条 curl 回填 token 里的值也没用（那只是公钥，签名仍缺私钥）。
+- 抓到一次合法签名去重放：下一个 nonce 变了 → 旧签名对不上 → 失败。
 
-- `device_hash` 为空的 token 视为**不绑定**（团队/浮动授权场景，仅限内部/管理签发）。
+已用真实服务 E2E 验证：合法设备 200；伪造签名 403；重放旧签名 403。
+
+**残留（诚实说明）**：仍是软件方案。若把**整个 license 目录**（含 `device-key` 私钥文件）一并拷走，则私钥也被带走 → 可用。要连这个都堵死需把私钥放进 **OS 钥匙串 / 安全芯片**（Keychain/TPM），让私钥读不出——后续可选加固。
+
+- `device_public_key` 为空的 token 视为**不绑定**（团队/浮动授权，仅限内部/管理签发，公开 `/activate` 不签发）。
 - 与"传激活码"不同：激活码可多设备使用、受 `max_activations` 次数限制；设备绑定针对的是"传已激活凭证"。
 
 ## 密钥与信任

contracts/license/v1/token.schema.json

@@ -30,7 +30,11 @@
 		},
 		"device_hash": {
 			"type": "string",
-			"description": "Optional device binding fingerprint."
+			"description": "Optional short fingerprint of the bound device public key (display/records only, non-authoritative)."
+		},
+		"device_public_key": {
+			"type": "string",
+			"description": "Base64 Ed25519 device public key. When present, pack-key resolution requires a challenge signed by the matching device private key. Empty means unbound (floating license)."
 		},
 		"license_api_version": {
 			"type": "string",

services/server/internal/service/license/client.go

@@ -3,10 +3,10 @@ package license
 import (
 	"bytes"
 	"context"
+	"crypto/ed25519"
 	"crypto/rand"
 	"crypto/sha256"
 	"encoding/base64"
-	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -51,7 +51,7 @@ type Client struct {
 	publisherAt    time.Time
 
 	deviceOnce sync.Once
-	deviceID   string
+	deviceKey  ed25519.PrivateKey
 }
 
 var _ Service = (*Client)(nil)
@@ -142,8 +142,8 @@ func (client *Client) Activate(ctx context.Context, code string) (StatusInfo, er
 		Token string `json:"token"`
 	}
 	err = client.postJSON(ctx, "/api/v1/activate", map[string]string{
-		"activation_code": code,
-		"device_hash":     client.deviceHash(),
+		"activation_code":   code,
+		"device_public_key": client.devicePublicKeyBase64(),
 	}, "", &activated)
 	if err != nil {
 		return client.Status(), err
@@ -207,12 +207,25 @@ func (client *Client) ResolvePackKey(ctx context.Context, keyID string) ([]byte,
 	if keyID == "" {
 		keyID = "default"
 	}
+	// Prove device possession: fetch a server challenge and sign it with the
+	// device private key (which never left this machine and is not in the token).
+	var challenged struct {
+		Challenge string `json:"challenge"`
+	}
+	if err := client.postJSON(ctx, "/api/v1/pack-keys/challenge", nil, stored.Token, &challenged); err != nil {
+		if errors.Is(err, ErrActivationRejected) {
+			return nil, fmt.Errorf("%w: challenge rejected", ErrPackKeyNotFound)
+		}
+		return nil, err
+	}
+	signature := ed25519.Sign(client.devicePrivateKey(), []byte(challenged.Challenge))
 	var resolved struct {
 		Key string `json:"key"`
 	}
 	if err := client.postJSON(ctx, "/api/v1/pack-keys/resolve", map[string]string{
-		"key_id":      keyID,
-		"device_hash": client.deviceHash(),
+		"key_id":           keyID,
+		"challenge":        challenged.Challenge,
+		"device_signature": base64.StdEncoding.EncodeToString(signature),
 	}, stored.Token, &resolved); err != nil {
 		if errors.Is(err, ErrActivationRejected) {
 			return nil, fmt.Errorf("%w: %q", ErrPackKeyNotFound, keyID)
@@ -377,55 +390,61 @@ func clonePublisherKeys(keys map[string][]byte) map[string][]byte {
 	return cloned
 }
 
-// deviceHash returns a stable fingerprint of this installation. It is derived
-// from a random device id persisted next to the license file, so a license
-// token copied to another machine (which has its own device id) fails the
-// device-binding check. Falls back to host attributes if the id cannot be
-// persisted.
-func (client *Client) deviceHash() string {
+// deviceKeyOnce loads (or creates) this installation's Ed25519 device keypair.
+// The private key is persisted next to the license file and never leaves the
+// device; only its public key is bound into the license token. Pack-key
+// resolution requires signing a server challenge with the private key, so a
+// license token copied to another machine cannot obtain keys.
+func (client *Client) devicePrivateKey() ed25519.PrivateKey {
 	client.deviceOnce.Do(func() {
-		client.deviceID = client.loadOrCreateDeviceID()
+		client.deviceKey = client.loadOrCreateDeviceKey()
 	})
-	sum := sha256.Sum256([]byte(client.deviceID))
-	return hex.EncodeToString(sum[:16])
+	return client.deviceKey
+}
+
+// devicePublicKeyBase64 returns the base64-std device public key sent at
+// activation and matched against the token binding.
+func (client *Client) devicePublicKeyBase64() string {
+	pub := client.devicePrivateKey().Public().(ed25519.PublicKey)
+	return base64.StdEncoding.EncodeToString(pub)
 }
 
-func (client *Client) loadOrCreateDeviceID() string {
-	path := filepath.Join(filepath.Dir(client.storePath), "device-id")
+func (client *Client) loadOrCreateDeviceKey() ed25519.PrivateKey {
+	path := filepath.Join(filepath.Dir(client.storePath), "device-key")
 	if raw, err := os.ReadFile(path); err == nil {
-		if id := strings.TrimSpace(string(raw)); id != "" {
-			return id
+		if seed, decodeErr := base64.StdEncoding.DecodeString(strings.TrimSpace(string(raw))); decodeErr == nil && len(seed) == ed25519.SeedSize {
+			return ed25519.NewKeyFromSeed(seed)
 		}
 	}
-	buf := make([]byte, 16)
-	if _, err := rand.Read(buf); err != nil {
-		return machineFallbackID()
+	seed := make([]byte, ed25519.SeedSize)
+	if _, err := rand.Read(seed); err != nil {
+		return machineFallbackKey()
 	}
-	id := hex.EncodeToString(buf)
-	// If the id cannot be persisted, fall back to a stable machine-derived id
-	// rather than returning this ephemeral one — otherwise every launch would
-	// regenerate a different fingerprint and silently invalidate an already
-	// activated license, forcing re-activation.
+	// If the key cannot be persisted, derive a stable machine-bound key instead
+	// of returning this ephemeral one — otherwise every launch would regenerate
+	// a different key and silently invalidate an already activated license.
 	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
-		return machineFallbackID()
+		return machineFallbackKey()
 	}
-	if err := os.WriteFile(path, []byte(id+"\n"), 0o600); err != nil {
-		return machineFallbackID()
+	if err := os.WriteFile(path, []byte(base64.StdEncoding.EncodeToString(seed)+"\n"), 0o600); err != nil {
+		return machineFallbackKey()
 	}
-	return id
+	return ed25519.NewKeyFromSeed(seed)
 }
 
-func machineFallbackID() string {
+func machineFallbackKey() ed25519.PrivateKey {
 	hostname, _ := os.Hostname()
 	home, _ := os.UserHomeDir()
-	return "host:" + hostname + "|" + home
+	seed := sha256.Sum256([]byte("mediago-device|" + hostname + "|" + home))
+	return ed25519.NewKeyFromSeed(seed[:])
 }
 
 // tokenMatchesDevice reports whether a token is usable on this device. A token
-// with an empty device hash is unbound (dev/legacy) and passes unconditionally.
+// with no bound device public key is unbound (dev/legacy) and passes. This is a
+// fast local check; the authoritative proof is the server challenge signature.
 func (client *Client) tokenMatchesDevice(payload TokenPayload) bool {
-	if strings.TrimSpace(payload.DeviceHash) == "" {
+	if strings.TrimSpace(payload.DevicePublicKey) == "" {
 		return true
 	}
-	return payload.DeviceHash == client.deviceHash()
+	return payload.DevicePublicKey == client.devicePublicKeyBase64()
 }

services/server/internal/service/license/client_test.go

@@ -206,25 +206,48 @@ func newFakeLicenseServer(t *testing.T) *fakeLicenseServer {
 	})
 	mux.HandleFunc("POST /api/v1/activate", func(w http.ResponseWriter, r *http.Request) {
 		var body struct {
-			ActivationCode string `json:"activation_code"`
-			DeviceHash     string `json:"device_hash"`
+			ActivationCode  string `json:"activation_code"`
+			DevicePublicKey string `json:"device_public_key"`
 		}
 		_ = json.NewDecoder(r.Body).Decode(&body)
 		if body.ActivationCode != "MG-GOOD-CODE" {
 			writeEnvelopeError(w, http.StatusForbidden, 40310, "activation code is invalid")
 			return
 		}
-		// Bind the issued token to the activating device, like the real server.
+		// Bind the issued token to the activating device's public key.
 		writeEnvelope(w, http.StatusOK, map[string]any{
-			"token": fake.issueToken(nil, body.DeviceHash, time.Now().Add(time.Hour)),
+			"token": fake.issueToken(nil, body.DevicePublicKey, time.Now().Add(time.Hour)),
 			"plan":  "pro",
 		})
 	})
-	mux.HandleFunc("POST /api/v1/pack-keys/resolve", func(w http.ResponseWriter, r *http.Request) {
+	mux.HandleFunc("POST /api/v1/pack-keys/challenge", func(w http.ResponseWriter, r *http.Request) {
 		if !strings.HasPrefix(r.Header.Get("Authorization"), "Bearer ") {
 			writeEnvelopeError(w, http.StatusUnauthorized, 40110, "license token is required")
 			return
 		}
+		nonce := make([]byte, 32)
+		_, _ = rand.Read(nonce)
+		writeEnvelope(w, http.StatusOK, map[string]any{"challenge": base64.StdEncoding.EncodeToString(nonce)})
+	})
+	mux.HandleFunc("POST /api/v1/pack-keys/resolve", func(w http.ResponseWriter, r *http.Request) {
+		token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
+		if strings.TrimSpace(token) == "" {
+			writeEnvelopeError(w, http.StatusUnauthorized, 40110, "license token is required")
+			return
+		}
+		var body struct {
+			KeyID           string `json:"key_id"`
+			Challenge       string `json:"challenge"`
+			DeviceSignature string `json:"device_signature"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&body)
+		// Verify the device proved possession of the private key bound in the token.
+		pub := fake.tokenDevicePublicKey(token)
+		sig, _ := base64.StdEncoding.DecodeString(body.DeviceSignature)
+		if len(pub) != ed25519.PublicKeySize || !ed25519.Verify(pub, []byte(body.Challenge), sig) {
+			writeEnvelopeError(w, http.StatusForbidden, 40314, "license is bound to another device")
+			return
+		}
 		writeEnvelope(w, http.StatusOK, map[string]any{
 			"key_id": "default",
 			"key":    base64.StdEncoding.EncodeToString(fake.packKey),
@@ -249,7 +272,7 @@ func (fake *fakeLicenseServer) publicKeyBase64() string {
 	return base64.StdEncoding.EncodeToString(fake.publicKey)
 }
 
-func (fake *fakeLicenseServer) issueToken(t *testing.T, deviceHash string, expiresAt time.Time) string {
+func (fake *fakeLicenseServer) issueToken(t *testing.T, devicePublicKey string, expiresAt time.Time) string {
 	if t != nil {
 		t.Helper()
 	}
@@ -258,13 +281,35 @@ func (fake *fakeLicenseServer) issueToken(t *testing.T, deviceHash string, expir
 		Plan:              "pro",
 		Entitlements:      []string{"pack.import.pro"},
 		ExpiresAt:         expiresAt.UTC(),
-		DeviceHash:        deviceHash,
+		DevicePublicKey:   devicePublicKey,
 		LicenseAPIVersion: "v1",
 	})
 	signature := ed25519.Sign(fake.private, payload)
 	return base64.RawURLEncoding.EncodeToString(payload) + "." + base64.RawURLEncoding.EncodeToString(signature)
 }
 
+// tokenDevicePublicKey extracts the bound device public key from a token,
+// mirroring how the real server reads it to verify the challenge signature.
+func (fake *fakeLicenseServer) tokenDevicePublicKey(token string) []byte {
+	parts := strings.SplitN(strings.TrimSpace(token), ".", 2)
+	if len(parts) != 2 {
+		return nil
+	}
+	raw, err := base64.RawURLEncoding.DecodeString(parts[0])
+	if err != nil {
+		return nil
+	}
+	var payload TokenPayload
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return nil
+	}
+	pub, err := base64.StdEncoding.DecodeString(payload.DevicePublicKey)
+	if err != nil {
+		return nil
+	}
+	return pub
+}
+
 func writeEnvelope(w http.ResponseWriter, status int, data any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)

services/server/internal/service/license/token.go

@@ -25,6 +25,7 @@ type TokenPayload struct {
 	Entitlements      []string  `json:"entitlements"`
 	ExpiresAt         time.Time `json:"expires_at"`
 	DeviceHash        string    `json:"device_hash,omitempty"`
+	DevicePublicKey   string    `json:"device_public_key,omitempty"`
 	LicenseAPIVersion string    `json:"license_api_version"`
 }