diff --git a/deploy/nginx.conf b/deploy/nginx.conf index f203943..c7a37e2 100644 --- a/deploy/nginx.conf +++ b/deploy/nginx.conf @@ -16,6 +16,11 @@ server { proxy_pass http://api:8080; proxy_set_header Host $http_host; } + location = /api/v1/key-packages { + client_max_body_size 12k; + proxy_pass http://api:8080; + proxy_set_header Host $http_host; + } add_header Content-Security-Policy "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'" always; add_header Referrer-Policy no-referrer always; diff --git a/docs/api.md b/docs/api.md index e70dd90..83b507a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -19,6 +19,9 @@ | POST | /api/v1/contacts/{id} | 请求体包含 action,可选 alias 和 category,成功返回 204 | | POST | /api/v1/inbox | 接收 messageId、recipientDevice 和 Base64 编码的 MLS 封包,返回字符串 sequence | | GET | /api/v1/inbox?after= | 按当前设备和递增游标取最多 64 条封包 | +| GET | /api/v1/contacts/{id}/devices | 返回已接受联系人的有效设备与公开身份密钥 | +| POST | /api/v1/key-packages | 当前设备发布带设备签名的 MLS KeyPackage,成功返回 204 | +| POST | /api/v1/contacts/{id}/devices/{device}/claim | 为当前设备原子领取一个联系人的未使用 KeyPackage | 用户名为 3–32 位 ASCII 字母、数字或下划线,忽略大小写。密码最少 12 个 Unicode 字符,最多 256 字节。platform 为 web 或 windows。公钥、签名和 challenge 使用无填充 Base64URL。设备使用 Ed25519 签名 UTF-8 字符串 `XHChat device authentication v1\n` 后紧接 challenge。该签名仅用于证明基础设备密钥持有权。 @@ -26,4 +29,6 @@ 设备投递当前要求双方是已接受的联系人,且两个设备均未撤销。接口校验 MLS 1.0 PrivateMessage 和 Welcome 的外层类型与长度,客户端负责完整协议验证。相同发送设备、接收设备、消息 ID 和封包的重试返回原游标,内容不同返回 409。WebSocket 的 inbox_changed 仅提示当前设备补拉。投递保留期由 XHCHAT_ENVELOPE_RETENTION 配置,默认 720 小时。 -下一阶段将增加 /conversations、/attachments 和 /key-packages。后续加入 /groups、/calls、/posts、/backups、/push 与独立的管理接口。 +密钥包与签名均使用标准 Base64。设备以已有的 Ed25519 密钥签名 UTF-8 前缀 `XHChat MLS KeyPackage v1\n{userId}\n{deviceId}\n` 和原始 MLS 封包的拼接。服务端验证签名和外层格式,密钥包可在发布后的 24 小时内领取一次。客户端仍需独立验证设备公钥信任和完整 MLS 对象。重试发布同一封包不会再次开放领取。 + +下一阶段将增加 /conversations 和 /attachments。后续加入 /groups、/calls、/posts、/backups、/push 与独立的管理接口。 diff --git a/docs/database.md b/docs/database.md index 27a97be..9f7300b 100644 --- a/docs/database.md +++ b/docs/database.md @@ -7,7 +7,7 @@ | sessions | 高熵令牌的 SHA-256 摘要为主键,关联设备,包含到期时间 | | contact_relationships、contact_blocks、contact_preferences | 关系按账号对去重,拉黑有方向,私有备注按拥有者授权 | | conversations、memberships | 会话与成员关系,记录角色和生效世代 | -| device_credentials、key_packages | 公开凭据及一次性密钥包,事务领取,撤销后停止发放 | +| devices、device_key_packages | 公开设备凭据及签名的一次性密钥包,事务领取,撤销后停止发放 | | device_envelopes | 二进制协议封包、投递游标和目标设备,按发送设备、接收设备和客户端消息 ID 幂等 | | attachments、backups | 对象存储标识、密文尺寸、配额和版本,密钥由端侧传递 | | calls、call_participants | 通话状态、参与设备和时间,不存媒体 | diff --git a/docs/progress.md b/docs/progress.md index faf73a3..5eb83a4 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -36,3 +36,7 @@ Web 和 Electron 共用 Vue 客户端,独立接入同一 Go API。真实 Postg ## 设备密文投递 服务端已实现联系人设备之间的 MLS 封包队列、幂等提交、离线游标补拉、实时同步提示和保留期。集成测试覆盖跨账号收件箱隔离、设备撤销及非封包请求拒绝。客户端会话与可操作的聊天界面尚待接入。 + +## 设备目录与密钥包 + +服务端已实现联系人设备目录、设备签名校验和一次性 MLS KeyPackage 领取。Compose 集成测试验证陌生人隔离、错误签名拒绝、并发只能领取一次、重复上传不会重新开放领取和撤销后目录隐藏。接下来需在双端接入可信公钥验证及 MLS 会话持久化。 diff --git a/server/internal/database/004_key_packages.sql b/server/internal/database/004_key_packages.sql new file mode 100644 index 0000000..68375a1 --- /dev/null +++ b/server/internal/database/004_key_packages.sql @@ -0,0 +1,13 @@ +CREATE TABLE device_key_packages ( + device_id uuid NOT NULL REFERENCES devices(id) ON DELETE CASCADE, + package_hash bytea NOT NULL CHECK (octet_length(package_hash)=32), + package bytea NOT NULL CHECK (octet_length(package) BETWEEN 32 AND 8192), + signature bytea NOT NULL CHECK (octet_length(signature)=64), + created_at timestamptz NOT NULL DEFAULT now(), + claimed_at timestamptz, + PRIMARY KEY (device_id, package_hash) +); + +CREATE INDEX device_key_packages_available ON device_key_packages(device_id, created_at) +WHERE claimed_at IS NULL; +CREATE INDEX device_key_packages_expiry ON device_key_packages(created_at); diff --git a/server/internal/database/database.go b/server/internal/database/database.go index 1333bef..ff39ecc 100644 --- a/server/internal/database/database.go +++ b/server/internal/database/database.go @@ -16,6 +16,9 @@ var contactsMigration string //go:embed 003_delivery.sql var deliveryMigration string +//go:embed 004_key_packages.sql +var keyPackagesMigration string + func Migrate(ctx context.Context, pool *pgxpool.Pool) error { tx, err := pool.Begin(ctx) if err != nil { @@ -28,7 +31,7 @@ func Migrate(ctx context.Context, pool *pgxpool.Pool) error { if _, err = tx.Exec(ctx, "CREATE TABLE IF NOT EXISTS schema_migrations (version integer PRIMARY KEY)"); err != nil { return err } - for index, migration := range []string{identityMigration, contactsMigration, deliveryMigration} { + for index, migration := range []string{identityMigration, contactsMigration, deliveryMigration, keyPackagesMigration} { version := index + 1 var applied bool if err = tx.QueryRow(ctx, "SELECT EXISTS (SELECT 1 FROM schema_migrations WHERE version=$1)", version).Scan(&applied); err != nil { diff --git a/server/internal/delivery/directory.go b/server/internal/delivery/directory.go new file mode 100644 index 0000000..724b256 --- /dev/null +++ b/server/internal/delivery/directory.go @@ -0,0 +1,141 @@ +package delivery + +import ( + "context" + "crypto/ed25519" + "crypto/sha256" + "errors" + + "github.com/jackc/pgx/v5" +) + +type DirectoryDevice struct { + ID string `json:"id"` + Name string `json:"name"` + PublicKey []byte `json:"publicKey"` +} + +type KeyPackage struct { + Package []byte `json:"package"` + Signature []byte `json:"signature"` +} + +var ErrSignature = errors.New("invalid key package device signature") +var ErrPackageLimit = errors.New("device key package limit reached") + +const acceptedContact = ` + EXISTS (SELECT 1 FROM contact_relationships + WHERE first_user=LEAST($1::uuid,$2::uuid) AND second_user=GREATEST($1::uuid,$2::uuid) + AND status='accepted') +` + +func (s *Store) Directory(ctx context.Context, owner, contact string) ([]DirectoryDevice, error) { + rows, err := s.db.Query(ctx, ` + SELECT id,name,public_key FROM devices + WHERE user_id=$2 AND revoked_at IS NULL AND `+acceptedContact+` + ORDER BY id LIMIT 128`, owner, contact) + if err != nil { + return nil, err + } + defer rows.Close() + result := make([]DirectoryDevice, 0) + for rows.Next() { + var device DirectoryDevice + if err := rows.Scan(&device.ID, &device.Name, &device.PublicKey); err != nil { + return nil, err + } + result = append(result, device) + } + return result, rows.Err() +} + +func (s *Store) PublishPackage(ctx context.Context, owner, device string, item KeyPackage) error { + tx, err := s.db.Begin(ctx) + if err != nil { + return err + } + defer tx.Rollback(ctx) + var public []byte + err = tx.QueryRow(ctx, "SELECT public_key FROM devices WHERE id=$1 AND user_id=$2 AND revoked_at IS NULL FOR UPDATE", device, owner).Scan(&public) + if errors.Is(err, pgx.ErrNoRows) { + return ErrUnavailable + } + if err != nil { + return err + } + binding := append([]byte("XHChat MLS KeyPackage v1\n"+owner+"\n"+device+"\n"), item.Package...) + if !ed25519.Verify(public, binding, item.Signature) { + return ErrSignature + } + hash := sha256.Sum256(item.Package) + var known bool + var available int + err = tx.QueryRow(ctx, ` + SELECT count(*) FILTER (WHERE claimed_at IS NULL AND created_at > now() - interval '24 hours'), + COALESCE(bool_or(package_hash=$2),false) + FROM device_key_packages WHERE device_id=$1 + `, device, hash[:]).Scan(&available, &known) + if err != nil { + return err + } + if known { + return tx.Commit(ctx) + } + if available >= 32 { + return ErrPackageLimit + } + if _, err := tx.Exec(ctx, "INSERT INTO device_key_packages(device_id,package_hash,package,signature) VALUES($1,$2,$3,$4)", + device, hash[:], item.Package, item.Signature); err != nil { + return err + } + return tx.Commit(ctx) +} + +func (s *Store) ClaimPackage(ctx context.Context, owner, requester, contact, device string) (KeyPackage, error) { + var item KeyPackage + tx, err := s.db.Begin(ctx) + if err != nil { + return item, err + } + defer tx.Rollback(ctx) + if _, err := tx.Exec(ctx, "SELECT id FROM users WHERE id IN ($1,$2) ORDER BY id FOR UPDATE", owner, contact); err != nil { + return item, err + } + var friends bool + err = tx.QueryRow(ctx, "SELECT "+acceptedContact, owner, contact).Scan(&friends) + if err != nil { + return item, err + } + if !friends { + return item, ErrUnavailable + } + var active int + err = tx.QueryRow(ctx, ` + SELECT count(*) FROM ( + SELECT id FROM devices WHERE ((id=$1 AND user_id=$2) OR (id=$3 AND user_id=$4)) + AND revoked_at IS NULL ORDER BY id FOR UPDATE + ) AS active_devices + `, requester, owner, device, contact).Scan(&active) + if err != nil { + return item, err + } + if active != 2 { + return item, ErrUnavailable + } + err = tx.QueryRow(ctx, ` + UPDATE device_key_packages SET claimed_at=now() + WHERE (device_id, package_hash)=( + SELECT device_id, package_hash FROM device_key_packages + WHERE device_id=$1 AND claimed_at IS NULL AND created_at > now() - interval '24 hours' + ORDER BY created_at, package_hash LIMIT 1 + ) + RETURNING package, signature + `, device).Scan(&item.Package, &item.Signature) + if errors.Is(err, pgx.ErrNoRows) { + return item, ErrUnavailable + } + if err != nil { + return item, err + } + return item, tx.Commit(ctx) +} diff --git a/server/internal/delivery/store.go b/server/internal/delivery/store.go index ffb5211..5216763 100644 --- a/server/internal/delivery/store.go +++ b/server/internal/delivery/store.go @@ -67,11 +67,7 @@ func (s *Store) Send(ctx context.Context, sender, recipient, message string, cip // This direct-message endpoint only connects accepted contacts. // A separate authorization flow is needed for same-account device transfers. var friends bool - err = tx.QueryRow(ctx, ` - SELECT EXISTS (SELECT 1 FROM contact_relationships - WHERE first_user=LEAST($1::uuid,$2::uuid) AND second_user=GREATEST($1::uuid,$2::uuid) - AND status='accepted') - `, senderUser, recipientUser).Scan(&friends) + err = tx.QueryRow(ctx, "SELECT "+acceptedContact, senderUser, recipientUser).Scan(&friends) if err != nil { return "", err } @@ -126,6 +122,10 @@ func (s *Store) Inbox(ctx context.Context, recipient string, after int64) ([]Env } func (s *Store) Cleanup(ctx context.Context, retention time.Duration) error { - _, err := s.db.Exec(ctx, "DELETE FROM device_envelopes WHERE created_at < $1", time.Now().Add(-retention)) + if _, err := s.db.Exec(ctx, "DELETE FROM device_envelopes WHERE created_at < $1", time.Now().Add(-retention)); err != nil { + return err + } + // Keep issued package hashes past the validity window of an individual upload. + _, err := s.db.Exec(ctx, "DELETE FROM device_key_packages WHERE created_at < now() - interval '90 days'") return err } diff --git a/server/internal/httpapi/api.go b/server/internal/httpapi/api.go index dc199d9..52dde20 100644 --- a/server/internal/httpapi/api.go +++ b/server/internal/httpapi/api.go @@ -50,6 +50,9 @@ func New(accounts *account.Store, contactStore *contacts.Store, envelopeStore *d mux.HandleFunc("POST /api/v1/contacts/{id}", a.authorized(a.changeContact)) mux.HandleFunc("GET /api/v1/inbox", a.authorized(a.inbox)) mux.HandleFunc("POST /api/v1/inbox", a.authorized(a.sendEnvelope)) + mux.HandleFunc("GET /api/v1/contacts/{id}/devices", a.authorized(a.contactDevices)) + mux.HandleFunc("POST /api/v1/contacts/{id}/devices/{device}/claim", a.authorized(a.claimPackage)) + mux.HandleFunc("POST /api/v1/key-packages", a.authorized(a.publishPackage)) return a.boundary(mux) } diff --git a/server/internal/httpapi/directory.go b/server/internal/httpapi/directory.go new file mode 100644 index 0000000..b4f2ac1 --- /dev/null +++ b/server/internal/httpapi/directory.go @@ -0,0 +1,73 @@ +package httpapi + +import ( + "errors" + "net/http" + "strings" + + "xhchat/server/internal/account" + "xhchat/server/internal/delivery" +) + +func (a *API) contactDevices(w http.ResponseWriter, r *http.Request, _ string, identity account.Identity) { + id := strings.ToLower(r.PathValue("id")) + if !uuidPattern.MatchString(id) { + problem(w, 404, "contact_not_found", "找不到该联系人") + return + } + result, err := a.delivery.Directory(r.Context(), identity.User.ID, id) + if err != nil { + unavailable(w, err) + return + } + respond(w, 200, result) +} + +func (a *API) publishPackage(w http.ResponseWriter, r *http.Request, _ string, identity account.Identity) { + var item delivery.KeyPackage + if !parseLimit(w, r, &item, 12<<10) { + return + } + wire := item.Package + if len(wire) < 32 || len(wire) > 8192 || wire[0] != 0 || wire[1] != 1 || wire[2] != 0 || wire[3] != 5 || len(item.Signature) != 64 { + problem(w, 400, "invalid_package", "密钥包格式无效") + return + } + if !a.limit(w, r, "package-publish:"+identity.Device.ID, 48) { + return + } + err := a.delivery.PublishPackage(r.Context(), identity.User.ID, identity.Device.ID, item) + switch { + case errors.Is(err, delivery.ErrSignature): + problem(w, 400, "invalid_package_signature", "密钥包设备签名无效") + case errors.Is(err, delivery.ErrPackageLimit): + problem(w, 409, "package_limit", "当前已有足够的未使用密钥包") + case errors.Is(err, delivery.ErrUnavailable): + problem(w, 404, "device_not_found", "设备不可用") + case err != nil: + unavailable(w, err) + default: + w.WriteHeader(204) + } +} + +func (a *API) claimPackage(w http.ResponseWriter, r *http.Request, _ string, identity account.Identity) { + id, device := strings.ToLower(r.PathValue("id")), strings.ToLower(r.PathValue("device")) + if !uuidPattern.MatchString(id) || !uuidPattern.MatchString(device) { + problem(w, 404, "package_unavailable", "密钥包不可用") + return + } + if !a.limit(w, r, "package-claim:"+identity.Device.ID, 24) { + return + } + item, err := a.delivery.ClaimPackage(r.Context(), identity.User.ID, identity.Device.ID, id, device) + if errors.Is(err, delivery.ErrUnavailable) { + problem(w, 404, "package_unavailable", "密钥包不可用") + return + } + if err != nil { + unavailable(w, err) + return + } + respond(w, 200, item) +} diff --git a/tests/delivery.test.mjs b/tests/delivery.test.mjs index 9159feb..db8a2f0 100644 --- a/tests/delivery.test.mjs +++ b/tests/delivery.test.mjs @@ -24,9 +24,8 @@ async function json(path, method, token, body, status = 200) { return response.json() } -async function register() { +async function register({ publicKey, privateKey } = generateKeyPairSync('ed25519')) { const { challenge } = await json('/auth/challenge', 'POST') - const { publicKey, privateKey } = generateKeyPairSync('ed25519') return json('/auth/register', 'POST', null, { username: 'qa_' + randomBytes(6).toString('hex'), password: randomBytes(24).toString('hex'), @@ -88,3 +87,32 @@ test('设备密文投递、幂等、离线补拉、实时提示和撤销', { tim ws.terminate() } }) + +test('设备密钥包验证签名并只领取一次', { timeout: 25000 }, async () => { + const keys = generateKeyPairSync('ed25519') + const owner = await register(keys) + const contactUser = await register() + const stranger = await register() + const directory = '/contacts/' + owner.user.id + '/devices' + const claim = directory + '/' + owner.device.id + '/claim' + const bytes = Buffer.concat([Buffer.from([0, 1, 0, 5]), randomBytes(96)]) + const binding = Buffer.concat([Buffer.from('XHChat MLS KeyPackage v1\n' + owner.user.id + '\n' + owner.device.id + '\n'), bytes]) + const packageData = { package: bytes.toString('base64'), signature: sign(null, binding, keys.privateKey).toString('base64') } + await json('/key-packages', 'POST', owner.token, { ...packageData, signature: randomBytes(64).toString('base64') }, 400) + assert.equal((await call('/key-packages', 'POST', owner.token, packageData)).status, 204) + assert.deepEqual(await json(directory, 'GET', contactUser.token), []) + await json(claim, 'POST', contactUser.token, null, 404) + await contact(owner, contactUser, 'request') + await contact(contactUser, owner, 'accept') + const [record] = await json(directory, 'GET', contactUser.token) + assert.equal(record.id, owner.device.id) + assert.deepEqual(Buffer.from(record.publicKey, 'base64'), Buffer.from(keys.publicKey.export({format:'jwk'}).x, 'base64url')) + assert.deepEqual(await json(directory, 'GET', stranger.token), []) + const attempts = await Promise.all([call(claim, 'POST', contactUser.token), call(claim, 'POST', contactUser.token)]) + assert.deepEqual(attempts.map((reply) => reply.status).sort(), [200, 404]) + assert.deepEqual(await attempts.find((reply) => reply.ok).json(), packageData) + assert.equal((await call('/key-packages', 'POST', owner.token, packageData)).status, 204) + await json(claim, 'POST', contactUser.token, null, 404) + assert.equal((await call('/devices/' + owner.device.id, 'DELETE', owner.token)).status, 204) + assert.deepEqual(await json(directory, 'GET', contactUser.token), []) +})