绑定设备身份并分发一次性 MLS 密钥包 #5
No files matched your search
@@ -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
@@ -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
@@ -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 | 通话状态、参与设备和时间,不存媒体 |
|
||||
|
||||
@@ -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);
|
||||
@@ -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 {
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
|
||||
@@ -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
@@ -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), [])
|
||||
})
|
||||
Reference in new issue
Block a user