agentlock 1.2.0__tar.gz → 1.2.1__tar.gz

{agentlock-1.2.0 → agentlock-1.2.1}/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to AgentLock will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2026-04-06
+
+### Added
+
+- **Ed25519 signed receipts (AARM R5)** -- Every authorization decision can produce a cryptographically signed receipt verifiable offline. `ReceiptSigner` supports Ed25519 (via PyNaCl) with HMAC-SHA256 fallback for environments without asymmetric key infrastructure. `ReceiptVerifier` detects tampered receipts. Receipts include decision, tool name, user identity, parameters hash, and policy version hash. Optional dependency: `pip install agentlock[crypto]`.
+- **Hash-chained tamper-evident context (AARM R2)** -- `ContextChain` creates an append-only hash chain of context entries. Each entry links to the previous entry's hash, forming a tamper-evident log. `verify_chain()` detects modification of any historical entry. `ContextProvenance` gains a `previous_hash` field. `ContextTracker.verify_context_chain()` validates chain integrity per session.
+- **`first_call_any_risk` DEFER trigger** -- Defers the first tool call in a session regardless of risk level. Configured via `DeferPolicyConfig(first_call_any_risk=True)`. Unlike `first_call_high_risk`, this catches MEDIUM and LOW risk tools used as attack footholds.
+- **`deny_on_block` whitelist escalation** -- When a `whitelist_path` transformation blocks a parameter (replacing it with `[BLOCKED: ...]`), the gate escalates from MODIFY to DENY. The tool does not execute. `ModifyResult` gains a `blocked_fields` list.
+- **Sibling deferral** -- When one tool call is DEFERRED in a turn, subsequent tool calls in the same turn (within a 5-second window) are automatically deferred. Prevents attackers from falling through to lower-friction tools after a DEFER fires.
+- **Prompt scan carry-forward** -- When a `prompt_scan` signal fires in a session, ALL subsequent tool calls are deferred regardless of whether the tool has its own `defer_policy`. Previously, tools without `defer_policy` (like `lookup_order`) bypassed scan-triggered deferral.
+- **`enforce_all_at_critical` hardening** -- When `HardeningConfig(enforce_all_at_critical=True)`, the gate blocks ALL tool calls at critical hardening severity (risk score >= 10), regardless of tool risk level. Previously, `enforce_at_critical` only blocked HIGH/CRITICAL risk tools.
+- **3 new `lookup_order` combo pairs** -- `(lookup_order, query_database)` weight 4, `(lookup_order, check_balance)` weight 3, `(lookup_order, search_contacts)` weight 3. Detects reconnaissance-to-data-access patterns.
+- New modules: `agentlock/receipts.py`, `agentlock/chain.py`
+- New exports: `SignedReceipt`, `ReceiptSigner`, `ReceiptVerifier`, `ChainedContextEntry`, `ContextChain`, `GENESIS_HASH`
+- Optional dependency group: `agentlock[crypto]` for PyNaCl >= 1.5.0
+- 102 new tests (847 total, 0 failures)
+
+### Changed
+
+- `AuthResult` gains `receipt: SignedReceipt | None` field
+- `AuthorizationGate.__init__()` accepts optional `receipt_signer` parameter
+- `DeferPolicyConfig` gains `first_call_any_risk: bool` field (default False)
+- `DeferralManager` gains `check_first_call_any_risk()`, `check_sibling_deferral()`, `record_deferral()` methods
+- `ModifyResult` gains `blocked_fields: list[str]` field
+- `ContextProvenance` gains `previous_hash: str` field
+- `ContextState` gains `context_chain: ContextChain` field
+- `ContextTracker` gains `verify_context_chain()` method
+- Package version updated to 1.2.1
+
+### Backward Compatibility
+
+- All 778 v1.2.0 tests pass without modification
+- `receipt` field defaults to None when no signer is configured
+- `first_call_any_risk` defaults to False
+- `enforce_all_at_critical` defaults to False
+- `blocked_fields` defaults to empty list
+- `previous_hash` defaults to empty string
+- Hash chain is populated transparently; existing `record_write()` callers require no changes
+
 ## [1.2.0] - 2026-03-30
 
 ### Added

{agentlock-1.2.0 → agentlock-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlock
-Version: 1.2.0
+Version: 1.2.1
 Summary: Authorization framework for AI agent tool calls. Your AI agent needs a login screen — AgentLock is that login screen.
 Project-URL: Homepage, https://agentlock.dev
 Project-URL: Documentation, https://agentlock.dev/docs
@@ -35,11 +35,14 @@ Requires-Dist: flask>=2.0; extra == 'all'
 Requires-Dist: langchain-core>=0.2; extra == 'all'
 Requires-Dist: mcp>=1.0; extra == 'all'
 Requires-Dist: pyautogen>=0.2; extra == 'all'
+Requires-Dist: pynacl>=1.5.0; extra == 'all'
 Requires-Dist: python-jose[cryptography]>=3.3; extra == 'all'
 Provides-Extra: autogen
 Requires-Dist: pyautogen>=0.2; extra == 'autogen'
 Provides-Extra: crewai
 Requires-Dist: crewai>=0.30; extra == 'crewai'
+Provides-Extra: crypto
+Requires-Dist: pynacl>=1.5.0; extra == 'crypto'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -261,6 +264,7 @@ pip install agentlock[autogen]      # AutoGen
 pip install agentlock[mcp]          # Model Context Protocol
 pip install agentlock[fastapi]      # FastAPI
 pip install agentlock[flask]        # Flask
+pip install agentlock[crypto]       # Ed25519 signed receipts
 pip install agentlock[all]          # Everything
 ```
 
@@ -424,6 +428,37 @@ output = gate.execute("query_database", db_func, token=result.token,
 
 The tool still executes. The admin still gets the answer. But PII never enters the LLM context where it can be weaponized by injection attacks.
 
+### Signed Receipts (AARM R5)
+
+Every authorization decision can produce a cryptographically signed receipt, verifiable offline without access to the gate. Tampered receipts fail signature verification.
+
+```python
+from agentlock import AuthorizationGate, ReceiptSigner, ReceiptVerifier
+
+signer = ReceiptSigner(signing_method="ed25519")
+gate = AuthorizationGate(receipt_signer=signer)
+
+result = gate.authorize("query_database", user_id="alice", role="admin")
+# result.receipt is a SignedReceipt with Ed25519 signature
+
+verifier = ReceiptVerifier(signing_method="ed25519", verify_key=signer.verify_key_bytes)
+assert verifier.verify(result.receipt)  # True
+```
+
+HMAC-SHA256 is available as a fallback when PyNaCl is not installed. Install Ed25519 support with `pip install agentlock[crypto]`.
+
+### Hash-Chained Context (AARM R2)
+
+Context entries form a tamper-evident append-only chain. Each entry includes the hash of the previous entry. Modifying any entry invalidates all subsequent entries.
+
+```python
+gate.notify_context_write(session_id, source=ContextSource.TOOL_OUTPUT,
+                          content_hash="abc123...")
+
+valid, broken_at = gate.context_tracker.verify_context_chain(session_id)
+# (True, None) if intact, (False, index) if tampered
+```
+
 ## Standards Alignment
 
 | Standard | Coverage |
@@ -441,7 +476,7 @@ The tool still executes. The admin still gets the answer. But PII never enters t
 |---------|-------|
 | **v1.0** | Core schema, tool permissions, enforcement architecture |
 | **v1.1** | Memory/context permissions, trust degradation, provenance tracking |
-| **v1.2** | Adaptive hardening, MODIFY/DEFER/STEP_UP decisions, multi-signal detection (745 tests) |
+| **v1.2** | Adaptive hardening, MODIFY/DEFER/STEP_UP decisions, signed receipts, hash-chained context (847 tests) |
 | **v1.3** | Output destination control, data flow policies |
 | **v2.0** | Execution scope, behavioral policy, anomaly detection, compliance templates |
 

{agentlock-1.2.0 → agentlock-1.2.1}/README.md

@@ -202,6 +202,7 @@ pip install agentlock[autogen]      # AutoGen
 pip install agentlock[mcp]          # Model Context Protocol
 pip install agentlock[fastapi]      # FastAPI
 pip install agentlock[flask]        # Flask
+pip install agentlock[crypto]       # Ed25519 signed receipts
 pip install agentlock[all]          # Everything
 ```
 
@@ -365,6 +366,37 @@ output = gate.execute("query_database", db_func, token=result.token,
 
 The tool still executes. The admin still gets the answer. But PII never enters the LLM context where it can be weaponized by injection attacks.
 
+### Signed Receipts (AARM R5)
+
+Every authorization decision can produce a cryptographically signed receipt, verifiable offline without access to the gate. Tampered receipts fail signature verification.
+
+```python
+from agentlock import AuthorizationGate, ReceiptSigner, ReceiptVerifier
+
+signer = ReceiptSigner(signing_method="ed25519")
+gate = AuthorizationGate(receipt_signer=signer)
+
+result = gate.authorize("query_database", user_id="alice", role="admin")
+# result.receipt is a SignedReceipt with Ed25519 signature
+
+verifier = ReceiptVerifier(signing_method="ed25519", verify_key=signer.verify_key_bytes)
+assert verifier.verify(result.receipt)  # True
+```
+
+HMAC-SHA256 is available as a fallback when PyNaCl is not installed. Install Ed25519 support with `pip install agentlock[crypto]`.
+
+### Hash-Chained Context (AARM R2)
+
+Context entries form a tamper-evident append-only chain. Each entry includes the hash of the previous entry. Modifying any entry invalidates all subsequent entries.
+
+```python
+gate.notify_context_write(session_id, source=ContextSource.TOOL_OUTPUT,
+                          content_hash="abc123...")
+
+valid, broken_at = gate.context_tracker.verify_context_chain(session_id)
+# (True, None) if intact, (False, index) if tampered
+```
+
 ## Standards Alignment
 
 | Standard | Coverage |
@@ -382,7 +414,7 @@ The tool still executes. The admin still gets the answer. But PII never enters t
 |---------|-------|
 | **v1.0** | Core schema, tool permissions, enforcement architecture |
 | **v1.1** | Memory/context permissions, trust degradation, provenance tracking |
-| **v1.2** | Adaptive hardening, MODIFY/DEFER/STEP_UP decisions, multi-signal detection (745 tests) |
+| **v1.2** | Adaptive hardening, MODIFY/DEFER/STEP_UP decisions, signed receipts, hash-chained context (847 tests) |
 | **v1.3** | Output destination control, data flow policies |
 | **v2.0** | Execution scope, behavioral policy, anomaly detection, compliance templates |
 

agentlock-1.2.1/SECURITY.md

@@ -0,0 +1,139 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|--------------------|
+| 1.2.x   | Yes                |
+| 1.1.x   | Yes                |
+| 1.0.x   | Yes                |
+
+## Reporting a Vulnerability
+
+AgentLock is a security-critical library. We take vulnerability reports seriously and aim to respond within 48 hours.
+
+### How to Report
+
+**Do NOT open a public GitHub issue for security vulnerabilities.**
+
+Instead, report vulnerabilities via one of these channels:
+
+1. **Email:** security@agentlock.dev
+2. **GitHub Security Advisories:** Use the "Report a vulnerability" button on the [Security tab](https://github.com/webpro255/agentlock/security/advisories/new)
+
+### What to Include
+
+- Description of the vulnerability
+- Steps to reproduce
+- Affected versions
+- Potential impact assessment
+- Suggested fix (if any)
+
+### Response Timeline
+
+| Step | Timeline |
+|------|----------|
+| Acknowledgment | Within 48 hours |
+| Initial assessment | Within 5 business days |
+| Fix development | Depends on severity |
+| Public disclosure | After fix is released |
+
+### Severity Classification
+
+We use CVSS v3.1 for severity scoring:
+
+- **Critical (9.0-10.0):** Fix and release within 48 hours
+- **High (7.0-8.9):** Fix and release within 7 days
+- **Medium (4.0-6.9):** Fix in next scheduled release
+- **Low (0.1-3.9):** Fix when resources allow
+
+### Responsible Disclosure
+
+We follow coordinated disclosure:
+
+1. Reporter contacts us privately
+2. We acknowledge and assess
+3. We develop and test a fix
+4. We release the fix and publish an advisory
+5. Reporter may publish details 30 days after fix release
+
+### Scope
+
+The following are in scope for security reports:
+
+- Authorization bypass in the gate or policy engine
+- Token replay or forgery
+- Receipt signature forgery or verification bypass
+- Context chain integrity bypass (hash chain tampering)
+- DEFER/STEP_UP bypass (tool executing when it should be deferred)
+- Session hijacking or fixation
+- Rate limit bypass
+- Redaction bypass (prohibited data leaking through)
+- Audit log tampering or omission
+- Dependency vulnerabilities affecting core functionality
+
+### Out of Scope
+
+- Vulnerabilities in optional framework integrations caused by the framework itself
+- Issues requiring physical access to the server
+- Social engineering attacks against project maintainers
+- Denial of service via resource exhaustion (unless trivially exploitable)
+
+### Recognition
+
+We maintain a security acknowledgments list. Reporters who follow responsible disclosure will be credited (with permission) in our CHANGELOG and security advisories.
+
+## Security Design Principles
+
+AgentLock is built on these security principles:
+
+- **Deny by default** -- no permissions = no access
+- **Infrastructure enforcement** -- agent cannot bypass the gate
+- **Out-of-band authentication** -- credentials never touch the conversation
+- **Single-use tokens** -- cannot be replayed
+- **Mandatory audit** -- every call logged, no exceptions
+- **Signed receipts** -- authorization decisions are cryptographically signed (Ed25519 or HMAC-SHA256) and verifiable offline
+- **Tamper-evident context** -- hash-chained context entries detect modification of historical records
+- **Monotonic trust degradation** -- session trust only goes down, never up
+
+## Security Testing
+
+AgentLock is tested against adversarial attack vectors across 35 categories including prompt injection, social engineering, data exfiltration, privilege escalation, tool chain attacks, memory poisoning, crisis exploitation, and refusal exhaustion.
+
+v1.2.1 results (222 vectors, scored by AgentShield):
+
+| Metric | Score |
+|--------|-------|
+| Overall | 88.7/B |
+| Injection pass rate | 93%+ |
+| PII protection | 100/A |
+| Jailbreak resistance | 100% |
+| Tool abuse prevention | 80%+ |
+
+Remaining failures are concentrated in categories where the model's helpfulness is exploited through plausible narratives with zero injection language. These are model-layer behaviors that middleware alone cannot fully address.
+
+## Defense Layers (v1.2.1)
+
+| Layer | Component | What It Does |
+|-------|-----------|-------------|
+| Pre-LLM | Prompt scanner | Detects injection, authority claims, encoding, impersonation |
+| Gate | Policy engine | Role, scope, rate limit, data classification checks |
+| Gate | Injection filter | Blocks reconnaissance, command injection, social engineering patterns |
+| Gate | PII filter | Blocks queries that would return data above caller clearance |
+| Gate | DEFER engine | Suspends ambiguous calls pending review |
+| Gate | STEP_UP engine | Requires human approval based on session risk |
+| Gate | MODIFY engine | Transforms parameters and outputs (PII redaction, domain restriction) |
+| Gate | Hardening engine | Monotonic risk scoring with targeted defensive instructions |
+| Post-execution | Redaction engine | Pattern-based PII removal from tool outputs |
+| Forensic | Signed receipts | Ed25519/HMAC-SHA256 signed authorization records |
+| Forensic | Context chain | Hash-chained tamper-evident context log |
+
+## Signal Detectors
+
+| Detector | Signals |
+|----------|---------|
+| Velocity | Rapid calls, topic escalation, burst patterns |
+| Combo | Suspicious tool pairs and sequences (16 pairs, 5 sequences) |
+| Echo | Response echoing, tool disclosure, credential patterns |
+| Prompt scan | 7 pattern categories with cross-turn repetition tracking |
+| Compound | Bonus scoring when multiple signal types co-occur |

{agentlock-1.2.0 → agentlock-1.2.1}/agentlock/__init__.py

@@ -34,19 +34,19 @@ Copyright 2026 David Grice
 SPDX-License-Identifier: Apache-2.0
 """
 
-__version__ = "1.2.0"
+__version__ = "1.2.1"
 
 from agentlock.audit import AuditLogger, AuditRecord, FileAuditBackend, InMemoryAuditBackend
+from agentlock.chain import GENESIS_HASH, ChainedContextEntry, ContextChain
 from agentlock.context import ContextProvenance, ContextState, ContextTracker
 from agentlock.decorators import agentlock
+from agentlock.defer import DeferralManager, DeferralRecord
 from agentlock.exceptions import (
     AgentLockError,
-    DeferredError,
-    ModifyAppliedError,
-    StepUpRequiredError,
     ApprovalRequiredError,
     AuthenticationRequiredError,
     ConfigurationError,
+    DeferredError,
     DeniedError,
     InsufficientRoleError,
     MemoryConfirmationRequiredError,
@@ -54,10 +54,12 @@ from agentlock.exceptions import (
     MemoryReadDeniedError,
     MemoryRetentionExceededError,
     MemoryWriteDeniedError,
+    ModifyAppliedError,
     RateLimitedError,
     SchemaValidationError,
     ScopeViolationError,
     SessionExpiredError,
+    StepUpRequiredError,
     TokenError,
     TokenExpiredError,
     TokenInvalidError,
@@ -65,27 +67,15 @@ from agentlock.exceptions import (
     TrustDegradedError,
     UnattributedContextError,
 )
-from agentlock.defer import DeferralManager, DeferralRecord
 from agentlock.gate import AuthorizationGate, AuthResult
-from agentlock.stepup import StepUpManager, StepUpNotifier, StepUpRequest
-from agentlock.modify import ModifyEngine, ModifyResult
 from agentlock.hardening import (
     HardeningConfig,
     HardeningDirective,
     HardeningEngine,
     HardeningSignal,
 )
-from agentlock.signals import (
-    ComboDetector,
-    ComboSignal,
-    EchoDetector,
-    EchoSignal,
-    PromptScanConfig,
-    PromptScanner,
-    VelocityDetector,
-    VelocitySignal,
-)
 from agentlock.memory_gate import InMemoryMemoryStore, MemoryDecision, MemoryEntry, MemoryGate
+from agentlock.modify import ModifyEngine, ModifyResult
 from agentlock.policy import (
     InjectionFilter,
     PiiFilter,
@@ -94,33 +84,44 @@ from agentlock.policy import (
     RequestContext,
 )
 from agentlock.rate_limit import RateLimiter
+from agentlock.receipts import ReceiptSigner, ReceiptVerifier, SignedReceipt
 from agentlock.redaction import RedactionEngine, RedactionResult
 from agentlock.schema import (
     SCHEMA_VERSION,
     AgentLockPermissions,
-    DeferPolicyConfig,
-    ModifyPolicyConfig,
-    StepUpPolicyConfig,
-    TransformationConfig,
     AuditConfig,
     ContextPolicyConfig,
     DataPolicyConfig,
+    DeferPolicyConfig,
     DegradationTrigger,
     HumanApprovalConfig,
     MemoryPolicyConfig,
     MemoryRetentionConfig,
+    ModifyPolicyConfig,
     RateLimitConfig,
     ScopeConfig,
     SessionConfig,
     SourceAuthorityConfig,
+    StepUpPolicyConfig,
     ToolDefinition,
+    TransformationConfig,
     TrustDegradationConfig,
 )
 from agentlock.session import Session, SessionStore
+from agentlock.signals import (
+    ComboDetector,
+    ComboSignal,
+    EchoDetector,
+    EchoSignal,
+    PromptScanConfig,
+    PromptScanner,
+    VelocityDetector,
+    VelocitySignal,
+)
+from agentlock.stepup import StepUpManager, StepUpNotifier, StepUpRequest
 from agentlock.token import ExecutionToken, TokenStore
 from agentlock.types import (
     ApprovalChannel,
-    DecisionType,
     ApprovalThreshold,
     AuditLogLevel,
     AuthMethod,
@@ -128,6 +129,7 @@ from agentlock.types import (
     ContextSource,
     DataBoundary,
     DataClassification,
+    DecisionType,
     DegradationEffect,
     DenialReason,
     MemoryPersistence,
@@ -198,13 +200,23 @@ __all__ = [
     # DEFER (v1.2)
     "DeferralManager",
     "DeferralRecord",
+    "DeferredError",
     # STEP_UP (v1.2)
     "StepUpManager",
     "StepUpRequest",
     "StepUpNotifier",
+    "StepUpRequiredError",
     # MODIFY (v1.2)
     "ModifyEngine",
     "ModifyResult",
+    # Signed receipts (AARM R5)
+    "SignedReceipt",
+    "ReceiptSigner",
+    "ReceiptVerifier",
+    # Hash-chained context (AARM R2)
+    "ChainedContextEntry",
+    "ContextChain",
+    "GENESIS_HASH",
     # Enums
     "DecisionType",
     "RiskLevel",

agentlock-1.2.1/agentlock/chain.py

@@ -0,0 +1,163 @@
+"""Hash-chained context entries (AARM R2).
+
+Each context entry includes the hash of the previous entry, forming a
+tamper-evident append-only chain.  Modifying any entry invalidates all
+subsequent entries.
+
+Usage::
+
+    chain = ContextChain()
+    chain.append(source="user_message", authority="authoritative",
+                 content_hash="abc123...")
+    chain.append(source="tool_output", authority="derived",
+                 content_hash="def456...")
+
+    valid, broken_at = chain.verify_chain()
+    assert valid
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "ChainedContextEntry",
+    "ContextChain",
+    "GENESIS_HASH",
+]
+
+# The chain starts from a well-known genesis hash (SHA-256 of empty string).
+GENESIS_HASH = hashlib.sha256(b"").hexdigest()
+
+
+def _generate_entry_id() -> str:
+    return f"cctx_{secrets.token_hex(8)}"
+
+
+def _compute_entry_hash(
+    previous_hash: str,
+    content_hash: str,
+    source: str,
+    authority: str,
+    writer_id: str,
+    timestamp: float,
+) -> str:
+    """Compute the deterministic hash of a chain entry."""
+    payload = (
+        f"{previous_hash}\x00{content_hash}\x00"
+        f"{source}\x00{authority}\x00"
+        f"{writer_id}\x00{timestamp:.6f}"
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+@dataclass(slots=True)
+class ChainedContextEntry:
+    """A single entry in the hash chain."""
+
+    entry_id: str = field(default_factory=_generate_entry_id)
+    timestamp: float = field(default_factory=time.time)
+    source: str = ""             # ContextSource value
+    authority: str = ""          # ContextAuthority value
+    content_hash: str = ""       # SHA-256 of actual content
+    previous_hash: str = ""      # hash of the previous ChainedContextEntry
+    entry_hash: str = ""         # SHA-256(previous_hash + content_hash + ...)
+    writer_id: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class ContextChain:
+    """Append-only hash chain of context entries.
+
+    Each appended entry is linked to the previous entry's ``entry_hash``,
+    forming a tamper-evident log.  Verifying the chain detects any
+    modification to historical entries.
+    """
+
+    def __init__(self) -> None:
+        self._entries: list[ChainedContextEntry] = []
+
+    def append(
+        self,
+        source: str,
+        authority: str,
+        content_hash: str,
+        *,
+        writer_id: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> ChainedContextEntry:
+        """Append a new entry, linking to the previous hash.
+
+        Args:
+            source: Context source (e.g. ``"user_message"``).
+            authority: Context authority level.
+            content_hash: SHA-256 of the actual content.
+            writer_id: Identity of the writer.
+            metadata: Additional context.
+
+        Returns:
+            The newly created chain entry.
+        """
+        prev = self.head_hash
+        ts = time.time()
+        entry_hash = _compute_entry_hash(
+            prev, content_hash, source, authority, writer_id, ts,
+        )
+        entry = ChainedContextEntry(
+            timestamp=ts,
+            source=source,
+            authority=authority,
+            content_hash=content_hash,
+            previous_hash=prev,
+            entry_hash=entry_hash,
+            writer_id=writer_id,
+            metadata=metadata or {},
+        )
+        self._entries.append(entry)
+        return entry
+
+    def verify_chain(self) -> tuple[bool, int | None]:
+        """Verify chain integrity.
+
+        Returns:
+            ``(True, None)`` if the chain is valid.
+            ``(False, index)`` where ``index`` is the first broken entry.
+        """
+        expected_prev = GENESIS_HASH
+        for i, entry in enumerate(self._entries):
+            if entry.previous_hash != expected_prev:
+                return False, i
+            recomputed = _compute_entry_hash(
+                entry.previous_hash,
+                entry.content_hash,
+                entry.source,
+                entry.authority,
+                entry.writer_id,
+                entry.timestamp,
+            )
+            if entry.entry_hash != recomputed:
+                return False, i
+            expected_prev = entry.entry_hash
+        return True, None
+
+    @property
+    def head_hash(self) -> str:
+        """Hash of the most recent entry, or GENESIS_HASH if empty."""
+        if not self._entries:
+            return GENESIS_HASH
+        return self._entries[-1].entry_hash
+
+    @property
+    def entries(self) -> list[ChainedContextEntry]:
+        """Read-only access to all entries."""
+        return list(self._entries)
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __getitem__(self, idx: int) -> ChainedContextEntry:
+        return self._entries[idx]

{agentlock-1.2.0 → agentlock-1.2.1}/agentlock/context.py

@@ -13,6 +13,7 @@ import time
 from dataclasses import dataclass, field
 from typing import Any
 
+from agentlock.chain import ContextChain
 from agentlock.schema import ContextPolicyConfig, TrustDegradationConfig
 from agentlock.types import ContextAuthority, ContextSource, DegradationEffect
 
@@ -36,6 +37,7 @@ class ContextProvenance:
     token_id: str | None = None
     session_id: str = ""
     content_hash: str = ""
+    previous_hash: str = ""
     parent_provenance_id: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
 
@@ -56,6 +58,7 @@ class ContextState:
     degraded_at: float | None = None
     active_effects: list[DegradationEffect] = field(default_factory=list)
     provenance_log: list[ContextProvenance] = field(default_factory=list)
+    context_chain: ContextChain = field(default_factory=ContextChain)
     unattributed_count: int = 0
 
 
@@ -131,6 +134,14 @@ class ContextTracker:
             }
             authority = defaults.get(source, ContextAuthority.UNTRUSTED)
 
+        # Append to the hash chain and capture previous_hash
+        chain_entry = state.context_chain.append(
+            source=source.value,
+            authority=authority.value,
+            content_hash=content_hash,
+            writer_id=writer_id,
+        )
+
         provenance = ContextProvenance(
             source=source,
             authority=authority,
@@ -139,6 +150,7 @@ class ContextTracker:
             token_id=token_id,
             session_id=session_id,
             content_hash=content_hash,
+            previous_hash=chain_entry.previous_hash,
             parent_provenance_id=parent_provenance_id,
             metadata=metadata or {},
         )
@@ -151,6 +163,18 @@ class ContextTracker:
 
         return provenance
 
+    def verify_context_chain(self, session_id: str) -> tuple[bool, int | None]:
+        """Verify the hash chain integrity for a session.
+
+        Returns:
+            ``(True, None)`` if valid or session not found.
+            ``(False, index)`` if tampered at the given index.
+        """
+        state = self._states.get(session_id)
+        if state is None:
+            return True, None
+        return state.context_chain.verify_chain()
+
     def record_unattributed(self, session_id: str) -> None:
         """Record that unattributed content entered context."""
         state = self.get_or_create(session_id)