Verify the connection, not just the proof.
Evidence-backed URL trust for Flare Web2Json consumers.
Website · Canonical URL attack demo · Product roadmap · Architecture · Contributing · Security
Run Cockpit: the persisted Coston2 Web2Json lifecycle from source preflight to integration package.
A valid FDC proof confirms a response to a request. It does not guarantee that a Solidity consumer checks the intended URL before accepting that proof. A consumer can verify authentic Web2Json evidence and still trust data from the wrong scheme, host, path, or query.
Orivra is built for Flare developers, smart-contract teams, auditors, and agentic
development workflows that consume public Web2Json data. It turns one strict
Web2JsonManifestV1 into:
- persisted preflight and lifecycle evidence;
- an explicit URL-invariant diagnosis for the tested consumer;
- deterministic safe Solidity that binds the expected source;
- a checksummed, replayable integration package.
The core distinction is deliberate: proof validity and source trust are two different facts.
- Open orivra.xyz.
- Choose the Open-Meteo Web2Json template and create a replay run. Replay mode exercises persisted evidence without broadcasting a blockchain transaction.
- Follow the six-stage Run Cockpit. After proof verification, Consumer changes
to
Ready; select it and useVerify consumerto start the project-owned Consumer Lab operation. It is intentionally not an automatic blockchain effect. - Compare the vulnerable-consumer diagnosis with the generated safe consumer and export the integration package.
For a wallet-free introduction, open the canonical URL attack demo. It shows why a valid proof is insufficient when the consumer omits the host invariant.
The public deployment runs the Web, API, worker and PostgreSQL composition on the selected VDS. It is a hackathon pilot, not a security audit or a guarantee of production fitness. Deadline incident restorations may update one service ahead of the deferred full candidate verification; the current operational snapshot and rollback procedure live in the runbook.
Requirements: Node.js 22.14.0 and npm 10.9.2.
git clone https://github.com/MarsherSusanin/Orivra.git
cd Orivra
nvm use
npm ci
npm run devOpen the Vite URL printed in the terminal. This command starts the Web client only. API-backed runs require PostgreSQL, the API, and the worker; use the hosted pilot for the fastest complete journey or follow the runbook for the full local composition.
The current live capability is Coston2, chain ID 114. Flare mainnet is a known
network identity but remains fail-closed as upstream-unsupported: the
official FDC overview currently lists
Web2Json only for Coston and Coston2. The immutable Mainnet RPC/registry
assessment is documented in ADR 0051.
flowchart LR
Manifest["Web2JsonManifestV1"] --> Preflight["HTTPS source preflight"]
Preflight --> Hub["FdcHub.requestAttestation"]
Hub --> Relay["Relay finalization + DA proof"]
Relay --> Verify["FdcVerification.verifyWeb2Json"]
Verify --> Lab["Consumer Lab URL invariants"]
Lab --> Solidity["Generated safe Solidity"]
Solidity --> Bundle["Checksummed integration package"]
The worker is the only component allowed to own relayer credentials or perform live external effects. The API never receives a user private key or a relayer private key. Replay mode remains evidence-only.
Orivra is an npm-workspace TypeScript monorepo with pure contracts and domain logic, explicit network adapters, persisted orchestration, and several bounded client surfaces.
flowchart TB
Clients["Web · CLI · GitHub Action · local MCP"] --> API["Authenticated API"]
API --> DB[("PostgreSQL\nappend-only events + commands")]
Worker["Restart-safe worker"] --> DB
Worker --> Coston2["Coston2 FDC · Relay · DA"]
DB --> Projection["RunProjectionV1"]
Projection --> Clients
DB --> Evidence["Proof bundle · receipt · Consumer Lab"]
Evidence --> Handoff["Safe Solidity + integration package"]
Important boundaries:
packages/contractscontains versioned public schemas and no I/O.packages/domaincontains deterministic state machines, canonical JSON, diagnostics, replay, checksums, and code generation.packages/fdc-coston2owns Coston2 adapters behind explicit ports.apps/apiowns authentication, idempotent commands, and PostgreSQL composition.apps/workerowns restart-safe external effects and the relayer boundary.- After Consumer Lab, the worker can optionally compare a directly deployed Coston2 consumer's runtime bytecode with the exact generated artifact. This is a read-only, block-bound observation; proxies, ownership and security audits are deliberately outside the claim.
- Web, CLI, Action, and MCP use public contracts and the persisted API path.
See ARCHITECTURE.md and the architecture decision records for the detailed trust model. The hosted pilot follows ADR 0029: one DigitalOcean VDS with Caddy as the only public ingress and application services on private Compose networks.
@proofline/mcp is a local stdio MCP server for user-controlled AI agents. It
exposes a bounded replay/evidence/Consumer Lab surface and has no wallet,
relayer, private-key, arbitrary-HTTP, or live-submission tool.
npm run build:mcp
PROOFLINE_API_URL=https://orivra.xyz/api \
PROOFLINE_PROJECT_TOKEN=project_... \
node packages/mcp/dist/index.jsCreate a CLI / MCP project token in Settings. The raw token is shown once and
must be stored only in a trusted local MCP client configuration. See
ADR 0049.
This hackathon submission delivers an end-to-end Coston2 Web2Json assurance workflow: strict manifests, persisted execution, the canonical URL-invariant attack demonstration, Consumer Lab diagnostics, generated safe Solidity, a Run Cockpit, replayable evidence, and local MCP access for user agents.
The submission focuses on making a subtle smart-contract trust failure visible and reproducible. It does not claim that Orivra or generated integrations have received a third-party security audit.
| Path | Purpose |
|---|---|
apps/api |
Authentication, project-scoped commands, artifacts, PostgreSQL composition |
apps/worker |
Restart-safe preflight, FDC lifecycle, proof and consumer effects |
src / apps/web |
React Web client and compatibility workspace |
packages/contracts |
Versioned schemas and public API types |
packages/domain |
Pure lifecycle, diagnostics, replay, checksum and codegen logic |
packages/fdc-coston2 |
Coston2 verifier, RPC, registry, Relay and DA adapters |
packages/cli |
Local command-line surface |
packages/action |
Checked-in GitHub Action runtime artifact |
packages/mcp |
Local stdio MCP server for user agents |
contracts |
Vulnerable and safe Solidity consumer fixtures |
docs/adr |
Architecture and trust-boundary decisions |
All first-party npm workspaces remain private; this repository does not publish
npm packages as part of the hackathon submission.
Install exact lockfile dependencies first:
nvm use
npm ciFast contributor gate:
npm run check:open-source
npm run typecheck
npm test
npm run build:mcp
npm run build
npm run test:sites
npm run test:action:artifactThe build produces the Web/Sites compatibility artifacts locally. The MCP build
produces packages/mcp/dist/index.js. The GitHub Action distribution is checked
in and must remain byte-synchronized with its source.
Real PostgreSQL contracts require Docker/Testcontainers and must not be counted as passing when skipped:
PROOFLINE_TESTCONTAINERS=1 npm run test:postgres -- --maxWorkers=1Additional Docker, recovery, live-Coston2, browser-accessibility, and release gates are documented in docs/runbook.md. Live tests require explicit operator-owned credentials; normal unit and replay tests do not.
npm run test:e2e is a hermetic Node replay test across the API and worker. It
does not replace Product Integration Verification in a real desktop/mobile
browser.
Do not put wallet keys, relayer keys, project tokens, API credentials, or .env
files in Git. Security issues should be reported privately as described in
SECURITY.md. The repository includes dependency-license and
open-source-readiness checks, but their success is not a security audit.
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. The date-free Orivra Public Backlog contains contribution-ready product and engineering work. Changes must preserve the persisted evidence and authorization boundaries rather than replacing them with test-only shortcuts.
Orivra first-party code is licensed under the
Apache License 2.0. Solidity files that explicitly carry
SPDX-License-Identifier: MIT remain licensed under the MIT License in
LICENSES/MIT.txt. Third-party dependencies retain their own
licenses; see THIRD_PARTY_NOTICES.md and NOTICE.