# WonderHive

WonderHive provides nine security, accessibility, performance, signing, monitoring, security-awareness, and trust evidence tools. Every product exposes a REST API under `/api/v1/` with Bearer token / API-key auth.

## Authentication

All product APIs support two auth methods:
- **Bearer token**: `Authorization: Bearer <api_key>` — API keys are created per-product via POST to `/api/v1/api-keys`
- **Session cookie**: Browser session obtained via Magic Link or Google OAuth login

Public endpoints (no auth): `POST /auth/login`, `POST /auth/magic-link`, `POST /auth/token`, `GET /products`

## API Discovery

Each product serves its [OpenAPI 3.2 spec](https://sentinel.wonderhive.org/api/v1/openapi.json) at `https://{product}.wonderhive.org/api/v1/openapi.json`.

| Product | Host | API Endpoints |
|---------|------|--------------|
| Gateway | wonderhive.org | Static homepage. No API. Product discovery via HTML links. |
| Sentinel | sentinel.wonderhive.org | Domains, DNS, alerts, audit-log (QUERY), API keys, products, plan (PATCH), checkout |
| VulnScanner | vulnscanner.wonderhive.org | Scans (QUERY), findings, products, orders, API keys, user settings (PATCH) |
| Lighthouse | lighthouse.wonderhive.org | Audits (QUERY), reports, orders, products, plan (PATCH), API keys |
| PhishSim | phishingsim.wonderhive.org | Campaigns (QUERY), employees, reports, products, plan, checkout, API keys |
| Accessibility | accessibility.wonderhive.org | Scans (QUERY), products, plan, checkout, auth |
| Printer | printer.wonderhive.org | Orders (QUERY), products, plan (PATCH), checkout, auth |
| Signer | signer.wonderhive.org | Orders (QUERY), signing, products, plan (PATCH), checkout, API keys |
| Trust Center | trust.wonderhive.org | Evidence, audit, WORM status |

## Product-Specific Agent Guidance

Each product has its own `llms.txt` with agent tools defined for its specific domain:

| Product | Guidance URL |
|---------|-------------|
| Sentinel | https://sentinel.wonderhive.org/llms.txt |
| VulnScanner | https://vulnscanner.wonderhive.org/llms.txt |
| Lighthouse | https://lighthouse.wonderhive.org/llms.txt |
| PhishSim | https://phishingsim.wonderhive.org/llms.txt |
| Accessibility | https://accessibility.wonderhive.org/llms.txt |
| Printer | https://printer.wonderhive.org/llms.txt |
| Signer | https://signer.wonderhive.org/llms.txt |
| Trust Center | https://trust.wonderhive.org/llms.txt |

## WebMCP Operations (Gateway Homepage)

The gateway homepage at https://wonderhive.org exposes these WebMCP tools via `/webmcp.json`:
- `list_products` — lists all 9 products with descriptions, URLs, and API base paths
- `get_product_details` — returns detailed info for a specific product by slug
- `get_llms_guidance` — returns this file (text/markdown)
- `get_product_llms_guidance` — returns the product-specific llms.txt for a given slug
- `get_sitemap` — returns the sitemap XML URL
- `get_openapi_spec` — returns the OpenAPI 3.2 spec URL for a specific product
- `get_authentication_guide` — returns authentication methods for all product APIs
- `get_agent_lifecycle` — returns the discover, auth, pay, use, MFA, and logout path
- `get_gdpr_guide` — returns data export and account deletion guidance
- `get_worm_status` — returns WORM audit status endpoint guidance
- `get_mfa_guide` — returns MFA setup, verification, and recovery-code guidance
- `navigate_to_product` — navigate to a specific product by slug

## Browser Interaction Flow

Agents can complete the customer path through visible pages or documented APIs:

1. View the gateway homepage at `https://wonderhive.org/` and choose a product link from the tool list.
2. Read the selected product's `/llms.txt` and `/api/v1/openapi.json` before acting.
3. Login on the product host at `/auth/login.php` using Google OAuth or Magic Link.
4. View plans on the product pricing page, then pay through the visible checkout form or `POST /api/v1/checkout` with an `Idempotency-Key`.
5. Return to the product dashboard and use rendered forms/buttons for browser actions, or call authenticated `/api/v1/` endpoints defined by OpenAPI.
6. Manage billing through `POST /api/v1/billing-portal`; logout through the visible logout control or `POST /api/v1/logout.php` with CSRF for cookie sessions.

Agents must not invent hidden flows, bypass reCAPTCHA/MFA/CSRF, or persist bearer/API-key credentials into browser sessions.

## Agent Lifecycle

1. Discover: `GET /webmcp.json`, then `GET /llms.txt`, then `GET /{product}/llms.txt`, then `GET /{product}/api/v1/openapi.json`.
2. Authenticate: use Magic Link or Google OAuth in the browser, or create an API key with `POST /api/v1/api-keys`. API keys are shown once at creation and are stored hash-only.
3. Pay: `GET /api/v1/products`, then `POST /api/v1/checkout` with an `Idempotency-Key` header, then verify access with `GET /api/v1/plan`.
4. Use: call product endpoints from the committed OpenAPI 3.2 spec at `/{product}/api/v1/openapi.json`.
5. Manage subscription: `POST /api/v1/billing-portal`.
6. MFA: `POST /api/v1/auth/mfa/setup`, `POST /api/v1/auth/mfa/verify`, and `POST /api/v1/auth/mfa/recovery-codes`. Billing changes, API-key creation, and data exports may require MFA step-up.
7. GDPR: `POST /api/v1/data/export` and `POST /api/v1/account/delete`.
8. WORM status: `GET /api/v1/worm/status` with `Authorization: Bearer <secret>`.
9. Logout: `POST /api/v1/logout.php`; cookie sessions require CSRF protection.

## Agent Guidance

- The gateway homepage is static HTML with no product runtime dependency.
- Do not infer hidden gateway actions: the homepage has no forms, AJAX fragments, or administrative actions.
- Product actions require authentication on the product host. See each product's `/api/v1/openapi.json` for full endpoint documentation.
- Use `QUERY` (RFC 9110) for body-bearing filtered searches on primary collections (scans, audits, orders, reports).
- Use `PATCH` for partial updates to resources (plan, settings).
- All APIs use JSON request/response bodies. Errors return `{"error": "<message>"}` with appropriate HTTP status.
- Use `www.recaptcha.net` for browser reCAPTCHA flows.
- Treat API-key authentication as request-local; do not persist bearer credentials into browser sessions.
- Rate limits apply per API key. `429 Too Many Requests` includes a `Retry-After` header.
- Homepage discovery path: `/webmcp.json` (WebMCP tools) → `/llms.txt` (agent guidance) → `/{product}/llms.txt` (product agent tools) → `/{product}/api/v1/openapi.json` (API specs).