Metadata-Version: 2.4
Name: wais-validator
Version: 0.1.0
Summary: Validate WAIS agents.json compliance. CLI + library.
Author-email: Deeger <hello@deeger.io>
License-Expression: MIT
Project-URL: Homepage, https://deeger.io
Project-URL: Repository, https://github.com/deegerhq/wais-validator
Keywords: ai,agents,wais,validation,agents-json
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wais-pod>=0.2.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# wais-validator

Validate [WAIS](https://deeger.io) `agents.json` manifests against the spec. CLI tool + Python library.

Checks your manifest for schema compliance, scope validity, risk level rules, endpoint liveness, JWKS reachability, and cross-field consistency — then gives you a score with actionable fix suggestions.

## Install

```bash
pip install -e ".[dev]"
```

Requires Python 3.10+ and [wais-pod](https://github.com/deegerhq/wais-pod).

## Usage

### Validate a live site

```bash
wais validate https://example.com
```

Fetches `/.well-known/agents.json` automatically.

### Validate a local file

```bash
wais validate --file agents.json
```

### Schema-only mode (skip HTTP checks)

```bash
wais validate --file agents.json --schema-only
```

### JSON output for CI

```bash
wais validate --file agents.json --format json
```

Exit code: `0` if score >= 50 (grade C or above), `1` otherwise.

## What it checks

| Category | What | Severity |
|----------|------|----------|
| **Schema** | JSON Schema validation against WAIS v0.1 spec | FAIL |
| **Scopes** | Standard scope validity, custom scope declarations, `standard_scopes_used` consistency | FAIL / WARN |
| **Risk** | Risk level overrides (can't lower below WAIS minimum), confirmation/payment vs risk | FAIL / WARN |
| **Endpoints** | HTTP liveness for each action endpoint (HEAD with OPTIONS fallback) | FAIL / WARN |
| **Auth** | JWKS reachability for each trusted issuer | FAIL / WARN |
| **Consistency** | HTTPS enforcement, duplicate action IDs, payment section presence | FAIL / WARN |

## Example output

A manifest with issues:

```
Validating: agents.json

  ✓ Schema Validation — 1 check(s) passed

  Risk Level Checks  2 error(s)
    ✗ Action 'cheap_checkout' sets risk_level to 'low' but the WAIS minimum for 'checkout.execute' is 'high'
      at actions[0].risk_level
      Fix: Set risk_level to "high" or higher (or remove it to use the standard).

  Consistency Checks  2 error(s), 1 warning(s)
    ✗ site.url uses 'http://' but WAIS requires HTTPS in production
      at site.url
      Fix: Change site.url to use https://. Only http://localhost is allowed for development.
    ✗ Duplicate action id 'browse_catalog' — also defined at actions[0]
      at actions[1].id
      Fix: Rename one of the 'browse_catalog' actions to have a unique id.
    ⚠ Some actions have requires_payment=true but the manifest has no 'payment' section
      at payment
      Fix: Add a "payment" section to your manifest with model, providers, and currencies.

╭──────────────────────── Result ────────────────────────╮
│ Score: 63/100    Grade: C    5 issue(s) found.         │
╰────────────────────────────────────────────────────────╯
```

A clean manifest:

```
Validating: agents.json

  ✓ Schema Validation — 1 check(s) passed
  ✓ Scope Checks — 4 check(s) passed
  ✓ Risk Level Checks — 4 check(s) passed
  ✓ Endpoint Liveness — 5 check(s) passed
  ✓ Authentication (JWKS) — 1 check(s) passed
  ✓ Consistency Checks — 1 check(s) passed

╭──────────────────────── Result ────────────────────────╮
│ Score: 100/100    Grade: A    No issues found.         │
╰────────────────────────────────────────────────────────╯
```

## Scoring

| Category | Weight |
|----------|--------|
| Schema | 30 pts |
| Scopes | 15 pts |
| Risk | 15 pts |
| Endpoints | 20 pts |
| Auth | 10 pts |
| Consistency | 10 pts |

Each FAIL deducts proportionally from its category. Warnings deduct 25% of what a FAIL would. Skipped categories (e.g. `--schema-only`) redistribute their points.

| Grade | Score |
|-------|-------|
| A | 90–100 |
| B | 75–89 |
| C | 50–74 |
| D | 25–49 |
| F | 0–24 |

## Use as a library

```python
from wais_validator import SYNC_VALIDATORS, compute_score, Category
import json

manifest = json.load(open("agents.json"))

results = []
for validator in SYNC_VALIDATORS:
    results.extend(validator(manifest))

score, grade = compute_score(results, active_categories={
    Category.SCHEMA, Category.SCOPES, Category.RISK, Category.CONSISTENCY
})

for r in results:
    if r.fix:
        print(f"{r.severity.value}: {r.message}\n  Fix: {r.fix}")
```

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
```

## License

MIT
