chore: scaffold PYRE MVP monorepo (structure + docs)
pnpm + TypeScript workspace per design doc §13:
- apps/{web,api,worker} skeletons (Next.js 16, Fastify 5, BullMQ)
- packages/{core,solana,prometheus,db,config} (core has real types/DTOs;
solana/prometheus are stubs)
- programs/pyre-core placeholder (future Anchor, v1.0)
- docs/: PYRE_MVP_DESIGN (canonical), ARCHITECTURE, SECURITY, TOKEN_CLASSIFICATION
- CLAUDE.md, README, .env.example (no private-key var by design)
Skeleton + docs only — no Solana/business logic yet. All workspaces typecheck clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
128
docs/SECURITY.md
Normal file
128
docs/SECURITY.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user