# Security

## What is secret in this project

| Value | Sensitivity | Why |
|---|---|---|
| `local_key` (per device) | **Secret** | The AES key material for the BLE and LAN sessions. Anyone holding it (within radio/LAN range of the device) can control it. |
| `local_key` (gateway) | **Secret** | One key authorizes **every sub-device behind the gateway**, so treat it as the most sensitive value in the file. |
| `device_id`, `uuid`, `node_id` | Private identifier | Permanently identify your specific unit. Useless for control without a `local_key`, but there is no reason to publish them — and unlike a key, they can never be rotated. |
| `product_id` | Public | Shared by every unit of a model (for example, `mknd4lci` is *all* Finger Robot 2s), so it identifies the product, not you. |
| Tuya IoT **Access ID / Secret** | **Secret** | Cloud API credentials used for the one-time `local_key` pull (API Explorer or `tinytuya wizard`). They are never needed at runtime — don't store them in this repo at all. |

## Where secrets live

All device credentials go in `config.toml` in the repo root, which is
**git-ignored**. Start from the committed template:

```bash
cp config.example.toml config.toml
```

Rules:

- Never commit `config.toml` (or force-add it).
- Never paste real values into code, tests, commit messages, issues, or PRs.
  Unit tests use synthetic credentials only (`testdevice000000000001`,
  `uuidTESTtest0000`, `abcdef0123456789`).
- Files produced by credential-pulling tools (such as `tinytuya wizard`'s
  `devices.json`, `tuya-raw.json`, `snapshot.json`, `tinytuya.json`) contain
  secrets — keep them out of the repo and delete them once `config.toml` is
  populated. `.gitignore` covers the known names.

## Rotation

`local_key` rotates whenever the device is re-paired in the Smart Life app.
If a key is ever exposed: re-pair the device, then re-pull the new key from
the Tuya IoT console (**Cloud → API Explorer →** `GET /v1.0/devices/{id}`).
`device_id`, `uuid`, and `node_id` are burned into the device and cannot be
rotated.

## Scanning

[gitleaks](https://github.com/gitleaks/gitleaks) scans the **full git
history** in CI on every push and pull request
([`.github/workflows/gitleaks.yml`](.github/workflows/gitleaks.yml)).
Run it locally before pushing:

```bash
gitleaks git . --no-banner
```

[`.gitleaks.toml`](.gitleaks.toml) allowlists the synthetic test credentials
and the `YOUR_*` placeholders from `config.example.toml` so real findings
stand out.

## Reporting

If you believe you've found a security issue in the protocol implementations,
open a GitHub issue — nothing here touches infrastructure beyond your own LAN
and your own devices.