blackcanyontickets/reactrebuild0825/QR_SPEC.md

QR Code Specification for Black Canyon Tickets

Overview

This document defines the QR code specification for Black Canyon Tickets, including payload formats, security models, encoding standards, and fallback mechanisms for reliable ticket validation.

QR Code Format Versions

Version 1: Simple Ticket ID (Current Implementation)

Format: TICKET_{UUID}

• Example: TICKET_123e4567-e89b-12d3-a456-426614174000
• Use Case: Basic ticket scanning with server-side validation
• Security: Relies entirely on server-side validation and database lookup
• Size: ~50 characters, generates small QR codes

Version 2: Signed Token (Enhanced Security)

Format: BCT.v2.{base64-payload}.{signature}

• Example: BCT.v2.eyJ0aWNrZXRJZCI6IjEyMyIsImV2ZW50SWQiOiI0NTYifQ.abc123signature
• Use Case: Tamper-proof tickets with offline validation capability
• Security: HMAC-SHA256 signed tokens prevent forgery
• Size: ~150 characters, generates larger but still scannable QR codes

QR Encoding Standards

Technical Specifications

• QR Version: Auto-select (typically Version 3-7 depending on payload)
• Error Correction: Level M (15% data recovery) - balanced redundancy
• Character Encoding: UTF-8 for international character support
• Module Size: Minimum 3px for mobile scanning reliability
• Quiet Zone: 4 modules minimum border around QR code

Size Requirements

• Minimum Print Size: 25mm x 25mm (1 inch x 1 inch)
• Recommended Print Size: 30mm x 30mm for thermal printers
• Maximum Size: No upper limit, but diminishing returns after 50mm
• Mobile Display: Minimum 150px x 150px on screen

Payload Specifications

Version 1 Payload (Simple)

Format: TICKET_{ticketId}
ticketId: UUID v4 format (36 characters with hyphens)

Version 2 Payload (Signed Token)

{
  "v": 2,                    // Version number
  "tid": "ticket-uuid",      // Ticket ID (UUID)
  "eid": "event-uuid",       // Event ID (UUID)  
  "iat": 1640995200,        // Issued at (Unix timestamp)
  "exp": 1641081600,        // Expires at (Unix timestamp)
  "zone": "GA",             // Optional: Ticket zone/section
  "seat": "A12"             // Optional: Seat assignment
}

Signature Algorithm: HMAC-SHA256 Signing Key: Environment variable QR_SIGNING_SECRET (32+ bytes) Token Structure: BCT.v2.{base64(payload)}.{base64(signature)}

Security Model

Threat Protection

1. Counterfeiting: Signed tokens prevent fake ticket generation
2. Replay Attacks: Server-side tracking of used tickets
3. Enumeration: UUIDs prevent ticket ID guessing
4. Tampering: HMAC signatures detect payload modification
5. Expiration: Time-based token expiry prevents old ticket reuse

Offline Validation

• Version 1: No offline validation possible
• Version 2: Signature validation possible without server connection
• Timestamp validation ensures tokens haven't expired
• Zone/seat validation for assigned seating events

Key Management

• Production: Rotate signing keys quarterly
• Development: Use fixed key for testing consistency
• Key Storage: Environment variables, never in code
• Backup Keys: Maintain previous key for transition periods

Manual Entry Fallback

Backup Code Format

Format: Last 8 characters of ticket UUID (alphanumeric)

• Example: If ticket ID is 123e4567-e89b-12d3-a456-426614174000, backup code is 74174000
• Input Method: Numeric keypad optimized for gate staff
• Validation: Same server API as QR scanning

Manual Entry UI Requirements

• Large Buttons: Minimum 60px touch targets
• High Contrast: White text on dark background
• Glove-Friendly: Works with work gloves and stylus
• Clear Display: Large font showing entered digits
• Error Feedback: Visual and audio feedback for invalid codes
• Quick Clear: Easy way to clear entry and start over

Fallback Scenarios

1. Damaged QR Codes: Paper torn, thermal printing faded
2. Poor Lighting: Dark venues, bright sunlight
3. Camera Issues: Device camera malfunction, lens dirty
4. Network Outages: Server down, internet connectivity issues
5. Staff Preference: Some staff prefer manual entry for speed

Implementation Guidelines

QR Code Generation

interface QRGenerationOptions {
  format: 'simple' | 'signed';
  errorCorrection: 'L' | 'M' | 'Q' | 'H';
  moduleSize: number;
  quietZone: number;
  backgroundColor: string;
  foregroundColor: string;
}

// Recommended settings for tickets
const ticketQROptions: QRGenerationOptions = {
  format: 'signed',           // Use signed tokens for security
  errorCorrection: 'M',       // 15% error correction
  moduleSize: 3,              // 3px per module
  quietZone: 4,               // 4 modules border
  backgroundColor: '#FFFFFF', // White background
  foregroundColor: '#000000'  // Black foreground
};

Validation Logic

interface QRValidationResult {
  valid: boolean;
  format: 'simple' | 'signed' | 'unknown';
  ticketId?: string;
  eventId?: string;
  errorReason?: 'invalid_format' | 'expired' | 'signature_invalid' | 'malformed';
  metadata?: {
    issuedAt?: number;
    expiresAt?: number;
    zone?: string;
    seat?: string;
  };
}

Error Handling

• Invalid Format: Clear error message with suggested manual entry
• Expired Tokens: Specific message about ticket expiration
• Signature Errors: Generic "invalid ticket" message (don't expose crypto details)
• Network Errors: Offline fallback with sync when connected
• Duplicate Scans: Clear indication of already-used tickets

Migration Strategy

Phase 1: Dual Format Support (Current)

• Support both simple and signed QR formats
• Generate simple QRs for existing events
• Use signed QRs for new events
• Scanner detects format automatically

Phase 2: Signed Token Default

• Default to signed tokens for all new tickets
• Maintain backward compatibility with simple format
• Update email templates and print layouts

Phase 3: Deprecate Simple Format

• Phase out simple ticket IDs over 6 months
• Migrate existing tickets to signed format
• Remove simple format support from scanners

Print and Display Guidelines

Thermal Printer Settings

• Resolution: 203 DPI minimum
• Print Speed: Medium (reduce burning/fading)
• Density: Medium-high for clear contrast
• Paper: Use high-quality thermal paper for longevity

Email Template Integration

• Size: 150px x 150px for email display
• Format: PNG with transparent background
• Fallback: Include backup code as text below QR
• Mobile Wallet: Apple Wallet and Google Pay compatible formats

Kiosk Display

• Screen Size: Minimum 200px x 200px display
• Brightness: High contrast mode for bright environments
• Backup Display: Show manual entry code alongside QR
• Timeout: QR code visible for 60 seconds minimum

Testing and Quality Assurance

QR Code Testing

• Device Coverage: Test on iOS Safari, Android Chrome, various camera hardware
• Print Quality: Test thermal printers, inkjet, laser printers
• Lighting Conditions: Indoor, outdoor, low-light scanning
• Distance Testing: Various scanning distances and angles

Security Testing

• Token Forgery: Attempt to create fake signed tokens
• Replay Attacks: Test duplicate ticket usage detection
• Timing Attacks: Verify constant-time signature validation
• Key Rotation: Test seamless key transitions

Manual Entry Testing

• Staff Usability: Test with actual gate staff in realistic conditions
• Glove Testing: Verify functionality with work gloves
• Error Recovery: Test invalid code entry and correction flows
• Performance: Measure entry speed vs QR scanning

Integration Points

Ticket Creation Flow

1. Generate UUID for ticket
2. Create signed token with metadata
3. Generate QR code image
4. Store QR data in database
5. Include in email and print templates

Scanning Validation Flow

1. Detect QR format (simple vs signed)
2. For signed: verify signature and expiration
3. Extract ticket ID and metadata
4. Call verification API
5. Handle response and update UI
6. Log scan result and sync offline queue

Manual Entry Flow

1. Staff taps keypad icon
2. Modal opens with numeric entry
3. Staff enters backup code
4. System validates format and calls API
5. Same success/error handling as QR scan
6. Log manual entry with source indicator

Performance Considerations

QR Generation Performance

• Caching: Cache generated QR images to avoid regeneration
• Async Generation: Generate QRs in background during ticket creation
• Image Optimization: Use appropriate compression for storage/transmission
• CDN Distribution: Serve QR images from CDN for faster loading

Scanning Performance

• Client-side Validation: Validate signed tokens locally before API call
• Debouncing: Prevent rapid-fire scanning of same ticket
• Offline Storage: Queue scans locally when network unavailable
• Background Sync: Sync queued scans in background when online

Manual Entry Optimization

• Predictive Input: Auto-format as user types (hyphens, spacing)
• Recent Codes: Cache recently entered codes for quick retry
• Validation Debouncing: Wait for complete entry before validation
• Keyboard Shortcuts: Support hardware keyboard shortcuts for staff

Compliance and Standards

Accessibility (WCAG 2.1 AA)

• Contrast: Minimum 4.5:1 contrast ratio for QR codes
• Alt Text: Descriptive alternative text for screen readers
• Keyboard Navigation: Full keyboard access to manual entry
• Screen Reader: Announce scan results and entry feedback

Privacy Considerations

• Data Minimization: Only include necessary data in QR payloads
• Anonymization: Don't include customer PII in QR codes
• Retention: Clear scan logs after event completion + 30 days
• Consent: Inform customers about QR code data collection

Industry Standards

• ISO/IEC 18004: QR Code 2005 standard compliance
• GS1 Standards: Optional GS1 application identifier compatibility
• NFC Forum: Consider NFC as additional touch-free option
• Mobile Wallet: Apple Wallet and Google Pay integration standards

Future Enhancements

Version 3: Advanced Features

• Multi-ticket QRs: Single QR for multiple tickets/guests
• Dynamic QRs: Time-rotating codes for enhanced security
• Biometric Binding: Link QR to photo ID or biometric data
• Smart Contracts: Blockchain-based ticket authenticity

Technology Improvements

• Computer Vision: Enhanced QR detection in difficult conditions
• Machine Learning: Predictive text for manual entry
• Augmented Reality: AR overlay for scanning guidance
• Voice Input: Voice-to-text backup entry option

Integration Expansions

• Third-party Wallets: Samsung Pay, PayPal, etc.
• Social Platforms: Share tickets via social media
• Calendar Integration: Automatic calendar event creation
• Transit Integration: Link with public transportation