# Safety

This file is the project's own list of everything OScope does and does not do on your computer. It is written to be
**checked against the code**, by you or by your AI. Each point names the file it lives in. If the code ever does
something this file does not say, that is a bug: please open an issue.

## What OScope never does

- It never asks for, reads, stores or sends a **private key, seed phrase or wallet file**. There is no place to enter one.
- It never **signs or sends a transaction**. It has no code that can.
- It has **no accounts, no logins, no tracking, no analytics** and no "phone home".
- It never **downloads or runs other code**. No auto-update, no `eval`, no scrambled or encoded code.
- It never reads or writes files **outside its own folder**. (It reads `.env` if you made one, and writes `data/`.)

Trading in OScope is **paper trading**: a practice wallet that exists only in your browser (`public/js/paper.js`).
No real SOL and no real coins are involved.

## What it connects to

All outgoing connections are made by the server, in two files. The server only *reads* from them; it sends no
information about you. (Like any web request, the other side sees your IP address.)

| Where | What for | Code |
|---|---|---|
| `wss://stream.pumpapi.io/` | The live trade stream. OScope listens; it sends nothing. You can change the address with `FEED_URL`. | `src/feed.mjs` `connectFeed` |
| `api.coinbase.com`, `api.kraken.com`, `api.binance.com` | The SOL price in dollars, every 20 seconds. The first that answers is used. | `src/feed.mjs` `solPrice` |
| The metadata and picture links of the coins you look at | Each coin's picture, description and social links. These addresses are chosen by whoever launched the coin. | `src/meta.mjs` |
| `ipfs.filebase.io`, `4everland.io`, `pump.mypinata.cloud` | Public IPFS gateways. Most coins keep their picture on IPFS; a link of that kind is asked for on these. You can change the list with `IPFS_GATEWAYS`. | `src/meta.mjs` `candidates`, `src/config.mjs` |

Because coin creators choose those addresses, every one is checked before it is fetched (`src/meta.mjs`
`safeUrl` and `get`):

- only `http` and `https`;
- never an address on your own computer or your local network (the name is looked up first; private, loopback and
  link-local addresses are refused);
- every redirect is checked the same way, three at most;
- size limits (256 KB for metadata, 6 MB for a picture) and an 8 second time limit.

`npm run doctor` and `npm run tape` also ask `api.coinbase.com` for the SOL price (`tools/`).

**Your browser** talks only to your own OScope server. The page's content policy (`csp` in `src/server.mjs`) allows
scripts, styles, fonts, pictures and connections from that server only: coin pictures reach the page through the
server, never straight from the internet. Links to pump.fun, Solscan and X open only when you click them, in a new
tab.

## What it listens on

- `127.0.0.1:3000` by default: **only your own computer**. If port 3000 is taken, the next free port.
- It answers only requests addressed to `localhost` / `127.0.0.1` (`hostOk` in `src/server.mjs`), so a website that
  points its own name at your computer gets nothing.
- Two websockets: `/ws` for the page and `/firehose` for your own tools. A web page from any other site cannot open
  either (the Origin check in the `upgrade` handler in `src/server.mjs`).
- It accepts only `GET` and `HEAD`. Nothing can be uploaded or changed through it.
- `HOST=0.0.0.0` opens it to other devices on your network. Only do that on a network you trust: it has no password.
- `npm run firehose` listens on `127.0.0.1:3100` and refuses every web page (`tools/firehose.mjs`).

## What it stores

- `data/coins.json` and `data/devs.json`: coins, trades and holders it saw. Public chain data, nothing about you.
- In your browser's local storage: your paper wallet, tracked wallet names, filters, hidden coins and settings.
  It stays in your browser. Settings → Export gives you a copy.

## What gets installed

- Two libraries and one helper, exact versions, with checksums in `package-lock.json`:
  [`ws`](https://github.com/websockets/ws) (websockets), [`lightweight-charts`](https://github.com/tradingview/lightweight-charts)
  (TradingView's open source chart library) and `fancy-canvas` (a helper `lightweight-charts` needs).
- `.npmrc` sets `ignore-scripts=true`: no package can run code while it installs.
- `package.json` has no install scripts.
- No build step. The files in `src/` and `public/` are what runs. The only minified file is the chart library's
  own release inside `node_modules/lightweight-charts/dist/`, as published on npm.

## Content from strangers

Coin names, descriptions, links and pictures are written by whoever launched the coin. OScope treats them as untrusted:

- names and descriptions are put on the page as plain text, never as HTML (`h()` in `public/js/util.js`);
- links must be `http` or `https`, and open in a new tab with no access to the OScope page (`safeHref` in
  `public/js/util.js`, `cleanLink` in `src/meta.mjs`);
- pictures are served with a policy that stops them from running scripts (the `/pic/` handler in `src/server.mjs`).

## Check it yourself

```sh
# every outgoing connection in the code
grep -rn "fetch(\|new WebSocket(" src tools public/js

# anything that touches files
grep -rn "node:fs\|node:child_process" src tools

# nothing runs at install
cat .npmrc
grep -n "\"scripts\"" -A 6 package.json

# keys, signing: there should be no match at all
grep -rniE "private.?key|secret.?key|seed phrase|mnemonic|signTransaction|sendTransaction|keypair" src tools public/js
```

## Found a problem?

Tell us on X: https://x.com/OScopetrade