> For the complete documentation index, see [llms.txt](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/security.md).

# Security

## Threat model

The assets worth protecting are:

1. **Account-scoped rows** — profiles, wallets, watchlists, alerts and trade history, protected by RLS scoped to `auth.uid()`.
2. **`ZEROX_API_KEY`** — a leaked key is billable third-party abuse.
3. **`ROBINHOOD_RPC_URL`** — a leaked private RPC is quota theft.
4. **The quote endpoint** — an unvalidated proxy lets anyone spend our key on arbitrary pairs.
5. **The user's funds** — protected by exact allowances and pre-signature re-validation.

## Controls

| Control             | Implementation                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| Secret isolation    | `process.env` read inside handlers in `*.server.ts` only; no `VITE_` secret ever                   |
| Import protection   | `.server.ts` suffix blocks the file from client bundles                                            |
| Input validation    | Zod on every server function input                                                                 |
| Token allowlist     | Only canonical addresses accepted; no arbitrary address proxying                                   |
| Chain pinning       | `chainId` must equal `4663` exactly                                                                |
| Slippage bounds     | Rejected outside a safe range                                                                      |
| Rate limiting       | Per-IP: 30/60s indicative, 12/60s firm quote                                                       |
| Error sanitizing    | `sanitizeError()` strips upstream bodies, URLs, and keys                                           |
| Eligibility         | Client-persisted **and** server-enforced; fails closed                                             |
| Approvals           | Exact amount, to `issues.allowance.spender` only                                                   |
| Tx re-validation    | Chain, taker, tokens, amounts checked before signing                                               |
| Headers             | CSP and secure headers set on the server handler                                                   |
| Row-level security  | Enabled on every public table, with grants issued in the same migration                            |
| Role checks         | `user_roles` + `SECURITY DEFINER` `has_role()`, kept out of the public API schema                  |
| Server-only tables  | `siwe_nonces` and `ai_insights` have no policies at all                                            |
| Append-only history | `alert_events` and `transaction_records` expose no client `UPDATE`/`DELETE` beyond acknowledgement |
| AI inputs           | Reality Check snapshots carry no wallet address, account ID, or holdings                           |
| Admin client        | Service-role client imported inside handlers only, never for ordinary reads                        |
| Logging             | No keys, seed phrases, signed-message contents, or eligibility details logged                      |

## Non-custodial guarantees

* No private key is generated, requested, stored, or transmitted.
* No seed phrase is ever requested. Any UI asking for one is not this app.
* The server never signs or broadcasts a transaction.
* Approvals are always exact-amount; `maxUint256` is never used as an approval value.

## Error handling policy

Check `response.ok` before parsing. Log the upstream status and a generic message server-side; return a sanitized `{ code, message }` to the client. Never relay an upstream body — it can contain the request URL including query parameters.

If a gateway or upstream call fails, surface the failure. Do not retry against a different endpoint and do not fall back to fabricated data.

## Reporting a vulnerability

Open a private security advisory on the repository rather than a public issue. Include reproduction steps and affected routes or functions. Do not include live secrets in the report.

## Pre-launch requirement

The compliance controls here are engineering mechanisms, not legal clearance. Production launch requires qualified legal review — stated in the app on `/about` and in [Disclaimers](/bubblegum-reality-docs/compliance/disclaimers.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/security.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.