<p align="center"><img src="docs/assets/banner.svg" alt="OpenProof — Your agent says done. OpenProof checks." width="100%"></p>

<p align="center"><strong>Evidence-based acceptance verification for AI-built web apps.</strong><br>Local CLI · MCP server · Agent skill · MIT licensed</p>

OpenProof turns an explicit acceptance plan into real browser checks and a readable evidence report. It connects each requirement to the observations that support it—and keeps missing evidence visible.

**Made by TwinForgeLabs.** No separate AI API key, hosted account, or GPU required.

> **v0.1 developer preview.** The browser runner is deterministic; your existing coding agent authors the assertions. OpenProof does not automatically understand a website from a URL or certify that an app is production-ready.

## Why this exists

A booking page can show “Booking confirmed” while its server returns an error. A test can click a button successfully without checking the result. A polished screenshot can hide an unimplemented requirement.

OpenProof records what was checked, what failed, and what still needs evidence. A green toast cannot substitute for an observed server response. An observed response cannot substitute for an independent persistence check.

## Try it in five minutes

Install [Node.js 22 or newer](https://nodejs.org/), download this source, and open a terminal in the project folder:

```sh
npm ci
npx playwright install chromium
npm run demo
```

On a Linux machine missing browser dependencies, use `npx playwright install --with-deps chromium` instead. The CLI needs Node.js and Chromium; the report can be opened in an ordinary browser.

The demo starts a local fixture, executes its checks, writes evidence, and shuts the fixture down. Its **expected result** is:

| Requirement | Result | Why |
| --- | --- | --- |
| Reveal rescheduling policy | Passed | The expected policy becomes visible. |
| Submit booking successfully | Failed | The UI claims success, but the booking endpoint returns HTTP 503. |
| Fit a 390px viewport | Passed | The page has no horizontal document overflow. |
| Deliver confirmation email | Unverified | No test inbox is configured. |

The demo command prints the generated `index.html` path. Open that file to inspect the results. `npm run demo` exits successfully when this deliberate failure is correctly detected; `openproof run` uses the report status for its exit code.

## The report

Each run writes a new directory, preserving earlier evidence:

```text
openproof-results/run-xxxxxx/
  index.html       Human-readable report
  report.json      Machine-readable observations
  report.md        Compact agent/CI handoff
  check-id.png     Browser screenshots, when captured
```

Optional Playwright trace ZIPs are saved only when `--trace` is enabled. Screenshots show the browser state; they are supporting evidence, not an automatic verdict.

![Actual OpenProof demo report](docs/assets/report-preview.png)

[Browse the sample report files](docs/demo/) · [Mobile report preview](docs/assets/report-mobile.png)

## Verify your own app

Write one requirement per line in `requirements.txt`:

```text
Visitors can reveal the cancellation policy.
A submitted booking is saved on the server.
Visitors receive a confirmation email.
```

Create an initial plan:

```sh
node src/cli.js init --url http://localhost:3000 --requirements requirements.txt
```

This preserves your requirements in `openproof.plan.json` with **no fabricated checks**. Ask your coding agent to inspect the app and add supported steps and assertions. Unmapped requirements remain unverified.

```sh
node src/cli.js validate openproof.plan.json
node src/cli.js run openproof.plan.json
```

For an authorized test flow that submits forms:

```sh
node src/cli.js run openproof.plan.json --allow-writes
```

Allow a separate API origin only when the application needs it:

```sh
node src/cli.js run openproof.plan.json --allow-origin http://localhost:8000 --allow-writes
```

### Result semantics

| Status | Meaning |
| --- | --- |
| **Passed** | Every mapped executable check for that requirement passed. |
| **Failed** | A check observed an action/assertion mismatch. |
| **Unverified** | Missing checks, manual evidence, unavailable infrastructure, or blocked requests. |

Overall status is failed if any requirement fails; otherwise unverified if any requirement is incomplete; otherwise passed. Exit codes are **0 = passed**, **1 = failed**, **2 = incomplete or invalid**.

## Connect Claude, Codex, Cursor, or another MCP host

OpenProof provides three local tools: `openproof_plan`, `openproof_inspect`, and `openproof_run`. Configure your host to launch:

```sh
node /absolute/path/OpenProof/src/mcp.js
```

Set `OPENPROOF_ALLOWED_ORIGINS` to the exact app/API origins and `OPENPROOF_OUTPUT_DIR` to a writable folder. Write requests are disabled unless `OPENPROOF_ALLOW_WRITES=1` is explicitly configured. With no origin list, MCP accepts only loopback targets.

See **[MCP setup and agent workflow](docs/AGENT-WORKFLOW.md)** for a configuration example and a paste-ready agent instruction. A portable `SKILL.md` workflow is supplied in `skills/openproof` for hosts that support it. MCP interoperability is tested at the protocol level; each agent application's installation and permission UI can differ.

## What is included

- Strict JSON plans with requirement-to-check mapping.
- Fresh Chromium contexts for each independent check.
- Desktop and mobile viewport checks.
- Role/name, label, test ID, and CSS locators.
- Form interactions, visibility/text/value/count assertions, and URL checks.
- Horizontal-overflow and observed console-error checks.
- Page-response and independent GET/JSON-field assertions.
- HTML, JSON, and Markdown reports; screenshots and opt-in traces.
- Redacted fill values in reproduction steps; password/private-element screenshot masking.
- Plan/artifact SHA-256 hashes for identifying the captured evidence.
- MCP integration, agent workflow, a deliberately broken demo, and automated tests.

The **[plan-format reference](docs/PLAN-FORMAT.md)** documents every supported field and its limits. The **[JSON Schema](docs/plan.schema.json)** supports editor tooling.

## What this release does not claim

- `noOverflow` is not a comprehensive mobile usability or accessibility audit.
- HTTP 200/201 does not establish database persistence or email delivery.
- No screenshot scoring, visual-diff engine, production login import, payment adapter, or test inbox is included.
- No autonomous repair loop is bundled. Your agent can fix the app and rerun the preserved plan.
- The CLI uses local browser automation; it is not a hosted public URL-scanning service or a network sandbox.
- Target pages execute JavaScript. Even GET requests can have side effects. Use authorized test environments.
- Evidence hashes are not signed attestations. An inadequate plan can miss defects; review requirement coverage.

## Privacy and execution policy

No telemetry, model calls, or report upload is built into OpenProof. Reports stay in your chosen local output folder. Browser requests are restricted to approved origins; non-read HTTP methods are blocked by default. Service workers and WebSockets are blocked in v0.1.

Fill values are redacted in report reproduction steps. Password inputs and elements marked `data-openproof-private` are masked in screenshots. This is **not comprehensive redaction**: other page data, logs, URLs, and optional traces may contain secrets or personal information. Review evidence before sharing. Avoid putting real credentials in a plan.

## Development

```sh
npm test
npm run demo
```

The suite exercises schema/coverage semantics, report escaping, real-browser failure detection, write blocking, API assertions, and MCP discovery/inspection/execution. Browser installation is required for integration tests.

```mermaid
flowchart TD
  A["User requirements"] --> B["Agent authors explicit checks"]
  B --> C["Isolated browser runner"]
  C --> D["Observed assertions"]
  B --> E["Missing or manual evidence"]
  D --> F["Requirement evidence report"]
  E --> F
```

### Contributing

Keep changes focused and add a test that demonstrates the behavior being improved. Prefer a small real failing journey over tests that repeat implementation details. Do not alter the demo's expected failure merely to make everything green. Use synthetic test data and omit private browser evidence from contributions.

### License

[MIT](LICENSE). Dependencies retain their own licenses. OpenProof is an independent TwinForgeLabs project; it is not affiliated with the agent platforms it can connect to.