# Sandbox Quickstart

## Requirements

- Node.js 24 or later.
- Install the lockfile dependencies once with `npm ci`.

## Start the application

```powershell
npm ci
npm run sandbox
```

Open `http://127.0.0.1:3000/app`. The server binds to loopback. `SANDBOX_PORT` may select another local port.

This command starts an in-memory SQLite fixture with one test pool, two fixed provider identities, a buyer, one merchant, support and independent test reviewers. Each browser persona receives a short-lived opaque session through the sandbox-only bootstrap endpoint. This is a local testing harness, not a login system. Do not expose, tunnel or deploy it.

## Run a payment and refund

### Optional persistence across restarts

```powershell
New-Item -ItemType Directory -Force data | Out-Null
$env:SANDBOX_DB_PATH = Join-Path (Get-Location) 'data\sandbox.sqlite'
npm.cmd run sandbox
```

Use the same path on subsequent starts. Keep the SQLite database and adjacent `.identities.key` file together; never commit or share the signing file. Back up with the process stopped, retaining WAL files if present, or use a proper SQLite backup. Missing keys for an existing database cause startup to fail rather than silently generating new identities. This is a plaintext local fixture key store, not production custody. Restrict the runtime directory's Windows ACL to the local user.

The UI reports the configured storage mode. Payments, reserves, case assignments, clock and idempotency survive restart; short-lived browser sessions do not and are renewed. The browser still remembers only its current payment in session storage. Remove `SANDBOX_DB_PATH` from the process environment to return to the default in-memory fixture. Persistence does not enable blockchain settlement or public hosting.

1. Refresh the pool and buyer balances.
2. Choose the demo pool/merchant and enter an amount in `TEST-USD`.
3. Execute protected payment. The app calls the existing offer, acceptance, authorization and reservation API routes, then uses a locally signed mock-provider message to settle.
4. The merchant may transfer received test balance to the simulator's external account.
5. Advance the local clock to the delivery/claim window and submit a test claim as the buyer.
6. Support assigns triage; an assigned reviewer admits it; support assigns two independent reviewers.
7. Advance through the response window and record both reviewer votes. The protocol keeps the reserve bound until the appeal deadline.
8. Advance through that deadline and inspect the resulting refund and read-only reconciliation.

The clock is a sandbox simulation control, not a system clock or production API operation. The normal protocol state transitions and authorization checks still execute.

## Commands

```powershell
npm run build:web
node --test test/sandbox-app.test.js test/api.test.js
npm run verify
```

For framework-independent browser checks, open the app in a browser while `npm run sandbox` is running. No wallet extension is required.

## API reference

`api/openapi.json` is the generated versioned API contract. `GET /v1/me/balance` returns the authenticated buyer or merchant's own simulated account. `GET /v1/pools/{id}` requires the owning pool-operator identity and returns total, available and reserved coverage. `GET /v1/reconciliation` is limited to the local single-pool owner and returns a read-only report summary and findings.

All API mutations require the normal bearer session, role/object authorization and an `Idempotency-Key`. Sandbox-only routes under `/__sandbox/` are omitted from OpenAPI and do not exist on the ordinary API server. They issue fixed local personas or drive the local test clock/mock provider; they are not production API endpoints.