# IOTA Web Guardian — MVP Validation Strategy

> **Version**: 0.1.0
> **Authors**: Paolo Alberti, Niccolò Normani
> **Scope**: Technical correctness + Product-Market Fit for the content creator segment

---

> **Deployment context**
>
> | Section | Requires remote deployment? |
> |---|---|
> | §2 — Technical Validation | **No** — fully local via `docker compose up` + local IOTA node |
> | §3.3 — Qualitative Interviews | **No** — demo the local stack over a screen share |
> | §3.4 — Quantitative Beta Metrics | **Yes** — requires publicly reachable CVS + x402 + Guardian for real creator sites |
> | §3.5 — Cohort Experiments | **Yes** — post-hackathon, v0.2 phase |
>
> **For the hackathon**: only §2 (technical) and §3.1–§3.3 (personas, hypotheses, interviews) are in scope. Sections §3.4 and §3.5 describe the post-hackathon beta and can be executed once services are deployed to a cloud environment.

---

## Table of Contents

1. [Goals and Philosophy](#1-goals-and-philosophy)
2. [Technical Validation](#2-technical-validation)
   - 2.1 [Unit Tests](#21-unit-tests)
   - 2.2 [Integration Tests](#22-integration-tests)
   - 2.3 [End-to-End Smoke Test](#23-end-to-end-smoke-test)
   - 2.4 [Security Boundary Tests](#24-security-boundary-tests)
   - 2.5 [Regression Checklist](#25-regression-checklist)
3. [Product-Market Fit Validation](#3-product-market-fit-validation)
   - 3.1 [Target Personas](#31-target-personas)
   - 3.2 [Core Hypotheses](#32-core-hypotheses)
   - 3.3 [Qualitative Research](#33-qualitative-research)
   - 3.4 [Quantitative Signals](#34-quantitative-signals)
   - 3.5 [Cohort Experiments](#35-cohort-experiments)
4. [Go / No-Go Criteria](#4-go--no-go-criteria)
5. [Feedback Loop and Iteration](#5-feedback-loop-and-iteration)

---

## 1. Goals and Philosophy

This document describes the validation approach for IOTA Web Guardian v0.1. It covers two orthogonal axes:

- **Technical validation** — does the system do what the spec says, correctly and securely?
- **PMF validation** — do content creators actually want this, and will they adopt it?

Both axes must be satisfied before declaring the MVP a success. A technically perfect system with no user demand is not a product. A product with demand but unreliable behaviour cannot be monetised.

The guiding principle is **falsifiability**: every hypothesis below must have a concrete, measurable test that can prove it wrong. We are not looking for confirmation; we are looking for the fastest path to learning what is true.

---

## 2. Technical Validation

### 2.1 Unit Tests

Each service and crate has unit tests for its core logic, runnable with `cargo test --workspace`.

#### `iota-guardian-secrets`

| Test | What it validates |
|---|---|
| Key generation stores correct public key | `generate_and_save` round-trip |
| Sign → verify with same key | Ed25519 sign / verify consistency |
| Loading a non-existent key file returns a clean error | Error handling |
| `GuardianJwkStorage` delegates to backend without exposing private bytes | Private key isolation |

#### Guardian Proxy

| Test | What it validates |
|---|---|
| Request without `X-Agent-VP` header → 401 with challenge nonce | Identity gate |
| Request with valid `X-Guardian-Token` (not expired) → proxied through | JWT fast path |
| Request with expired `X-Guardian-Token` → 401 re-issued | Token expiry |
| `X-Guardian-Token` with wrong signing key → 401 | Signature validation |
| Human browser heuristic (no bot UA, no `X-Agent-VP`) → proxied | Human pass-through |

#### CVS

| Test | What it validates |
|---|---|
| VP with correct challenge nonce and valid signature → `{valid: true}` | Happy path |
| VP with wrong nonce → `{valid: false}` | Replay protection |
| VP with tampered VC payload → `{valid: false}` | VC integrity |
| VC issuer not in Super Certifier list → `{valid: false}` | Trust chain enforcement |
| DID Document not found on Tangle → descriptive error | Resolution failure |

#### x402 Payment Facilitator

| Test | What it validates |
|---|---|
| `POST /v1/challenge` → returns nonce + recipient + amount | Challenge issuance |
| Payment proof with matching nonce and correct amount → `{success: true}` | Happy path |
| Payment proof with wrong nonce → rejected | Nonce binding |
| Payment proof with insufficient amount → rejected | Amount enforcement |
| Duplicate payment proof (nonce replay) → rejected | One-time use |

#### AI Agent CLI

| Test | What it validates |
|---|---|
| `setup` writes a valid key file and prints the public key | Key generation |
| `vp::sign_vp` produces a JWT verifiable by the CVS | VP signing |
| Config round-trip: save → load → same values | Config serialisation |

---

### 2.2 Integration Tests

These tests run with all services up (`docker compose up`) and a local IOTA node (`iota start --force-regenesis --with-faucet`).

#### Trust chain bootstrap

1. Start all services.
2. Open Super Certifier Admin → onboard one certifier → publish Super Certifier DID Document.
3. Set `CVS_SUPER_CERTIFIER_DID` in `.env`, restart CVS.
4. **Assert**: `GET /v1/health` on CVS returns `200` and `super_certifier_did` is set.

#### Agent registration → VC issuance

1. Run `iota-guardian-agent setup`.
2. Run `iota-guardian-agent register --ra-url http://localhost:8085`.
3. In Certifier Service UI, approve the request.
4. **Assert**: CLI downloads `credential.vc.jwt` to `~/.iota-guardian-agent/`.
5. **Assert**: Agent DID object is visible on the local IOTA node (query via IOTA Explorer or RPC).

#### Guardian identity gate

1. `GET http://localhost:8080/content/test` → **assert** `401` with `challenge` in body.
2. Attach `X-Agent-VP` (signed with agent key + VC) → **assert** `402` (payment required).
3. Attach `X-Payment-Proof` (mock payload for MVP) → **assert** `200` with content body and `X-Guardian-Token` header.
4. Repeat step 3 with cached `X-Guardian-Token` → **assert** `200`, no CVS or x402 round-trip in service logs.

#### Human pass-through

1. `GET http://localhost:8080/content/test` with a standard `User-Agent` and no `X-Agent-VP` → **assert** `200` proxied directly.
2. **Assert**: no `X-Guardian-Token` header in response.
3. **Assert**: no CVS or x402 calls in service logs.

---

### 2.3 End-to-End Smoke Test

This is the canonical demo script. It must pass before any release.

```
1. Fresh environment: ./scripts/setup.sh
2. Start local IOTA node
3. Deploy identity package: ./scripts/deploy-identity-pkg.sh
4. docker compose up --build
5. Onboard Super Certifier (Admin UI)
6. Restart CVS with CVS_SUPER_CERTIFIER_DID set
7. iota-guardian-agent setup
8. iota-guardian-agent register
9. Approve in Certifier Service UI
10. iota-guardian-agent fetch http://localhost:8080/content/test
    Expected output:
      [guardian] 401 — identity required
      [guardian] Signing VP (DID: did:iota:...)
      [guardian] 402 — payment required
      [guardian] NOTE: MVP mode — submitting mock payment proof
      [guardian] Response status: 200
      --- Response (200) ---
      Hello from the protected origin!
```

All ten steps must complete without manual intervention beyond the UI approval in step 9.

---

### 2.4 Security Boundary Tests

These tests specifically probe the trust and isolation guarantees that differentiate IOTA Web Guardian from naive blocklists.

| Threat | Test | Expected result |
|---|---|---|
| **Credential replay** | Resubmit a previously accepted `X-Agent-VP` nonce | `401` — nonce already consumed |
| **Forged VC** | Present a VC signed with a key not in any trusted Certifier's DID Document | `401` — trust chain verification fails |
| **Wrong recipient payment** | Submit a payment proof where the recipient address doesn't match `GUARDIAN_PAYMENT_RECIPIENT` | `402` still required — proof rejected |
| **Token forgery** | Craft an `X-Guardian-Token` JWT signed with a random key | `401` — local JWT signature validation fails |
| **Certifier impersonation** | Register a certifier not listed in the Super Certifier DID Document and attempt to issue a VC | CVS rejects the VP — `{valid: false}` |
| **Private key exposure** | Inspect all HTTP request/response logs across all services during a full fetch flow | Agent private key bytes never appear in any log or network payload |

---

### 2.5 Regression Checklist

Before merging to `main`, the following must all pass:

```bash
cargo test --workspace               # all unit tests green
cargo fmt --all -- --check           # no formatting drift
cargo clippy --all --all-features --all-targets -- -D warnings  # no warnings
pnpm -r check                        # SvelteKit type checks
pnpm -r lint                         # ESLint clean
# Full end-to-end smoke test (§2.3)
```

---

## 3. Product-Market Fit Validation

### 3.1 Target Personas

The MVP targets **independent content creators** in the following order of priority:

| Priority | Persona | Description | Why first |
|---|---|---|---|
| 1 | **WordPress blogger** | Solo creator with 10k–500k monthly visits, tech-literate but not a developer | Largest addressable segment; WordPress plugin removes all friction |
| 2 | **Newsletter author** | Paid newsletter (Substack, Ghost) with SEO-optimised public posts | Direct revenue anxiety about AI substitution |
| 3 | **Journalist / media outlet** | Small editorial team, existing paywall mentality | High willingness to pay for attribution tools |
| 4 | **Developer / technical blogger** | Self-hosted, comfortable with Docker | Will adopt Rust proxy; early adopter amplifier |

### 3.2 Core Hypotheses

Each hypothesis has a null hypothesis (H₀) and a success signal.

#### H1 — The Pain is Real

> **H₀**: Content creators do not perceive uncompensated AI scraping as a meaningful revenue or attribution threat.

> **Success signal**: >60% of interviewees spontaneously mention AI scraping as a concern before we name it, and rate the impact ≥ 4/5 on a severity scale.

#### H2 — The Barrier is Integration Cost

> **H₀**: Content creators are willing to adopt complex technical solutions (server access, DNS changes, infrastructure management) to protect their content.

> **Success signal**: In usability tests, >70% of WordPress bloggers complete a Guardian installation in under 15 minutes with no external help.

#### H3 — Micropayments are Acceptable

> **H₀**: AI Agent companies will not pay per-access micropayments; they prefer bulk licensing or refuse to pay at all.

> **Success signal**: At least two AI Agent company representatives (in interviews or pilot) express willingness to pay ≤ $0.001 per access rather than be blocked entirely.

#### H4 — Trust Chain Resonates

> **H₀**: The KYC/KYB certifier model adds friction that outweighs its value for AI companies.

> **Success signal**: AI company interviewees prefer the credential-based model over IP blocklists or per-domain negotiations, citing legal compliance as a driver.

#### H5 — IOTA Payments are Not a Dealbreaker

> **H₀**: Requiring IOTA-specific payment infrastructure is a hard blocker for adoption by AI companies and content creators.

> **Success signal**: <40% of interviewees cite IOTA-specific tooling as a concern; those who do are satisfied by the explanation that it is invisible to them (handled by the CLI / agent SDK).

---

### 3.3 Qualitative Research

#### Interviews — Content Creators (target: 10 interviews)

**Recruitment**: WordPress community Slack, IndieHackers, Twitter/X #blogging threads.

**Script outline**:

1. *Warm-up (5 min)*: Tell me about your content and how you earn from it.
2. *Problem probe (10 min)*: Have you noticed changes in your organic traffic over the last 18 months? What do you attribute it to? Have you heard about AI scrapers?
3. *Solution probe — unprompted (10 min)*: What have you tried or considered to protect your content? Why did or didn't it work?
4. *Concept test (15 min)*: Show the README flow diagram. Walk through: "You install a plugin, AI agents are required to identify themselves and pay a fraction of a cent per access, humans see no change." Ask: What's confusing? What do you trust or distrust? What would stop you from installing it today?
5. *Pricing (5 min)*: What price per AI access would feel fair vs. insulting vs. worth your time to set up?
6. *Wrap-up*: Would you participate in a paid beta? Can you refer another creator we should speak to?

**Signals to capture**:
- Severity score for AI scraping pain (1–5)
- Spontaneous mention of pain before probe
- Top objections to adoption
- Acceptable price range per AI access
- Willingness to recommend

#### Interviews — AI Agent Companies (target: 5 interviews)

**Recruitment**: AI-focused startup communities, LinkedIn, contacts in LLM tooling companies.

**Script outline**:

1. How does your agent/crawler currently access web content?
2. Have you ever been blocked or rate-limited for scraping? How did you handle it?
3. If a standardised, verified-identity + micropayment protocol existed, what would make you adopt it vs. fight it?
4. What would the payment ceiling be (per access) before you'd just scrape without compliance?
5. Who at your company would make the decision to integrate with such a system?

---

### 3.4 Quantitative Signals

> **Post-hackathon / v0.2 phase.** These metrics require services deployed to a publicly reachable environment so that real content creator sites can install the WordPress plugin or point at the hosted Guardian. Not applicable to the local `docker compose` setup.

These are leading indicators to track during a closed beta (target: 20 content creator sites).

| Metric | Definition | Target (90-day beta) | Interpretation |
|---|---|---|---|
| **Activation rate** | % of signups who complete Guardian setup | ≥ 60% | Measures integration friction |
| **Time to first protection** | Minutes from signup to first blocked AI request | Median ≤ 15 min | Confirms <15min integration promise |
| **Human false-positive rate** | % of human requests incorrectly challenged or blocked | < 0.1% | Core correctness guarantee |
| **AI identification rate** | % of detected AI requests that present valid VP+VC | Baseline measurement — no target yet | Tells us how many agents are compliant |
| **Revenue received** | IOTA micropayments received by beta creators | Any non-zero amount | Proves the payment flow works end-to-end |
| **7-day retention** | % of activated sites still running Guardian after 7 days | ≥ 75% | Measures stickiness vs. uninstall-on-friction |
| **NPS** | Net Promoter Score from beta survey | ≥ 30 | Referral potential |

---

### 3.5 Cohort Experiments

> **Post-hackathon / v0.2 phase.** Requires remote deployment and a live beta cohort.

Two controlled experiments to run during the beta period, each with ≥10 participants per arm.

#### Experiment A — Installation UX (WordPress Plugin)

**Question**: Does a guided onboarding wizard reduce activation drop-off vs. the plain plugin activation screen?

| Arm | Treatment |
|---|---|
| Control | Standard plugin activation, user reads README |
| Treatment | In-plugin setup wizard (5 steps with inline explanations) |

**Primary metric**: % who reach "first AI request blocked" within 24 hours of installing.

**Decision rule**: If treatment arm improves activation by ≥15pp, prioritise wizard in v0.2.

---

#### Experiment B — Pricing Display

**Question**: Does showing estimated monthly earnings (based on site traffic) at setup time increase willingness to configure a price?

| Arm | Treatment |
|---|---|
| Control | Price-per-access input field, no context |
| Treatment | Price field + "Sites like yours earn ~$X/month at this traffic level" |

**Primary metric**: % who set a non-zero price (vs. leaving default).

**Decision rule**: If treatment increases non-zero price selection by ≥20pp, include earnings estimator in v0.2 UI.

---

## 4. Go / No-Go Criteria

The MVP is considered validated when **all** of the following are met:

### Technical

- [ ] End-to-end smoke test (§2.3) passes on a clean machine in under 30 minutes setup time.
- [ ] All unit and integration tests pass (`cargo test --workspace`, `pnpm -r check`).
- [ ] All six security boundary tests (§2.4) pass.
- [ ] Human false-positive rate is zero in smoke test (no human requests blocked or challenged).

### Product

- [ ] ≥6/10 creator interviews confirm AI scraping as a real, felt pain (H1 validated).
- [ ] ≥7/10 creators complete WordPress plugin setup in ≤15 minutes in usability test (H2 validated).
- [ ] At least one AI Agent company representative expresses willingness to pay micropayments (H3 minimum bar).
- [ ] Beta activation rate ≥50% (lower bound — signals the integration is not fatally broken).

### One disqualifying condition

If the human false-positive rate exceeds 0.1% in any production-like test, the MVP is **not shippable** regardless of all other results. Blocking human visitors is an existential risk to adoption: content creators will remove any tool that hurts their audience.

---

## 5. Feedback Loop and Iteration

### Signal collection during beta

Every beta site should have a lightweight feedback path:

1. **In-plugin feedback button** — single question: "Is Guardian working as expected? (yes / no / something's wrong)". Visible in the WP admin panel.
2. **Weekly email digest** to beta users: blocked AI requests count, estimated earnings, one open question (rotating).
3. **Error telemetry** (opt-in): Guardian logs unexpected status codes (not content) to a central endpoint. Allows us to detect CVS or x402 failures before users report them.

### Iteration triggers

| Signal | Action |
|---|---|
| Activation rate < 30% | Halt new signups; run 3 usability sessions to find the blocker; fix before reopening |
| Human false-positive > 0 in beta | Immediate hotfix; email all beta users with status update |
| >3 creators cite IOTA tooling as a blocker | Evaluate abstracting payment layer to support additional networks in v0.2 |
| AI company interview reveals hard blocker to compliance | Reassess trust chain model with that company as design partner |
| NPS < 0 | Stop acquisition; run churn interviews with every departed beta user |

### Cadence

| Week | Activity |
|---|---|
| 1–2 | Deploy to beta cohort; monitor activation and error telemetry |
| 3 | First creator interviews (aim for 5 completed) |
| 4 | Mid-beta review: activation rate, retention, top support tickets |
| 5–6 | Remaining interviews; AI company outreach |
| 7 | Synthesise all signals; go/no-go decision |
| 8 | If go: publish v0.2 roadmap and open public waitlist |