Kiwy-Signage/working_files/CARD_READER_AUTHENTICATION.md

# USB Card Reader Authentication

This document describes the USB card reader authentication feature for the Kiwy Signage Player.

## Overview

The player now supports user authentication via USB card readers when accessing the edit/drawing interface. When a user clicks the edit button (pencil icon), they must swipe their card to authenticate before being allowed to edit the image.

## How It Works

1. **Edit Button Click**: User clicks the pencil icon to edit the current image
2. **Validation Checks**:
   - Verify current media is an image (not video)
   - Check if editing is allowed for this media (`edit_on_player` permission from server)
3. **Card Reader Prompt**:
   - Display "Please swipe your card..." message
   - Wait for card swipe (5 second timeout)
   - Read card data from USB card reader
   - Store the card data (no validation required)
4. **Open Edit Interface**: Edit interface opens with card data stored
5. **Save & Upload**: When user saves the edited image:
   - Card data is included in the metadata JSON
   - Both image and metadata (with card data) are uploaded to server
   - Server receives `user_card_data` field for tracking who edited the image

## Card Reader Setup

### Hardware Requirements
- USB card reader (HID/keyboard emulation type)
- Compatible cards (magnetic stripe or RFID depending on reader)

### Software Requirements
The player requires the `evdev` Python library to interface with USB input devices:

```bash
# Install via apt (recommended for Raspberry Pi)
sudo apt-get install python3-evdev

# Or via pip
pip3 install evdev
```

### Fallback Mode
If `evdev` is not available, the player will:
- Log a warning message
- Use a default card value (`DEFAULT_USER_12345`) for testing
- This allows development and testing without hardware

## Card Data Storage

The card data is captured as a raw string and stored without validation or mapping:

- **No preprocessing**: Card data is stored exactly as received from the reader
- **Format**: Whatever the card reader sends (typically numeric or alphanumeric)
- **Sent to server**: Raw card data is included in the `user_card_data` field of the metadata JSON
- **Server-side processing**: The server can validate, map, or process the card data as needed

### Metadata JSON Format
When an image is saved, the metadata includes:
```json
{
  "time_of_modification": "2025-12-08T10:30:00",
  "original_name": "image.jpg",
  "new_name": "image_e_v1.jpg",
  "original_path": "/path/to/image.jpg",
  "version": 1,
  "user_card_data": "123456789"
}
```

If no card is swiped (timeout), `user_card_data` will be `null`.

## Testing the Card Reader

A test utility is provided to verify card reader functionality:

```bash
cd /home/pi/Desktop/Kiwy-Signage/working_files
python3 test_card_reader.py
```

The test tool will:
1. List all available input devices
2. Auto-detect the card reader (or let you select manually)
3. Listen for card swipes and display the data received
4. Show how the data will be processed

### Test Output Example
```
✓ Card data received: '123456789'
  Length: 9 characters
  Processed ID: card_123456789
```

## Implementation Details

### Main Components

1. **CardReader Class** (`main.py`)
   - Handles USB device detection
   - Reads input events from card reader
   - Provides async callback interface
   - Includes timeout handling (5 seconds)

2. **Card Read Flow** (`show_edit_interface()` method)
   - Validates media type and permissions
   - Initiates card read
   - Stores raw card data
   - Opens edit popup

3. **Metadata Creation** (`_save_metadata()` method)
   - Includes card data in metadata JSON
   - No processing or validation of card data
   - Sent to server as-is

### Card Data Format

Card readers typically send data as keyboard input:
- Each character is sent as a key press event
- Data ends with an ENTER key press
- Reader format: `[CARD_DATA][ENTER]`

The CardReader class:
- Captures key press events
- Builds the card data string character by character
- Completes reading when ENTER is detected
- Returns the complete card data to the callback

### Security Considerations

1. **Server-Side Validation**: Card validation should be implemented on the server
2. **Timeout**: 5-second timeout prevents infinite waiting for card swipe
3. **Logging**: All card reads are logged with the raw card data
4. **Permissions**: Edit permission must be enabled on the server (`edit_on_player`)
5. **Raw Data**: Card data is sent as-is; server is responsible for validation and authorization

## Troubleshooting

### Card Reader Not Detected
- Check USB connection
- Run `ls /dev/input/` to see available devices
- Run the test script to verify detection
- Check `evdev` is installed: `python3 -c "import evdev"`

### Card Swipes Not Recognized
- Verify card reader sends keyboard events
- Test with the `test_card_reader.py` utility
- Check card format is compatible with reader
- Ensure card is swiped smoothly at proper speed

### Card Data Not Captured
- Check card data format in logs
- Enable debug logging to see raw card data
- Test in fallback mode (without evdev) to isolate hardware issues
- Verify card swipe completes within 5-second timeout

### Permission Denied Errors
- User may need to be in the `input` group:
  ```bash
  sudo usermod -a -G input $USER
  ```
- Reboot after adding user to group

## Future Enhancements

Potential improvements for the card reader system:

1. **Server Validation**: Server validates cards against database and returns authorization
2. **Card Enrollment**: Server-side UI for registering new cards
3. **Multiple Card Types**: Support for different card formats (barcode, RFID, magnetic)
4. **Client-side Validation**: Add optional local card validation before opening edit
5. **Audit Trail**: Server tracks all card usage with timestamps
6. **RFID Support**: Test and optimize for RFID readers
7. **Barcode Scanners**: Support USB barcode scanners as alternative
8. **Retry Logic**: Allow re-swipe if card read fails

## Related Files

- `/src/main.py` - Main implementation (CardReader class, authentication flow)
- `/src/edit_drowing.py` - Drawing/editing interface (uses authenticated user)
- `/working_files/test_card_reader.py` - Card reader test utility
- `/requirements.txt` - Dependencies (includes evdev)