# Security

> Security model and threat documentation for PYRE. Aligned with
> [`PYRE_MVP_DESIGN.md`](PYRE_MVP_DESIGN.md) §3, §16, and §17 — when in doubt, the
> design doc wins.

PYRE is a wallet-cleanup tool. Its entire value proposition rests on trust:
users connect a wallet and let PYRE help them destroy or close token accounts.
That only works if PYRE can never harm the user, never take custody of funds, and
never hide what it is doing.

---

## Core trust rule

> **Recovered ATA rent returns to the user by default.**

Rent must **never** be silently taxed, redirected, pooled, or counted as Essence
unless a future version creates an explicit opt-in donation mode.

For the MVP:

- Recovered rent goes to the user.
- Burned junk does **not** count as Essence.
- Swapped scraps may become Essence **only if the user explicitly approves**.
- Any optional SOL contribution must be separate and explicit.
- All actions require wallet approval.
- **PYRE never has custody of private keys.**

> **PYRE returns your rent. The scraps feed the fire.**

---

## Wallet security

- **Never request private keys.**
- **Never run custodial signing.**
- **Never auto-execute without the user signing** locally in their own wallet.
- **Always show a transaction preview** before any signature is requested.
- **Decode the transaction before signing.**
- **Match the decoded transaction against the preview** (accounts to close,
  tokens to burn, rent amount, rent destination, fees, warnings). If the decoded
  transaction does not match the preview, do not sign.

---

## Token safety

- Unknown assets default to **skip**.
- Token-2022 defaults to **skip** for the MVP.
- NFTs default to **skip**.
- Valuable assets default to **skip**.
- The user must **manually select** anything risky.
- High-value actions require **stronger confirmation**.

For the full classifier specification — categories, allowed actions, the
"Unknown means skip" rule, and the complete safety checklist — see
[`TOKEN_CLASSIFICATION.md`](TOKEN_CLASSIFICATION.md).

---

## Backend security

- **Rate-limit scan endpoints.**
- **Validate wallet pubkeys.**
- **Validate token-account ownership** (the account must belong to the wallet).
- **Do not trust client-submitted classifications** — recompute classification
  server-side before building any transaction.
- **Log all transaction build requests.**
- **Protect admin endpoints.**
- **Use environment secrets only.**
- **Rotate API keys if leaked.**

---

## AI safety

- **Filter** generated names, tickers, and lore.
- **Avoid** hate, explicit, extremist, copyrighted, impersonation, and scam-like
  outputs.
- **Require human approval before first launches.** Prometheus generates a
  candidate package for human review; it never launches tokens directly.

---

## Abuse scenarios

Reproduced from design doc §17. Each is stated as **Risk → Defense**.

### Misclassification of valuable asset

- **Risk:** The classifier mislabels a valuable token and the user loses it.
- **Defense:** Protected token registry, USD value threshold, major-token skip
  list, and manual advanced override only.

### Fake dust farming

- **Risk:** A user creates many fake tokens to inflate their status.
- **Defense:** No allocation by token count, no reward by account count; Essence
  weighting only in future versions.

### Rent confusion

- **Risk:** People claim PYRE steals rent.
- **Defense:** The receipt clearly shows rent returned, the transaction preview
  clearly shows the destination, and rent is not pooled by default.

### AI output abuse

- **Risk:** Prometheus generates an offensive or copyrighted token.
- **Defense:** Safety filters, blocked terms, ticker collision checks, and human
  approval in the MVP.

### Pump.fun launch abuse

- **Risk:** Spawn launches look like team-rug launches.
- **Defense:** Manual review, public launch record, no profit promises, clear
  entertainment framing, and disclosure of the launch wallet / creator.

---

## No private keys, anywhere

PYRE is non-custodial by design. There is intentionally **no private-key or
mnemonic environment variable anywhere in the project**, and there never will be.
All signing happens client-side in the user's wallet. Any change that introduces
key custody, mnemonic handling, or custodial signing violates the core trust
rule and must be rejected.