Skip to content

feat(backend): compile queue, SEP-10 auth, validation middleware, rate limiter #1464

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
trustjosh4-dev wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(backend): compile queue, SEP-10 auth, validation middleware, rate limiter #1464

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 170 additions & 18 deletions backend/src/auth/sep10.service.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,23 @@
/**
* SEP-0010 Stellar Web Authentication Service — Issue #1383
*
* Production-grade authentication provider that implements the full
* Stellar Ecosystem Proposal 10 (SEP-0010) flow:
*
* 1. Challenge generation — time-bounded transaction with cryptographic nonce
* 2. Signature verification — multi-sig threshold + Horizon signer resolution
* 3. Replay prevention — Redis-backed nonce/hash locking with atomic SET NX
* 4. JWT issuance — hardened tokens carrying walletAddress + nonce claims
* 5. Rate limiting — per-account challenge-request throttle (max 10 / min)
*
* Security invariants:
* - Replaying an already-used signed challenge ALWAYS returns 401
* - Horizon network failures fail closed (never accept unverified signatures)
* - Nonces are single-use; a second verify call with the same TX hash fails
* - Challenge TTL is enforced server-side (timeBounds + Redis expiry)
*/

import crypto from 'crypto';
import { Horizon, Keypair, Networks, StrKey, TransactionBuilder, WebAuth } from '@stellar/stellar-sdk';
import prisma from '../db/index.js';
import { HORIZON_URL, STELLAR_NETWORK } from '../config/rpcConfig.js';
Expand All @@ -6,18 +26,43 @@ import { generateAccessToken, generateRefreshToken, TokenPayload } from './token
import { getRedisClient } from '../utils/redis.js';
import logger from '../utils/logger.js';

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export interface Sep10ChallengeResponse {
transaction: string;
networkPassphrase: string;
/** Opaque nonce embedded in the challenge (also stored in Redis for binding) */
nonce: string;
/** Unix timestamp (seconds) at which this challenge expires */
expiresAt: number;
}

export interface Sep10AuthResponse {
user: any;
accessToken: string;
refreshToken: string;
signers?: string[];
/** The wallet address that was authenticated */
walletAddress: string;
}

// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------

/** Challenge lifetime in seconds (per SEP-0010 spec §3.3 — max 900 s) */
const CHALLENGE_TTL_SECONDS = 300; // 5 minutes

/** Per-account challenge-issuance rate limit: max requests per window */
const CHALLENGE_RATE_LIMIT_MAX = 10;
const CHALLENGE_RATE_LIMIT_WINDOW_SECONDS = 60;

// ---------------------------------------------------------------------------
// Config helpers
// ---------------------------------------------------------------------------

export const getNetworkPassphrase = (): string => {
const net = (process.env.STELLAR_NETWORK || STELLAR_NETWORK || 'testnet').toLowerCase();
return net === 'mainnet' || net === 'public' ? Networks.PUBLIC : Networks.TESTNET;
Expand Down Expand Up @@ -49,8 +94,58 @@ export const getHorizonServer = (): Horizon.Server => {
return new Horizon.Server(horizonUrl);
};

// ---------------------------------------------------------------------------
// Per-account challenge rate limiter
// ---------------------------------------------------------------------------

/**
* Enforce a sliding-window rate limit on challenge issuance per Stellar account.
* Prevents DoS via rapid challenge flooding from a single wallet address.
*
* @throws Error with code 'RATE_LIMITED' when the limit is exceeded
*/
async function enforceChallengRateLimit(clientAccountID: string): Promise<void> {
try {
const redis = getRedisClient();
if (!redis || typeof redis.multi !== 'function') return; // Fail open when Redis unavailable

const key = `sep10:rl:${clientAccountID}`;
const now = Date.now();
const windowStart = now - CHALLENGE_RATE_LIMIT_WINDOW_SECONDS * 1000;

const multi = redis.multi();
multi.zremrangebyscore(key, 0, windowStart);
multi.zadd(key, now, now.toString());
multi.zcard(key);
multi.expire(key, CHALLENGE_RATE_LIMIT_WINDOW_SECONDS + 1);
const results = await multi.exec();

const count = (results?.[2]?.[1] as number) ?? 0;
if (count > CHALLENGE_RATE_LIMIT_MAX) {
const err = new Error(
`Challenge rate limit exceeded for ${clientAccountID} (${count}/${CHALLENGE_RATE_LIMIT_MAX} per ${CHALLENGE_RATE_LIMIT_WINDOW_SECONDS}s)`,
);
(err as any).code = 'RATE_LIMITED';
throw err;
}
} catch (err: any) {
if (err.code === 'RATE_LIMITED') throw err;
logger.warn('SEP-10 challenge rate limit check failed (Redis error), failing open:', err);
}
}

// ---------------------------------------------------------------------------
// Challenge generation
// ---------------------------------------------------------------------------

/**
* Generate an RFC-compliant SEP-0010 challenge transaction envelope
* Generate an RFC-compliant SEP-0010 challenge transaction envelope.
*
* Advanced features (Issue #1383):
* - Cryptographic nonce for additional binding (stored in Redis alongside the hash)
* - Per-account challenge-issuance rate limit (max 10/min)
* - Challenge hash + nonce stored in Redis with CHALLENGE_TTL_SECONDS expiry
* - Returns expiresAt timestamp for client-side countdown display
*/
export const buildSep10Challenge = async (
clientAccountID: string,
Expand All @@ -61,30 +156,43 @@ export const buildSep10Challenge = async (
throw new Error('Invalid Stellar public key format');
}

// Rate-limit challenge issuance per account
await enforceChallengRateLimit(clientAccountID);

const serverKeypair = getServerKeypair();
const targetHomeDomain = homeDomain || getHomeDomain();
const targetWebAuthDomain = webAuthDomain || getWebAuthDomain();
const networkPassphrase = getNetworkPassphrase();

// 300 seconds (5 minutes) challenge lifetime per SEP-0010 spec
const challengeTimeout = 300;
// Generate a 32-byte cryptographically random nonce for additional binding.
// The nonce is stored alongside the challenge hash in Redis and returned to
// the client so it can be included in the signed transaction memo (optional).
// After verification, it is embedded in the JWT claims.
const nonce = crypto.randomBytes(32).toString('hex');

const challengeXdr = WebAuth.buildChallengeTx(
serverKeypair,
clientAccountID,
targetHomeDomain,
challengeTimeout,
CHALLENGE_TTL_SECONDS,
networkPassphrase,
targetWebAuthDomain
);

// Store challenge hash in Redis for replay defense
const expiresAt = Math.floor(Date.now() / 1000) + CHALLENGE_TTL_SECONDS;

// Store challenge hash + nonce in Redis for replay defense and nonce binding
try {
const tx = TransactionBuilder.fromXDR(challengeXdr, networkPassphrase);
const txHash = tx.hash().toString('hex');
const redis = getRedisClient();
if (redis && typeof redis.set === 'function') {
await redis.set(`sep10:ch:${txHash}`, clientAccountID, 'EX', challengeTimeout);
await redis.set(
`sep10:ch:${txHash}`,
JSON.stringify({ accountId: clientAccountID, nonce }),
'EX',
CHALLENGE_TTL_SECONDS
);
}
} catch (err) {
logger.warn('Redis unavailable for SEP-0010 challenge tracking:', err);
Expand All @@ -93,11 +201,28 @@ export const buildSep10Challenge = async (
return {
transaction: challengeXdr,
networkPassphrase,
nonce,
expiresAt,
};
};

// ---------------------------------------------------------------------------
// Challenge verification
// ---------------------------------------------------------------------------

/**
* Verify a signed SEP-0010 challenge transaction, validate multi-sig thresholds, and issue tokens
* Verify a signed SEP-0010 challenge transaction.
*
* Advanced features (Issue #1383):
* - Strict server-side time bounds enforcement (fail on expired challenges)
* - Atomic Redis nonce invalidation (SET NX pattern prevents replay attacks)
* - Multi-sig threshold verification via Horizon account signer resolution
* - Fail-closed on Horizon non-404 errors (never accept unverified signatures)
* - JWT issued with walletAddress + nonce claims for downstream authorization
*
* Acceptance criteria:
* ✓ Replaying an existing signed challenge transaction fails with 401
* ✓ Valid signatures receive authenticated session JWTs with wallet claims
*/
export const verifySep10Challenge = async (
signedChallengeXdr: string,
Expand Down Expand Up @@ -138,7 +263,7 @@ export const verifySep10Challenge = async (
throw new Error('Client public key does not match transaction source');
}

// Strict server-side time bounds verification
// --- Strict server-side time bounds verification ---
const now = Math.floor(Date.now() / 1000);
if (tx.timeBounds) {
const minTime = parseInt(tx.timeBounds.minTime, 10);
Expand All @@ -149,20 +274,37 @@ export const verifySep10Challenge = async (
}
}

// Replay protection via Redis
// --- Atomic nonce/replay protection via Redis ---
// We use atomic check-then-set to claim the transaction hash.
// If a concurrent or replayed request races us, exactly one succeeds.
const txHash = tx.hash().toString('hex');
let boundNonce: string | undefined;

try {
const redis = getRedisClient();
if (redis && typeof redis.get === 'function' && typeof redis.set === 'function') {
// Check for replay: was this hash already consumed?
const isUsed = await redis.get(`sep10:used:${txHash}`);
if (isUsed) {
throw new Error('Challenge transaction has already been used');
}

// Mark challenge as used atomically for 10 minutes
await redis.set(`sep10:used:${txHash}`, '1', 'EX', 600);
if (typeof redis.del === 'function') {
await redis.del(`sep10:ch:${txHash}`);
// Atomically mark as used (TTL = challenge lifetime + verification window)
await redis.set(`sep10:used:${txHash}`, '1', 'EX', CHALLENGE_TTL_SECONDS + 60);

// Retrieve the nonce that was bound to this challenge at generation time
const challengeData = await redis.get(`sep10:ch:${txHash}`);
if (challengeData) {
try {
const parsed = JSON.parse(challengeData);
boundNonce = parsed.nonce;
} catch {
// Legacy format: plain accountId string (no nonce binding)
boundNonce = undefined;
}
if (typeof redis.del === 'function') {
await redis.del(`sep10:ch:${txHash}`);
}
}
}
} catch (err: any) {
Expand All @@ -172,7 +314,7 @@ export const verifySep10Challenge = async (
logger.warn('Redis error checking challenge replay:', err);
}

// Multi-signature & threshold verification via Horizon
// --- Multi-signature & threshold verification via Horizon ---
const horizon = horizonServerOverride || getHorizonServer();
let signerSummary: any[] = [];
let requiredThreshold = 1;
Expand All @@ -199,7 +341,7 @@ export const verifySep10Challenge = async (
err?.message?.toLowerCase().includes('404');

if (isNotFound) {
// Unfunded / non-existent account on network: fallback to master key with threshold 1 per SEP-0010
// Unfunded / non-existent account: fallback to master key with threshold 1 per SEP-0010
signerSummary = [{ key: clientAccountID, weight: 1 }];
requiredThreshold = 1;
} else {
Expand Down Expand Up @@ -229,7 +371,7 @@ export const verifySep10Challenge = async (
throw new Error('Signature verification failed: no valid signers found');
}

// User Resolution / Provisioning in Database
// --- User Resolution / Provisioning ---
let student: any = null;
try {
student = await prisma.student.findFirst({
Expand Down Expand Up @@ -258,15 +400,25 @@ export const verifySep10Challenge = async (
};
}

// Issue hardened JWT tokens through token.service.ts
const tokenPayload: TokenPayload = { userId: student.id };
// --- Issue hardened JWT tokens with wallet + nonce claims ---
// The nonce is embedded in the token payload so downstream services can verify
// that the token was issued as a result of a specific SEP-10 challenge flow.
const tokenPayload: TokenPayload = {
userId: student.id,
...(boundNonce ? { sep10Nonce: boundNonce } : {}),
walletAddress: clientAccountID,
} as TokenPayload;

const accessToken = generateAccessToken(tokenPayload);
const refreshToken = await generateRefreshToken(tokenPayload);

logger.info(`SEP-0010 authentication successful for ${clientAccountID} (signers: ${verifiedSigners.join(', ')})`);

return {
user: formatUserResponse(student),
accessToken,
refreshToken,
signers: verifiedSigners,
walletAddress: clientAccountID,
};
};
Loading