@weave_protocol/ward 0.1.0

package/README.md

@@ -0,0 +1,214 @@
+# 🛡️ @weave_protocol/ward
+
+[![npm version](https://img.shields.io/npm/v/@weave_protocol/ward.svg)](https://www.npmjs.com/package/@weave_protocol/ward)
+[![npm](https://img.shields.io/npm/dm/@weave_protocol/ward.svg)](https://www.npmjs.com/package/@weave_protocol/ward)
+[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+**WARD.md — the agent security policy standard.**
+
+> *AGENTS.md tells your agent what to do.*
+> *SKILL.md tells your agent how to do it.*
+> ***WARD.md tells your agent what it can't.***
+
+Part of the [Weave Protocol](https://github.com/Tyox-all/Weave_Protocol) security suite.
+
+```bash
+npm install @weave_protocol/ward
+```
+
+---
+
+## What is WARD.md?
+
+Agents are now infrastructure-as-code. They're defined in markdown files
+(`AGENTS.md`, `SKILL.md`), version-controlled, and shared across registries.
+
+If agent *behavior* is declared in a file, agent *security* should be too.
+
+**WARD.md** is a standard format for declaring the security policy of an
+AI agent. It lives next to `AGENTS.md` and `SKILL.md` in the same repo,
+and is read by harnesses (Antigravity, Claude Code, MDASH) and runtime
+enforcers (Mund, Hundredmen, Dōmere) to keep the agent inside its lane.
+
+```
+my-agent-project/
+├── AGENTS.md          # what the agent does
+├── SKILL.md           # how the agent does it
+├── WARD.md            # what the agent can't do  ← this package
+└── .weave/
+    └── attestations/  # cryptographic proofs that the policy held
+```
+
+---
+
+## Quick start
+
+```bash
+# Generate a starter WARD.md
+npx @weave_protocol/ward init
+
+# Validate it
+npx @weave_protocol/ward validate WARD.md
+
+# Show a human-readable summary
+npx @weave_protocol/ward explain WARD.md
+```
+
+---
+
+## A minimal WARD.md
+
+```markdown
+---
+ward: "1.0"
+agent: my-data-analyzer
+---
+
+# WARD.md
+
+## Filesystem
+allow:
+  - read: /workspace/**
+  - write: /workspace/output/**
+deny:
+  - read: /workspace/secrets/**
+default: deny
+
+## Network
+deny:
+  - url: "**"
+default: deny
+
+## Capabilities
+allow:
+  - file_read
+  - file_write
+deny:
+  - shell_exec
+default: deny
+
+## Behavioral Limits
+maxIterations: 50
+maxRuntimeSeconds: 300
+maxCostUSD: 5.00
+
+## Verification
+required: true
+backend: domere
+frequency: session_end
+```
+
+That's a complete policy. The agent can read inputs and write outputs, can't
+touch secrets, can't make network calls, can't shell out, can't burn more
+than $5 or run for more than 5 minutes — and every action is attested at
+session end.
+
+---
+
+## Programmatic use
+
+```typescript
+import { parseWard, checkFilesystem, checkNetwork, checkCapability } from "@weave_protocol/ward";
+import { readFileSync } from "node:fs";
+
+const policy = parseWard(readFileSync("./WARD.md", "utf8"));
+
+// Before any filesystem action:
+const fs = checkFilesystem(policy, "read", "/workspace/secrets/keys.txt");
+if (fs.decision !== "allow") throw new Error(fs.reason);
+
+// Before any network call:
+const net = checkNetwork(policy, "https://api.evil.com/exfil", "POST");
+if (net.decision !== "allow") throw new Error(net.reason);
+
+// Before any tool invocation:
+const cap = checkCapability(policy, "shell_exec");
+if (cap.decision === "require_approval") {
+  await promptHuman("shell_exec needs your approval");
+} else if (cap.decision === "deny") {
+  throw new Error(cap.reason);
+}
+```
+
+Every check returns `{ decision: "allow" | "deny" | "require_approval", reason, severity }`
+so hosts can decide whether to block, log, prompt, or attest.
+
+---
+
+## Policy sections
+
+WARD.md is markdown with YAML frontmatter. Each top-level section maps
+to a typed sub-policy:
+
+| Section | Controls |
+|---------|----------|
+| `## Filesystem` | Read/write/execute/delete/list rules with glob patterns |
+| `## Network` | Outbound HTTP allowlist with optional method restrictions |
+| `## Capabilities` | Tools the agent may invoke (with optional approval gating) |
+| `## Data Boundaries` | Egress classifications (PII, PHI, credentials...) and redaction |
+| `## Behavioral Limits` | Iterations, runtime, cost, tokens, tool calls, external services |
+| `## Multi-Agent` | Trust chain, isolation level, semantic drift threshold |
+| `## Compliance` | SOC2 / HIPAA / GDPR / CCPA / ISO27001 / PCI-DSS frameworks |
+| `## Verification` | Attestation backend (Dōmere), blockchain, frequency |
+| `## Threat Model` | Which threats this policy is designed against |
+| `## Incident Response` | What to do when a violation occurs |
+
+See [SPEC.md](./SPEC.md) for the full specification.
+
+---
+
+## CLI
+
+```bash
+weave-ward init [--strict]    Create a starter WARD.md (basic or strict template)
+weave-ward parse <file>       Print parsed policy as JSON
+weave-ward validate <file>    Validate the file and report issues
+weave-ward explain <file>     Human-readable summary
+weave-ward help               Show help
+```
+
+Exit codes for `validate`: `0` = valid, `1` = invalid, `2` = usage error.
+Use in CI to gate PRs that change agent policies.
+
+---
+
+## Examples
+
+The package ships with three example WARD.md files:
+
+- [`examples/basic.WARD.md`](./examples/basic.WARD.md) — read-only data analyzer
+- [`examples/strict.WARD.md`](./examples/strict.WARD.md) — locked-down production deployer
+- [`examples/compliance.WARD.md`](./examples/compliance.WARD.md) — HIPAA + SOC2 healthcare records agent
+
+---
+
+## Why a standard?
+
+The harness wars are on. Google has Antigravity. Microsoft has MDASH.
+Anthropic has Claude Code. Every major platform is building its own
+orchestration layer. Their agent definition formats differ slightly, but
+they're all converging on the same idea: **agents as files**.
+
+What's missing is a portable, declarative way to say *what an agent isn't
+allowed to do*. Today every harness rolls its own ad-hoc allowlist somewhere
+in a config file. That doesn't survive cross-platform agent sharing, doesn't
+gate at PR review time, and isn't cryptographically attestable.
+
+WARD.md is the format that does all three.
+
+---
+
+## Status
+
+**v0.1 (this release):** parser, validator, type system, CLI, runtime check
+primitives (`checkFilesystem`, `checkNetwork`, `checkCapability`,
+`checkDataEgress`, `checkBehavioral`).
+
+**Coming next:** platform adapters for Antigravity / Claude Code / MDASH,
+integration with Mund's scanner, Dōmere attestation hooks, MCP server.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](../LICENSE).

package/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ward
+description: Use this skill when the user wants to define, parse, validate, or enforce security policies for AI agents using the WARD.md standard. Triggers on requests to "add WARD.md", "create agent security policy", "what can this agent do", "lock down this agent", "set up guardrails", "define agent boundaries", or any work involving WARD.md files alongside AGENTS.md / SKILL.md. Also useful when reviewing existing agent code that lacks a declared security policy.
+---
+
+# WARD.md — Agent Security Policy Standard
+
+The `@weave_protocol/ward` package provides the parser, validator, and runtime check primitives for WARD.md files — the standard for declaring AI agent security policies as version-controlled markdown.
+
+## When to use
+
+- User has an agent (LangChain, MCP server, Antigravity, Claude Code, MDASH) and wants to lock down what it can/can't do
+- User has AGENTS.md or SKILL.md files in their repo and needs to add security guardrails
+- User asks "how do I prevent this agent from accessing X" or "how do I limit cost"
+- User wants a portable, declarative security policy that survives across harness platforms
+- User is reviewing an agent project and notices there's no declared policy
+
+## Commands
+
+```bash
+npx @weave_protocol/ward init             # Create a starter WARD.md (basic template)
+npx @weave_protocol/ward init --strict    # Create a strict, default-deny WARD.md
+npx @weave_protocol/ward validate WARD.md # Validate a file
+npx @weave_protocol/ward explain WARD.md  # Human-readable policy summary
+npx @weave_protocol/ward parse WARD.md    # Print parsed policy as JSON
+```
+
+## Programmatic use
+
+```typescript
+import { parseWard, checkFilesystem, checkNetwork, checkCapability } from "@weave_protocol/ward";
+
+const policy = parseWard(wardSource);
+const decision = checkFilesystem(policy, "read", path);
+// decision.decision: "allow" | "deny" | "require_approval"
+```
+
+## What a WARD.md contains
+
+Section headings (H2) define the policy:
+
+- `## Filesystem` — read/write/execute/delete/list rules with glob patterns
+- `## Network` — outbound URL allowlist
+- `## Capabilities` — tools the agent may invoke (with approval gating)
+- `## Data Boundaries` — egress classifications (PII, PHI, credentials)
+- `## Behavioral Limits` — iterations, runtime, cost, tokens
+- `## Multi-Agent` — trust chain, isolation, semantic drift threshold
+- `## Compliance` — SOC2 / HIPAA / GDPR / etc.
+- `## Verification` — attestation backend, blockchain, frequency
+- `## Threat Model` — in-scope / out-of-scope threats
+- `## Incident Response` — what to do on violation
+
+## Decision rules
+
+| Situation | Action |
+|---|---|
+| Greenfield agent, no policy yet | `weave-ward init`, then customize |
+| Production / sensitive agent | `weave-ward init --strict` |
+| User asks "can this agent...?" | Read their WARD.md, run `weave-ward explain` |
+| CI gating PRs | Add `weave-ward validate WARD.md` to the pipeline |
+
+## Templates
+
+The `init` command writes either a **basic** (sensible defaults) or **strict** (default-deny everywhere, approval required for elevated actions, mandatory attestation) starter file. Pick `--strict` when:
+
+- The agent touches production systems
+- The agent handles regulated data (PHI, PCI, PII)
+- The agent has access to credentials or secrets
+- The agent can spend money or invoke side-effectful APIs
+
+Otherwise the basic template is fine and the user can customize from there.
+
+## Anti-patterns
+
+- **Don't reinvent agent allowlists in custom config files.** If the user is hand-rolling permissions, suggest WARD.md instead — it's portable, version-controllable, and CI-validatable.
+- **Don't put secrets in WARD.md.** WARD.md is a *policy* file. It declares what's allowed, not credentials. Secrets belong in Hord or a real secrets manager.
+- **Don't generate WARD.md without showing the user what it permits.** Run `weave-ward explain` after generation so they can see the resulting policy in plain English.
+
+## Pairs with
+
+- `@weave_protocol/mund` — runtime threat scanner that can consume WARD policies
+- `@weave_protocol/domere` — verification backend referenced by `## Verification`
+- `@weave_protocol/hundredmen` — MCP interceptor that enforces capability rules
+- `@weave_protocol/cli` — `weave init` will scaffold a WARD.md alongside framework middleware

package/SPEC.md

@@ -0,0 +1,258 @@
+# WARD.md Specification
+
+Version 1.0 · April 2026
+
+This document specifies the WARD.md file format: a portable, version-controlled standard for declaring AI agent security policies.
+
+> Implementation details of how WARD.md policies are enforced at runtime, attested, or cross-validated against other harness layers are intentionally not published here. This document covers the file format only.
+
+---
+
+## 1. File location
+
+A WARD.md file is named `WARD.md` (case-insensitive in practice; the canonical form is uppercase). It typically sits at the root of an agent's directory, alongside `AGENTS.md` and `SKILL.md`:
+
+```
+my-agent/
+├── AGENTS.md
+├── SKILL.md
+└── WARD.md
+```
+
+For multi-agent harnesses, each agent may have its own WARD.md in its own subdirectory, plus optionally a top-level WARD.md governing the harness as a whole.
+
+---
+
+## 2. Structure
+
+A WARD.md file has two parts:
+
+1. **YAML frontmatter** between two `---` lines. Contains metadata about the policy itself.
+2. **Markdown body** containing one or more **policy sections**, each introduced by an H2 heading (`##`).
+
+```markdown
+---
+ward: "1.0"
+agent: my-agent
+name: Optional human name
+description: Optional description
+---
+
+# WARD.md
+
+## Filesystem
+...
+
+## Network
+...
+```
+
+The body may contain prose for human readers. Only H2 sections are interpreted as policy.
+
+---
+
+## 3. Frontmatter
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `ward` | string | yes | Spec version. `"1.0"` for this document. |
+| `agent` | string | no | Identifier or relative path referencing an AGENTS.md file. |
+| `name` | string | no | Human-readable policy name. |
+| `description` | string | no | One-line description. |
+
+---
+
+## 4. Section format
+
+Section bodies are interpreted as a YAML-like block. Each section has a fixed schema documented below. Sections may appear in any order. Unknown sections are preserved as opaque text — they don't break parsing, but they don't enforce anything either.
+
+For each rule-based section (Filesystem, Network, Capabilities), the schema is:
+
+```yaml
+allow:
+  - <rule>
+  - <rule>
+deny:
+  - <rule>
+  - <rule>
+default: allow | deny
+```
+
+**Evaluation order:** deny rules are checked first. If no deny rule matches, allow rules are checked. If no rule matches, the `default` is applied. If `default` is unspecified, it is `deny` for hard-security sections (Filesystem, Network, Capabilities) and `allow` for soft sections.
+
+---
+
+## 5. The sections
+
+### 5.1 `## Filesystem`
+
+```yaml
+allow:
+  - read: /workspace/**
+  - write: /workspace/output/**
+  - list: /workspace/**
+deny:
+  - read: ~/.ssh/**
+  - read: /workspace/secrets/**
+  - execute: "**"
+default: deny
+```
+
+**Operations:** `read`, `write`, `execute`, `delete`, `list`.
+
+**Paths:** glob patterns. `*` matches any character except `/`. `**` matches across `/`. `?` matches a single character.
+
+### 5.2 `## Network`
+
+```yaml
+allow:
+  - url: "https://api.company.com/**"
+    methods: [GET, POST]
+deny:
+  - url: "**"
+default: deny
+```
+
+**`url`:** glob pattern matched against the full URL.
+**`methods`:** optional list of HTTP methods this rule applies to. Omit to apply to all.
+
+### 5.3 `## Capabilities`
+
+```yaml
+allow:
+  - file_read
+  - file_write
+  - http_request
+requireApproval:
+  - secrets_read
+  - code_exec
+deny:
+  - shell_exec
+  - ssh
+  - sudo
+default: deny
+```
+
+Tool names are strings. They may use glob patterns.
+
+`requireApproval` produces a `require_approval` decision at runtime — hosts decide how to gather approval (chat prompt, webhook, etc).
+
+### 5.4 `## Data Boundaries`
+
+```yaml
+egressAllow: [public, internal]
+egressDeny: [confidential, secret, pii, phi, pci, credentials]
+redact:
+  - type: pii
+    replacement: "[REDACTED]"
+```
+
+**Classifications:** `public`, `internal`, `confidential`, `secret`, `pii`, `phi`, `pci`, `credentials`. Custom classifications are permitted; hosts may ignore unrecognized ones.
+
+### 5.5 `## Behavioral Limits`
+
+```yaml
+maxIterations: 50
+maxRuntimeSeconds: 300
+maxCostUSD: 5.00
+maxTokens: 100000
+maxToolCalls: 30
+maxExternalServices: 3
+```
+
+All fields are optional. A missing field means the limit is unenforced.
+
+### 5.6 `## Multi-Agent`
+
+```yaml
+isolation: strict
+maxSemanticDrift: 0.3
+trustChain:
+  upstream: [data-fetcher]
+  downstream: [report-generator]
+```
+
+**`isolation`:** `none`, `soft`, `strict`, `sandboxed`.
+**`maxSemanticDrift`:** number 0–1. The interpretation is host-specific.
+**`trustChain`:** which other agents may hand work to / receive work from this one.
+
+### 5.7 `## Compliance`
+
+```yaml
+frameworks: [soc2, hipaa, gdpr]
+backend: domere
+```
+
+Declaring a framework signals that the agent operates under that regime. Hosts may auto-inject additional constraints (e.g., HIPAA implies certain data classifications must be in `egressDeny`).
+
+### 5.8 `## Verification`
+
+```yaml
+required: true
+backend: domere
+blockchain: solana
+frequency: every_action
+attestor: <pubkey or DID>
+```
+
+**`frequency`:** `every_action`, `every_handoff`, `every_iteration`, `session_end`, `manual`.
+
+### 5.9 `## Threat Model`
+
+```yaml
+inScope:
+  - prompt_injection
+  - data_exfil
+  - credential_theft
+outOfScope:
+  - physical_attack
+  - side_channel
+```
+
+Informational. Documents what the policy is designed to defend against. Hosts may use this to tune scanner sensitivity.
+
+### 5.10 `## Incident Response`
+
+```yaml
+onViolation:
+  - log
+  - alert
+  - terminate
+  - attest_violation
+severityThreshold: medium
+```
+
+**Actions:** `log`, `alert`, `terminate`, `rollback`, `attest_violation`, `notify_human`, `block_further`.
+**`severityThreshold`:** minimum severity at which actions fire. `low` | `medium` | `high` | `critical`.
+
+---
+
+## 6. Validation
+
+A WARD.md file is **valid** if it parses and contains no semantic errors. It may still produce **warnings** for missing recommended sections (e.g., no behavioral limits, no verification).
+
+CI integrations should treat `weave-ward validate` exit code `1` as a failed check.
+
+---
+
+## 7. Versioning
+
+This document specifies `ward: "1.0"`. Future minor versions will add sections or fields and remain backwards compatible. Major version bumps may change the semantics of existing fields and will require explicit migration.
+
+---
+
+## 8. Extensions
+
+The format is intentionally extensible. Unknown sections are preserved by parsers and may be interpreted by host-specific tooling. Hosts wishing to add proprietary sections should namespace them (e.g., `## X-CompanyName-Policy`).
+
+---
+
+## 9. Reference implementation
+
+The reference parser, validator, and runtime check primitives are published as [`@weave_protocol/ward`](https://www.npmjs.com/package/@weave_protocol/ward). All other implementations must produce equivalent results for any well-formed WARD.md file.
+
+---
+
+## 10. License
+
+This specification is published under [Apache 2.0](../LICENSE). The format is free to adopt without restriction.

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * weave-ward CLI
+ *
+ *   weave-ward init                       Generate a starter WARD.md
+ *   weave-ward parse <file>               Print parsed policy as JSON
+ *   weave-ward validate <file>            Validate and show issues
+ *   weave-ward explain <file>             Human-readable policy summary
+ *   weave-ward help
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}