Merge pull request '绑定设备身份并分发一次性 MLS 密钥包' (#5) from xhgit/mls-device-directory into main

Reviewed-on: http://git.xhmcl.com/xhgit/XHChat/pulls/5
This commit was merged in pull request #5.
This commit is contained in:
xhgit committed 2026-11-13 11:07:30 +00:00
commit e53e8b8f37
11 files changed
+286 -11

No files matched your search

+5
View File
@@ -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;
+6 -1
View File
@@ -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 与独立的管理接口。
+1 -1
View File
@@ -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 | 通话状态、参与设备和时间,不存媒体 |
+4
View File
@@ -36,3 +36,7 @@ Web 和 Electron 共用 Vue 客户端,独立接入同一 Go API。真实 Postg
## 设备密文投递
服务端已实现联系人设备之间的 MLS 封包队列、幂等提交、离线游标补拉、实时同步提示和保留期。集成测试覆盖跨账号收件箱隔离、设备撤销及非封包请求拒绝。客户端会话与可操作的聊天界面尚待接入。
## 设备目录与密钥包
服务端已实现联系人设备目录、设备签名校验和一次性 MLS KeyPackage 领取。Compose 集成测试验证陌生人隔离、错误签名拒绝、并发只能领取一次、重复上传不会重新开放领取和撤销后目录隐藏。接下来需在双端接入可信公钥验证及 MLS 会话持久化。
@@ -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);
+4 -1
View File
@@ -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 {
+141
View File
@@ -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)
}
+6 -6
View File
@@ -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
}
+3
View File
@@ -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)
}
+73
View File
@@ -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)
}
+30 -2
View File
@@ -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), [])
})