Sign-In (SIWX)
Let users sign in by approving a CAIP-122 authentication request in D9 Wallet. Your backend verifies the cryptographic proof and establishes a session. Sign-in is off-chain and incurs no fee.
Prerequisites: walletRuntime from Quickstart and a backend capable of persisting single-use challenges.
1. Issue a challenge (backend)
Section titled “1. Issue a challenge (backend)”Generate a fresh challenge for each sign-in attempt, persist it in your database, and return it to the frontend:
| Field | Value |
|---|---|
domain |
Your exact frontend domain, e.g. dapp.example.com |
uri |
Your exact audience URI |
chains |
["d9net:000000000000000000000000000000d9"] |
nonce |
Cryptographically random, single-use string (16–128 characters) |
requestId |
A fresh UUID |
iat, exp |
ISO 8601 UTC timestamps to the second; use a short TTL (e.g. 5 minutes) |
statement |
Plain-text prompt shown to the user describing what they are signing in to |
2. Request wallet approval (frontend)
Section titled “2. Request wallet approval (frontend)”Pass the backend challenge to requestWalletSignIn. It displays the pairing UI, waits for wallet approval, and returns the single CACAO proof (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));
// Dismiss the pairing UI as soon as the wallet connects 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("Expected exactly one approved authentication"); } return auth; })).pipe(Effect.ensuring(Effect.sync(hidePairing))), );}3. Submit the proof to your backend (frontend)
Section titled “3. Submit the proof to your backend (frontend)”Send auth to your backend as-is. Do not trust or pass a separate user-supplied address—your backend derives the authenticated address directly from the verified proof.
The CACAO proof contains three sections:
h:{ t: "caip122" }p:domain,iss(did:pkh:d9net:...:<address>),nonce,aud,exp,request_id, and related fieldss: signature algorithm (sr25519,ed25519, orecdsa), hex signature, and public key
4. Verify the proof and issue a session (backend)
Section titled “4. Verify the proof and issue a session (backend)”Perform all verification strictly on the server—never trust client-side assertions:
- Look up the stored challenge by
nonceandrequest_id. Confirm it exists, is unexpired, and has not been consumed. - Verify
nbf <= now <= expagainst server time. - Reconstruct the canonical sign-in message from the stored challenge using
serializeD9SiwxMessagefrom@d9-network/dapp-connector/protocol. - Verify the signature over
<Bytes>${siwxMessage}</Bytes>. - Confirm that the public key in
scorresponds to the address inp.iss; that address identifies the signed-in user. - In a single atomic database transaction, mark the challenge as consumed and issue your session cookie or token to prevent replay attacks.
Verify
Section titled “Verify”- A valid sign-in proof creates a backend session.
- Replaying the exact same proof fails at step 4.1.
If the wallet or connector returns an error, check the authentication_* codes in Troubleshooting.
