Add comprehensive ticket validation with controlTicket function

[chtitux]

Summary

This PR introduces a complete ticket validation system for dosipas tickets, including a new controlTicket() function that performs comprehensive validation checks, a web UI component for ticket control, and supporting infrastructure.

Key Changes

Core Validation (src/control.ts)

• New controlTicket() function: Decodes a ticket once and runs 13 focused validation checks covering:

  • Header format and version validation
  • Security metadata completeness (Level 1 & 2)
  • Level 1 and Level 2 signature verification (async)
  • Ticket expiry validation (supports both U1 and U2 header formats)
  • Specimen/test ticket detection
  • Activation status verification
  • Issuing detail validation (year, day, issuer presence)
  • Transport document presence and validity
  • Intercode extension validation with optional network ID matching
  • Dynamic data format detection (FDC1, Intercode _RICS.ID1)
  • Dynamic content freshness checks with UTC offset support

• Check result aggregation: Each check returns a CheckResult with name, pass/fail status, severity level (error/warning/info), and optional message. Overall validity is determined by whether all error-severity checks pass.

• Flexible options: ControlOptions supports custom reference time, Level 1 key provider callback, and expected Intercode network ID validation.

Type Definitions (src/types.ts)

• Added ControlOptions, CheckResult, and ControlResult interfaces
• Added Level1KeyProvider interface for async key retrieval

Testing (tests/control.test.ts)

• Comprehensive test suite covering:
  • Decode failures and error handling
  • Real-world tickets (SNCF TER, Soléa, CTS, Grand Est)
  • Signature verification (Level 1 & 2)
  • Expiry validation with past/future dates
  • Specimen ticket detection
  • Tampered ticket detection
  • Network ID validation (matching and mismatches)
  • Dynamic content freshness calculations
  • Edge cases (missing issuer, no transport documents, etc.)

Web UI Components

• ControlTab.tsx: New tab component featuring:

  • Hex input with camera scanner integration
  • Overall status banner (valid/invalid with error/warning counts)
  • Traveler information display with formatted birthdates
  • Validation checks list grouped by severity
  • Check badges with icons and detailed messages
  • FIPS key trust toggle for Level 1 verification

• useTicketControl.ts: React hook for async ticket control with:

  • Debounced validation (200ms)
  • Key provider integration
  • Loading and error state management

App Integration

• Updated App.tsx to add Control tab navigation
• Added #control&hex=... URL hash support for sharing control results
• Integrated navigation between Decode, Encode, and Control tabs

Exports

• Exported controlTicket from main src/index.ts

Notable Implementation Details

• Expiry calculation: Handles both U1 headers (issuing date + duration) and U2 headers (end-of-validity year/day + time + duration)
• Dynamic content freshness: Supports FDC1 timestamps and Intercode dynamic data with UTC offset calculations
• Async signature verification: Level 1 verification requires a key provider callback; Level 2 uses embedded public key
• Severity-based validation: Distinguishes between critical errors, warnings, and informational checks for flexible validation policies
• Network ID validation: Optional Intercode network ID matching with hex string comparison

https://claude.ai/code/session_01E6k4nTRriYRsm3eAbyv4gd