SIWE message validation and SIWE_DOMAIN

Every wallet signature this platform accepts is checked against a strict EIP-4361 parser in backend/src/utils/siwe.ts. It reads the whole message, not a few fields out of it, and it refuses anything that is not addressed to this site, is not version 1, or is outside its validity window — before it spends the nonce or calls out to verify the signature.

The practical consequence for you is one configuration decision and one class of failure. The decision is which host name the platform considers to be itself. The failure is that a user browsing to any other host cannot sign in with a wallet, no matter how correct their signature is.

The expected domain

expectedSiweDomain() resolves one host name, and the message must claim it. The expectation is taken from configuration and never from the request's Host header, because the caller controls that header on their own request.

There is no fail-open path here. If neither variable is usable the endpoint returns 500 rather than skipping the check, so a wallet login cannot be completed against an install that has not decided what it is called.

SIWE_DOMAIN holds exactly one value. It is not a list, and nothing splits it on commas.

It is backend-only, so a restart is enough

Unlike NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID, SIWE_DOMAIN is never compiled into the frontend bundle, and it is read from process.env each time a message is validated rather than once at module load. Editing .env and running pnpm restart is sufficient — there is no frontend rebuild in this loop. See Installing Wallet Connect for the variable that does need one.

The browser decides what the message claims

Both signing paths build the message from the page they are running on:

const siweMessage = new SiweMessage({
  domain: window.location.host,     // line 163
  address: account.address,
  statement: "Sign in with Ethereum to P2P Platform",
  uri: window.location.origin,      // line 166
  version: "1",
  chainId: Number.parseInt(String(network.chainId || "1")),
  nonce: await fetchServerNonce(),
  issuedAt: new Date().toISOString(),
  expirationTime: new Date(Date.now() + 5 * 60_000).toISOString(),
});

frontend/app/[locale]/(dashboard)/user/profile/components/tabs/wallet-tab.tsx builds the identical object for linking.

So the claimed domain is whatever host the user typed. Any reachable host that is not the configured one produces a 401 at sign-in, even though it serves the same application from the same database.

Two things follow, and both are operational rather than cosmetic.

Redirect the aliases, do not serve on them. The sample configuration in Nginx names both example.com and www.example.com on one server_name line, so both hosts serve the application — and only one of them can carry wallet sign-in. Add a 301 from the alias to the canonical host, or accept that half your users cannot use the feature.

A local or staging install needs its own value. The stock NEXT_PUBLIC_SITE_URL="http://localhost" resolves to localhost while pnpm dev serves the frontend on port 3000, so wallet sign-in fails on every fresh development box until you set SIWE_DOMAIN=localhost:3000 or correct NEXT_PUBLIC_SITE_URL to include the port.

The URI: line is checked the same way: its host must equal the expected domain. A value that is not a parseable absolute URL fails the same test, since the host it yields is the empty string.

What the parser enforces

On success the parser returns three values and nothing else: the address lowercased (matching the lowercasing setter on providerUser.providerUserId, so the lookup does not depend on the table's collation), the chain id in eip155:<id> form, and the nonce.

What is not checked

The statement line is parsed but never compared. Both signing paths hard-code it to "Sign in with Ethereum to P2P Platform", which is what your users see in their wallet's approval sheet regardless of your branding; there is no setting that changes it. Request ID and Resources are skipped. Nothing validates the address's EIP-55 checksum — the signature recovery in verifySignature is what proves the address, and it is case-insensitive.

The validity window and your server clock

There are two independent bounds on age.

The five-minute expiry the frontend writes. Both signing paths set expirationTime to five minutes after the browser's current time. This is the bound that fires in practice.

The ten-minute cap on Issued At. Applied unconditionally, so a third-party client that omits Expiration Time is still bounded. Issued At missing, or unparseable — the string yesterday, for example — is treated as stale rather than as fresh.

Both are evaluated against the server's clock and both timestamps come from the browser's clock, so what actually matters is the difference between them.

A whole platform reporting expired or stale on the first attempt is a clock problem, not a user problem. Confirm with timedatectl on the app server and make sure NTP is actually synchronising, because nothing else in the platform is this sensitive to a fast clock.

The nonce's own Redis TTL is also 300 seconds, so a user who leaves the wallet prompt open long enough to trip the message expiry is usually about to trip the nonce expiry as well. The messages differ — SIWE message has expired comes from the parser, Invalid or expired login nonce from the Redis consume — but the remedy is the same: start again.

Where validation sits in the login sequence

POST /api/auth/login/wallet runs these in order and stops at the first failure. The steps are narrated to the request log under the LOGIN module, so the last recorded step names the check that failed.

Step 5 runs before step 6, deliberately. A message that fails validation does not burn the user's nonce, so they can retry immediately with the same one until its 300-second TTL runs out — which matters, because the nonce endpoint and the login endpoint share a rate-limit budget of five requests per fifteen minutes.

The same validation runs on linking, and on unlinking

parseAndValidateSiwe(message, expectedSiweDomain()) is called from three handlers, with the same expectations and the same error strings in each:

So a linking failure and a login failure have identical causes. If a user reports that Connect wallet on /user/profile?tab=wallet fails, everything on this page applies unchanged — a misconfigured SIWE_DOMAIN breaks both, and fixing it fixes both. The connect handler's order is the same as the login handler's, with an authentication check ahead of it and a duplicate-address check behind it; it logs under the WALLET module rather than LOGIN.

With that setting on, the disconnect handler additionally requires that the signed address equals the address being unlinked, answering 401 "Signature does not match the address being unlinked." when it does not.

Reading the failures

Every one of these responses carries the exact string as HTTP JSON in the shape { "message": "…", "statusCode": 401 }.

Once you have the string, it maps straight back:

Related

• Wallets, chains and endpoints — the chain allow-list the parsed chain id is checked against.
• The sign-in flow — the nonce, the session and the 2FA gate that follow validation.
• Linking a wallet — the connect handler in full.
• Troubleshooting.