Wallet Authentication

​

Flow

1. Frontend detects Freighter.
2. Frontend requests a challenge from the backend.
3. Backend creates a one-time message with wallet, nonce, domain, network, and expiration.
4. Worker signs the message with Freighter signMessage.
5. Frontend submits challenge ID, wallet address, and signature.
6. Backend verifies the signature with SEP-53 message hashing and returns a bearer session.

​

Request Challenge

POST /api/v1/auth/challenge
Content-Type: application/json

{
  "walletAddress": "G..."
}

​

Verify Challenge

POST /api/v1/auth/verify
Content-Type: application/json

{
  "challengeId": "challenge_123",
  "walletAddress": "G...",
  "signature": "base64-signature"
}

​

Security Rules

• Challenges expire quickly.
• Nonces are one-time use.
• Signatures are never logged.
• Challenge messages include network passphrase.
• Backend verification hashes Stellar Signed Message:\n plus the challenge message before checking the Ed25519 signature.
• Sessions should be revocable before production use.