# Why create-bsv-app

> The problems with wiring BSV wallet auth by hand, and the positions create-bsv-app takes to solve them.

> Agents: search these docs with the `search_docs` tool on the MCP server at https://createbsvapp.vercel.app/mcp, or read everything at https://createbsvapp.vercel.app/llms-full.txt.

## The problems

Adding "log in with a wallet" to a web app sounds like one feature. Done properly, it's a dozen.

**Connecting is a state machine, not a button.** Users have a desktop wallet, a phone wallet or neither. Desktop needs a local probe; phone needs a relay server, a session, a QR code and a WebSocket. Every app reinvents this, and most only ship the happy path.

**Signatures are easy; secure signatures are not.** A proof must name *which server* it's for, *what action* it authorizes, *which exact body* it covers, *when* it expires, and be refused the *second* time it arrives. Miss one and you've built a replayable password. These are the bugs that never show up in a demo.

**The boring parts are where the holes are.** An API client that follows redirects can carry a proof to another host. A server that falls back to a random key in production changes identity on every deploy. A CORS rule mistaken for auth protects nothing. None of these are BSV problems, and all of them break BSV auth.

**Then there's the glue.** Providers in `main.tsx`, routes in `App.tsx`, CORS and the relay in the server, environment variables on both sides, and a README nobody keeps current.

## The positions we take

**Generate code, don't wrap it in a library.** The code that decides who's logged in is the code you most need to read, change and own. create-bsv-app writes small, plain TypeScript files into your project. No runtime package of ours sits in your dependency tree, and nothing is hidden. The cryptography itself comes from maintained packages (`@bsv/sdk`, `@bsv/auth`, `@bsv/wallet-relay`).

**Identity comes from the wallet.** No passwords, no emails, no reset flows. The user's [identity key](https://createbsvapp.vercel.app/docs/glossary#identity-key) *is* the account, proven by a signature on every request that matters.

**Fail closed.** Proofs expire in two minutes and work once. The API client refuses redirects and caps sizes. Production config refuses to start without HTTPS and a stable key. When something's wrong, you get an error at deploy time instead of a breach later.

**One pipeline, four ways in.** Prompts, flags, a JSON file and a browser form all produce the same config and the same result. Humans and [agents](https://createbsvapp.vercel.app/docs/agents) drive the same tool.

**Working beats blank.** `npm run dev` gives you a running app with a connected wallet, a login and a signed request, so you start from something that works and change it.

## What it isn't

- **Not a wallet.** Users bring their own BRC-100 wallet, such as [BSV Browser](https://browser.bsvb.tech/).
- **Not a framework.** After scaffolding, it's out of the way. Re-run it only to [add capabilities](https://createbsvapp.vercel.app/docs/add-to-existing).
- **Not (yet) payments.** The scaffold covers identity and authentication. Transactions are your next step: see [your first payment](https://createbsvapp.vercel.app/docs/bsv-primer#your-first-payment).
- **Not a backend-as-a-service.** No accounts, no hosted database, no lock-in. You deploy two ordinary apps.

## Read next

::: cards
[**Quick start** From an empty folder to a connected wallet.](https://createbsvapp.vercel.app/docs)

[**Security model** What a verified proof guarantees, and what it doesn't.](https://createbsvapp.vercel.app/docs/security)
:::