# Money Proof Forge

**Know what you can safely spend today, what happens over the next 30 days, and why.**

Money Proof Forge is a self-hosted cash-flow control tower for people whose money spans banks, currencies, cash, credit cards, and crypto. It combines current balances with dated income and obligations, then produces an explainable forecast for the next decision.

This is a working personal system, released early for people who prefer auditable code and local control over a polished universal finance platform.

## What it does

- separates owned funds from available credit;
- forecasts cash flow from balances and dated events;
- edits or cancels one future occurrence without changing the recurring schedule;
- models credit-card statement payments and shows their basis;
- tracks cash purchases and receipt files;
- converts the full dashboard between USD, RUB, and AMD;
- shares a revocable, read-only summary;
- exposes read-only financial tools through MCP for Codex and compatible ChatGPT clients;
- keeps the T-Bank browser session on your Mac through a local bridge.

The product never initiates payments, transfers, card changes, or bank settings changes.

## The core model

```text
owned bank funds + cash
+ confirmed future income
- upcoming obligations
- credit-card payment
- savings reserve
= explainable safe-to-spend
```

Cancelled events stay visible but leave every forecast. Adjusted events preserve the original recurring rule. Stale bank data or an unknown card payment blocks a definitive spending recommendation instead of inventing precision.

## Architecture

```text
T-Bank in a dedicated Chrome profile on macOS
                    │
                    │ normalized read-only snapshots
                    ▼
              Money Bridge
                    │
                    ▼
 Fastify + SQLite + server-rendered PWA + MCP
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
     phone/desktop       Codex or ChatGPT
```

Bank passwords, SMS codes, cookies, and browser storage stay on the Mac. The server receives normalized account, balance, transaction, and credit-card data. Payment and settings routes are blocked in the bridge.

## Run locally

Requirements: Node.js 22+, Docker Compose, and macOS for the current T-Bank bridge.

```sh
cp .env.example .env
# Replace every placeholder secret in .env.
docker compose up --build
```

Open `http://localhost:3088`.

The MCP endpoint is `http://localhost:3088/mcp` and expects:

```text
Authorization: Bearer <APP_AUTH_TOKEN>
```

## Connect the macOS bridge

Build the project, save the bridge token in a local file with owner-only permissions, then run:

```sh
npm run build
node scripts/install-money-bridge.mjs /path/to/bridge-token http://localhost:3088 personal-mac
```

The installer creates a dedicated Chrome profile and a macOS LaunchAgent. Log in only inside that profile. The bridge can sync while the dashboard runs elsewhere.

## Current scope

- The bundled plan contains demonstration values. Edit the seed data before a fresh personal deployment.
- The bank connector targets T-Bank and relies on its current authenticated web flows.
- IDBank, Unibank, automatic TRC-20 income detection, and receipt OCR are not implemented.
- This software provides planning information, not financial advice.

## Security

Read [SECURITY.md](SECURITY.md) before exposing an instance to the internet. Use long independent secrets, HTTPS, rate limits, a firewall, encrypted backups, and a dedicated bridge profile. Never commit `.env`, SQLite data, browser profiles, receipt uploads, or exported bank files.

Please report vulnerabilities privately. Do not open a public issue containing credentials, bank data, or an exploitable proof of concept.

## Product thesis

Most finance tools explain the past. Money Proof Forge supports the next decision. The target user has irregular income, several currencies, cash or crypto, and obligations spread across dates and accounts.

The repository includes the [business hypothesis and validation playbook](docs/product/2026-09-01-business-validation-playbook.md), with an eight-week customer-development plan, interview script, PMF thresholds, and outcome metrics.

## Development

```sh
npm ci
npm run typecheck
npm run lint
npm test
npm run build
```

## License

MIT. See [LICENSE](LICENSE).