BreakEscape/planning_notes/rfid_keycard/00_OVERVIEW.md

# RFID Keycard Lock System - Overview

## Executive Summary

This document outlines the implementation of a new RFID keycard lock system with Flipper Zero-style interface for the BreakEscape game. The system includes:

1. **RFID Lock Type**: New lock type that accepts keycards
2. **Keycard Items**: Physical keycards with unique IDs
3. **RFID Cloner Device**: Flipper Zero-inspired tool for cloning/emulating cards
4. **Two Minigame Modes**:
   - **Unlock Mode**: Tap keycard or emulate cloned card to unlock
   - **Clone Mode**: Read and save keycard data

## User Stories

### Story 1: Player Uses Valid Keycard
1. Player approaches RFID-locked door
2. Player has matching keycard in inventory
3. Player clicks door → RFID minigame opens
4. Interface shows "Tap Card" prompt
5. Player clicks to tap → Door unlocks instantly
6. Success message: "Access Granted"

### Story 2: Player Uses RFID Cloner to Emulate
1. Player has previously cloned a keycard using RFID cloner
2. Player approaches locked door without physical card
3. Player has rfid_cloner in inventory
4. Minigame opens showing Flipper Zero interface
5. Interface shows: "RFID > Saved > Emulate"
6. Shows saved tag: "Emulating [EM4100] Security Card"
7. Player confirms → Door unlocks
8. Success message with Flipper Zero style feedback

### Story 3: Player Clones NPC's Keycard via Conversation
1. Player talks to NPC who has keycard
2. Conversation choice appears: "[Secretly clone keycard]"
3. Ink tag triggers: `# clone_keycard:Security Officer|4AC5EF44DC`
4. RFID cloner minigame opens in clone mode
5. Flipper Zero interface shows:
   ```
   RFID > Read
   "Reading 1/2"
   "> ASK PSK"
   "Don't move Card..."

   "EM-Micro EM4100"
   "Hex: 4A C5 EF 44 DC"
   "FC: 239 Card: 17628 CL: 64"
   "DEZ 8: 15680732"

   [Save] [Cancel]
   ```
6. Player clicks Save → Card saved to cloner memory
7. Can now emulate this card to unlock doors

### Story 4: Player Clones Own Keycard
1. Player has keycard in inventory
2. Player has rfid_cloner in inventory
3. Player clicks keycard in inventory
4. RFID cloner minigame opens in clone mode
5. Same reading/saving process as Story 3
6. Player can now use either physical card or emulation

### Story 5: Player Tries Wrong Card
1. Player approaches door requiring "CEO Keycard"
2. Player has "Security Keycard" instead
3. Minigame shows tap interface
4. Player taps → "Access Denied - Invalid Card"
5. Door remains locked

## System Architecture

### Components

```
RFID Keycard System
├── Lock Type: "rfid"
│   └── Requires: keycard_id (e.g., "ceo_keycard")
│
├── Items
│   ├── Keycard (type: "keycard")
│   │   ├── key_id: "ceo_keycard"
│   │   ├── rfid_hex: "4AC5EF44DC"
│   │   ├── rfid_facility: 239
│   │   └── rfid_card_number: 17628
│   │
│   └── RFID Cloner (type: "rfid_cloner")
│       └── saved_cards: []
│
├── Minigame: RFIDMinigame
│   ├── Mode: "unlock"
│   │   ├── Show available cards
│   │   ├── Show saved emulations
│   │   └── Tap/Emulate action
│   │
│   └── Mode: "clone"
│       ├── Show reading animation
│       ├── Display card data
│       └── Save to cloner
│
└── Ink Integration
    └── Tag: # clone_keycard:name|hex
```

## Key Features

### 1. Flipper Zero-Style Interface
- **Authentic UI**: Matches Flipper Zero's monospaced, minimalist design
- **Navigation**: RFID > Read/Saved > Emulate
- **Card Reading**: Shows ASK/PSK modulation animation
- **Card Data Display**: Hex, Facility Code, Card Number, DEZ format

### 2. Realistic RFID Workflow
- **EM4100 Protocol**: Industry-standard 125kHz RFID tags
- **Hex ID Format**: 5-byte hex strings (e.g., "4A C5 EF 44 DC")
- **Facility Codes**: Organization identifiers (0-255)
- **Card Numbers**: Unique card IDs within facility
- **DEZ 8 Format**: 8-digit decimal representation

### 3. Dual Usage Modes
- **Physical Cards**: Direct unlock with matching keycard
- **Cloner Device**: Read, save, and emulate cards
- **Stealth Cloning**: Clone NPC cards during conversation
- **Inventory Cloning**: Clone your own cards

### 4. Integration with Existing Systems
- **Lock System**: Extends unlock-system.js with 'rfid' case
- **Minigame Framework**: Uses base-minigame.js foundation
- **Ink Conversations**: New tag for triggering clone mode
- **Inventory System**: Clickable keycards trigger cloning

## Technical Specifications

### RFID Card Data Structure
```javascript
{
  type: "keycard",
  name: "CEO Keycard",
  key_id: "ceo_keycard",           // Matches lock's "requires"
  rfid_hex: "4AC5EF44DC",           // 5-byte hex ID
  rfid_facility: 239,               // Facility code (0-255)
  rfid_card_number: 17628,          // Card number
  rfid_protocol: "EM4100"           // Protocol type
}
```

### RFID Cloner Data Structure
```javascript
{
  type: "rfid_cloner",
  name: "RFID Cloner",
  saved_cards: [
    {
      name: "Security Officer",
      hex: "4AC5EF44DC",
      facility: 239,
      card_number: 17628,
      protocol: "EM4100",
      cloned_at: "2024-01-15T10:30:00Z"
    }
  ]
}
```

### RFID Lock Definition
```json
{
  "room_server": {
    "locked": true,
    "lockType": "rfid",
    "requires": "ceo_keycard"
  }
}
```

## Implementation Benefits

### For Game Design
- **New Puzzle Type**: Social engineering (clone NPC cards)
- **Stealth Mechanic**: Secretly clone cards without detection
- **Tech Realism**: Authentic hacking tool experience
- **Progressive Challenge**: Start with cards, upgrade to cloner

### For Players
- **Tactile Feedback**: Flipper Zero UI is satisfying to use
- **Learning**: Teaches real RFID concepts
- **Flexibility**: Multiple solutions to locked doors
- **Collection**: Collect and organize cloned cards

### For Story
- **Mission Variety**: Infiltration missions requiring card cloning
- **Character Interaction**: NPCs with different access levels
- **Escalation**: Low-level cards → Clone higher access
- **Consequences**: Using wrong card could trigger alarms

## Alignment with Existing Systems

### Similar to Keys/Pintumbler
- **Lock Type**: Same pattern as "key" lock type
- **Item Matching**: key_id matches requires field
- **Minigame**: Same framework as lockpicking minigame
- **Success Flow**: Same unlock callback pattern

### Differences
- **No Lockpicking**: Can't pick RFID locks (unlike key locks)
- **Cloning Mechanic**: Unique to RFID system
- **Digital Data**: Hex IDs instead of physical pin heights
- **Inventory Interaction**: Clicking cards triggers cloning

## Success Criteria

### Must Have
- ✅ RFID lock type works in scenarios
- ✅ Keycards unlock matching doors
- ✅ RFID cloner can save cards
- ✅ Cloner can emulate saved cards
- ✅ Flipper Zero UI is recognizable
- ✅ Ink tag triggers clone mode
- ✅ Clicking inventory cards triggers clone

### Should Have
- ✅ Reading animation is smooth
- ✅ Card data displays correctly
- ✅ Multiple cards can be saved
- ✅ UI matches Flipper Zero aesthetic
- ✅ Error messages for wrong cards

### Could Have
- 🔄 Sound effects for card read/tap
- 🔄 Animation for card tap
- 🔄 Visual feedback on Flipper screen
- 🔄 Multiple RFID protocols (EM4100, HID, etc.)
- 🔄 Card writing/modification

## Out of Scope (Future Enhancements)

- RFID frequency analysis
- Custom card programming
- RFID jamming/blocking
- NFC support (different from RFID)
- Badge photos/visual cards
- Access control system hacking