登录认证 (SIWX)
让用户在 D9 钱包中批准一次 CAIP-122 认证请求,随后由后端校验密码学凭证并建立会话。整个过程在链下完成,不产生任何手续费。
前置条件: 已配置快速上手中的 walletRuntime,并具备可持久化存储一次性 Challenge 的后端服务。
1. 生成登录 Challenge(后端)
Section titled “1. 生成登录 Challenge(后端)”为每次登录请求生成全新的 Challenge,写入数据库后再返回给前端:
| 字段 | 说明 |
|---|---|
domain |
精确的前端域名,例如 dapp.example.com |
uri |
精确的目标受众 URI |
chains |
["d9net:000000000000000000000000000000d9"] |
nonce |
密码学随机、一次性的防重放字符串(16–128 位字符) |
requestId |
全新的 UUID |
iat、exp |
精确到秒的 ISO 8601 UTC 时间戳;建议使用较短有效期(如 5 分钟) |
statement |
展示给用户的纯文本说明,清晰描述登录目的 |
2. 请求钱包签署认证(前端)
Section titled “2. 请求钱包签署认证(前端)”将后端下发的 Challenge 传入 requestWalletSignIn,函数会展示配对界面、等待钱包确认并返回唯一的 CACAO 认证凭证(auth):
import { Effect, Schema } from "effect";import { D9DAppConnector } from "@d9-network/dapp-connector";import { D9AuthenticateParamsSchema } from "@d9-network/dapp-connector/protocol";import { walletRuntime } from "./wallet";
export async function requestWalletSignIn( challengePayloadFromBackend: unknown, showPairing: (uri: string, cancel: () => Promise<void>) => void, hidePairing: () => void,) { return walletRuntime.runPromise( Effect.scoped(Effect.gen(function* () { const connector = yield* D9DAppConnector; const params = yield* Schema.decodeUnknownEffect(D9AuthenticateParamsSchema)( challengePayloadFromBackend, );
const start = yield* connector.authenticate(params); showPairing(start.uri, () => walletRuntime.runPromise(start.cancel));
// 钱包连上后立即关闭配对界面 yield* Effect.forkScoped( Effect.gen(function* () { yield* start.walletConnected; yield* Effect.sync(hidePairing); }), );
const result = yield* start.response; const [auth] = result.auths; if (result.auths.length !== 1 || !auth) { throw new Error("预期仅返回一条已批准的认证凭证"); } return auth; })).pipe(Effect.ensuring(Effect.sync(hidePairing))), );}3. 将凭证提交至后端(前端)
Section titled “3. 将凭证提交至后端(前端)”原样将 auth POST 至后端接口。不要依赖前端额外传入的账户地址——后端应直接从通过校验的凭证中提取登录地址。
CACAO 凭证由三部分组成:
h:{ t: "caip122" }p:domain、iss(did:pkh:d9net:...:<address>)、nonce、aud、exp、request_id等载荷字段s:签名算法(sr25519、ed25519或ecdsa)、十六进制签名与公钥
4. 校验凭证并签发会话(后端)
Section titled “4. 校验凭证并签发会话(后端)”所有校验都必须在服务端严格执行,切勿信任浏览器端提交的声明:
- 根据
nonce与request_id查询数据库中的 Challenge,确认记录存在、未过期且未被使用。 - 以服务端当前时间校验
nbf <= now <= exp。 - 使用
@d9-network/dapp-connector/protocol的serializeD9SiwxMessage,基于服务端存储的 Challenge 重新拼装规范 SIWX 消息。 - 对
<Bytes>${siwxMessage}</Bytes>验证签名。 - 确认
s中的公钥与p.iss中的地址匹配,该地址即为已认证的登录用户。 - 在同一个原子数据库事务中将 Challenge 标记为已消费,并签发会话 Cookie 或 Token,彻底防止重放攻击。
- 首次提交有效凭证成功获得后端会话。
- 再次提交同一凭证会在第 4.1 步被拒绝。
若钱包或连接器抛出异常,请查阅问题排查中的 authentication_* 错误码。
