diff --git a/README.md b/README.md index d854370..118c763 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,77 @@ -# PreFlight +
+ PreFlight logo -**A release gate for paid agent services.** PreFlight behaves like a real customer: it discovers a live service, verifies the x402 buyer journey, and returns a criterion-level `RELEASE`, `BLOCK`, or `UNKNOWN` decision with portable signed proof. +

PreFlight

-[Live product](https://usepreflight.xyz) · [Hosted API](https://api.usepreflight.xyz/api/v1/service) · [API docs](docs/api.md) · [MCP docs](docs/mcp.md) · [CLI](docs/cli.md) · [Receipts](docs/receipts.md) +

Your first real customer before launch.

-Source is publicly available for review. No license for reuse, modification, or redistribution is granted unless stated otherwise. +

+ PreFlight discovers what a paid agent service actually exposes, optionally completes a bounded real payment, verifies settlement and delivery, and returns RELEASE, BLOCK, or UNKNOWN with criterion-level evidence, remediation, and signed proof. +

-![PreFlight product overview](docs/assets/preflight-home.png) +

+ Launch PreFlight + · + Documentation + · + Hosted API + · + npm CLI +

-## Why PreFlight exists +

+ CI status + npm version + Node >=20 + x402 enabled + MCP hosted +

-An endpoint being online is not enough. A paid agent service can still fail when a buyer tries to use it: +

Source is publicly available for review. No license for reuse, modification, or redistribution is granted unless stated otherwise.

+
-- the 402 challenge can advertise the wrong network, asset, amount, or `payTo`; -- the declared contract can drift from the live response; -- settlement can succeed while delivery fails; -- a duplicate payment replay can accidentally deliver twice; -- a generic score can hide exactly what has to be fixed. +![PreFlight release verification flow from endpoint discovery to signed verdict](docs/assets/readme/preflight-hero.svg) -PreFlight turns that into a release gate. It compares declared intent against observed production behavior, acts as a bounded buyer when authorized, and returns evidence-backed criteria instead of a vague badge. +## A service can be online and still be unbuyable -![PreFlight release report](docs/assets/preflight-release-report.png) +Health checks do not prove that a paid agent service works for a real customer. -## How it works +A service can respond successfully while its live contract advertises the wrong price, network, asset, or payee. Payment can settle while delivery fails. Declared behavior can drift from production. A generic score can hide the exact issue blocking release. -```mermaid -sequenceDiagram - actor Dev as Developer - participant Web as Web / CLI / MCP - participant API as PreFlight API - participant Target as Agent service - participant X as x402 / X Layer - participant DB as Report store +PreFlight tests the buyer journey before customers discover the failure. - Dev->>Web: Submit endpoint or manifest - Web->>API: Discovery request - API->>Target: Observe HTTPS, MCP, x402 challenge - API-->>Web: Proposed manifest with provenance - Dev->>API: Confirm release check - API-->>Dev: x402 payment challenge - Dev->>API: Paid replay - opt Authorized buyer proof - API->>Target: Pay as bounded buyer - Target->>X: Settle payment - Target-->>API: Deliver response - end - API->>API: Evaluate criteria - API->>DB: Publish private report after settlement - API-->>Dev: RELEASE / BLOCK / UNKNOWN + signed receipt -``` +- Contract drift between what was declared and what is live +- Incorrect payment challenge terms +- Successful settlement followed by failed delivery +- Duplicate-payment or replay inconsistencies +- Missing evidence and unclear remediation -## Key capabilities +## How PreFlight works + +PreFlight separates free discovery from paid release verification. Nothing is charged until the developer confirms the discovered contract and starts the full check. + +![PreFlight workflow separating free discovery from paid release verification](docs/assets/readme/preflight-workflow.svg) -- **Discovery-first workflow** — inspect a live endpoint before paying for a full verification. -- **Proposed manifest with provenance** — every inferred field says where it came from and whether it needs confirmation. -- **Real buyer proof** — with owner attestation, PreFlight can pay and take delivery as a bounded buyer. -- **Deterministic decision model** — `RELEASE`, `BLOCK`, or `UNKNOWN`, built from criterion states. -- **Exact remediation** — contradictions include observed evidence and a fix. -- **Signed receipts** — Ed25519 receipt over canonical JSON, verifiable outside the report page. -- **Private reports** — bearer capability tokens; report IDs are not public access. -- **MCP wrapper** — hosted MCP endpoint for agent-native discovery and paid tool invocation. -- **Embeddable badge and gallery** — opt-in proof surfaces for release-ready services. +1. Submit a public endpoint. +2. Discover the live service contract. +3. Review a proposed manifest with provenance. +4. Confirm the release check and complete the x402 payment. +5. Optionally authorize bounded buyer proof against the target service. +6. Receive a decision, criterion evidence, remediation, and a signed receipt. + +## What PreFlight verifies + +| Surface | What is checked | +| --- | --- | +| Discovery | What the endpoint actually exposes over HTTPS, MCP, and payment challenges | +| Contract integrity | Whether price, network, asset, payee, and declared behavior match production | +| Payment challenge | Whether the buyer receives coherent and actionable payment terms | +| Settlement | Whether the required payment state is actually reached | +| Delivery | Whether the service returns the promised result after payment | +| Replay behavior | Whether repeated payment or delivery attempts behave safely | +| Evidence | Whether each criterion is supported by an observable fact rather than a generic score | -## Decision model +## Decisions you can ship against | Decision | Meaning | | --- | --- | @@ -70,54 +79,54 @@ sequenceDiagram | `BLOCK` | At least one mandatory criterion contradicts the release. | | `UNKNOWN` | PreFlight could not safely prove the criterion either way. Unknown is honest; it is never silently upgraded. | -Criteria use: +Each decision is built from criterion-level states: -- `MATCH` — observed production behavior matches the declaration; -- `CONTRADICTION` — observed production behavior conflicts with the declaration; -- `UNKNOWN` — not enough safe evidence; -- `NOT_APPLICABLE` — criterion does not apply to this surface. +- `MATCH` — observed production behavior matches the declaration +- `CONTRADICTION` — observed production behavior conflicts with the declaration +- `UNKNOWN` — there is not enough safe evidence +- `NOT_APPLICABLE` — the criterion does not apply to this surface -## Architecture +![PreFlight report showing verdict, criterion evidence, remediation, and signed receipt](docs/assets/readme/preflight-evidence.png) -```mermaid -flowchart LR - Web[Web app] --> API[Fastify API] - CLI[CLI] --> API - MCP[MCP clients] --> MCPRoute[Hosted Streamable HTTP MCP] - MCPRoute --> API - API --> Safe[Safe egress + discovery] - Safe --> Target[Agent service] - API --> Seller[x402 seller gate] - API --> Buyer[Bounded x402 buyer] - Buyer --> Target - Seller --> X[X Layer / x402 facilitator] - Buyer --> X - API --> Criteria[Criterion engine] - Criteria --> Reports[(Postgres reports)] - API --> Receipts[Ed25519 receipt signer] - Receipts --> Proof[Receipts / badges / gallery] -``` +_Real product output: verdict, criterion evidence, remediation, and signed proof._ + +## Key capabilities -## Quick start +- **Discovery-first input** — start with a public endpoint rather than a hand-authored manifest. +- **Proposed manifest with provenance** — inferred fields show where they came from and whether confirmation is required. +- **Bounded buyer proof** — with owner attestation and spend limits, PreFlight can pay and take delivery like a real customer. +- **Deterministic verdicts** — RELEASE, BLOCK, or UNKNOWN from criterion states, not an opaque aggregate score. +- **Actionable remediation** — contradictions include observed evidence and the exact issue to fix. +- **Signed receipts** — Ed25519 signatures over canonical JSON, verifiable outside the report page. +- **Private reports** — bearer capability tokens protect non-public report data. +- **Agent-native access** — use the hosted API, MCP endpoint, or npm CLI. +- **Portable proof** — opt-in badges and gallery entries expose only approved release evidence. -### Web +## Use PreFlight your way -Open [usepreflight.xyz](https://usepreflight.xyz), paste a public service endpoint, and review the proposed manifest. Discovery is free; full `verify_release` checks require x402 payment. +| Surface | Best for | Entry point | +| --- | --- | --- | +| Web | Interactive discovery and human-readable reports | `https://usepreflight.xyz` | +| API | Programmatic release checks | `https://api.usepreflight.xyz` | +| MCP | Agent-native discovery and verification | `https://api.usepreflight.xyz/mcp` | +| CLI | Local workflows and CI integration | `@vinaystwt/preflight-cli` | -### API +#### Web + +Open https://usepreflight.xyz, paste a public endpoint, and review the proposed manifest. Discovery is free. A full release verification costs 0.10 USDT. + +#### API ```bash curl -s https://api.usepreflight.xyz/api/v1/service | jq curl -s https://api.usepreflight.xyz/api/v1/contracts/release-manifest/v1 | jq ``` -`POST /api/v1/verify-release` is a paid x402 endpoint. An unpaid request returns an HTTP 402 challenge; a funded agent replays with `PAYMENT-SIGNATURE`. +POST /api/v1/verify-release is the paid x402 release-check endpoint. An unpaid request returns a payment challenge; a funded client replays the request with the required payment proof. See [docs/api.md](docs/api.md). -### MCP - -PreFlight’s MCP server is hosted; installing the CLI is not required. +#### MCP ```json { @@ -129,50 +138,60 @@ PreFlight’s MCP server is hosted; installing the CLI is not required. } ``` -See [docs/mcp.md](docs/mcp.md). - -### CLI +CLI installation is not required for the hosted MCP service. -The CLI is published as `@vinaystwt/preflight-cli` with the `preflight` binary. +See [docs/mcp.md](docs/mcp.md). -Install and smoke-test: +#### CLI ```bash npm install -g @vinaystwt/preflight-cli preflight --help preflight verify --help preflight verify-receipt --help +npx @vinaystwt/preflight-cli --help ``` -## Signed receipts +See [docs/cli.md](docs/cli.md). -Every completed check can issue a signed receipt: +## Architecture + +PreFlight keeps discovery, payment verification, bounded buyer execution, criterion evaluation, report storage, and receipt signing as explicit trust boundaries. -- payload is canonical JSON with sorted keys; -- payload hash is SHA-256; -- signature algorithm is Ed25519; -- public keys are served at `GET /api/v1/pubkeys`; -- public receipts are served at `GET /api/v1/receipts/{receipt_id}`. +![PreFlight architecture showing web, CLI, MCP, payment, buyer proof, reports, and receipts](docs/assets/readme/preflight-architecture.svg) -![Signed receipt inspector](docs/assets/preflight-receipt-inspector.png) +Web, CLI, and MCP clients call the Fastify API. Discovery uses guarded egress to inspect public services. The seller gate verifies payment to PreFlight, while bounded buyer execution can independently pay the target service. A deterministic criterion engine writes private reports and signs portable receipts with Ed25519. -See [docs/cli.md](docs/cli.md) and [docs/receipts.md](docs/receipts.md). +See [docs/architecture.md](docs/architecture.md). + +## Signed receipts + +Every completed verification can issue a portable receipt: + +- canonical JSON with sorted keys; +- SHA-256 payload hash; +- Ed25519 signature; +- public verification keys at `GET /api/v1/pubkeys`; +- public receipt lookup at `GET /api/v1/receipts/{receipt_id}`. + +See [docs/receipts.md](docs/receipts.md) and [docs/cli.md](docs/cli.md). ## Security and trust boundaries PreFlight is a verifier, not a custody product. -- Private reports require capability tokens. -- Reports publish after the required settlement state. -- Probe egress refuses private/internal targets and unsafe redirects. -- Buyer proof requires owner attestation and spend caps. +- Private reports require bearer capability tokens. +- Reports are published only after the required settlement state. +- Probe egress rejects private/internal targets and unsafe redirects. +- Bounded buyer proof requires owner attestation and spend caps. - Terms-hash drift aborts buyer proof before payment. -- Wallets are separated by role. -- Ambiguous evidence returns `UNKNOWN`, not a false release. +- Seller, buyer, and operational wallets are separated by role. +- Ambiguous evidence returns UNKNOWN rather than a false release. See [docs/security.md](docs/security.md). -## Local development +
+Local development Backend: @@ -203,25 +222,30 @@ npm run build --prefix packages/cli (cd packages/cli && npm pack --dry-run) ``` -## Project structure +
+ +
+Project structure ```text src/ Fastify API, MCP, release criteria, payments, receipts src/db/migrations/ Additive database migrations web/ Next.js web application -packages/cli/ CLI package source -docs/ Public API, MCP, receipt, security and operations docs +packages/cli/ Published CLI source +docs/ API, MCP, receipt, security, architecture, and deployment docs test/ Backend and release-gate tests ``` +
+ ## Status and limitations - Agent ID resolution is intentionally conservative unless an authoritative listing resolver is configured. - Gallery entries are opt-in. - Chain anchoring is disabled unless explicitly configured and proven. - Browser receipt verification may fall back honestly if local Ed25519 support is unavailable. -- The CLI is published as `@vinaystwt/preflight-cli@0.1.0`; keep documented commands limited to verified registry-install behavior. +- The CLI is published as `@vinaystwt/preflight-cli@0.1.0`; documented commands are limited to verified registry behavior. ## License -No public license has been selected yet. Do not assume open-source reuse rights until a license file is added. +No public license has been selected. Do not assume rights to reuse, modify, or redistribute the source unless a license is added. diff --git a/docs/assets/preflight-home.png b/docs/assets/preflight-home.png deleted file mode 100644 index 2f51558..0000000 Binary files a/docs/assets/preflight-home.png and /dev/null differ diff --git a/docs/assets/preflight-receipt-inspector.png b/docs/assets/preflight-receipt-inspector.png deleted file mode 100644 index 77569bf..0000000 Binary files a/docs/assets/preflight-receipt-inspector.png and /dev/null differ diff --git a/docs/assets/preflight-release-report.png b/docs/assets/preflight-release-report.png deleted file mode 100644 index 7df88ee..0000000 Binary files a/docs/assets/preflight-release-report.png and /dev/null differ diff --git a/docs/assets/readme/preflight-architecture.svg b/docs/assets/readme/preflight-architecture.svg new file mode 100644 index 0000000..8fdda4a --- /dev/null +++ b/docs/assets/readme/preflight-architecture.svg @@ -0,0 +1,71 @@ + + PreFlight architecture showing web, CLI, MCP, payment, buyer proof, reports, and receipts + Four trust-zone architecture diagram showing client surfaces, the PreFlight control plane, external payment and service boundaries, and evidence proof surfaces. + + + + + + + + + + + + + + + 1 CLIENT SURFACES + 2 PREFLIGHT CONTROL PLANE + 3 EXTERNAL BOUNDARY + 4 EVIDENCE + PROOF + + + Web + CLI + MCP clients + Hosted MCP route + + + + PreFlight API + Discovery + safe egressSSRF guard + redirects + x402 seller gate + Bounded x402 buyerOwner attestationSpend caps + Criterion engine + Postgresreports + Ed25519signer + + + + Paid agent serviceObserved target + X Layer / facilitatorx402 settlement + + + + Private report + Public receipt + Release badge + Opt-in gallery + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/readme/preflight-evidence.png b/docs/assets/readme/preflight-evidence.png new file mode 100644 index 0000000..e51d790 Binary files /dev/null and b/docs/assets/readme/preflight-evidence.png differ diff --git a/docs/assets/readme/preflight-hero.svg b/docs/assets/readme/preflight-hero.svg new file mode 100644 index 0000000..46a42dc --- /dev/null +++ b/docs/assets/readme/preflight-hero.svg @@ -0,0 +1,111 @@ + + PreFlight release verification flow from endpoint discovery to signed verdict + Instrument-style flow from service endpoint through live discovery, bounded buyer proof, settlement and delivery, and RELEASE, BLOCK, or UNKNOWN signed receipt output. + + + + + + + + + + + + + + + + + + + + + + PreFlight + RELEASE GATE + + + + + + + + + Service endpoint + Public HTTPS target + POST /verify-release + + + + + + + + + FREE + Live discovery + + + + + + + + + + Observed fields + provenance + + + + + + + + + PAID CHECK + Bounded buyer proof + + + + + + + + + Owner attestation + spend caps + + + + + + + + + Settlement + delivery + CRITERION EVIDENCE + + + + + + RELEASE + + BLOCK + + UNKNOWN + + + + + + + + Signed receipt + ED25519 + + diff --git a/docs/assets/readme/preflight-logo.svg b/docs/assets/readme/preflight-logo.svg new file mode 100644 index 0000000..67568df --- /dev/null +++ b/docs/assets/readme/preflight-logo.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/assets/readme/preflight-workflow.svg b/docs/assets/readme/preflight-workflow.svg new file mode 100644 index 0000000..a68cb79 --- /dev/null +++ b/docs/assets/readme/preflight-workflow.svg @@ -0,0 +1,64 @@ + + PreFlight workflow separating free discovery from paid release verification + Two-lane workflow: free discovery submits an endpoint, discovers the live contract, and reviews a proposed manifest; paid verification starts the release check, verifies payment settlement and delivery, and returns a verdict with signed proof. + + + + + + + + + FREE DISCOVERY + PAID VERIFICATION + + + CONFIRM + PAY BOUNDARY + + + + 01 + Submit endpoint + Public endpoint + + + + 02 + Discover live contract + Observed fields + provenance + + + + 03 + Review proposed manifest + Developer confirmation + + + + + + 04 + Start release check + 0.10 USDT via x402 + + + + 05 + Verify payment, settlement, and delivery + Optional bounded buyer proof + + + + 06 + Receive verdict and signed proof + Evidence + remediation + receipt + + RELEASE + BLOCK + UNKNOWN + + + +