Bridge API Reference

Complete API reference for the Bridge Validation system.

BridgeValidator Class

The BridgeValidator class handles session validation with Flowless.

Constructor

class BridgeValidator {
  constructor(config?: {
    flowlessApiUrl?: string;
    validationSecret?: string;
    timeout?: number;
    retryAttempts?: number;
  })
}

Parameters:

Parameter	Type	Default	Description
flowlessApiUrl	string	process.env.FLOWLESS_API_URL	Flowless API URL
validationSecret	string	process.env.BRIDGE_VALIDATION_SECRET	Bridge secret key
timeout	number	5000	Request timeout (ms)
retryAttempts	number	3	Number of retry attempts

Example:

import { BridgeValidator } from './lib/auth/bridge-validator';

const validator = new BridgeValidator({
  flowlessApiUrl: 'https://your-instance.pubflow.com',
  validationSecret: 'your-bridge-secret',
  timeout: 5000,
  retryAttempts: 3
});

Methods

validateSession()

Validates a session with Flowless backend.

async validateSession(sessionId: string): Promise<ValidationResult>

Parameters:

Parameter	Type	Required	Description
sessionId	string	✅ Yes	Session ID to validate

Returns: Promise<ValidationResult>

interface ValidationResult {
  success: boolean;
  session?: SessionData;
  error?: string;
  cached?: boolean;
}

interface SessionData {
  user_id: string;
  email: string;
  name: string;
  user_type?: string;
  organization_id?: string;
  permissions?: string[];
  expires_at?: string;
  validated_at: string;
}

Example:

const result = await validator.validateSession('session_123');

if (result.success && result.session) {
  console.log('User ID:', result.session.user_id);
  console.log('Email:', result.session.email);
  console.log('Cached:', result.cached);
} else {
  console.error('Validation failed:', result.error);
}

healthCheck()

Checks the health of the Flowless connection.

async healthCheck(): Promise<HealthCheckResult>

Returns: Promise<HealthCheckResult>

interface HealthCheckResult {
  success: boolean;
  latency?: number;
  error?: string;
}

Example:

const health = await validator.healthCheck();

if (health.success) {
  console.log(`✅ Flowless is healthy (${health.latency}ms)`);
} else {
  console.error(`❌ Flowless is down: ${health.error}`);
}

Validation Modes

Configure security levels for session validation.

Environment Variable

VALIDATION_MODE=STANDARD

Available Modes

Mode	IP Check	User-Agent Check	Device ID Check	Use Case
DISABLED	❌	❌	❌	Development only
STANDARD	✅	❌	❌	Basic security
ADVANCED	✅	✅	❌	Recommended
STRICT	✅	✅	✅	Maximum security

Example:

// In your environment config
const config = {
  VALIDATION_MODE: 'ADVANCED' // IP + User-Agent validation
};

Caching

The Bridge Validator automatically caches valid sessions using LRU cache.

Cache Configuration

SESSION_VALIDATION_CACHE_TTL=300  # 5 minutes

Cache Behavior

• Cache Hit: Returns cached session data (1-2ms)
• Cache Miss: Validates with Flowless (20-50ms)
• Auto-Invalidation: Cache expires after TTL
• Max Size: 1000 sessions (configurable)

Example:

// First call - Cache MISS (validates with Flowless)
const result1 = await validator.validateSession('session_123');
console.log('Cached:', result1.cached); // false

// Second call - Cache HIT (returns from cache)
const result2 = await validator.validateSession('session_123');
console.log('Cached:', result2.cached); // true

Error Handling

Common Errors

Error	Status	Description	Solution
Session ID is required	400	Missing session ID	Provide session ID
Invalid session	401	Session not found or expired	Re-authenticate user
Bridge secret mismatch	403	Invalid bridge secret	Check BRIDGE_VALIDATION_SECRET
Flowless unreachable	503	Cannot connect to Flowless	Check FLOWLESS_API_URL

Example:

try {
  const result = await validator.validateSession(sessionId);
  
  if (!result.success) {
    // Handle validation failure
    console.error('Validation failed:', result.error);
    return { error: result.error };
  }
  
  // Success
  return { user: result.session };
  
} catch (error) {
  // Handle network/system errors
  console.error('System error:', error);
  return { error: 'Service unavailable' };
}

Best Practices

1. ✅ Use caching - Reduces latency and Flowless load
2. ✅ Set appropriate TTL - Balance security and performance
3. ✅ Use VALIDATION_MODE=STRICT in production
4. ✅ Handle errors gracefully - Provide clear error messages
5. ✅ Monitor health - Regular health checks
6. ✅ Log validation attempts - Track failed validations

See Also

• Bridge Validation Guide
• Validation Modes
• Auth Middleware