# 4 · Theft & Stolen Keys

Configure and operate carjacking, lockpick, hotwire and stolen-key cleanup.

# Carjacking

Carjacking can start automatically when a player holds aim on an NPC driver with an allowed firearm.

```lua
Config.Carjacking = {
    Enabled = true,
    AimHoldMs = 850,
    DurationMs = 3200,
    CooldownMs = 10000,
    GiveKeysOnSuccess = true,
    SuccessChance = 100,
    AlarmChance = 35,
    RequireWeapon = true,
}
```

The NPC/vehicle action is reserved and validated server-side. The finish step validates the reserved vehicle, plate, action token, timing and distance without depending on volatile NPC network ownership.

Blocked melee, utility and throwable weapons can be configured through `Config.Carjacking.BlockedWeapons`.


# Lockpick

Lockpick configuration:

```lua
Config.Lockpick = {
    Enabled = true,
    Item = 'lockpick',
    DurationMs = 6500,
    Difficulty = 4,
    BreakChanceOnFail = 35,
    AlarmChanceOnFail = 70,
    AlarmChanceOnSuccess = 15,
    GiveKeysWhenKeysFoundInside = true,
}
```

The configured inventory bridge validates and removes the item when required.

Command:

```text
/lockpick
```

Developer client export:

```lua
exports.nord_vehiclekeys:StartLockpick(vehicle)
```


# Hotwire

Hotwire configuration:

```lua
Config.Hotwire = {
    Enabled = true,
    Item = nil,
    DurationMs = 9000,
    Difficulty = 6,
    FailCooldownMs = 3500,
    AlarmChanceOnFail = 65,
    AlarmChanceOnSuccess = 20,
}
```

Set `Item` to an item name if a hotwire kit should be required. When `nil`, no item is required.

Command:

```text
/nordkeys_hotwire
```

Developer client export:

```lua
exports.nord_vehiclekeys:StartHotwire(vehicle)
```


# Stolen Key Lifecycle

Keys obtained through NPC theft, lockpick-found-keys or hotwire are temporary stolen/session keys.

```lua
Config.StolenKeys = {
    RemoveOnVehicleExit = true,
    MaxDurationSeconds = 900,
    ExitGraceMs = 1200,
    ServerCheckMs = 750,
}
```

Default behaviour:

1. The stolen key is issued for the specific vehicle.
2. The player can use the vehicle normally while the stolen key is valid.
3. After the player enters the vehicle and later exits it, the stolen key is revoked.
4. The physical `vehicle_key` item for that stolen access is removed.
5. A safety timeout removes abandoned session keys even if the player never enters the vehicle.

Permanent owner/shared/admin keys are not removed by the stolen-key cleanup flow.


# Blocked Vehicle Classes

The theft system can block GTA vehicle classes and models.

Default blocked classes:

```lua
Config.Theft.BlockedClasses = {
    [14] = true, -- boats
    [15] = true, -- helicopters
    [16] = true, -- planes
    [18] = true, -- emergency
    [19] = true, -- military
    [21] = true, -- trains
}
```

Specific models can also be blocked:

```lua
Config.Theft.BlockedModels = {
    'rhino',
}
```