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)
```json
{
  "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
```typescript
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
```typescript
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