01. Gen6 MW Authentication

Authentication

Gen6 dApps uses a two-tier authentication system combining blockchain wallet signatures with JWT tokens for secure API access (all provided through G6 MW instance(s)).

Overview

Authentication requires:

1. Polkadot Wallet - User must have a connected wallet (via extension or Google auth)

2. JWT Token - User must sign a challenge to prove wallet ownership

The JWT token is stored in an HttpOnly cookie and included automatically in all API requests.

Authentication Flow

Step 1: Get Challenge

Request a signing challenge from the backend.

Endpoint: POST /auth/challenge

Request:

const response = await fetch(`${apiUrl}/auth/challenge`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    public_address: g6_address // SS58-355 encoded address
  })
})

const data = await response.json()

Request Body:

interface ChallengeRequest {
  public_address: string // SS58-355 encoded Gen6 address
}

Response:

interface ChallengeResponse {
  challenge: string // Random challenge string to sign
}

Example:

{
  "challenge": "7f8a9b3c..."
}

---

Step 2: Sign Challenge

Sign the challenge using the Polkadot wallet.

Implementation:

import { getSigner } from '@/packages/auth/lib/signer'

// Get signer based on authentication method
const signerResult = await getSigner(
  authMethod,
  authState.walletAddress,
  authState.googleAccessToken,
  api
)

if (!signerResult.signer.signRaw) {
  throw new Error('signRaw is not available on the signer')
}

// Sign the challenge
const signature = await signerResult.signer.signRaw({
  address: g6_address,
  data: challenge,
  type: 'bytes'
})

const signedChallenge = signature.signature

---

Step 3: Verify Signature

Send the signed challenge to verify and obtain a JWT token.

Endpoint: POST /auth/verify

Request:

const response = await fetch(`${apiUrl}/auth/verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    public_address: g6_address,
    signature: signature,
    origin: authMethod === 'google' ? 'google' : 'native'
  })
})

Request Body:

interface VerifyRequest {
  public_address: string // SS58-355 encoded address
  signature: string // Hex-encoded signature from wallet
  origin: string // 'google' or 'native' (auth method identifier)
}

Response:

• Sets HttpOnly cookie with JWT token

• Returns success status

Cookie Details:

• Name: Session cookie (managed by backend)

• HttpOnly: true (not accessible via JavaScript)

• Secure: true (HTTPS only in production)

• SameSite: Lax

---

Step 4: Verify Authentication Status

Check if the current user is authenticated.

Endpoint: GET /auth/jwt_ping

Implementation:

import axiosInstance from '@/packages/auth/api/axiosInstance'

export const queryJWTPing = async () => {
  const response = await axiosInstance.get('/auth/jwt_ping')
  return response.data
}

Response:

The response structure depends on the backend implementation. Check the actual response format returned by the backend.

Usage in React:

import useIsAuthenticated from '@/packages/auth/hooks/useIsAuthenticated'

function Component() {
  const { isAuthenticated } = useIsAuthenticated()

  if (!isAuthenticated) return <div>Please log in</div>

  return <div>Welcome!</div>
}

Query Configuration:

useQuery({
  queryKey: ['jwtPing', g6_address],
  queryFn: queryJWTPing,
  enabled: !!g6_address && hasAuthMethod,
  retry: false,
  staleTime: 5 * 60 * 1000, // 5 minutes
  gcTime: 10 * 60 * 1000,
  refetchOnWindowFocus: true,
  refetchOnReconnect: true
})

---

Faucet

Request test tokens from the faucet.

Endpoint: POST /faucet/request

Requirements:

• Authenticated user (JWT token in HttpOnly cookie)

Request:

const response = await fetch(`${getApiUrl()}/faucet/request`, {
  method: 'POST',
  credentials: 'include'
})

Response:

interface FaucetResponse {
  success: boolean
  tx_hash?: string
  amount?: string
}

Note: Faucet is automatically called after successful authentication for Google auth users.

---

Route Guards

Protect routes with authentication checks.

Pattern:

import { createFileRoute } from '@tanstack/react-router'
import { useGen6 } from 'gen6-context'
import { useIsAuthenticated } from '@/packages/auth/hooks/useIsAuthenticated'
import { Unlogged } from '@/components/unlogged'
import { Unauthorized } from '@/components/unauthorized'

export const Route = createFileRoute('/protected-route')({
  component: RouteComponent
})

function RouteComponent() {
  const { currentAccount } = useGen6()
  const { isAuthenticated } = useIsAuthenticated()

  // First tier: Check wallet connection
  if (!currentAccount) {
    return <Unlogged />
  }

  // Second tier: Check JWT authentication
  if (!isAuthenticated) {
    return <Unauthorized />
  }

  // User is fully authenticated
  return <ProtectedPage />
}

---

Complete Authentication Hook

The useAuthorize hook combines all authentication steps.

Location: src/packages/auth/hooks/useAuthorize.tsx

Usage:

import useAuthorize from '@/packages/auth/hooks/useAuthorize'

function LoginButton() {
  const { authorize, isLoading } = useAuthorize((success) => {
      if (success) {
        toast.success('Successfully authenticated!')
      } else {
        toast.error('Authentication failed')
      }
  })

  // Trigger authorize when needed (e.g. implicitly or via button)
  const handleLogin = () => {
    authorize()
  }

  return (
    <button onClick={handleLogin} disabled={isLoading}>
      {isLoading ? 'Authenticating...' : 'Login'}
    </button>
  )
}

Implementation Details:

export function useAuthorize(
  setAuthenticationStatus: (success: boolean) => void
) {
  const { currentAccount } = useGen6()

  const authorize = async () => {
    // 1. Get challenge
    // 2. Sign challenge (handles Google/Wallet differences)
    // 3. Verify signature
    // 4. Reset/Invalidate queries
    // 5. Call setAuthenticationStatus(true/false)
  }

  return { authorize, isLoading }
}

---

Axios Configuration

All authenticated API calls use the centralized axios instance.

Location: src/packages/auth/api/axiosInstance.ts

Configuration:

import axios from 'axios'
import { getApiUrl } from '@/data/nodes'

export const axiosInstance = axios.create({
  baseURL: getApiUrl(),
  headers: {
    'Content-Type': 'application/json'
  },
  withCredentials: true // Include cookies
})

---

Security Best Practices

JWT Token Management

1. HttpOnly cookies - Tokens not accessible via JavaScript (XSS protection)

2. Secure flag - HTTPS only in production

---

Common Issues

"Authentication failed"

• Cause: Wallet not connected or signature invalid

• Solution: Ensure wallet extension is installed and unlocked

"CORS error"

• Cause: Origin not whitelisted on backend

• Solution: Verify origin parameter matches backend whitelist

---

Address Encoding

Gen6 uses SS58 address format with prefix 355.

Conversion:

import { encodeAddress } from '@polkadot/util-crypto'

// Convert to Gen6 address format
const g6_address = encodeAddress(publicKey, 355)

Example:

Public Key: 0x1234...
Gen6 Address: g6x1234... (SS58-355)

Always use the Gen6-encoded address for API requests.

---

Next Steps

• Identity Management - Create and manage user profiles

• Real-Seal - Sign documents and texts

• Ncrypt - Send encrypted messages