ADR-003 身份地址与实例短码

• 状态：提议，待总控决策
• 日期：2026-09-23
• 决策范围：MVP 用户 ID、实例短码、显示地址、二维码和未知实例导入语义
• 关联：ADR-004、实例配置/服务端接口设计

背景

v1.1 示例使用 7K3M-2Q9F-PL8D@A7D4，用户 ID 为不易混淆的 Crockford Base32 子集，实例短码由实例长期签名公钥哈希截断产生；二维码同时包含 HTTPS URL、ID、短码和指纹。

这里仍有两个安全问题：

1. 4 个 Base32 字符只有约 20 bit，不足以作为跨互联网唯一或安全身份。
2. 只有短码的手输地址不能在没有全局目录的前提下安全发现未知实例；自动寻找会引入目录、隐私和钓鱼边界。

v1.1 MUST 与建议的区分

MUST：注册不依赖手机号/邮箱；服务端随机分配不可枚举的 ID；实例配置签名并在首次连接展示/固定指纹；后续变化阻断；不提供昵称全局搜索。

建议格式：12 字符 Base32 用户 ID、4 字符实例短码和当前二维码字段仍可调整，尚未冻结编码、校验位或 URI canonicalization。

设计不变量

• 人类可读短码只作提示/消歧，不是信任根、路由授权或 TLS 替代品。
• 实例权威身份是规范化 HTTPS origin 与长期签名公钥指纹的绑定。
• 联系人权威身份至少绑定实例身份、用户随机 ID、身份公钥/验证状态。
• 二维码解析后先展示 origin 和指纹，再由用户确认；重复导入不得静默替换已固定实例。
• 地址解析和二维码字段必须有版本、长度上限、重复字段拒绝和规范化规则。

选项

A 保留 4 字符实例短码

• 优点：短、易读，与说明书示例一致。
• 缺点：碰撞概率高，只能在已配置实例集合内作提示；不能安全发现未知实例。

B 增长为 8 至 10 字符

• 优点：显著降低无意碰撞，手工核对更可靠。
• 缺点：地址更长；仍不能替代完整指纹或安全发现机制。

C 地址直接包含域名或可验证完整实例标识

• 优点：可路由，语义清楚。
• 缺点：域名变更、同域多实例、IDN/Unicode、端口和重定向带来规范化与钓鱼问题；泄露实例域名。

建议

MVP 分离“显示地址”和“可导入联系载荷”：

• 显示地址：<user-id>@<instance-short-code>，仅用于已配置 Profile 内输入/展示。
• QR/deep link：包含版本、规范化 HTTPS origin、用户 ID、实例短码、完整实例公钥指纹和可选展示名。
• 手输地址指向未知短码时，不做全局发现；提示用户提供部署/联系人二维码或明确输入 HTTPS origin，再核对完整指纹。
• 本机检测短码碰撞；发生碰撞时 UI 显示更长短码/指纹，不能凭短码选实例。

建议把默认实例短码提高到至少 8 个 Base32 字符，但这与 v1.1 的 4 字符示例不同，需总控批准。无论长度，安全判断都使用完整指纹。

候选格式

user_id display: 7K3M-2Q9F-PL8D
address display: 7K3M-2Q9F-PL8D@A7D4-9Q2M   # 长度待决

vmax://contact/v1?
  origin=https%3A%2F%2Fchat.example.com&
  user=7K3M2Q9FPL8D&
  instance=A7D49Q2M&
  fingerprint=<base64url-or-base32-full-digest>

上例只展示字段，不是已冻结 URI。查询参数顺序不能直接作为签名字节；签名对象使用 ADR-004 的规范化格式。

编码和校验待决

用户 ID 熵

12 个 Base32 字符约 60 bit。它可满足 10^6 注册无顺序模式的要求，但是否足以覆盖长期规模、碰撞预算和在线猜测需计算并由服务端压测。增加字符或校验位会影响 UX。

短码派生

待选择：

• Truncate(Base32(SHA-256(canonical-public-key)))
• 使用协议套件指定的哈希，并把 "VMax instance code v1" 域分离标签纳入输入

推荐第二种显式版本/域分离形式；完整输入必须是规范化公钥对象，不是 PEM 文本或 UI 字符串。

易错输入

• 解析大小写不敏感，展示统一大写；拒绝/映射易混淆字符的策略必须唯一。
• 连字符仅展示，不进入二进制 ID。
• 是否增加校验字符待可用性测试；校验只能防输入错误，不能提供认证。

验证

• 生成至少 10^6 用户 ID，检查长度、字符集、分布、碰撞和顺序模式；按预计总量重新计算碰撞预算。
• 生成大规模实例密钥，测量 4/8/10 字符碰撞；构造本机碰撞 UI 测试。
• URI 模糊测试：重复参数、超长值、大小写、百分号编码、IDN、端口、尾斜线、重定向、片段和未知版本。
• 已固定实例发生 origin/公钥变化时必须阻断；二维码不能静默覆盖。
• 从实例 A 复制用户 ID 到 B 不得解析为同一联系人。

待总控决策

• 实例短码长度：4、8 或 10；推荐至少 8，完整指纹始终为权威。
• 用户 ID 长度及是否增加校验位。
• HTTPS origin 的规范化规则和允许端口/路径。
• 二维码是否携带实例配置签名、联系人签名，及各自签名对象。
• 是否接受“未知实例手输地址无法自动发现”的 MVP 体验；推荐接受以避免全局目录。