Alpha documentation

Integrate one honest decision path.

Start with a public policy, explicit identity confidence, origin-side enforcement, and a receipt that does not overstate what happened.

1. Alpha contract

Input

— ward.json policy
— request path
— declared crawler
— optional verification evidence

Output

— allow / observe / redact
— claimed / verified / mismatch
— policy version and rule
— optional evidence receipt

No receipt proves downstream training, storage, summarisation, or attribution. Read the complete contract.

2. Verify before installing

The reference site exposes its policy and status without an account.

curl -sS https://getward.org/.well-known/ward.json
curl -sS https://getward.org/api/ward/status
curl -sS -D - -o /dev/null -A 'GPTBot/1.0' \
  https://getward.org/ward-canary

See the expected headers and full response comparison on the live proof page.

3. Publish ward.json

Place a policy at /.well-known/ward.json. A path rule may reserve a represented use or force marked-block redaction.

{
  "version": "1.0",
  "publisher": "Example Publisher",
  "enforcement": "server",
  "default": {
    "indexing": true,
    "training": false,
    "summarization": true
  },
  "rules": [{
    "path": "/private-contact",
    "summarization": false,
    "redact": true
  }]
}

4. Evaluate and enforce

The repository alpha separates detection, verification and policy evaluation. The npm package exposes this contract as version 0.2; pin the exact release you have inspected.

import {
  inspectCrawlerIdentity,
  evaluateWardRequest,
  redactHtml,
} from "ward-protocol";

const identity = inspectCrawlerIdentity(userAgent, {
  verification: await verifyAtTheOrigin(request),
});

if (identity) {
  const decision = evaluateWardRequest({ policy, path, identity });
  const result = decision.action === "redact"
    ? redactHtml(html)
    : { html, redactedCount: 0, reasons: [] };
}

Next.js App Router: do not post-process only the HTML shell. A protected value can also appear in the React Server Component payload. Decide in middleware, forward the decision as a request header, and omit the value during server rendering.

5. Emit decision headers

X-WARD-Bot-Detected	Registry name matched by the request
X-WARD-Identity	claimed, verified, or mismatch
X-WARD-Identity-Method	user-agent or deployment verification method
X-WARD-Action	allow, observe, or redact
X-WARD-Uses	training, search-index, or user-fetch
X-WARD-Policy-Hash	SHA-256 of the evaluated policy in WARD Alpha canonical JSON
X-WARD-Event-Id	Idempotency key for the optional receipt

6. Store an optional evidence receipt

Create a project in the alpha dashboard, then POST the origin decision. Do not send response bodies or raw visitor IP addresses.

POST /api/v1/events
Authorization: Bearer YOUR_PROJECT_KEY
Content-Type: application/json

{
  "sourceEventId": "e941…",
  "botName": "GPTBot",
  "botCompany": "OpenAI",
  "path": "/ward-canary",
  "identityStatus": "claimed",
  "identityMethod": "user-agent",
  "uses": ["training"],
  "action": "redact",
  "policyVersion": "1.0",
  "policyHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "matchedRule": "/ward-canary"
}

A successful create returns 201 with a receipt id. Retrying the same sourceEventId returns the existing receipt with duplicate: true.

7. Deployment gates

Test human, training, search-index, user-fetch, and mismatch cases.
Search the complete response—including streamed payloads—for protected fixtures.
Keep origin IP verification behind a trusted proxy boundary.
Pin the policy hash and exact library version in evidence.
Treat the dashboard as decision telemetry, not proof of training.