feat: v0.2 Enterprise-Grade Trust Verification Protocol (#14)

feat: v0.2 Enterprise-Grade Trust Verification Protocol

Author: shivdeep1

.gitignore

@@ -82,4 +82,8 @@ ROLL_OUT_STATUS.md
 LLM_HANDOFF.md
 .hypothesis/
 COWORK.md
+REVIEW_BRIEF.md
+AIRLOCK_COMPANY.md
+PROTOCOL_DEBATE.md
+IMPLEMENTATION_PLAN.md
 .claude/

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to the Airlock Protocol are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-04-05
+
+### Added
+- **Trust Tiers**: Progressive trust levels (UNKNOWN -> CHALLENGE_VERIFIED -> DOMAIN_VERIFIED -> VC_VERIFIED) with configurable score ceilings per tier
+- **Tiered Decay**: Per-tier reputation half-lives (30/90/180/365 days) with decay floor at 0.60 for established agents
+- **Proof-of-Work**: SHA-256 Hashcash anti-Sybil protection on handshake with adaptive difficulty
+- **Privacy Mode**: `privacy_mode` field in HandshakeRequest (`any`/`local_only`/`no_challenge`) for GDPR/DPDP compliance
+- **Structured LLM Output**: JSON schema evaluation via LiteLLM `response_format` parameter
+- **Dual-LLM Evaluation**: Optional second model cross-validation with conservative agreement protocol
+- **Answer Fingerprinting**: SimHash + SHA-256 duplicate/near-duplicate detection for bot farm defense
+- New `GET /pow-challenge` endpoint for PoW challenge issuance
+- `TrustTier` IntEnum in attestations for relying party visibility
+- `fingerprint_flags` field in AirlockAttestation
+- 60+ new tests (property-based, security, integration)
+
+### Changed
+- `AirlockAttestation` now includes `tier`, `privacy_mode`, and `fingerprint_flags` fields
+- `HandshakeRequest` now includes optional `pow` and `privacy_mode` fields
+- Reputation scoring respects tier ceilings (LLM-only agents capped at 0.70)
+- Decay uses tier-specific half-lives instead of single global value
+
+### Security
+- PoW prevents Sybil/DoS attacks on handshake endpoint
+- Answer fingerprinting detects coordinated bot farm submissions
+- Dual-LLM evaluation requires attacker to fool two independent models
+- `privacy_mode: local_only` prevents data from leaving gateway instance
+
 ## [0.1.0] - 2026-04-01
 
 ### Added
@@ -33,5 +60,5 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - IETF Internet-Draft specification (draft-airlock-agent-trust-00)
 - Protocol specification (790 lines, RFC-style)
 - Monitoring and deployment documentation
-- 306 tests passing across 30 test files
-- Apache 2.0 license
+- 338 tests passing across 30 test files
+- BSL 1.1 gateway license, Apache 2.0 SDKs, CC-BY-4.0 spec

CLAUDE.md

@@ -36,12 +36,15 @@ airlock/
   engine/       — Orchestrator, event bus, state machine
   gateway/      — FastAPI routes and handlers
   integrations/ — Anthropic, LangChain, OpenAI SDKs
+  pow.py        — Proof-of-Work (SHA-256 Hashcash, adaptive difficulty)
   registry/     — Agent registry and store
-  reputation/   — Trust scoring and decay
+  reputation/   — Trust scoring, tiered decay, floor protection
   schemas/      — Pydantic models
+    trust_tier.py — TrustTier IntEnum + score ceilings
   sdk/          — Client SDK and middleware
   semantic/     — Challenge evaluation + rule engine
-tests/          — 27 test files, 198+ tests
+    fingerprint.py — SimHash + SHA-256 answer fingerprinting
+tests/          — 399+ tests (unit, integration, property-based, security)
 ```
 
 ## Conventions
@@ -55,6 +58,7 @@ tests/          — 27 test files, 198+ tests
 - **No print():** Use `logging` module. Never print() in library code.
 - **DID format:** Always validate DID strings match `did:key:z6Mk...` pattern before processing.
 - **Secrets:** Never log or expose private keys, challenge secrets, or JWT tokens.
+- **Feature flags:** All new v0.2 features have feature flags in config.py for backward compatibility.
 
 ## Common Mistakes to Avoid
 - Don't use `json.dumps()` for Pydantic models — use `model.model_dump_json()`

CONTRIBUTING.md

@@ -24,7 +24,13 @@ pip install -e ".[dev]"
 python -m pytest tests/ -v
 ```
 
-All new code must include tests. The test suite must maintain 338+ passing tests.
+All new code must include tests. The test suite must maintain 399+ passing tests.
+
+Test categories include:
+- **Unit tests** — Individual module behavior
+- **Integration tests** — Cross-module and gateway end-to-end flows
+- **Property-based tests** — Hypothesis-driven invariant checking (crypto, scoring, fingerprinting)
+- **Security tests** — Sybil resistance, replay protection, injection mitigation
 
 ## Linting
 

README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/airlock-protocol/airlock/actions/workflows/ci.yml/badge.svg)](https://github.com/airlock-protocol/airlock/actions/workflows/ci.yml)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![License](https://img.shields.io/badge/License-Multi--License-blue.svg)](#license)
 [![PyPI version](https://img.shields.io/pypi/v/airlock-protocol.svg)](https://pypi.org/project/airlock-protocol/)
 [![DCO](https://img.shields.io/badge/DCO-required-brightgreen.svg)](https://developercertificate.org/)
 
@@ -12,6 +12,21 @@
 
 ---
 
+## What's New in v0.2
+
+### Trust & Security
+- **Trust Tiers** — Progressive trust levels (Unknown -> Challenge-Verified -> Domain-Verified -> VC-Verified) with score ceilings
+- **Proof-of-Work** — SHA-256 Hashcash anti-Sybil protection on handshake
+- **Privacy Mode** — `local_only`, `any`, `no_challenge` modes for GDPR/DPDP compliance
+- **Dual-LLM Evaluation** — Optional cross-validation with conservative agreement
+- **Answer Fingerprinting** — SimHash + SHA-256 bot farm detection
+- **Structured LLM Output** — JSON schema evaluation (no free-text parsing)
+- **Tiered Decay** — Per-tier reputation half-lives with floor protection
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release notes.
+
+---
+
 ## The Problem
 
 AI agents are rapidly gaining the ability to communicate with each other autonomously (via protocols like Google A2A and Anthropic MCP). There is no standard mechanism for verifying agent identity, authorization, or trustworthiness. The agent ecosystem is repeating the same mistake email made — building communication without authentication. Email took 20 years to bolt on SPF, DKIM, and DMARC after spam became an existential crisis. The Agentic Airlock builds the trust layer *before* the agent spam crisis hits.
@@ -56,6 +71,8 @@ Resolve → Handshake → Challenge → Verdict → Seal
                         └─────┴─────────────────────────────────── ┘
 ```
 
+**v0.2 additions:** Handshake now supports optional **Proof-of-Work** (SHA-256 Hashcash) for anti-Sybil protection. Agents are assigned a **Trust Tier** (Unknown/Challenge-Verified/Domain-Verified/VC-Verified) that governs score ceilings and decay rates. **Privacy Mode** (`local_only`/`any`/`no_challenge`) allows callers to control data residency for GDPR/DPDP compliance. Challenge evaluation supports **Dual-LLM** cross-validation with conservative agreement.
+
 ---
 
 ## The 5 Phases
@@ -105,7 +122,7 @@ git clone https://github.com/airlock-protocol/airlock.git
 cd airlock
 pip install -e ".[dev]"
 python demo/run_demo.py       # 3-agent demo, no external services needed
-python -m pytest tests/ -v    # 313 tests
+python -m pytest tests/ -v    # 399+ tests
 ```
 
 > **[→ Full Getting Started Guide](GETTING_STARTED.md)**
@@ -154,7 +171,8 @@ When you publish: see **[RELEASING.md](RELEASING.md)** (PyPI OIDC, npm `NPM_TOKE
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `POST` | `/resolve` | Look up an agent by DID and return its profile |
-| `POST` | `/handshake` | Submit a signed `HandshakeRequest` for verification |
+| `POST` | `/handshake` | Submit a signed `HandshakeRequest` for verification (optional PoW + privacy_mode) |
+| `GET` | `/pow-challenge` | Issue a Proof-of-Work challenge (SHA-256 Hashcash, adaptive difficulty) |
 | `POST` | `/challenge-response` | Submit an agent's answer to a semantic challenge |
 | `POST` | `/register` | Register an `AgentProfile` (DID + capabilities + endpoint) |
 | `POST` | `/feedback` | Signed `SignedFeedbackReport` (Ed25519 + nonce); see SDKs |
@@ -196,15 +214,26 @@ New agents start at a neutral score of **0.50**.
 | `REJECTED` | `−0.15` (fixed penalty) |
 | `DEFERRED` | `−0.02` (small nudge — ambiguity is a signal) |
 
+### Trust Tiers (v0.2)
+
+| Tier | Score Ceiling | Decay Half-Life |
+|------|---------------|-----------------|
+| `UNKNOWN` | 0.50 | 30 days |
+| `CHALLENGE_VERIFIED` | 0.70 | 90 days |
+| `DOMAIN_VERIFIED` | 0.90 | 180 days |
+| `VC_VERIFIED` | 1.00 | 365 days |
+
+Agents with 10+ interactions have a decay floor of **0.60** — established agents never drop back to fully unknown.
+
 ### Half-Life Decay
 
 Scores decay toward neutral (0.50) over time using the standard radioactive decay formula:
 
 ```
-decayed = 0.5 + (score − 0.5) × 2^(−elapsed_days / 30)
+decayed = 0.5 + (score − 0.5) × 2^(−elapsed_days / half_life)
 ```
 
-An agent that stops interacting gradually becomes "unknown" rather than "suspect" — matching real-world trust intuitions. The half-life is 30 days.
+In v0.2, `half_life` is tier-specific (see table above) instead of a single global value. An agent that stops interacting gradually becomes "unknown" rather than "suspect" — matching real-world trust intuitions.
 
 ---
 
@@ -214,6 +243,7 @@ An agent that stops interacting gradually becomes "unknown" rather than "suspect
 airlock-protocol/
 ├── airlock/
 │   ├── config.py                  # Pydantic settings (env vars with AIRLOCK_ prefix)
+│   ├── pow.py                     # Proof-of-Work (SHA-256 Hashcash, adaptive difficulty)
 │   ├── crypto/
 │   │   ├── keys.py                # Ed25519 KeyPair + did:key encoding/decoding
 │   │   ├── signing.py             # sign_model / verify_model + canonicalization
@@ -227,28 +257,30 @@ airlock-protocol/
 │   │   ├── handlers.py            # Request handlers (signature gate + event publish)
 │   │   └── routes.py              # FastAPI router + endpoint wiring
 │   ├── reputation/
-│   │   ├── scoring.py             # Half-life decay + verdict delta computation
+│   │   ├── scoring.py             # Tiered decay + verdict delta + floor protection
 │   │   └── store.py               # LanceDB-backed TrustScore persistence
 │   ├── schemas/
 │   │   ├── challenge.py           # ChallengeRequest + ChallengeResponse
 │   │   ├── envelope.py            # MessageEnvelope, TransportAck, TransportNack
 │   │   ├── events.py              # VerificationEvent hierarchy (typed)
-│   │   ├── handshake.py           # HandshakeRequest + HandshakeResponse
+│   │   ├── handshake.py           # HandshakeRequest + HandshakeResponse (PoW + privacy_mode)
 │   │   ├── identity.py            # AgentDID, AgentProfile, VerifiableCredential
 │   │   ├── reputation.py          # TrustScore schema
 │   │   ├── session.py             # VerificationSession + SessionSeal
+│   │   ├── trust_tier.py          # TrustTier IntEnum + score ceilings
 │   │   └── verdict.py             # TrustVerdict, AirlockAttestation, CheckResult
 │   ├── sdk/
 │   │   ├── client.py              # AirlockClient (async httpx wrapper)
 │   │   └── middleware.py          # AirlockMiddleware (protect decorator)
 │   └── semantic/
-│       └── challenge.py           # LLM-backed challenge generation + evaluation
+│       ├── challenge.py           # LLM-backed challenge generation + evaluation
+│       └── fingerprint.py         # SimHash + SHA-256 answer fingerprinting
 ├── integrations/
 │   └── airlock-mcp/               # MCP stdio server (gateway tools)
 ├── sdks/
 │   └── typescript/                # npm package `airlock-client` (HTTP + types)
 ├── examples/                      # Agent scenarios + demos
-└── tests/                         # Pytest suite (gateway, engine, SDK, A2A, …)
+└── tests/                         # Pytest suite — 399+ tests (gateway, engine, SDK, A2A, security, property-based)
 ```
 
 ---
@@ -264,6 +296,9 @@ airlock-protocol/
 | **Reputation with memory** | Half-life decay means reputation is time-sensitive — a trusted agent that goes dark eventually becomes "unknown" again |
 | **Local-first** | LanceDB is embedded (no server). The entire stack runs on a laptop: `python demo/run_demo.py` |
 | **A2A compatible** | The `HandshakeRequest` schema is designed to wrap Google A2A `message` objects |
+| **Progressive trust** | Trust tiers gate score ceilings — LLM-only agents are capped at 0.70; full VC verification unlocks 1.00 |
+| **Privacy-aware** | `privacy_mode` lets callers control data residency (`local_only` keeps all data on the gateway instance) |
+| **Anti-Sybil** | Proof-of-Work on handshake + answer fingerprinting make bot farm attacks economically infeasible |
 
 ---
 
@@ -284,7 +319,13 @@ All settings can be configured via environment variables with the `AIRLOCK_` pre
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE).
+| Component | License |
+|-----------|---------|
+| SDKs, crypto, schemas (`sdks/`, `airlock/crypto/`, `airlock/schemas/`) | Apache 2.0 |
+| Gateway, engine (`airlock/gateway/`, `airlock/engine/`) | BSL 1.1 (converts to Apache 2.0 on 2030-04-04) |
+| Specification (`docs/spec/`) | CC-BY-4.0 |
+
+See [LICENSE](LICENSE) for details.
 
 ## Author
 

airlock/config.py

@@ -87,6 +87,26 @@ class AirlockConfig(BaseSettings):
     scoring_threshold_blacklist: float = 0.15
     scoring_diminishing_factor: float = 0.1
 
+    # -----------------------------------------------------------------------
+    # Trust tier ceilings (overridable via env)
+    # -----------------------------------------------------------------------
+    scoring_tier_0_ceiling: float = 0.50
+    scoring_tier_1_ceiling: float = 0.70
+    scoring_tier_2_ceiling: float = 0.90
+    scoring_tier_3_ceiling: float = 1.00
+
+    # -----------------------------------------------------------------------
+    # Per-tier decay half-lives (days)
+    # -----------------------------------------------------------------------
+    scoring_decay_half_life_tier_0: float = 30.0
+    scoring_decay_half_life_tier_1: float = 90.0
+    scoring_decay_half_life_tier_2: float = 180.0
+    scoring_decay_half_life_tier_3: float = 365.0
+
+    # Decay floor — agents with N+ successful verifications don't drop below this
+    scoring_decay_floor: float = 0.60
+    scoring_decay_floor_min_interactions: int = 10
+
     # -----------------------------------------------------------------------
     # Challenge questions (path to external JSON, empty = use built-in generic set)
     # -----------------------------------------------------------------------
@@ -102,6 +122,37 @@ class AirlockConfig(BaseSettings):
     rule_min_answer_length: int = 20
     rule_min_sentences: int = 2
 
+    # -----------------------------------------------------------------------
+    # Proof-of-Work (anti-Sybil)
+    # -----------------------------------------------------------------------
+    pow_required: bool = False
+    pow_difficulty: int = Field(default=20, ge=1, le=32)
+    pow_ttl_seconds: int = Field(default=120, ge=30, le=600)
+    pow_difficulty_new_did: int = Field(default=22, ge=1, le=32)
+
+    # -----------------------------------------------------------------------
+    # Privacy mode
+    # -----------------------------------------------------------------------
+    privacy_mode_default: str = "any"
+    privacy_mode_allow_no_challenge: bool = True
+
+    # -----------------------------------------------------------------------
+    # LLM evaluation settings
+    # -----------------------------------------------------------------------
+    llm_structured_output: bool = True
+    llm_dual_evaluation: bool = False
+    litellm_model_secondary: str = ""
+    litellm_api_base_secondary: str = ""
+
+    # -----------------------------------------------------------------------
+    # Answer fingerprinting (bot farm detection)
+    # -----------------------------------------------------------------------
+    fingerprint_enabled: bool = True
+    fingerprint_hamming_threshold: int = Field(default=5, ge=0, le=10)
+    fingerprint_window_size: int = Field(default=1000, ge=100, le=100000)
+    fingerprint_exact_duplicate_action: str = "fail"
+    fingerprint_near_duplicate_action: str = "flag"
+
     # Event bus drain timeout during shutdown (seconds).
     event_bus_drain_timeout_seconds: float = Field(default=30.0, ge=1.0, le=600.0)