Policy Kit

The @peac/control package provides programmatic policy evaluation. Parse peac.txt policy files, fetch policies from issuer URLs, evaluate purpose-based access rules, and enforce consent decisions in your application.

---

Install

Terminal

pnpm add @peac/control

---

Parse a policy

Parse a peac.txt policy string into a structured, queryable object:

parse-policy.ts

import { parsePolicy } from '@peac/control';

const policy = await parsePolicy(`
version: 0.9.2
protocol: peac
peac:
  consent:
    ai_training: conditional
    scraping: denied
  economics:
    pricing: $0.01/gb
  attribution:
    required: true
`);

console.log(policy.consent.ai_training); // 'conditional'
console.log(policy.attribution.required); // true

---

Fetch and parse from URL

Fetch a policy directly from an issuer's well-known endpoint:

fetch-policy.ts

import { fetchPolicy } from '@peac/control';

const policy = await fetchPolicy('https://api.example.com');
// Fetches /.well-known/peac.txt and parses it

fetchPolicy() resolves the issuer URL to /.well-known/peac.txt, fetches the file, and returns the same parsed policy object as parsePolicy().

---

Evaluate purpose

Check whether a specific purpose is allowed under a parsed policy:

evaluate-purpose.ts

import { evaluatePurpose } from '@peac/control';

const result = evaluatePurpose(policy, 'train');
// { allowed: false, reason: 'ai_training is conditional' }

const result2 = evaluatePurpose(policy, 'search');
// { allowed: true }

Canonical purpose tokens

Token	Meaning
train	AI model training
search	Search engine indexing
inference	Real-time inference against content
index	General content indexing
user_action	Direct user-initiated action

First-match-wins evaluation

Purpose evaluation matches the declared token against the policy's ordered rules and returns the first match. If no rule matches, the purpose is denied by default.

---

PEAC-Purpose header

Clients declare their intended purpose using the PEAC-Purpose HTTP header. The middleware can then evaluate the declared purpose against the published policy before issuing a receipt.

HTTP Request

GET /api/data HTTP/1.1
Host: api.example.com
PEAC-Purpose: search

When combined with the Express middleware, purpose evaluation happens automatically -- the middleware reads the PEAC-Purpose header, evaluates it against the issuer's policy, and includes the result in the signed receipt.

---

Next steps

Policy (peac.txt)

The policy file format, well-known endpoint, and field reference.

Express Middleware

Auto-enforce policies and issue receipts in Express.js.

Protocol Scope

The verification domains that PEAC evidence covers.