跳转到内容

登录认证 (SIWX)

让用户在 D9 钱包中批准一次 CAIP-122 认证请求,随后由后端校验密码学凭证并建立会话。整个过程在链下完成,不产生任何手续费。

前置条件: 已配置快速上手中的 walletRuntime,并具备可持久化存储一次性 Challenge 的后端服务。

为每次登录请求生成全新的 Challenge,写入数据库后再返回给前端:

字段 说明
domain 精确的前端域名,例如 dapp.example.com
uri 精确的目标受众 URI
chains ["d9net:000000000000000000000000000000d9"]
nonce 密码学随机、一次性的防重放字符串(16–128 位字符)
requestId 全新的 UUID
iat、exp 精确到秒的 ISO 8601 UTC 时间戳;建议使用较短有效期(如 5 分钟)
statement 展示给用户的纯文本说明,清晰描述登录目的

将后端下发的 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))),
);
}

原样将 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. 校验凭证并签发会话(后端)”

所有校验都必须在服务端严格执行,切勿信任浏览器端提交的声明:

  1. 根据 nonce 与 request_id 查询数据库中的 Challenge,确认记录存在、未过期且未被使用。
  2. 以服务端当前时间校验 nbf <= now <= exp。
  3. 使用 @d9-network/dapp-connector/protocol 的 serializeD9SiwxMessage,基于服务端存储的 Challenge 重新拼装规范 SIWX 消息。
  4. 对 <Bytes>${siwxMessage}</Bytes> 验证签名。
  5. 确认 s 中的公钥与 p.iss 中的地址匹配,该地址即为已认证的登录用户。
  6. 在同一个原子数据库事务中将 Challenge 标记为已消费,并签发会话 Cookie 或 Token,彻底防止重放攻击。
  • 首次提交有效凭证成功获得后端会话。
  • 再次提交同一凭证会在第 4.1 步被拒绝。

若钱包或连接器抛出异常,请查阅问题排查中的 authentication_* 错误码。